DESIGN.md，设计师应该知道它

2026 年 4 月，Google Labs 开源了一个叫 DESIGN.md 的规范。GitHub 上 11.6 k star，1 k fork，不到一个月。

设计小站之所以现在才写这类文章，是一直在观察其社区影响和生态，以确定其值得写！

它做的事情很直接：「用一个文件，把设计系统同时写给人和 AI Agent 看。」

这篇文章讲清楚四件事：「它是什么，为什么设计师需要关心，怎么上手，以及怎么让 AI 编程工具立刻用起来。」

一句话解释

DESIGN.md 是一个纯文本文件，包含两层内容：

1. 「YAML front matter」 — 机器可读的设计 Token（颜色 hex 值、字体参数、间距数值）
2. 「Markdown body」 — 人类可读的设计理由（为什么选这个颜色、这个字体用在哪里）

Token 给精确值，prose 给理由。AI Agent 读 Token 生成代码，设计师读 prose 理解决策。

它长什么样

一个最简单的 DESIGN.md 文件：

---name: Heritagecolors:  primary: "#1A1C1E"  secondary: "#6C7278"  tertiary: "#B8422E"  neutral: "#F7F5F2"typography:  h1:    fontFamily: Public Sans    fontSize: 3rem    fontWeight: 700    lineHeight: 1.1    letterSpacing: "-0.02em"  body-md:    fontFamily: Public Sans    fontSize: 1remrounded:  sm: 4px  md: 8pxspacing:  sm: 8px  md: 16pxcomponents:  button-primary:    backgroundColor: "{colors.tertiary}"    textColor: "#FFFFFF"    rounded: "{rounded.sm}"    padding: 12px  button-primary-hover:    backgroundColor: "{colors.primary}"---## OverviewArchitectural Minimalism meets Journalistic Gravitas.## Colors- **Primary (#1A1C1E):** Deep ink for headlines and core text.- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.

几个关键点：

• --- 分隔符之间的 YAML 是「规范值」，AI Agent 直接解析使用
• Markdown 正文是「设计理由」，告诉 Agent “为什么”这样设计
• {colors.tertiary} 是 「Token 引用」，避免重复写 hex 值。改颜色只改一处
• 组件变体（hover、active）是「独立 entry」，不是嵌套。button-primary-hover 是对的，button-primary.hover 是错的

规范章节顺序

DESIGN.md 定义了 8 个标准章节。可以省略，但出现必须按这个顺序：

为什么设计师需要关心这个

以前的设计系统工作流有个断裂点：「设计师在 Figma 里定义了完美的设计系统，但 AI Agent 看不到。」

Agent 写代码时，要么靠猜，要么靠开发者手动传达。中间一定走样。

DESIGN.md 填了这个缝。它是设计师和 AI Agent 之间的「契约文件」。

设计师不需要写代码。但需要把设计决策翻译成机器能理解的语言。DESIGN.md 就是这个翻译层。

实操一：5 分钟写出你的第一个 DESIGN.md

不需要从零开始。照着下面走就行。

第 1 步：确定品牌调性

先回答一个问题：你的产品给人什么感觉？专业严肃？轻松友好？暗色调？明亮干净？把答案写在 Overview 章节。三五句话够了。

第 2 步：定义色彩体系

至少 4 个颜色：

colors:primary:"#1A1C1E"# 主色，标题和核心文字secondary:"#6C7278"# 辅助色，边框、说明文字tertiary:"#B8422E"# 强调色，按钮和交互元素neutral:"#F7F5F2"# 中性色，背景

然后在 Markdown 正文里解释每个颜色的用途。

第 3 步：选定字体层级

typography:h1:fontFamily:PublicSansfontSize:3remfontWeight:700body-md:fontFamily:PublicSansfontSize:1remfontWeight:400lineHeight:1.6

第 4 步：制定间距和圆角

rounded:sm:4pxmd:8pxspacing:sm:8pxmd:16pxlg:24px

第 5 步：定义常用组件

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

写完保存为项目根目录的 DESIGN.md。跑一下 lint 看有没有问题：

npx @google/design.md lint DESIGN.md

实操二：一键复刻大牌设计风格

不想从零写？有两条快车道。

方案 A：从 Refero Styles 直接拿

Refero Styles 收录了数十个知名品牌的完整 DESIGN.md。打开任何一个品牌，你能看到：

• 完整的色彩 Token 表（含 hex 值和语义角色）
• 字体层级（字号、字重、行高、字间距）
• 间距和圆角规范
• 组件定义（按钮、卡片、输入框）
• Do’s and Don’ts

比如 Linear 的风格是这样定义的：

❝

Midnight Command Center: A dark, layered interface lit by precise accents, like a high-tech control panel.

❞

它的色彩体系：

