design.md：Google Labs 给 AI 编程 Agent 立的设计系统 "宪法"，一套 YAML 让 Agent 一次就生成对的设计
design.md：Google Labs 给 AI 编程 Agent 立的设计系统” 宪法”，一套 YAML 让 Agent 一次就生成对的设计
一、一个让设计师崩溃的真实场景
周一上午 10 点，你刚把新一版品牌色” 墨黑 + 石灰 + 波士顿陶土橙” 同步给设计系统，PM 就丢过来一个 Jira：让 Claude Code 帮官网做一个” 夏季活动” 落地页。
你心里咯噔一下。因为你知道接下来会发生什么：
- AI 看着截图猜颜色，生成一个偏蓝的” 墨黑”，跟品牌色差了两个色阶；
- 字体随便挑，Inter、Roboto、Public Sans 混着用，标题字重 700、正文 400，全凭” 感觉”；
- 圆角一会儿 4px、一会儿 12px，按钮一会儿实心、一会儿描边；
- 你花了 3 周定的 4 级 spacing scale 在 AI 眼里只有” 大、中、小” 三个值。
更扎心的是：你已经在 /docs/design-system.md 里写了 8000 字规范，但 AI 压根没读 —— 它只看到你贴进 prompt 的那张 Figma 截图。
问题出在哪？AI 不缺设计规范，它缺一个” 机器可读、且不会被它忽略” 的设计说明书。
如果有一种文件格式，能把颜色、字体、间距、组件、Do’s and Don’ts 同时用结构化 tokens 和人类可读散文 写在一份 Markdown 里，让任何 Agent 一打开就能理解，并且能一键导出 Tailwind v4 @theme、W3C DTCG 等行业标准 —— 会怎样？
这就是 google-labs-code/design.md 想做的事。今天它以 16,829 stars、单日 504 新增登上了 GitHub Trending，背后是 Google Labs 团队亲自操刀 —— 格式已经在 alpha 阶段，并提供同名 npm CLI 工具。
二、它到底解决什么问题
一句话：给 AI 编程 Agent 一份” 持久化、结构化、能 lint、能 diff、能导出” 的设计系统宪法。
传统 AI 编程工作流里，让模型” 遵守设计规范” 只能靠这些” 笨办法”：
- 截图喂图：模型看到的是像素，不是语义。换个 hover 状态、换个分辨率就翻车。
- 粘贴 Figma 链接：模型拿到的是 read-only URL，看一眼就忘，下一次 prompt 又得重新发。
- 长篇 Markdown 规范：模型懒得读 8000 字散文，更不会在生成代码时引用具体 token。
- 手工导出 Tailwind config：维护成本高，每次设计变更都得人工同步。
design.md 选择了一条完全不同的路：把设计系统写成一个标准的 Markdown 文件，但用 YAML frontmatter 承载机器可读的 tokens，用 ## 章节承载人类可读的设计意图。再配合官方 CLI，能 lint、能 diff 前后变更、能一键导出 Tailwind v3/v4 CSS、W3C DTCG 等格式。
效果如何？官方在文档里给了一个非常直观的例子：
一个符合规范的 agent 读完之后，会自动生成” 墨黑标题 + Public Sans + 石灰背景 + 波士顿陶土橙按钮” 的落地页 —— 而你只贴了那一份 DESIGN.md 文件。
三、核心功能亮点
1. 双层结构：YAML tokens + Markdown 散文
DESIGN.md 文件由两部分组成，缺一不可：
- YAML frontmatter（规范性值）：所有 token 的” 硬数值”，比如颜色十六进制、字号 rem 值、圆角 px。
- Markdown 主体（应用上下文）：每个章节用
##标题写” 为什么这么设计”、” 什么时候用”、” 什么时候不要用”。
官方原话：
“Tokens give agents exact values. Prose tells them why those values exist and how to apply them.”
也就是说，tokens 是骨架，散文是灵魂。模型读到 #1A1C1E 知道是墨黑；读到 “Use deep ink for headlines only — never for body text” 才不会在段落里乱用。
2. 严格的章节顺序规范
DESIGN.md 规定了 8 个标准章节，出现时必须按顺序：
- Overview（别名 Brand & Style）
- Colors
- Typography
- Layout（别名 Layout & Spacing）
- Elevation & Depth
- Shapes
- Components
- Do’s and Don’ts
这套顺序不是强制的（章节可省略），但一旦出现就必须按此顺序排列 —— 这一点对 Agent 非常友好，因为它可以按位置预判下一个字段是什么，不用每次都重新解析整个文件结构。
3. 完整的 Token 类型系统
支持的 token 类型覆盖了前端设计的 90% 场景：
- Color：任何 CSS 颜色格式都行 ——hex、
rgb()、oklch()、命名色都 OK。 - Dimension：number + 单位（
px、em、rem），连负 letter-spacing-0.02em都能写。 - Token Reference：可以用
{colors.primary}这种路径引用别的 token，避免重复定义。 - Typography：对象类型，包含
fontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation—— 基本上把 OpenType 字体特性也覆盖了。
4. 组件（Component）抽象
Components 是这套规范里最像” 面向对象” 的部分。一个 component 是一个命名的 token 组，包含 backgroundColor、textColor、typography、rounded、padding、size 等子属性。
更妙的是，变体（hover、active、pressed）用独立 component 条目 + 关联命名来表达，比如 Button 和 Button:hover。这跟 Tailwind v4 的 data-attribute variants 哲学非常接近，导出时基本无损耗。
5. 容错哲学：未知内容不报错
对” 未知内容” 的处理是这套规范里最值得 AI 工程借鉴的设计：
| 场景 | 行为 |
|---|---|
| 未知章节标题 | 保留，不报错 |
| 未知颜色 token 名 | 只要值合法就接受 |
| 未知 typography token 名 | 当作合法 typography 接受 |
| 未知 component 属性 | 接受但给 warning |
| 重复章节标题 | 报错，拒绝文件 |
也就是说，“前向兼容” 做得非常激进 —— 你今天写一个新章节、明天写一个新属性，旧的 parser 都不会炸。只有” 重复” 这种真正的歧义才会被拒绝。这对 Agent 生态极其友好：模型可以自由探索新结构，而不会因为小创新就把整个流水线打挂。
6. 官方 CLI：lint /diff/export /spec
仓库同步发布了一个 npm 包：@google/design.md（命令行别名 designmd）。提供 4 个核心命令：
lint <file>：校验文件结构，错误退出码 1，正确退出码 0。可以塞进 CI。diff <before> <after>：对比两份 DESIGN.md，输出 token 级别的变更。退出码 1 表示 “after” 比 “before” 有更多 error/warning—— 可以直接当 PR 检查用。export <file> --format=...：导出成 4 种格式：json-tailwind（Tailwind v3theme.extend对象）css-tailwind（Tailwind v4@theme { ... }块，含 CSS 自定义属性）tailwind（json-tailwind的别名）dtcg（W3C Design Tokens Format Module）
spec：把格式规范本身 dump 出来，方便塞进 agent 的 system prompt 当作上下文。
四、实战示例：5 分钟搭一个品牌落地页
假设你是某 SaaS 公司的前端工程师，品牌色是” 墨黑 + 石灰 + 波士顿陶土橙”，主字体 Public Sans。先写一份 DESIGN.md：
1 | --- |
接下来用官方 CLI 一行命令导出 Tailwind v4：
1 | npx -p @google/design.md designmd export brand.DESIGN.md --format=css-tailwind |
输出大致是：
1 | @theme { |
最后把这个文件丢给 Claude Code：
“读一下 ./brand.DESIGN.md 和 ./tailwind.css，按规范给我做一个夏季活动落地页。”
你会得到一份字体、颜色、圆距、按钮全部对齐品牌的 React/Tailwind 代码 —— 而不是又一份”AI 自己挑的颜色”。
五、适用场景和限制
适用场景
- 品牌官网、营销页：需要严格遵循 VI 的页面，AI 一稿就能交。
- 设计系统迁移：从 Figma Tokens、W3C DTCG 迁到 Tailwind v4，可以用
export反向生成。 - PR/CI 校验：把
lint和diff塞进 GitHub Actions，PR 里自动评论” 你删了 3 个 token、新增 1 个未授权颜色”。 - 多 Agent 协作：把
spec命令输出塞进 system prompt，让任何 Agent（不只是 Claude Code）都能理解格式。
限制与坑
- 状态：alpha：40 个 commit，规范仍在演化，生产环境建议先小范围试点。
- Windows 坑：
npm install会因为@触发 Markdown 文件关联，必须用npx -p @google/design.md designmd间接调用。 npm error ENOVERSIONS：如果团队用了私有 npm 镜像，需要检查.npmrc里是否覆盖了@google:registry，正确注册表必须是https://registry.npmjs.org/。- 变体表达仍然偏弱：hover、active、pressed 还得手写多份 component，没原生
state字段，期待后续版本。 - 不是设计工具：DESIGN.md 不替代 Figma，它只负责” 机器可读的那部分”，视觉探索还得在 Figma 里完成。
六、总结
design.md 解决了一个被忽视很久的问题：设计系统和 AI Agent 之间缺一座桥。
它没有发明新概念 ——tokens、组件、章节这些老熟人都有；但它做了一个非常聪明的妥协：
- 机器要的硬数值放进 YAML frontmatter，能 lint、能 diff、能导出。
- 人写的设计意图留在 Markdown 散文里，告诉模型” 为什么” 和” 什么时候不要用”。
- 未知内容不报错的容错哲学，让 Agent 生态可以自由探索新结构。
对于一个每天都在让 AI 生成 UI 的团队来说，这意味着 —— 你不用再每次 prompt 都重复品牌规范了。把 DESIGN.md 放进仓库根目录，剩下的交给 CLI 和 Agent。
如果你正被”AI 总是生成错颜色、错字体、错间距” 折磨，今天就花 30 分钟写一份 DESIGN.md，然后跑一行 npx -p @google/design.md designmd export --format=css-tailwind。你会感谢自己的。
项目地址：https://github.com/google-labs-code/design.md
CLI 包：@google/design.md（别名 designmd）
License：Apache 2.0
Stars：16,829（截至撰文日）