DESIGN.md集成CI/CD完整教程：GitHub Actions中校验与回归阻断

DESIGN.md集成CI/CD完整教程GitHub Actions中校验与回归阻断【免费下载链接】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 是一种面向编码智能体的视觉识别描述格式规范它为 AI 提供持久、结构化的设计系统理解。本教程将带你把 DESIGN.md 的lint 校验与diff 回归检测接入 GitHub Actions实现 CI/CD 流水线中的自动校验与回归阻断让每一次设计令牌design tokens的改动都有质量门禁把关。为什么 DESIGN.md 需要 CI/CD 守护DESIGN.md 文件由两层组成YAML 前置元数据—— 机器可读的设计令牌颜色、字体、圆角、间距、组件Markdown 正文—— 人类可读的设计决策说明令牌是规范值AI 智能体依据它生成 UI。一旦令牌被误改——比如拼错{colors.primery}导致引用断裂、或对比度不达标——生成的界面就会悄悄劣化。人工评审很容易漏掉这类问题而 DESIGN.md 官方 CLI 提供了结构化 JSON 报告和明确的退出码天然适合在 CI 中做质量门禁。️完整格式规范见 docs/spec.md官方示例可参考 examples/atmospheric-glass/DESIGN.md。快速了解DESIGN.md CLI 的四大命令CLI 包名为google/design.mdnpm核心命令如下命令作用关键退出码lint校验 DESIGN.md 结构正确性1 发现错误0 通过diff对比两个版本的令牌与检查发现1 检测到回归export导出为 Tailwind / DTCG / CSS 变量等格式0 成功spec输出格式规范便于注入智能体提示词0所有命令默认输出 JSON方便在 CI 中解析与存档。lint内置 11 条规则包括断裂引用broken-ref、WCAG 对比度contrast-ratio、孤立项检测orphaned-tokens等详见 packages/cli/src/commands/lint.ts。第一步本地安装与 DESIGN.md 校验在动手写 CI 之前先在本地跑通npx google/design.md lint DESIGN.md输出是结构化 JSONfindings数组列出每条发现severity、path、messagesummary汇总错误/警告/信息数量。只要summary.errors 0进程就以退出码1结束——这正是 CI 判断失败的依据源码逻辑见 packages/cli/src/commands/lint.ts。提示在 Windows/PowerShell 上.md后缀可能与 Markdown 文件关联冲突请改用无后缀别名npx -p google/design.md designmd lint DESIGN.md第二步编写 GitHub Actions 工作流自动 lint在仓库的.github/workflows/design-lint.yml中新增以下工作流以main分支的 DESIGN.md 为校验对象name: DESIGN.md Lint on: pull_request: paths: - DESIGN.md jobs: design-lint: runs-on: ubuntu-latest steps: - name: 检出代码 uses: actions/checkoutv4 - name: 配置 Node.js uses: actions/setup-nodev4 with: node-version: 20 - name: 运行 DESIGN.md 结构校验 run: npx google/design.md lint DESIGN.md id: lint - name: 上传校验报告失败时保留证据 if: always() run: | npx google/design.md lint DESIGN.md lint-report.json || true echo DESIGN.md lint 报告已生成 - name: 上传报告工件 if: always() uses: actions/upload-artifactv4 with: name: design-lint-report path: lint-report.json几个设计要点paths过滤只有 DESIGN.md 变更时才触发避免无谓的流水线消耗 ⚡if: always() 工件上传即使校验失败JSON 报告也会保留为工件便于在 PR 中直接查看具体是哪条规则报错门禁天然生效lint发现错误时退出码为1该步骤立即红叉PR 无法通过强制状态检查required check合并第三步用 diff 命令阻断设计回归lint只保证当前版本合法而diff能回答新版本是否比基线更差。其判断逻辑若after版本的 error 或 warning 数量多于before版本即判定为回归退出码1实现见 packages/cli/src/commands/diff.ts。在 CI 中我们让 PR 分支的 DESIGN.md 与main分支的基线版本对比- name: 对比基线阻断设计令牌回归 run: | git show origin/main:DESIGN.md DESIGN-baseline.md npx google/design.md diff DESIGN-baseline.md DESIGN.md diff-report.jsondiff的 JSON 输出包含三部分字段说明tokens按颜色/字体/圆角/间距/组件分组列出added/removed/modified令牌findings.delta前后版本 error、warning 数量差值regression布尔值是否为回归实战效果如果有人把tertiary颜色改成了对比度不达标的值contrast-ratio规则会新增一条 warningregression变为true流水线红叉阻断合并——而改动者能直接从tokens.colors.modified中定位到被改坏的令牌名。进阶在流水线中导出设计令牌校验通过后可以顺手用export命令把令牌同步给下游消费方保证单一数据源npx google/design.md export --format css-tailwind DESIGN.md theme.css # Tailwind v4 npx google/design.md export --format json-tailwind DESIGN.md tailwind.json # Tailwind v3 npx google/design.md export --format dtcg DESIGN.md tokens.json # W3C DTCG npx google/design.md export --format css-vars DESIGN.md theme.css # CSS 变量注意export成功时退出码恒为0源文件的 lint 问题由lint命令负责把关因此建议先 lint、后 export的顺序编排步骤。命令实现见 packages/cli/src/commands/export.ts。退出码速查表CI 判断依据命令退出码0退出码1退出码2lint无错误发现 error 级问题输入文件无法读取diff无回归检测到回归error/warning 变多任一文件无法读取export导出成功非法--format或生成器错误输入文件无法读取退出码2通常意味着路径写错或分支基线获取失败编写工作流时值得用|| true兜底并输出错误信息避免流水线静默跳过。总结你的设计系统现在有了自动护栏✅结构校验lint在每次 PR 中自动捕捉断裂引用、拼错的令牌键名、对比度问题✅回归阻断diff以基线为锚点阻止设计系统越改越差✅多格式同步export让 Tailwind / DTCG 等下游始终与 DESIGN.md 保持同频DESIGN.md 规范当前处于alpha阶段格式仍在演进中但其 CLI 的退出码契约非常稳定可以放心作为 CI/CD 的质量门禁基石。动手把上面的工作流加入你的仓库让 AI 生成的每一个界面都值得信赖吧延伸阅读完整格式规范docs/spec.md玻璃拟态示例设计系统examples/atmospheric-glass/CLI 入口源码packages/cli/src/index.ts贡献指南CONTRIBUTING.md【免费下载链接】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），仅供参考