DESIGN.md：给 AI 编程工具看的设计规范文件

一句话定位：DESIGN.md 是 Google Labs 推出的一份开放格式规范，用一个 DESIGN.md 文件同时承载机器可读的 design tokens 和人类可读的设计说明，让 AI 编程工具更稳定地理解界面风格。

基础信息卡片

• 项目名称：DESIGN.md
• 仓库地址：https://github.com/google-labs-code/design.md
• 规范文档：https://stitch.withgoogle.com/docs/design-md/specification
• NPM 包：@google/design.md
• 命令入口：design.md
• 项目定位：A format specification for describing a visual identity to coding agents
• 开源协议：Apache-2.0
• 当前版本：0.1.1

解决什么问题

如果只是把一套颜色、字号、间距丢给 AI，它能读到值，但很难真正理解这套设计背后的意图。

比如下面这些问题，在实际使用 AI 生成页面时都很常见：

• 它知道主色是什么，却不知道什么场景才该用主色强调
• 它知道按钮圆角和字号，却不知道这套界面整体是偏克制、偏轻盈还是偏活泼
• 它能读到 token，却很难稳定理解组件语义、品牌气质和使用边界
• 换一个 Agent、换一次会话，生成出来的页面风格就开始漂

DESIGN.md 处理的，就是这类“有数值但没语境，有说明但不够结构化”的问题。

它的核心思路很直接：把精确 token 和设计说明放进同一个文件里，让机器和人看到的是同一份设计系统。

核心功能

1. 用 YAML Front Matter 描述机器可读 token

在 DESIGN.md 顶部，可以写结构化的设计 token，比如：

• colors
• typography
• rounded
• spacing
• components

README 里的最小示例就是这样的：

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

这部分的价值很明确：AI 工具不需要再从一大段自然语言里猜颜色、字号和间距，而是可以直接读取确定值。

2. 用 Markdown Body 描述设计意图和使用方式

DESIGN.md 不只放 token，还要求在正文里继续写清楚：

• 整体风格和品牌气质
• 配色策略为什么这么定
• 排版该呈现什么感觉
• 组件应该怎么用
• 哪些做法应该避免

官方 spec 把这部分定义成标准章节顺序，常见包括：

1. Overview
2. Colors
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do’s and Don’ts

这一步很关键，因为很多设计系统真正难传达的不是 token 本身，而是 token 背后的语义。

3. 允许 token 引用，方便形成完整系统

在 DESIGN.md 里，token 不只是散值，还支持引用关系，比如：

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px

这意味着它不只是在记录“颜色表”和“字号表”，而是在描述一个更完整的设计系统结构。

4. 自带 CLI 工具链，不只是文档格式

项目不只是定义格式，还提供了 CLI 能力。README 和包信息里已经给出了完整入口：

npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md export --format tailwind DESIGN.md
npx @google/design.md spec

目前能直接看到的能力包括：

• lint：校验结构、token 引用、颜色对比度等
• diff：比较两个 DESIGN.md 的 token 和说明变化
• export：导出到 Tailwind、DTCG 等格式
• spec：输出完整规范内容，方便直接给 Agent 使用

也就是说，DESIGN.md 并不是“写一份规范给人看”就结束，而是可以真的进入工程流程。

5. 仓库已经给了完整示例，不只是抽象概念

这个仓库里已经带了多套示例设计系统，比如：

• Atmospheric Glass
• Paws & Paths
• Totality Festival Design System

这些示例不是只写几行 token，而是把颜色、字体、圆角、组件配置和整套设计说明都写进了 DESIGN.md，很适合直接拿来理解它到底想解决什么问题。

适合谁

我觉得它尤其适合这几类团队：

• 已经让 AI 参与前端开发的团队
  希望不同 Agent 在生成界面时尽量保持一致。

• 有设计系统，但信息散落在多个地方的团队
  想把 token、组件规范、设计描述收拢到一个统一入口里。

• 设计和开发协作频繁的产品团队
  既想让设计原则写得清楚，也想让工具链能直接消费。

• 想把设计系统接进工程流程的团队
  需要 lint、diff、export 这类能力，而不只是一个静态文档。

如果只是做一两个简单页面，这套规范未必立刻体现价值；但只要项目开始强调品牌一致性、可维护性和 AI 生成稳定性，它的意义就会越来越明显。

快速上手

如果想最快感受 DESIGN.md 的方式，我建议按这条路径走：

第一步，先写一份最小 DESIGN.md

先不追求很全，只写最关键的部分：

• colors
• typography
• spacing
• Overview
• Colors
• Components

也就是先把“值”和“说明”最重要的部分补齐。

第二步，用 linter 检查结构

npx @google/design.md lint DESIGN.md

先确认：

• 格式是不是合法
• token 引用有没有断掉
• 对比度是否合理
• 章节顺序是否符合规范

第三步，再接入自己的生成流程

如果你本来就在用 AI 生成页面、组件或者主题样式，那么可以把 DESIGN.md 当作稳定上下文的一部分，让它不只是看 prompt，而是真正理解你这套设计系统。

结论

DESIGN.md 最值得关注的地方，不是它把 design token 换了种写法，而是它把过去经常分散处理的几件事重新收拢到了一起：

• 机器要精确值
• 人要设计说明
• 团队要统一入口
• 工具链要可校验、可对比、可导出

从这个角度看，它更像是给“AI 参与前端和设计系统协作”补的一层基础设施。

如果后续更多 AI 编程工具开始支持这种格式，那么 DESIGN.md 很可能会变成设计系统和 Agent 之间一个很自然的中间层。