DESIGN.md：让 AI 终于能写出不丑的 UI

你有没有发现，AI 生成的 UI 总是长同一副面孔？无论是 Claude、Cursor 还是 Copilot，吐出来的前端页面几乎是 shadcn + Material Design 的默认模板：灰色背景、蓝色按钮、圆角卡片、Inter 字体。不是不好看，但千篇一律——像所有 AI 都上了同一个设计课。

问题的根源不在 AI 的审美能力，而在它没有设计上下文。AGENTS.md 告诉 Agent 怎么构建项目，但没有告诉它项目应该长什么样。于是 Agent 只能 fallback 到最通用的视觉方案。

2025 年，Google Labs 的 Stitch 团队开源了一个新标准来解决这个问题：DESIGN.md。

一、DESIGN.md 是什么 #

一句话：DESIGN.md 是用纯 Markdown 写的设计系统，让 AI Agent 读懂你的视觉品牌。

它和项目里的其他"协议层"文件站在同一排：

文件	谁读	定义什么
`README.md`	人类	项目是什么
`AGENTS.md` / `CLAUDE.md`	编码 Agent	怎么构建项目（工程上下文）
`DESIGN.md`	设计 Agent	项目应该长什么样（设计上下文）

这个三层结构揭示了一个重要的认知：AI 协作的核心不是能力，而是上下文。 AI 能做很多事，但如果你不给它约束，它就做最"安全"的事——而安全的设计就是 generic 设计。

DESIGN.md 的格式规范由 Google Labs 在 google-labs-code/design.md 仓库维护，Apache-2.0 开源，目前 Alpha 版。它不是强制绑定 Stitch 工具的——任何 AI Agent 都能直接读。

二、文件结构：Token + Rationale 双轨 #

DESIGN.md 的设计哲学藏在它的结构里：YAML front matter 给精确值，Markdown prose 给设计理由。两者缺一不可。

---
# YAML front matter — 机器读的 Token
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.sm}"
---

## Overview          ← Markdown 正文 — 人类和 Agent 都读的理念

深邃墨色用于标题，传递永久感。Boston Clay 红仅用于主交互，
每屏只有一个最重要的按钮使用此色……

## Colors
## Typography
## Components
## Do's and Don'ts

为什么需要双轨？因为纯 Token 只告诉你"是什么"，但不知道"为什么"。

Tailwind config 里写 primary: "#B8422E"，Agent 知道主色是红色，但不知道这个红只能用在 CTA 按钮、不能用在装饰边框。Markdown prose 说"Boston Clay 红是唯一的交互驱动色"，Agent 才能在没有明确规则的场景里做出正确的设计判断。

这就是 DESIGN.md 最深刻的洞察：设计系统不只是值表，更是决策指南。

三、八个 Canonical Section #

官方 Spec 规定了八个 Section，按固定顺序排列（缺了可以跳过，但顺序不能乱）：

#	Section	解决什么问题
1	Overview / Brand & Style	品牌个性、情感基调——“playful 还是 professional”
2	Colors	调色板 + 语义角色（primary/secondary/tertiary/error）
3	Typography	字体族、9-15 级层级、weight/lineHeight/letterSpacing
4	Layout & Spacing	网格模型、8px 间距尺度、留白哲学
5	Elevation & Depth	阴影系统 / Glassmorphism 层级 / 色调分层
6	Shapes	圆角尺度（sm/md/lg/full）
7	Components	按钮/卡片/输入框样式 + hover/active 状态变体
8	Do’s and Don’ts	设计护栏——“每屏主色只用一次”、“别混圆角和尖角”

其中 Do’s and Don’ts 是最容易被忽略但最有价值的 Section。它不是建议，而是护栏——在 Agent 没有明确规则时，这些约束阻止它做出最坏的选择。

四、Token 系统：语义引用而非硬编码 #

DESIGN.md 的 Token 参考了 W3C DTCG（Design Tokens Community Group）JSON Spec，但用的是更 Agent-friendly 的 YAML 格式。

一个关键设计：Components 里用 {colors.primary} 引用上层 Token，不硬编码 hex 值。

1
2
3
4
5
6
7
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"   ← 引用，不是 "#B8422E"
    textColor: "#FFFFFF"
    rounded: "{rounded.sm}"
  button-primary-hover:
    backgroundColor: "{colors.primary}"     ← 同样引用

这意味着：改一个 colors.tertiary 的 hex 值，所有引用它的组件自动跟着变。语义引用 > 硬编码——这是设计系统从"写一次用一次"到"写一次用全局"的关键跨越。

Token 还可以导出为下游格式：

1
2
3
4
5
6
7
8
# 导出为 Tailwind theme JSON
npx -y @google/design.md export --format tailwind DESIGN.md

# 导出为 W3C DTCG JSON
npx -y @google/design.md export --format dtcg DESIGN.md

# Lint：检查结构 + Token 引用 + WCAG 对比度
npx -y @google/design.md lint DESIGN.md

从 DESIGN.md → Tailwind theme → CSS class，是一条完整的设计→代码链路。

五、69 个现成风格库：Awesome DESIGN.md #

VoltAgent 维护的 awesome-design-md 仓库收集了 69 个从真实网站提取的 DESIGN.md，覆盖了从 Stripe 到 SpaceX、从 Linear 到 Ferrari 的视觉系统。

