DESIGN.md 进 CI：用 lint 校验设计规范
DESIGN.md 的工程化指南：YAML 值与 Markdown 意图的双层结构、官方 lint/diff/export/spec 四命令、WCAG AA 校验边界、exit code 陷阱与完整 CI 接入示例。
过去一年，"让 Agent 写出风格一致的 UI"成为一个真实存在的工程问题。答案正在收敛到一个朴素的方案：用纯文本文件把设计规范写下来，让 Agent 在动手前先读它。
DESIGN.md 是这个方案里最受关注的一个。它来自 Google Labs 官方开源仓库（Apache-2.0 许可，目前处于 alpha 阶段），并且配套一个可以独立运行的官方 CLI：支持 lint、diff、export、spec 四个命令，最新的 v0.4.0 已在 10 月上旬被社区反复实测。
更重要的是它的定位变化：DESIGN.md 不再只是"给 Agent 看的说明文档"，而是可以 lint、可以 diff、可以进 CI 拦截的工程制品。设计 token 的治理，第一次有了官方可执行的工具链。
注意：DESIGN.md 格式目前仍是 alpha，规范未来会变化；接入 CI 时请锁定 CLI 版本。本文以 v0.4.0 的行为为准。
一、从"给 Agent 看的文档"到"可校验的工程制品"
Agent 时代正在形成一套约定：不同职责交给不同的纯文本规范文件。
| 文件 | 管什么 | 核心作用 |
|---|---|---|
| CLAUDE.md | 行为 | 告诉 Agent 如何完成任务、遵循哪些流程 |
| DESIGN.md | 视觉 | 定义颜色、字体、间距、组件规则等设计意图 |
| AGENTS.md | 协作 | 定义多个 Agent 或工具之间的协作约定 |
Community 里流传的一句总结很准确：CLAUDE.md 管行为，DESIGN.md 管视觉，AGENTS.md 管协作。
DESIGN.md 真正的价值在于可校验：你的颜色对比度、token 引用、章节完整性，都可以用一条命令检查，并且把检查接入 CI，让不合规的设计规范无法合入主分支。
二、DESIGN.md 格式速览：YAML 值 + Markdown 意图
DESIGN.md 采用双层结构：
- YAML frontmatter：放规范值（token），例如色值、字体名、字号比例。
- Markdown 正文：放设计意图，解释这些值为什么这样定义、该如何使用。
这样分工的意义是：机器读 YAML 做校验和导出，人和 Agent 读 Markdown 理解上下文。
固定章节顺序
官方规范要求章节按固定顺序组织，lint 工具依赖这个顺序做完整性检查：
- Overview
- Colors
- Typography
- Layout
- Elevation & Depth
- Shapes
- Components
- Do's and Don'ts
写 Prompt 型设计规范、或让 Agent 生成 DESIGN.md 草稿时，按照这个顺序组织，才能顺利通过校验。
结构示意
下面是一个最小结构示意（字段以实际规范为准）：
---
colors:
primary: "#1a1a1a"
background: "#ffffff"
accent: "#2563eb"
typography:
base: "Inter"
scale: "1.25"
---
## Overview
这是一个文档型产品，强调可读性与克制的强调色……
## Colors
primary 用于正文与主按钮，accent 只用于链接与焦点态……
三、官方 CLI 四命令：lint / diff / export / spec
四个命令覆盖了设计规范的完整生命周期：
| 命令 | 作用 |
|---|---|
lint | 按规则校验 DESIGN.md，包含 WCAG AA 对比度检查 |
diff | 对比两份规范或两个版本之间的差异 |
export | 导出为 Tailwind config 或 W3C DTCG 设计 token |
spec | 输出规范化说明，便于团队对齐格式 |
本地跑一次校验：
npx @google/design.md lint DESIGN.md
lint 的规则与 WCAG AA 边界
lint 内置 8 条校验规则，其中最有存在感的是对比度检查：按 WCAG AA 的 4.5:1 标准核对文本与背景的组合。
需要明确它的边界：lint 不检查焦点态、不检查语义结构、也不检查动效。它能挡住的是"硬伤"，不能替代设计评审。
exit code 陷阱：为什么对比度问题不会让 CI 失败
这是最容易踩的坑：lint 发现对比度问题时只告警、不报错，进程仍然以 exit 0 结束。也就是说，直接把 lint 挂进 CI，对比度不合格的规范依然会通过。
要在 CI 里严格拦截，需要读取 lint 的 JSON 输出，自行判断并返回非零退出码。下面的检查逻辑是示意（以实际输出格式为准）：
# 示意：把 lint 结果保存下来，出现对比度告警时手动让 CI 失败
npx @google/design.md lint DESIGN.md > lint-result.json
if grep -qi "contrast" lint-result.json; then
echo "对比度校验未通过"
exit 1
fi
四、实战：把 DESIGN.md 校验接入 CI 管线
一个可直接参考的 GitHub Actions 配置。注意两点：使用官方 workaround 中的 designmd 命令名，并锁定版本：
name: design-lint
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Lint DESIGN.md
run: npx -p @google/design.md@0.4.0 designmd lint DESIGN.md
严格模式：解析 JSON 输出
如果团队要求"对比度不达标必须阻塞合入"，在上面基础上增加一步：保存 JSON 输出、检查是否存在对比度告警、命中则以非零退出码结束。思路与上一节的示意一致，关键是把"告警"翻译成 CI 语义里的"失败"。
五、导出到 Tailwind config 与 DTCG：设计 token 的落地路径
lint 保证规范"写得对"，export 解决规范"用得起来"：
- 导出为 Tailwind config：让前端工程直接消费设计 token，配色和字体不再散落在组件里。
- 导出为 W3C DTCG 格式：与更广泛的设计工具链互通。
值得一提的是：DESIGN.md 的 CLI 是独立运行的，不需要 Stitch 账号。即使团队不打算使用 Stitch 生成界面，也可以单独把它当作设计规范的校验与导出工具。
六、故障排查：三类常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| ENOVERSIONS | 依赖或版本解析失败 | 锁定 CLI 版本，清理缓存后重装 |
| Windows 下无输出 | design.md 命令与文件关联冲突 | 使用 workaround 命令 |
| broken-ref | 规范内引用了不存在的 token 或章节 | 按报错行号修正引用 |
Windows / PowerShell 用户遇到命令冲突时，改用：
npx -p @google/design.md designmd lint DESIGN.md
七、常见问题（FAQ）
Q1：不用 Stitch 账号，能单独使用 DESIGN.md 和这个 CLI 吗？
可以。格式规范与 CLI 都是独立项目，本地运行、进 CI 都不依赖 Stitch 云服务。
Q2：为什么对比度问题不会让 CI 失败？
lint 对对比度问题只输出告警并以 exit 0 结束；严格拦截需要解析 JSON 输出并自行返回非零退出码。
Q3：团队刚开始用，最小可行的做法是什么？
两步：在 AGENTS.md 里加一行"任何 UI 工作前先读 DESIGN.md"，然后给仓库加一条 lint 的 CI 检查。规范内容可以边用边补。
八、总结
DESIGN.md 把"设计规范"从口头约定变成了工程制品：可写、可校验、可导出、可拦截。对于已经有 CI 习惯的团队，它几乎是零成本引入——一条命令检查，一条流水线守住底线。
继续阅读：
- 想看 CLI 如何串起设计与代码：Stitch CLI 完全指南
- 想知道设计系统如何提取：用 URL 提取整套设计系统
- 想从提示词开始学起：Stitch 提示词教程