Google 的 DESIGN.md 火到 14.9K Star：AI 写页面最缺的，可能不是更强模型

用 AI 连续生成五个页面，很容易得到五套“各自都还行”的设计。

第一个页面用了深蓝和圆角卡片，第二个页面自己换成渐变紫，第三个页面按钮高度变了，第四个页面把标题字体换成另一套，第五个页面又重新解释了一遍品牌风格。

这不完全是模型能力问题。

如果每次会话只收到一句“保持专业、简洁、有科技感”，Agent 实际上没有一个稳定、精确、可以跨工具传递的设计事实源。

Google Labs 开源的 DESIGN.md，试图用一个普通 Markdown 文件解决这件事。官方仓库目前约 14.9K Star，而且它并不只是写给人看的设计说明，而是一份同时给人、Agent 和构建工具使用的设计契约。

一份文件，为什么要分成两层

DESIGN.md由两部分组成。

第一层是 YAML Frontmatter，保存机器可读的精确 Token：颜色、字体、字号、行高、间距、圆角和组件属性。

第二层是 Markdown 正文，解释品牌气质、布局原则、组件使用方式以及 Do's and Don'ts。

一个最小示例大概是这样：

---
version: alpha
name: Incident Console
colors:
  primary: "#172033"
  accent: "#D94A2B"
  surface: "#F7F3EA"
  on-primary: "#FFFFFF"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 700
    lineHeight: 1.1
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.accent}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.sm}"
---

## Overview

面向生产事故处理的高密度控制台。视觉应冷静、明确，
避免娱乐化渐变和大面积装饰。

## Do's and Don'ts

- 关键告警只使用 accent 色。
- 不使用玻璃拟态，不让装饰干扰状态识别。

Token 告诉 Agent“具体是多少”，正文告诉它“为什么这样做”和“遇到没写过的场景如何取舍”。

如果只有 Token，Agent 可能机械地套颜色，却不知道什么时候应该克制；如果只有散文描述，模型又会在每次生成时重新解释“专业”和“简洁”。

它解决的不是第一版，而是第五版

第一版页面只需要一名 Agent 时，自由描述通常也能工作。

真正的问题出现在多人、多 Agent、多仓库或多轮迭代：

• 一个 Agent 负责抽取现有网站风格；
• 一个 Agent 负责生成组件；
• 另一个 Agent 负责新页面；
• 设计师修改品牌色；
• QA 检查响应式、对比度和视觉回归；
• Tailwind、Figma Token 或其他工具还要消费同一套值。

如果没有中间契约，每个环节都会重新翻译一次设计意图，偏差会逐轮累积。

更合理的工作流是：先把现有风格整理为 DESIGN.md，再让实现、检查和导出都围绕这份文件进行。

品牌真的改变，就修改契约；页面没有遵守契约，就修改实现。不要让两种变化混在一起。

官方 CLI 已经把它变成了可执行规范

DESIGN.md不只是一个文件命名约定。官方提供了 @google/design.mdCLI：

npm install @google/design.md

npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

lint可以检查结构、断裂的 Token 引用、重复章节和对比度等问题，并输出结构化 JSON。

diff可以比较两个版本中新增、删除和修改的颜色、字体、间距与正文规则，用于判断设计契约是否发生回归。

export可以输出 Tailwind v3 JSON、Tailwind v4 CSS 主题或 W3C DTCG Token，让 Markdown 不停留在文档层。

把它放进 UI 测试流程，应该怎么做

以一个 AI 生成的后台控制台为例，我会把门禁分成三层。

第一层：契约本身是否有效

• YAML 能否解析；
• Token 引用是否存在；
• 颜色格式和尺寸单位是否合法；
• 章节是否重复或顺序错误；
• 关键前景色和背景色对比度是否满足要求。

这层适合用 lint在 CI 中自动完成。

第二层：实现是否消费正确 Token

• CSS 或 Tailwind 主题是否由指定版本的 DESIGN.md导出；
• 组件有没有绕开 Token 写硬编码颜色；
• Hover、Active、Disabled、Focus 状态是否都有定义；
• 新页面是否复用了组件，而不是重新复制一套样式。

这层需要静态扫描、组件测试和代码评审配合。

第三层：真实画面是否正确

• 文字是否溢出；
• 移动端是否裁切；
• 弹窗、下拉框和 Tooltip 是否被遮挡；
• 长中文、异常状态和空数据是否破坏布局；
• 浏览器实际渲染是否与基线截图一致。

这层仍然需要浏览器、视觉回归和人工判断。DESIGN.md能证明 Token 正确，不能证明一个复杂页面没有重叠和截断。

一份设计文件如何流向代码和测试

建议把以下产物绑定到同一个版本：

• DESIGN.md：规范源文件；
• theme.css或 tailwind.theme.json：构建使用的导出物；
• design-lint.json：结构、引用与对比度检查结果；
• 组件 Story 或演示页：覆盖主要状态；
• 桌面与移动端基线截图；
• 视觉回归报告。

这样出现差异时，可以区分三种情况：

1. 契约变化：设计师主动修改了 Token 或规则。
2. 导出变化：工具升级导致生成结果不同。
3. 实现漂移：页面绕过契约，或者布局在真实数据下失效。

更适合 Agent 的地方，是它允许未知内容存在

规范对扩展采取相对宽容的策略：未知章节可以保留，未知颜色 Token 名只要值合法就能接受，未知组件属性会产生 Warning，而断裂引用和重复章节则会报错。

这对 Agent 很重要。

过于严格的 Schema 会逼着不同团队把所有设计语义压缩成少量固定字段；过于宽松的 Markdown 又无法自动检查。DESIGN.md在精确 Token 和开放正文之间做了折中。

但这个折中也意味着使用方必须定义自己的质量阈值：Warning 是否阻断合并、哪些章节强制存在、组件状态必须覆盖到什么程度，官方格式不会替团队做完所有治理决定。

现在要不要直接用

可以试，但不应该把它当成已经稳定的行业标准。

官方明确标注当前格式仍处于 alpha，Schema、CLI 和导出行为都可能继续变化。更稳妥的做法是：

1. 先在一个新页面或内部工具中试点。
2. 固定 CLI 版本，不使用浮动最新版。
3. 把 DESIGN.md、导出物和截图基线一起纳入代码评审。
4. 为升级准备迁移检查，而不是自动覆盖旧文件。
5. 保留现有设计系统和组件库，不要让 Markdown 取代已经成熟的工程资产。

DESIGN.md最有价值的地方，不是又创造了一种文档格式。

它把过去只存在于设计师脑中、Figma 页面和零散 Prompt 里的视觉决策，变成了 Agent 能读取、工具能验证、代码能消费、QA 能回归的仓库资产。

更强的模型可以让第一版更漂亮，但只有稳定的契约，才能让第五版仍然像同一个产品。

参考资料

• Google Labs DESIGN.md 官方仓库
• DESIGN.md 完整格式规范
• W3C Design Tokens Community Group