DESIGN.md：让编码 Agent 读懂设计系统的一份格式规范

生成式编程里，编码 Agent 写 UI 代码时最容易翻车的地方，是它猜不准你的设计风格——颜色、字号、圆角、间距全靠临场发挥。DESIGN.md 就是 Google Labs 给出的解法：一份文件格式规范，把设计系统写成「机器能读 + 人能看懂」的两层结构，让 Agent 拿到确定的设计值，而不是去猜。项目仓库 github.com/google-labs-code/design.md，Star 约 27.5k、Fork 2.3k，主语言 TypeScript（占 96.4%），Apache-2.0 协议，最新版本 0.4.0 发布于 2026 年 7 月 27 日。

它解决的问题

编码 Agent 生成界面时没有关于设计系统的「记忆」：它不知道你的品牌主色是什么、标题用什么字体、按钮圆角是几像素。DESIGN.md 用一个文件补上这块短板——把设计系统以结构化、可持久维护的形式交给 Agent。读了这个文件的 Agent，能直接生成带深墨色标题、暖石灰底色、「Boston Clay」行动按钮的界面，而不是一套随意猜出来的配色。

一个文件，两层结构

DESIGN.md 文件由两层组成：

  • YAML front matter：文件开头、由 --- 围栏包裹的部分，是机器可读的设计 token，给出精确数值。
  • Markdown 正文：人类可读的设计理由，解释这些数值是什么、怎么用。

token 是规范里的「标准答案」，正文是围绕这些答案的说明。

Token：给机器的精确值

token 按类型分为几类：颜色（Color）是任意 CSS 颜色值；尺寸（Dimension）是数字加单位，如 48px；token 引用（Token Reference）用 {colors.primary} 这类路径指向其它 token；排版（Typography）是含 fontFamily、fontSize、lineHeight 等字段的对象。

一个典型示例把主题色拆成四档：Primary #1A1C1E（深墨色，用于标题与正文）、Secondary #6C7278（石板灰，用于边框与说明文字）、Tertiary #B8422E（「Boston Clay」，交互的唯一强调色）、Neutral #F7F5F2（暖石灰底色，比纯白更柔和）。

命令行工具

项目附带 CLI 包 @google/design.md，可通过 npx 调用，四个主要命令：

  • lint：校验文件结构，抓断裂的 token 引用，检查 WCAG 对比度，输出结构化 JSON。
  • diff：对比两个版本的设计系统，报告 token 与说明文字层面的差异。
  • export：把 token 导出为 Tailwind v3 配置、Tailwind v4 主题 CSS，或 W3C DTCG 的 tokens.json。
  • spec：输出格式规范全文，可加 --rules 附带规则表。

安装用 npm install @google/design.md，或直接 npx @google/design.md lint DESIGN.md。在 Windows/PowerShell 下有个坑：npx 的包名后缀 .md 会与系统的 Markdown 文件关联产生冲突，官方建议改用别名 designmd，即 npx -p @google/design.md designmd lint DESIGN.md。

十一项校验规则

lint 内部跑 11 条规则，每条有固定的严重级别。例如 broken-ref（error）抓引用不到任何 token 的路径；contrast-ratio（warning）抓组件前后景色对比度低于 WCAG AA 门槛（4.5:1）的组合；unknown-key（warning）提示某个顶层 YAML 键像是已知 schema 键的拼写错误。

上手方式

新建一个 DESIGN.md，在 YAML front matter 里定义颜色、字体、圆角、间距，再用 Markdown 正文说明用法，然后跑 npx @google/design.md lint DESIGN.md 校验。需要注意：规范目前处于 alpha 版本，spec、token schema 和 CLI 都在持续演进，接口可能随版本调整。

几个边界行为

规范对未知内容的处理是「宽容 + 告警」：未知的 section 标题会保留、不报错；未知的顶层 key 若值像 token（如十六进制色值、字体系列）则告警，否则静默；但重复的 section 标题会直接报错并拒绝整个文件。此外，项目明确声明不参与 Google 的开源软件漏洞赏金计划。

如果你正在用 Agent 生成前端代码，给项目根目录放一个 DESIGN.md，让 Agent 拿到确定的设计值而不是猜——这就是这套规范带来的直接收益。