Google DESIGN.md深度解析：5步让AI精准还原你的设计系统

一、引言：AI写UI为什么总是"跑偏"？

如果你用过AI编码助手生成前端界面，一定经历过这种挫败感：

• 第一屏的主色是 `#2563EB`，翻到第三屏变成了 `#3B82F6`；
• 按钮圆角在首页是 8px，到设置页成了 4px；
• 同一个组件，Claude Code 生成的版本和 Cursor 生成的版本，字体大小差了两个层级。

核心问题不在于AI能力不够，而在于"设计意图"没有被持久化存储。每次对话，AI都从零开始"猜测"你的设计规范——上下文窗口一刷新，视觉一致性就归零。

2026年4月，Google Labs开源了DESIGN.md规范——用一份Markdown文件解决了这个问题。上线不到两月，GitHub上已收获15K+ Star，配套生态（CLI工具、Chrome插件、社区模板库）初具规模。

本文将带你深入理解DESIGN.md的双层架构、CLI工具链与实战模板。

二、DESIGN.md是什么？

DESIGN.md是一份放在项目根目录的Markdown文件，但它不是普通的文档——它同时面向人类阅读和机器解析，由两层结构组成：

| 层级 | 格式 | 阅读者 | 承载内容 |

|------|------|--------|----------|

|Token层| YAML Front Matter | AI Agent / CLI工具 | 精确的设计标记值（色值、字号、间距、圆角） |

|Prose层| Markdown正文 | 人类设计师 / AI推理 | 设计意图、品牌调性、使用规范、Dos & Don'ts |

这种设计的巧妙之处在于：YAML是"事实"（机器校验用），Prose是"理由"（AI推理用）——两者互补，缺一不可。

设计哲学

DESIGN.md的核心理念来自Google Stitch团队三个洞察：

• **AI不需要Figma文件。** 它需要的是结构化的变量值（色板、类型阶梯、间距刻度）加上上下文解释。
• **设计规范应该是"可版本控制的"。** 就像代码一样，diff DESIGN.md应该能清晰看出token级别的回归。
• **工具无关性。** DESIGN.md不应该绑定任何特定AI编码助手——它应该是可移植的。

三、Token层：YAML Front Matter深度解析

这是DESIGN.md的机器可解析层。AI直接读取这些值来生成UI，CLI工具用它做校验和对比。当前规范定义了以下核心Token类别：

# DESIGN.md - YAML Front Matter 规范（v0.2.0） version: alpha name: Heritage # ============ 1. 颜色系统 ============ colors: primary: "#1A1C1E" secondary: "#2D3135" tertiary: "#B8422E" # 品牌强调色 neutral: "#F7F5F2" # 页面底色 text: primary: "#1A1C1E" secondary: "#5F6368" inverse: "#FFFFFF" # ============ 2. 字体系统 ============ typography: fontFamily: primary: "Public Sans, sans-serif" mono: "JetBrains Mono, monospace" scale: h1: fontSize: 3rem fontWeight: 700 lineHeight: 1.2 h2: fontSize: 2rem fontWeight: 600 lineHeight: 1.3 body: fontSize: 1rem fontWeight: 400 lineHeight: 1.6 caption: fontSize: 0.75rem fontWeight: 400 lineHeight: 1.4 # ============ 3. 间距系统 ============ spacing: unit: 4 # 基础间距单位(px) scale: [0, 4, 8, 12, 16, 24, 32, 48, 64] # ============ 4. 圆角系统 ============ rounded: none: "0" sm: "4px" md: "8px" lg: "12px" full: "9999px" # ============ 5. 阴影系统 ============ elevation: sm: "0 1px 2px rgba(0,0,0,0.05)" md: "0 4px 6px rgba(0,0,0,0.07)" lg: "0 10px 25px rgba(0,0,0,0.1)" # ============ 6. 组件Token ============ components: button-primary: backgroundColor: "{colors.tertiary}" textColor: "#FFFFFF" rounded: "{rounded.md}" paddingX: "{spacing.24px}" paddingY: "{spacing.12px}" fontWeight: 600 button-secondary: backgroundColor: "transparent" textColor: "{colors.primary}" borderColor: "{colors.primary}" rounded: "{rounded.md}" card: backgroundColor: "#FFFFFF" rounded: "{rounded.lg}" shadow: "{elevation.md}" padding: "{spacing.24px}" input: backgroundColor: "#FFFFFF" borderColor: "{colors.secondary}" rounded: "{rounded.sm}" paddingX: "{spacing.16px}" paddingY: "{spacing.8px}"

