让 Claude Code 帮你改一个按钮，它能把圆角、字号、阴影全给你换一遍；让 Cursor 补一个弹窗，它写出来的颜色跟你项目里已有的调色盘八竿子打不着。不是模型不行，是你没把「设计系统」告诉它。
过去我们靠口头描述：「用这个蓝」「圆角小一点」「标题用那套字体」。AI 听懂了，但过两天它又忘了。6 月 27 日冲上 GitHub 日榜的 Google Labs 项目 DESIGN.md，做的就是这件事：用一份文件，把设计系统写成 AI 能长期记住、能校验、能消费的格式。
不是新框架，不是新设计工具，只是一个约定好的 Markdown 文件。看完这篇，你就能给项目加上这份「设计说明书」，让 AI 编码助手不再乱改 UI。
一份文件解决什么问题
DESIGN.md 的核心思路很朴素：把「机器可读的设计 Token」和「人类可读的设计理念」放在同一个文件里。顶部用 YAML 写死颜色、字体、间距、组件属性；下面用 Markdown 解释这些 Token 为什么这样设计、什么时候该用哪个。
对 AI 编码助手来说，这相当于一份持久化的设计约束。它不用每次从聊天记录里猜你的审美，也不用去翻散落各处的 Figma 链接。打开仓库，看到 DESIGN.md，就能知道：
- 主色、辅色、中性色分别是什么；
- 标题、正文、标签该用什么字体和字号；
- 按钮、卡片、输入框的圆角和间距规范；
- 这套设计想传达什么气质（冷淡、活泼、高端、复古）。
项目仓库是 github.com/google-labs-code/design.md，目前处于 alpha 阶段，Apache 2.0 协议。GitHub 上已经有 2.2 万多 Star，说明这个痛点确实普遍存在。
文件结构：YAML 在前面，理念在后面
一份合法的 DESIGN.md 分成两部分，用 --- 隔开：
---
version: alpha
name: Heritage
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
body-md:
fontFamily: Public Sans
fontSize: 1rem
rounded:
sm: 4px
md: 8px
spacing:
sm: 8px
md: 16px
---
## Overview
Architectural Minimalism meets Journalistic Gravitas. The UI evokes a premium matte finish — a high-end broadsheet or contemporary gallery.
## Colors
The palette is rooted in high-contrast neutrals and a single accent color.
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.
YAML 部分是给 AI 消费的硬约束，Markdown 部分是给 AI 提供上下文。比如你说「Boston Clay 是唯一的交互驱动色」，AI 在生成按钮、链接、徽章时就不会乱用其他颜色。
支持的 Token 类型
- Color：任意 CSS 颜色格式，hex、rgb()、oklch()、命名颜色都可以；
- Dimension：数字加单位，如
48px、-0.02em； - Typography：对象形式，包含
fontFamily、fontSize、fontWeight、lineHeight等； - Token 引用：用
{colors.primary}这种写法在组件里引用上层 Token。
组件定义怎么写
组件 Token 放在 components 下，目前支持的属性包括 backgroundColor、textColor、typography、rounded、padding、size、height、width。状态变体用独立条目，比如 button-primary 和 button-primary-hover 分开写：
components:
button-primary:
backgroundColor: "{colors.tertiary}"
textColor: "{colors.neutral}"
typography: "{typography.label-caps}"
rounded: "{rounded.md}"
padding: "{spacing.md}"
button-primary-hover:
backgroundColor: "#9A3522"
textColor: "{colors.neutral}"
章节顺序有讲究
如果写 Markdown 章节，出现顺序必须按规范来：Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do’s and Don’ts。章节标题可以省略，但写的话别乱序，否则 linter 会报 section-order 警告。
校验：给设计系统加 CI
DESIGN.md 自带 CLI，安装很简单：
npm install @google/design.mdWindows 上如果 .md 后缀被系统关联占用，改用 designmd 别名：
npx -p @google/design.md designmd lint DESIGN.mdlint 命令
npx @google/design.md lint DESIGN.md它会检查 9 条规则，包括：
broken-ref：Token 引用{colors.primary}解析不到定义；contrast-ratio：组件背景色和文字色对比度低于 WCAG AA 标准；missing-primary：定义了颜色但缺少primary；orphaned-tokens：定义了颜色 Token 但没有任何组件引用；section-order：Markdown 章节顺序不对。
这些规则对 AI 编码助手特别有用。你不用担心 AI 生成一个深底深字的按钮，因为 lint 会先把对比度问题报出来。
diff 命令
改设计系统最怕「暗改」。diff 可以对比两个版本的 DESIGN.md：
npx @google/design.md diff DESIGN.md DESIGN-v2.md输出会告诉你哪些 Token 被增删改，如果新版本引入了更多错误，CLI 返回码为 1，可以直接接进 CI 做回归拦截。
导出到 Tailwind 或 DTCG
同一套 Token 可以导出成不同格式，适配不同技术栈：
# Tailwind v3 的 theme.extend 配置
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
# Tailwind v4 的 @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这意味着设计师维护 DESIGN.md，前端开发按自己框架消费，不用互相重复定义。
接到 Claude Code / Cursor / Copilot 工作流
DESIGN.md 真正的价值，是成为 AI 编码助手的上下文文件。下面是我建议的落地方式。
1. 放在仓库根目录
AI 编码助手在读取项目时，通常会扫描根目录下的 README、CLAUDE.md、PROJECT_CONTEXT.md 等文件。把 DESIGN.md 放在仓库根目录，并在 README 里提一句：
所有 UI 改动请遵循仓库根目录的 DESIGN.md。
Claude Code、Cursor、Copilot 在收到样式相关请求时，会优先读取这份文件。
2. 与 CLAUDE.md 配合使用
如果你已经写过 CLAUDE.md，可以把 DESIGN.md 作为它的子文件引用。在 CLAUDE.md 里加一段：
## Design System
All UI changes must follow the tokens and guidelines in DESIGN.md.
Run `npx @google/design.md lint DESIGN.md` before committing any visual change.关于怎么写项目级上下文文件，可以看我之前写的 AI 编程下半场，比的是「工程化」，里面聊了怎么让 AI 像靠谱工程师一样干活。
3. 在 CI 里强制校验
在 .github/workflows/design.yml 里加一步：
name: Design System Check
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm install -g @google/design.md
- run: designmd lint DESIGN.md
这样 AI 生成的 PR 如果违反了设计系统，CI 会直接标红。人审的时候也能省不少口舌。
4. 给 AI 下指令时直接引用
不要只说「把按钮改成品牌色」。改成：
Update the primary button to use
tertiaryfrom DESIGN.md as background, and run the linter to verify contrast.
这种带 Token 引用的指令，比模糊描述稳定得多。如果你常用 Claude Code 做分支式开发，也可以参考 Claude Code 的 /fork 工作流，让 AI 在独立分支里试改设计系统，不污染主分支。
一个更小的实战例子
假设你有一个个人博客，设计系统特别简单，可以写成：
---
name: My Blog
colors:
primary: "#0EA5E9"
secondary: "#64748B"
background: "#0F172A"
surface: "#1E293B"
text: "#F8FAFC"
typography:
heading:
fontFamily: Inter
fontSize: 2rem
fontWeight: 700
body:
fontFamily: Inter
fontSize: 1rem
lineHeight: 1.75
rounded:
sm: 6px
md: 12px
spacing:
sm: 8px
md: 16px
lg: 32px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "{colors.text}"
rounded: "{rounded.md}"
padding: "{spacing.md}"
---
## Overview
A dark, high-contrast personal blog with a single blue accent for all interactive elements.
## Colors
- **Primary (#0EA5E9):** Sky blue, used for links and buttons only.
- **Background (#0F172A):** Deep slate, the main page background.
- **Surface (#1E293B):** Lighter slate for cards and code blocks.
- **Text (#F8FAFC):** Near-white for maximum readability on dark surfaces.
## Typography
Inter for both headings and body. Headings are bold and tight; body text is generous for long reading.
把这个文件丢进仓库，AI 在改博客主题时就不会再给你配出一个「紫色按钮配橙色 hover」的 UI。
它不能替代什么
DESIGN.md 不是设计工具，不能替代 Figma、Sketch 或设计师的审美判断。它做的是「把已经定下来的设计系统，用 AI 能稳定消费的格式写下来」。如果你的设计系统本身还在反复改，DESIGN.md 也会跟着改，这很正常。用 diff 命令追踪这些变化，反而比口头同步更清楚。
另外，它是 alpha 阶段，格式和 CLI 都可能变化。建议先在非核心项目试跑，稳定后再推广到主仓库。
总结
AI 编码助手不是故意把你的页面改丑，它是没拿到足够稳定的输入。Google Labs 的 DESIGN.md 提供了一种轻量解法：一份 YAML + Markdown 文件，既给人类读，也给 AI 读。
你现在能做的：
- 打开一个常用项目，在根目录新建
DESIGN.md； - 用 YAML 写出 3-5 个颜色、2-3 套字体、1-2 个组件；
- 跑
npx @google/design.md lint DESIGN.md校验； - 在 README 或 CLAUDE.md 里告诉 AI：所有 UI 改动先看这个文件。
如果你之前折腾过本地模型或者想更系统地让 AI 接管代码工作，也可以看看 本地部署大模型完全指南，或者回顾 AWS 说的「规范驱动开发」——DESIGN.md 其实就是把规范驱动落到文件层面。
一份 DESIGN.md 改变不了世界，但能让你的 AI 少做几次「我以为你喜欢这个颜色」的乌龙。
发表回复