AI 编码助手终于「懂审美」了:Google DESIGN.md 让设计系统对 可读

DESIGN.md · 设计系统 · AI Agent · 视觉规范 · Google Labs —— Google 实验室推出的 DESIGN.md 格式，让 AI 编程助手能「看懂」并持续 遵循你团队的设计语言，彻底告别「每次生成都换一套 UI」的割裂体验。

AI 编码助手为什么总「不懂设计」

用 Cursor、Copilot 或 Claude 写前端时，你一定遇到过这种场景： 让它画一个按钮——它用蓝色圆角；关掉对话再开，同样的需求——它换成 绿色扁平。问题出在 AI 缺少对设计系统的「记忆」。

传统设计交付物（Figma 链接、静态设计稿、设计规范 PDF）对 AI 「不可读」。即便你在 prompt 里贴了色值，模型也只把这当作一次性 上下文，关闭对话即遗忘。一个团队几十个组件、数百个 token， 靠复制粘贴到每轮对话里根本不可行。

DESIGN.md 用最朴素的方式解决了这个矛盾：把设计系统写成 AI 和人都 能读的文件。YAML front matter 给机器精确值，Markdown 正文给 AI 设计意图与判断逻辑——你写的不是配置文件，是 AI 的「设计直觉」。

三步上手：从零定义你的设计系统

项目提供了两种接入方式：纯格式或配合 CLI 工具链。推荐从CLI开始。

第一步：编写 DESIGN.md

在项目根目录创建一个 DESIGN.md 文件。前面 YAML 部分定义精确的 设计 token（颜色、字体、间距、圆角、组件），后面 Markdown 正文 描述设计意图与使用约束。

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

正文部分写设计考量——为什么用这个颜色、什么场景用哪个 token。

## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary** – Deep ink for headlines and core text.
- **Tertiary** – "Boston Clay", the sole driver for interaction.

「Boston Clay」这种具体指代，比「Modern, clean, premium」 包含的信息量大得多。模型读到它，能联想到真实的材质与色调。 CLI 的 lint 命令会校验 token 引用断裂和 WCAG 对比度：

npx @google/design.md lint DESIGN.md

输出为结构化 JSON，错误、警告、信息分别计数。

第二步：差异对比与持续维护

设计迭代后，用 diff 命令检测 token 级别的增删改：

npx @google/design.md diff DESIGN.md DESIGN-v2.md

返回 JSON 报告每个 colors／typography 键的 added、removed、 modified 状态。diff 还会检测回归——如果新版增加了错误或警告， exit code 为 1，可在 CI 中阻止合入。

第三步：导出到前端框架

git clone --depth 1 https://github.com/google-labs-code/design.md 要把设计 token 变成 CSS 或者 Tailwind 配置，跑 export 命令：

npx @google/design.md export --format json-tailwind DESIGN.md

# Tailwind v4 CSS @theme 块
npx @google/design.md export --format css-tailwind DESIGN.md

# 标准 DTCG tokens.json
npx @google/design.md export --format dtcg DESIGN.md

这套流程打通了「设计定义 -> token 校验 -> 框架集成」的闭环。

常见误区

不要试图用 token 穷举所有场景——这是 DESIGN.md 与 Tailwind 配置的 本质区别。DESIGN.md 靠 prose（散文正文）传递判断力，token 只是 参照锚点。如果某个组件的圆角在不同语境下不同，在 Do's and Don'ts 里写意图比硬塞新 token 更有效。

核心创新：用 Prose 驱动设计

DESIGN.md 的架构分两层：

YAML 层（机器可读）：定义 colors、typography、spacing、 rounded、components 等 token。组件属性支持引用语法 {colors.primary}，形成 token 依赖图。lint 规则中的 broken-ref 专门检查引用是否指向已定义的 token。

Markdown 层（AI 可读）：8 个固定顺序的 ## 段落，从 Overview 到 Do's and Don'ts。正文可以引用 token 名（如 {colors.primary}），但这不是渲染指令，而是语意参照——让 model 理解使用场景，而非机械套用。

真正的创新在于「负约束自动推导」

PHILOSOPHY.md 中讲了一个关键洞察：当你说「这是一个 1970 年代 大学课堂讲义风格的 UI」，AI 自动就知道它不应该发光、不该有渐变、 不该用大字号衬线装饰。具体的参照对象（a specific reference） 自动携带了它的约束集，这是形容词堆叠做不到的。

CLI 的 9 条 lint 规则集中在 token 健康和结构合规上，刻意不介入 「设计好坏」的判断。规则如 missing-primary（缺少主色警告）、 contrast-ratio（WCAG AA 对比度检查）、orphaned-tokens （定义了但未被任何组件引用的 token）——都是机械可验证的。 真正需要审美判断的事，交给了 prose。

另一个巧妙设计：未知内容宽容处理。出现 spec 未定义的 section （如 ## Motion）时，linter 不会报错而是保留它；出现未知 token 名只要值合法就接受。这使格式可以自然生长——每个团队可以注入自己 的特有 token（动画、图标、语音领域的时间常量），而不需要等 spec 更新。linter 对「未知组件属性」仅抛 warning，不阻止使用。

落地场景与发展空间

场景一：多 Agent 协作的前端团队

如果你的项目同时使用 Cursor、Copilot 和自定义 agent，放在项目 根目录的 DESIGN.md 像一个「共享设计大脑」——所有 agent 读同一份 文档，生成的 UI 风格一致。配合 CI lint 步骤，每次 PR 都会校验 token 引用和对比度。

场景二：Design Token 治理枢纽

设计团队在 Figma 里维护 token，前端团队需要同步到 Tailwind / 自定义组件库。DESIGN.md 可以作为中间格式：Figma -> DTCG -> DESIGN.md -> Tailwind。prose 部分被 AI 理解，token 部分被工具链 消费，一条文档服务两边。

更广阔的想象

Google Labs 把这个项目定位为「alpha」，意味着核心结构还在演进。 值得关注的方向包括：

DESIGN.md 解决的不是「怎么写 CSS」的问题，而是「怎么让 AI 理解 你团队的审美」。19K+ star 的速度说明，这不是一个小众需求。

对前端团队而言，现在就可以花 30 分钟写一个 DESIGN.md 放到项目 根目录——下一轮 AI 生成的 UI，会比「Modern, clean, premium」 具体得多。