关键特性——Token引用：注意组件定义中的{colors.tertiary}语法。这是一种惰性引用机制，意味着修改一处色值，所有引用它的组件自动跟随——与CSS变量的思路一致，但在Markdown层面实现。

四、Prose层：8大规范章节

YAML给了AI精确的数值，但"精确"不等于"正确"。AI还需要理解什么时候用哪个值、为什么这么选、有哪些禁忌。这就是Prose层的作用。

DESIGN.md规范要求正文必须按以下固定顺序组织8个章节（lint工具会校验顺序）：

1. Overview (品牌概览与风格基调) 2. Colors (颜色使用规则与语义) 3. Typography (字体层级与可读性指南) 4. Layout & Spacing (布局原则与间距规则) 5. Elevation & Depth (阴影层级与视觉深度) 6. Shapes (圆角、边框与图形语言) 7. Components (组件使用规范) 8. Do's and Don'ts (正反示例)

示例：Prose层的写法规格

## Colors ### Primary Palette - **Primary (`#1A1C1E`)**: 正文、主按钮文字、图标默认色。 使用场景：所有主要文字内容、导航栏底色。 - **Tertiary (`#B8422E`)**: 品牌强调色。仅用于主CTA按钮、链接悬停态、 关键状态指示器。**禁止**用于大面积背景或非交互元素， 避免视觉过载。 ### Usage Rules - 页面底色始终使用 `neutral`（#F7F5F2）， 卡片使用纯白 `#FFFFFF` 以形成层次对比。 - 文字与背景的对比度必须满足 WCAG AA 标准（正文≥4.5:1， 大文字≥3:1）。 --- ## Do's and Don'ts ### ✅ Do - 所有主CTA按钮使用 Tertiary 色 + 白色文字 - 卡片统一使用 `lg` 圆角 + `md` 阴影 ### ❌ Don't - 不要在同一页面混合使用 Primary 和 Tertiary 作为按钮主色 - 不要对正文使用小于 `body` 的字号（移动端除外）

这种"数值 + 语义规则"的双层结构，让AI在生成UI时同时拥有"图纸"和"施工规范"。

五、CLI工具链：不止是Lint

Google提供了npm包@google/design.md，提供四大核心命令。我们来看可运行示例：

1. 安装与校验

# 全局安装CLI工具 npm install -g @google/design.md # 校验DESIGN.md的结构完整性、Token引用正确性和WCAG对比度 npx @google/design.md lint DESIGN.md

Lint阶段会执行7条校验规则：

• **结构完整性**：8个Prose章节是否按规范顺序排列
• **Token引用合法性**：`{colors.xxx}` 引用是否指向真实存在的Token
• **色值格式**：是否使用合法的HEX值
• **WCAG AA对比度**：正文文字与背景对比度是否≥4.5:1
• **类型阶梯连续性**：字号是否形成合理梯度（h1 > h2 > body > caption）
• **间距单位一致性**：所有spacing值是否为基础单位的整数倍
• **版本字段**：version字段是否存在且为合法值

2. Token级回归对比

# 对比两个版本的DESIGN.md，输出Token级别的变更差异 npx @google/design.md diff DESIGN.md DESIGN.v2.md

输出示例：

colors.primary: "#1A1C1E" → "#0D0E0F" [BREAKING] colors.tertiary: "#B8422E" → "#C94A2F" [PATCH] typography.h1.fontSize: 3rem → 3.25rem [MINOR]

这让你可以在CI中自动检测设计系统的Breaking Change——和代码语义化版本管理完全一致的思路。

3. 多格式导出

# 导出为Tailwind CSS v4 @theme配置 npx @google/design.md export DESIGN.md --format tailwind-v4 # 导出为CSS自定义属性（CSS Variables） npx @google/design.md export DESIGN.md --format css-properties # 导出为W3C DTCG标准JSON（Design Tokens Community Group） npx @google/design.md export DESIGN.md --format dtcg-json

以Tailwind v4导出为例，输出如下：

