Google DESIGN.md：让 AI Agent 理解你的设计系统

Google DESIGN.md：让 AI Agent 理解你的设计系统

设计系统不再只属于设计师，AI 编码 Agent 也需要"读懂"设计。Google Labs 开源的 DESIGN.md 规范，正是解决这个问题的关键尝试。

引言

你是否遇到过这样的场景：

• 用 AI 生成的 UI，每次风格都不一样
• Agent 不知道为什么品牌色是某个特定的值
• 跨项目的 UI 无法保持一致性
• 设计师的设计稿，Agent 无法理解其中的设计决策

问题的根源是：传统设计系统分散在多个地方——CSS 文件、Figma 组件库、设计文档、品牌指南。AI Agent 没有一个统一的入口来"读懂"整个设计系统。

Google Labs 的解决方案是：DESIGN.md——一个让 AI Agent 理解设计系统的标准文件格式。

什么是 DESIGN.md？

核心定位：一个文件，同时满足人类和 AI 的需求。

DESIGN.md 是 Google Labs 开源的设计系统规范格式（Apache-2.0 许可），专门为 AI 编码 Agent 设计。它把设计系统的所有信息整合到一个 Markdown 文件：

┌─────────────────────────────────────────────────┐ │ DESIGN.md │ ├─────────────────────────────────────────────────┤ │ YAML Front Matter（机器可读） │ │ - 设计 tokens 的精确数值 │ │ - 颜色、字体、间距、组件属性 │ ├─────────────────────────────────────────────────┤ │ Markdown Body（人类可读） │ │ - 设计 rationale（为什么这样设计） │ │ - 使用场景和注意事项 │ │ - Do's and Don'ts │ └─────────────────────────────────────────────────┘

GitHub 仓库：https://github.com/google-labs-code/design.md
Stars：8,697（截至 2026-04-27）
CLI：npx @google/design.md

文件结构详解

YAML Front Matter：设计 Tokens

YAML 部分是机器可读的精确数值，定义了整个设计系统的"骨架"：

---version:alphaname:Heritagedescription:Architectural minimalism meets journalistic gravitas.colors:primary:"#1A1C1E"# 深墨色，用于标题和核心文本secondary:"#6C7278"# 中灰，用于辅助文本tertiary:"#B8422E"# Boston Clay，品牌强调色neutral:"#F7F5F2"# 浅米色，背景和卡片typography:h1:fontFamily:Public SansfontSize:3remfontWeight:700lineHeight:1.1letterSpacing:"-0.02em"body-md:fontFamily:Public SansfontSize:1remfontWeight:400lineHeight:1.5rounded:sm:4pxmd:8pxlg:16pxspacing:sm:8pxmd:16pxlg:24pxcomponents:button-primary:backgroundColor:"{colors.tertiary}"textColor:"#FFFFFF"rounded:"{rounded.sm}"padding:12pxbutton-primary-hover:backgroundColor:"{colors.primary}"---

关键特性：

• Token 引用：用{colors.primary}引用其他 token，保持单一数据源
• 组件定义：直接定义组件的样式属性
• 变体分离：button-primary-hover是独立的 key，不是嵌套结构

Markdown Body：设计 Rationale

Markdown 部分是人类可读的设计理由，告诉 AI Agent为什么要这样设计：

## Overview Architectural Minimalism meets Journalistic Gravitas. This design system draws from print editorial heritage while embracing digital scalability. ## Colors - **Primary (#1A1C1E):** Deep ink for headlines and core text. Creates visual weight without overwhelming. - **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction. Used only for primary actions, never for decoration. ## Typography Public Sans for everything except small all-caps labels. The geometric sans-serif maintains clarity at all sizes while subtly referencing newspaper mastheads. ## Components `button-primary` is the only high-emphasis action on a page. Use sparingly — when everything is important, nothing is. ## Do's and Don'ts ✅ Do: Use tertiary color only for primary actions ✅ Do: Maintain generous whitespace between sections ❌ Don't: Apply rounded corners to inputs (keep them sharp) ❌ Don't: Mix tertiary with other accent colors

Canonical Section Order

DESIGN.md 规范要求章节必须按固定顺序排列：

注意：重复的章节标题会导致 lint 失败。

CLI 工具：验证、对比、导出

1. Lint（验证）

npx @google/design.md lint DESIGN.md

Lint 检查 7 条规则：