每个参考配套：

DESIGN.md — 设计系统定义
preview.html — 亮色色板 + 字号 + 组件预览
preview-dark.html — 暗色版本

这意味着你不需要从零设计视觉系统。选一个最贴近你项目定位的风格，微调 accent 色、字体和间距，就能得到品牌一致的 UI。

按项目类型的选型参考：

项目类型	推荐参考	关键词
SaaS / 企业后台	Linear, Vercel, Stripe	极简精确、单色 accent
AI / 模型平台	Claude, VoltAgent, Mistral	暗色 + 醒目 accent、终端感
DevTools / 编辑器	Cursor, Warp, Raycast	IDE-like 暗色、gradient accent
教育平台 / 文档	Mintlify, Notion, Cal	温暖极简、阅读优先
数据仪表盘	PostHog, Sentry, ClickHouse	暗色仪表盘、数据密集
电商 / 高端展示	Apple, Tesla, Nike	大留白、cinematic 摄影
金融 / 加密	Revolut, Coinbase, Wise	fintech precision

六、实战流程：从选型到部署 #

Step 1：选风格 #

浏览 https://getdesign.md/ 或克隆 awesome-design-md 仓库，根据项目定位选最贴合的 DESIGN.md。

Step 2：获取文件 #

1
2
3
4
5
# 从 getdesign.md 获取（推荐）
# 访问 https://getdesign.md/<site>/design-md 拷贝完整文件

# 或从仓库克隆
git clone https://github.com/VoltAgent/awesome-design-md.git

Step 3：放入项目并微调 #

拷贝到项目根目录，按需求改 accent 色、字体、间距尺度，然后 lint：

1
npx -y @google/design.md lint DESIGN.md

Step 4：导出并应用 #

Tailwind 项目：导出 theme → 导入到 tailwind.config.js
Vue / React 项目：DESIGN.md 放在 repo → Agent 读它写组件样式
纯 HTML 项目：Agent 把 token 转为 CSS variables

Step 5：让 Agent 知道 #

对 AI coding agent 说：

照项目根目录的 DESIGN.md 设计系统来写 UI。

Agent 会同时读 YAML token（精确值）和 Markdown prose（设计理由），输出品牌一致的 UI。

七、更深一层的思考 #

DESIGN.md 不是一个文件格式的故事。它是一个认知模式的故事。

过去十年，设计系统的载体从 PSD → Sketch → Figma → 代码（Tailwind/CSS variables），每次进化都在让设计更接近开发。但这些格式有一个共同的问题：它们是人类之间的协作工具，不是 AI 的协作工具。

Figma 的 JSON schema 对 LLM 来说太重、太嵌套、太语义模糊。Tailwind config 是代码，但只有值没有理由。DTCG JSON 是最标准化的设计 Token 格式，但纯数据——没有 prose。

DESIGN.md 的选择是用 Markdown。不是因为它技术上最先进，而是因为它是 LLM 最擅长理解的格式。Markdown 是"AI-native"的表达载体——就像 SQL 是数据库-native 的查询语言、JSON 是 API-native 的数据格式一样。

这揭示了一个更普遍的原则：和人协作用人的格式，和 AI 协作用 AI 的格式。 当你的消费者是 LLM 时，最优的文档格式不是最结构化的那个，而是最容易被理解的那个。

README.md 定义了项目是什么（面向人类），AGENTS.md 定义了怎么构建（面向 Agent），DESIGN.md 定义了应该长什么样（面向 Agent）。三个文件，三个角色，三种上下文——但都用同一种格式：Markdown。

这不是巧合。这是**“纯文本作为 AI 协议”**模式的又一次验证。

八、当前状态与生态 #

Alpha 版：格式、schema、CLI 都在活跃开发，预期还有 breaking changes
Google Labs / Stitch 背书，但格式本身是 Apache-2.0 开源，不绑定任何工具
CLI：@google/design.md on npm，提供 lint/diff/export 功能
参考库：69 个社区贡献的现成风格（awesome-design-md）
生态系统：Google Stitch 是参考消费者，但 Claude Code、Cursor、任何 coding Agent 都能直接读

总结 #

DESIGN.md 解决的核心问题：AI 生成的 UI 不丑了，但丑在同一张脸上。 这不是 AI 能力不足，而是上下文缺失。

YAML Token 给精确值，Markdown prose 给设计理由。双轨结构让 Agent 在有规则时遵守规则、在没规则时理解意图。69 个现成风格库让"从零设计视觉系统"变成"选一个最贴合的然后微调"。

但更重要的收获是它揭示的认知模式：当你和 AI 协作时，最有效的文档不是最结构化的，而是最容易被理解的。 Markdown 是 AI-native 的表达载体——DESIGN.md、AGENTS.md、README.md，三种上下文、同一种格式。

这不是一个文件格式的创新，而是人机协作语言的又一次进化。

参考链接：

官方 Spec 仓库：google-labs-code/design.md
风格参考库：VoltAgent/awesome-design-md
在线浏览：getdesign.md
Google Stitch 文档：stitch.withgoogle.com/docs/design-md
CLI 工具：@google/design.md on npm