DESIGN.md pre-commit钩子实战：让坏设计令牌提交不了仓库

DESIGN.md pre-commit钩子实战：让坏设计令牌提交不了仓库

【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md

DESIGN.md 是一个面向 AI 编码代理的开源设计系统格式规范，配套的官方 CLI 可对设计令牌（颜色、字体、间距、圆角等 Design Token）执行 lint、diff、export 三类检查。本文面向新手，带你用 3 步把lint接入 git 的 pre-commit 钩子，让坏设计令牌在提交的瞬间就被拦截，永远进不了仓库。

为什么 pre-commit 是设计令牌的最佳守门员

坏设计令牌通常从这几类路径混进仓库：

• 断掉的引用：组件引用了{colors.brand}这类根本不存在的令牌
• 对比度不足：文字/背景色组合低于 WCAG AA 的 4.5:1 标准
• 键名拼写错误：把colors:写成colours:，整组令牌被静默丢弃

靠肉眼审查很难发现这些问题，而 DESIGN.md CLI 内置了 11 条 lint 规则可以自动捕获。关键在于它的退出码：lint发现 error 级问题时退出码为1，否则为0——这正是 git 钩子"放行 / 拦截"提交所需要的行为。

核心实现见 packages/cli/src/commands/lint.ts。

三步配置：最快的 pre-commit 钩子接入方法

第 1 步：本地安装 CLI

npm install -D @google/design.md

Windows（PowerShell）用户请给包名加引号，避免@被 shell 特殊处理：

npm install -D "@google/design.md"

第 2 步：编写 pre-commit 钩子脚本

在仓库根目录创建.git/hooks/pre-commit文件（需赋予可执行权限），内容如下：

#!/bin/sh # 仅当本次提交包含 DESIGN.md 时才执行检查 if git diff --cached --name-only | grep -q '^DESIGN\.md$'; then npx designmd lint DESIGN.md fi

说明：

• designmd是官方提供的别名命令，可避免 Windows 下.md后缀与 Markdown 文件关联冲突，跨平台行为一致
• grep那一行保证提交其他文件时钩子零开销
• lint 失败（退出码 1）时 git 会自动中止提交，你看到的就是带findings和summary的结构化 JSON 报告

第 3 步：提交验证

git commit -m "update: 调整主按钮配色"

一切正常则直接提交；若有 error 级问题被拦截，按 JSON 中path指出的位置修复后重新提交即可 ✅

💡 如果项目已使用 lint-staged 等文件级检查工具，也可以把同一条命令挂到*.md规则里，效果等价。

哪些坏设计令牌会被拦截

linter 内置 11 条规则，完整清单见 packages/cli/src/linter/linter/rules/index.ts。日常最常触发的前几条：

⚠️ 注意：默认只有error级发现（如broken-ref）会阻断提交，warning 仅作提示。若希望 warning 也拦截，可在钩子中解析--format json输出的summary.warnings字段，自行决定是否exit 1。

进阶：用 diff 命令拦住设计"回退"

lint解决"当前文件是否有错"，而diff解决"新版是否比旧版更差"。当后一个文件的 error 或 warning 数量多于前一个文件时，命令退出码为1，回归判定逻辑见 packages/cli/src/commands/diff.ts：

npx designmd diff DESIGN.md DESIGN-v2.md

在钩子里把暂存区版本的 DESIGN.md 与git show HEAD:DESIGN.md取出的旧版本做 diff，就能连"质量悄悄降级"的设计系统改动也一并拦住。

延伸阅读

• 完整格式规范：docs/spec.md
• CLI 命令与规则参考：README.md
• 设计理念（为什么散文比令牌更重要）：PHILOSOPHY.md
• 完整示例，含令牌文件与 Tailwind 导出配置：examples/atmospheric-glass/DESIGN.md、examples/atmospheric-glass/tailwind.config.js

常见问题

Q：为什么不放进 CI，非要 pre-commit？CI 是兜底防线，但反馈发生在推送之后；pre-commit 把反馈压缩到几秒内，修复成本最低。两者可以并存。

Q：钩子会不会拖慢日常提交？不会。脚本只在暂存区包含DESIGN.md时才运行 lint，其他提交几乎零开销。

Q：Windows 上行为一致吗？一致，但建议使用designmd别名；PowerShell 下@与.md后缀都容易被系统误解析，详见 README.md 的 Getting Started 章节。

【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md