WCAG 检查的价值：这是 lint 最实用的功能——自动检查无障碍合规。

2. Diff（对比）

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

对比两个版本的 DESIGN.md，检测是否存在回归（设计变化导致的问题）。返回 exit 1 表示有回归。

3. Export（导出）

# 导出为 Tailwind theme JSONnpx @google/design.mdexport--formattailwind DESIGN.md>tailwind.theme.json# 导出为 W3C DTCG JSON（Design Tokens Format Module）npx @google/design.mdexport--formatdtcg DESIGN.md>tokens.json

导出格式：

• Tailwind：直接用于 Tailwind CSS 配置
• DTCG：W3C 标准格式，可被其他设计工具（Figma、Style Dictionary）导入

Token 类型规范

组件属性白名单：backgroundColor,textColor,typography,rounded,padding,size,height,width

常见 Pitfalls

1. Hex 颜色必须引号

# ❌ 错误：YAML 会把 # 当成注释colors:primary:#1A1C1E# ✅ 正确colors:primary:"#1A1C1E"

2. 负值尺寸需要引号

# ❌ 错误：YAML 会把 -0.02em 解析成奇怪的东西letterSpacing:-0.02em# ✅ 正确letterSpacing:"-0.02em"

3. 变体不嵌套

# ❌ 错误：嵌套变体components:button-primary:backgroundColor:"{colors.tertiary}"hover:backgroundColor:"{colors.primary}"# ✅ 正确：变体是独立的 keycomponents:button-primary:backgroundColor:"{colors.tertiary}"button-primary-hover:backgroundColor:"{colors.primary}"

4. Token 引用必须完整路径

# ❌ 错误：缺少路径backgroundColor:"{primary}"# ✅ 正确：完整路径backgroundColor:"{colors.primary}"

生态系统

DESIGN.md 规范正在快速发展，已经出现多个周边项目：

为什么 DESIGN.md 重要？

1. 解决 AI 生成 UI 的不一致问题

传统方式：Agent 需要从多个分散的来源（CSS、文档、截图）拼凑设计信息，每次生成结果都不一致。

DESIGN.md：Agent 有一个完整、结构化的设计系统文件，每次生成都能遵循相同的规范。

2. 让 Agent 理解设计决策

不只是知道"品牌色是 #B8422E"，还知道"这是 Boston Clay，唯一用于交互的颜色，从不用于装饰"。

这种rationale 层的信息，让 Agent 能做出更符合设计意图的判断。

3. 设计系统的可验证性

通过 CLI 的 lint 和 diff，设计系统变得可验证、可追踪：

• WCAG 无障碍合规自动检查
• 版本对比检测回归
• 导出格式保证跨工具兼容

4. 实现 “Design as Token”

这正是 “All as Token” 思维在设计领域的落地：

• 设计系统不再是分散的文档和组件库
• 而是一个 AI Agent 可读取、可理解、可验证的单一文件
• 设计 tokens 变成了可被 Agent 直接引用的精确值

实践建议

新项目：从 DESIGN.md 开始

1. 在项目根目录创建DESIGN.md
2. 定义核心 tokens（颜色、字体、间距）
3. 用 lint 验证格式和 WCAG 合规
4. 用 export 导出 Tailwind/DTCG JSON
5. 在 AI Agent 提示中引用这个文件

现有项目：逆向提取

1. 使用design-md-firefox扩展从现有网站提取样式
2. 或手动整理现有设计文档，转换为 DESIGN.md 格式
3. 用 diff 对比版本，确保无回归

团队协作

• 设计师：维护 DESIGN.md 的 rationale 部分
• 开发者：维护 tokens 的精确数值
• AI Agent：生成 UI 时引用 DESIGN.md
• CI/CD：lint 检查无障碍合规

结语

DESIGN.md 的出现，标志着设计系统正在从"设计师专用工具"向"AI Agent 可理解格式"演进。

它解决了一个核心矛盾：

• 设计师需要丰富的设计理由（人类可读）
• AI Agent 需要精确的设计数值（机器可读）

DESIGN.md 用一个文件同时满足两者，让 AI Agent 不只是"生成 UI"，而是"理解设计系统"。

这正是 “Design as Token” 的实践——设计系统变成 AI 可读取、可验证、可复用的单一文件。

当万物都变成 token，设计也不例外。

附录：资源链接

数据来源：GitHub google-labs-code/design.md、Hermes design-md skill、2026-04-27