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）