这些数据直接就是 DESIGN.md 的 YAML front matter。你只需要：

1. 在 Refero 上找到你喜欢的品牌
2. 复制它的 DESIGN.md
3. 改成你的品牌名和颜色值
4. 跑 lint 验证

方案 B：从 GitHub 仓库 fork

Google 官方仓库的 examples/ 目录有现成的 DESIGN.md 模板：

• 「Atmospheric Glass」 — 暗色调毛玻璃风格，50+ 个颜色 Token
• 「Paws and Paths」 — 温暖友好的宠物/生活方式风格
• 「Totality Festival」 — 大胆前卫的活动/艺术风格

git clone https://github.com/google-labs-code/design.mdcd design.md/examples# 挑一个最接近你品牌的，复制出来改

实操三：让 AI 编程工具立刻用起来

这是 DESIGN.md 最核心的价值。写好文件，AI 工具就能自动遵循你的设计规范。

Claude Code

Claude Code 会自动读取项目根目录的 DESIGN.md。不需要额外配置。

# 1. 把 DESIGN.md 放在项目根目录cp DESIGN.md ~/my-project/DESIGN.md# 2. 让 Claude Code 生成组件claude "根据 DESIGN.md 创建一个登录页面"

Claude Code 会读取 YAML front matter 中的 Token 值，生成的代码自动使用你定义的颜色、字体、间距。

Cursor

Cursor 也支持 DESIGN.md。把文件放在项目根目录即可。

# 在 Cursor 的 Composer 中直接引用："根据 DESIGN.md 的规范，创建一个 Dashboard 布局"

Cursor 会解析 Token 引用（{colors.primary}），确保生成的代码和你的设计系统一致。

OpenAI Codex

Codex 同样能读取 DESIGN.md。在项目中放好文件后：

codex "按照 DESIGN.md 的组件规范实现一个表单页面"

批量导入：用 CLI 导出为工具原生格式

如果你的项目已经在用 Tailwind CSS，可以一键导出：

# 导出为 Tailwind v3 theme JSONnpx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json# 导出为 Tailwind v4 CSS @theme 块npx @google/design.md export --format css-tailwind DESIGN.md > theme.css# 导出为 W3C DTCG 标准格式（通用）npx @google/design.md export --format dtcg DESIGN.md > tokens.json

导出的 tailwind.theme.json 可以直接粘贴到 tailwind.config.js 的 theme.extend 里。这样即使不用 DESIGN.md，AI 工具也能通过 Tailwind 配置读到你的设计 Token。

Refero MCP：让 AI Agent 直接搜索真实产品界面

Refero MCP 是更进一步的方案。它把 130,000+ 真实产品界面和 10,000+ 用户流程直接喂给 AI Agent。

支持的工具：Claude Code、Cursor、Codex、Windsurf、Lovable、Manus

安装方式（以 Cursor 为例）：

{"mcpServers": {"refero": {"command": "npx","args": ["@refero/mcp-server"],"env": {"REFERO_API_KEY": "your-api-key"      }    }  }}

装好后，你可以直接对 AI 说：

• “找几个金融科技产品的 onboarding 流程参考”
• “Linear 的空状态是怎么设计的？给我看看”
• “参考 Stripe 的卡片布局，做一个定价页面”

Agent 会自动搜索 Refero 库，提取设计模式，然后生成代码。它不是在猜，是在「参考真实产品」。

实操四：验证和迭代

写完 DESIGN.md 不是终点。用 CLI 工具持续验证。

Lint：检查结构和无障碍

npx @google/design.md lint DESIGN.md

它会检查 7 条规则：

最有价值的是 「contrast-ratio」。它会自动检查每个组件的文字颜色和背景色对比度是否达到 WCAG AA 标准。不用再肉眼检查。

Diff：版本对比

改了设计系统后，用 diff 检查有没有回归：

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

它会告诉你哪些 Token 被新增、删除、修改，以及是否存在回归。

真实案例：从 Refero 复刻 Linear 风格

完整走一遍流程。

第 1 步：在 Refero 上找到 Linear

打开 styles.refero.design，搜索 Linear。

你会看到完整的 DESIGN.md，包含：

• 19 个颜色 Token（从 Pitch Black 到 Neon Lime）
• 2 个字体（Inter Variable + Berkeley Mono）
• 16 个间距值（4 px 到 128 px）
• 11 个组件定义（按钮、卡片、输入框、Badge）
• 详细的 Do’s and Don’ts

第 2 步：复制并修改

把 Linear 的 DESIGN.md 复制到你的项目，改成你的品牌：

# 改前（Linear）name:Linearcolors:primary:"#f7f8f8"# Porcelainsecondary:"#8a8f98"# Storm Cloudtertiary:"#e4f222"# Neon Lime# 改后（你的品牌）name:MyProductcolors:primary:"#1A1C1E"# 深墨色secondary:"#6C7278"# 灰石色tertiary:"#B8422E"# 波士顿红

