DESIGN.md diff命令完全指南令牌级回归检测与regression判定【免费下载链接】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.mdDESIGN.md 的 diff 命令是设计系统版本对比的利器它把两版 DESIGN.md 文件喂给google/design.mdCLI逐一对比颜色、字体、圆角、间距与组件等设计令牌design tokens输出结构化的变更报告并用一个regression布尔值告诉你这一版设计系统是不是变差了。本指南带你从零理解它的原理与用法。为什么设计系统也需要回归检测传统软件的回归检测盯的是功能行为而 AI 编码代理依赖的设计系统同样会退化某次修改后主色primary被删掉了、按钮对比度跌破 WCAG AA 标准、或组件令牌引用断链。这些设计回归人工很难逐版盯出来。DESIGN.md 格式把设计标识拆成两层机器可读的 YAML 令牌tokens 人类可读的设计说明prose。diff 命令正是在令牌层面做精准比对让设计系统的每次演进都可审计、可拦截。 完整的格式规范见 docs/spec.md一个真实的设计系统示例可参考 examples/heritage/DESIGN.md。3 步快速上手 diff 命令一键运行无需安装首次会自动从 npm 拉取npx google/design.md diff DESIGN.md DESIGN-v2.md参数说明before位置参数旧版 DESIGN.md 文件路径after位置参数新版 DESIGN.md 文件路径--format输出格式默认json 小技巧两个位置参数都支持传-从标准输入读取内容方便把 diff 接进管道。读懂 JSON 输出令牌变更一目了然diff 的结果分三大块源码位置packages/cli/src/commands/diff.ts1️⃣tokens五大类令牌的新增 / 删除 / 修改每类令牌都返回added/removed/modified三个数组令牌类别对比内容colors颜色令牌typography字体排版令牌rounded圆角刻度spacing间距刻度components组件令牌含 hover 等变体一个典型输出长这样{ tokens: { colors: { added: [accent], removed: [], modified: [tertiary] } }, findings: { before: { errors: 0, warnings: 1 }, after: { errors: 0, warnings: 1 }, delta: { errors: 0, warnings: 0 } }, regression: false }2️⃣findingslint 结果的前后对照diff 内部会先对两个文件各跑一遍完整的 lint共 11 条规则如断链引用broken-ref、对比度不足contrast-ratio、缺少primary色missing-primary等再给出before/after两个摘要及delta差值。3️⃣regression一句话结论regression: true → 这版设计系统变差了 regression: false → 质量没有倒退regression 判定规则什么时候算回归核心逻辑只有两行非常直白diff.ts#L78-L79当后文件的 errors 数量 前文件或 warnings 数量 前文件时判定为回归。注意三个细节✅只看错误和警告的增长infos提示不参与判定✅令牌变了 ≠ 回归新增颜色、调整间距只要不引发 lint 问题增多regression仍为false——diff 关心的是质量倒退而非内容变化✅持平不算回归错误/警告数量不变delta 为 0时放行。退出码 3 个信号让 diff 成为 CI 的质量门退出码含义典型场景0无回归新版质量持平或提升1检测到回归regression: trueCI 中自动拦截本次提交2输入文件无法读取路径写错、权限不足FileReadError 会给出友好提示 在 CI 里只需一行命令即可把设计质量倒退变成红灯npx google/design.md diff $OLD_DESIGN_MD DESIGN.md幕后原理diffMaps 如何做令牌级对比对比引擎是 utils.ts 中的diffMaps函数思路简单而可靠遍历后文件的每个令牌键新出现的 →added用JSON.stringify做值级深比较键相同但值变了 →modified遍历前文件的键消失的 →removed。组件令牌会先被序列化为其属性对象diff.ts#L87-L93因此button-primary的padding从 12px 改成 16px 也能被精准捕获。相关行为由 diff.test.ts 中的用例覆盖组件新增、删除、属性修改各有验证。实战建议把 diff 融入设计系统迭代流程版本命名习惯保留DESIGN-v1.md、DESIGN-v2.md快照每次大改版前存档CI 集成把diff退出码接入流水线regression: true时阻断合并配合 lint单独跑npx google/design.md lint DESIGN.md可看当前文件的完整问题清单与 diff 报告互为补充。关键文件速查路径作用packages/cli/src/commands/diff.tsdiff 命令主逻辑与 regression 判定packages/cli/src/utils.tsdiffMaps令牌对比引擎packages/cli/src/commands/diff.test.ts组件 diff 的测试用例packages/cli/src/linter/rules/index.ts11 条 lint 规则汇总docs/spec.mdDESIGN.md 完整格式规范掌握diff命令后你的设计系统就从凭感觉维护升级为每次迭代都有质量凭证——这正是 DESIGN.md 让 AI 代理稳定产出一致 UI 的底层保障。【免费下载链接】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），仅供参考