/* 自动生成自 DESIGN.md — 请勿手动编辑 */ @theme { --color-primary: #1A1C1E; --color-tertiary: #B8422E; --color-neutral: #F7F5F2; --font-family-primary: "Public Sans", sans-serif; --font-family-mono: "JetBrains Mono", monospace; --radius-sm: 4px; --radius-md: 8px; --radius-lg: 12px; --spacing-unit: 0.25rem; }

这意味着一份DESIGN.md = Tailwind配置 + CSS变量 + 设计文档，真正实现了"单一事实来源"。

4. 规范参考输出

# 输出完整的格式规范，可直接喂给AI Agent作为prompt上下文 npx @google/design.md spec

六、AI编码三剑客：AGENTS.md / SKILL.md / DESIGN.md

DESIGN.md不是孤立存在的。2025-2026年，AI编码工具生态逐步形成了一套三层指令分工体系：

┌──────────────────────────────────────┐ │ 项目根目录 │ ├────────────┬────────────┬─────────────┤ │ AGENTS.md │ SKILL.md │ DESIGN.md │ │ (行为层) │ (任务层) │ (视觉层) │ ├────────────┼────────────┼─────────────┤ │ 角色与约束 │ 可复用技能 │ 设计系统 │ │ 代码风格 │ 领域知识 │ 视觉Token │ │ 禁止事项 │ 工作流 │ 组件规范 │ │ 项目上下文 │ 工具配置 │ 品牌调性 │ └────────────┴────────────┴─────────────┘

| 维度 | AGENTS.md | SKILL.md | DESIGN.md |

|------|-----------|----------|-----------|

|解决什么| AI该怎么做 | AI能做什么 | AI长什么样 |

|类比| 员工手册 | 操作SOP | 品牌VI手册 |

|受众| 所有Agent | 特定任务Agent | 前端生成Agent |

|标准化| Linux Foundation托管 | agentskills.io | Google Labs开源 |

实际工作流：当你对Claude Code说"创建一个登录页面"，Agent会同时读取：

• `AGENTS.md` → 知道用TypeScript，禁止any类型
• `DESIGN.md` → 知道主色 `#B8422E`，按钮圆角 `8px`，使用Public Sans字体
• 生成的UI**自动符合团队规范**，无需反复prompt。

七、实战：5步接入现有项目

# Step 1: 使用Chrome扩展从现有网站提取样式生成DESIGN.md初稿 # 安装 design-md-chrome 扩展 → 打开你的产品页 → 一键提取 # Step 2: 手动调优Token值和Prose规则 # Step 3: 放入项目根目录 cp DESIGN.md /path/to/your-project/ # Step 4: 运行lint校验 cd /path/to/your-project npx @google/design.md lint DESIGN.md # Step 5: 加入CI流水线（GitHub Actions示例）

# .github/workflows/design-lint.yml name: DESIGN.md Lint on: pull_request: paths: - 'DESIGN.md' jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npx @google/design.md lint DESIGN.md

八、当前局限与展望

作为Alpha阶段规范（v0.2.0），DESIGN.md仍有明显局限：

| 局限 | 影响 | 预期解决 |

|------|------|----------|

| 仅支持sRGB色域 | 无法表达Display P3广色域 | v0.3.0+ |

| Google主导治理 | 标准化进程依赖单一实体 | 可能移交社区基金会 |

| 概率性执行 | Agent是"被引导"而非"被编译"，仍有漂移风险 | 更严格的Agent侧约束 |

| 静态文件 | 无法动态响应品牌切换（暗黑模式/多主题） | 规划中 |

尽管如此，DESIGN.md已经展现了一种"设计即代码"的新范式——把设计系统从Figma画布搬进Git仓库，让AI第一次拥有了对设计规范的持久记忆。

九、结语

AI编码正在从"Vibe Coding"（凭感觉生成）走向"Spec-Driven Development"（规范驱动开发）。DESIGN.md是这个趋势的关键基础设施之一——它不是要取代设计工具，而是在设计师和AI之间建立了一个标准化的握手协议。

放在项目根目录的一个Markdown文件，就能让所有AI编码助手读懂你的品牌语言。这件事的价值，随着AI生成代码比例的持续增长，会被越来越多团队认识到。

**参考资源**

- GitHub仓库：[google-labs-code/design.md](https://github.com/google-labs-code/design.md)

- 社区模板：[VoltAgent/awesome-claude-design](https://github.com/VoltAgent/awesome-claude-design)（68+品牌灵感模板）

- CLI工具：`npm install @google/design.md`

- 配套规范：AGENTS.md（Linux Foundation）、SKILL.md（agentskills.io）