保留 Linear 的布局策略、间距体系、组件结构，只换颜色和字体。

第 3 步：Lint 验证

npx @google/design.md lint DESIGN.md

确保没有 broken ref、对比度合规。

第 4 步：让 AI 生成代码

# Claude Codeclaude "根据 DESIGN.md 创建一个 SaaS 产品的 Dashboard"# Cursor# 在 Composer 中输入同样的话# Codexcodex "按照 DESIGN.md 实现 Dashboard 组件"

生成的代码会自动使用你修改后的配色，但保留 Linear 的布局逻辑和间距体系。

与现有工具的关系

DESIGN.md 不是替代品，是桥梁。

生态：社区已经跑起来了

DESIGN.md 开源不到一个月，社区已经自发建起了完整的工具链。

getdesign.md — 70 个大牌 DESIGN.md 直接用

getdesign.md 是社区维护的 DESIGN.md 收录站，目前已有 「70 个」知名品牌的完整 DESIGN.md 文件，覆盖 9 个行业分类：

每个品牌的 DESIGN.md 都包含完整的色彩 Token、字体层级、间距规范、组件定义和 Do’s/Don’ts。

「用法」：打开 getdesign.md，搜索你喜欢的品牌，复制它的 DESIGN.md，改成你的品牌名和颜色值。

Chrome 扩展：一键提取任意网站的设计系统

Chrome Web Store 上有两个相关的扩展：

• 「DESIGN.md Style Extractor (TypeUI)」 — 打开任意网站，点击扩展按钮，自动检测 CSS 变量并生成 DESIGN.md 文件。支持导出为 Google Stitch、Claude Code、Codex、Cursor 等工具的格式。
• 「DESIGN.md Generator」 — 类似功能，提取网站的设计系统并生成标准 DESIGN.md 文件。

这意味着你可以打开 Stripe 的官网，一键生成它的 DESIGN.md。不用手动数颜色、量间距。

Google Stitch 集成

Google 自己的 Stitch 工具已经原生支持 DESIGN.md。Stitch 是 Google 的 AI 设计工具，可以把 DESIGN.md 作为输入，自动生成符合设计规范的 UI。

在 Stitch 的文档中，DESIGN.md 被定义为标准的设计系统描述格式。这意味着 Google 内部已经在用这个规范了。

社区反馈：来自 Hacker News 的真实声音

DESIGN.md 在 Hacker News 上引发了讨论（37 points, 4 comments）。几个值得关注的观点：

「关于和 Figma 的关系」：

❝

“How is DESIGN.md to play nicely with eg Figma Design Tokens, or tailwind.config.js? Is it to become the source-of-truth, or simply point to those?” — @gavmor

❞

「关于”specsmaxxing”」：

❝

“I went down quite a rabbit hole experimenting with what I call ‘specsmaxxing’. My first reaction is that everything I see defined here in DESIGN.md is already codified in my actual themes configs, or component files.” — @brendanmc 6

❞

「关于扩展性」：

❝

“I would suggest expanding on it. For example, could it include brand tone and descriptions of visual style. That way it would be helpful for writing copy text and creating art assets.” — @Finnoid

❞

「关于快速启动」：

❝

“DESIGN.md very useful for quickly getting something up and running. We built a site where you can explore DESIGN.md files from popular websites.” — @necatiozmen（getdesign.md 的作者）

❞

这些反馈说明两件事：一是 DESIGN.md 确实解决了真实痛点；二是社区在主动扩展它的边界。

写在最后

DESIGN.md 解决的问题很朴素：「让 AI Agent 看懂你的设计系统。」

它不是要替代 Figma，也不是要替代设计系统文档。它是两者和 AI Agent 之间的桥梁。

对设计师来说，学习成本很低。YAML 语法比 CSS 简单，Markdown 更是写文档的基本功。真正需要花时间的，是把脑子里的设计决策「显式化」 — 为什么选这个颜色、为什么用这个字体、按钮为什么这样设计。

这些决策以前存在设计师的脑子里，现在要写下来给机器看。

这反而是件好事。写 DESIGN.md 的过程，本身就是在梳理和验证自己的设计逻辑。

「参考资料」

• Google DESIGN.md GitHub 仓库（Apache-2.0）
• Refero Styles — 设计风格参考库
• Refero MCP — 让 AI Agent 搜索真实产品界面
• getdesign.md — 70 个大牌 DESIGN.md 收录站
• DESIGN.md Style Extractor — Chrome 扩展
• Google Stitch — 原生支持 DESIGN.md
• DESIGN.md 规范文档
• npm: @google/design.md CLI
• awesome-design-md — GitHub 收录