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.mdWindows（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。日常最常触发的前几条：
| 规则 | 级别 | 检查内容 |
|---|---|---|
broken-ref | error | 令牌引用未指向任何已定义令牌 |
missing-primary | warning | 定义了颜色却缺少primary主色 |
contrast-ratio | warning | 组件文字/背景对比度低于 4.5:1 |
orphaned-tokens | warning | 颜色令牌定义了却从未被组件引用 |
section-order | warning | Markdown 章节顺序不符合规范 |
unknown-key | warning | 顶层键名疑似拼写错误（如colours） |
⚠️ 注意：默认只有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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
