让 Claude Code 改一个按钮颜色。它改了。你再让它改另一个相似按钮。它跑偏了。第三个按钮的颜色跟第一个又不一样。
这不是 Claude 的问题。所有 AI 编程助手在前端代码里都有这个通病：它能读懂代码，但读不懂设计意图。”保持专业、简洁、有科技感”这种描述，在 AI 眼里每次都是不同的 HEX 值，同一个间距在不同文件里是不同的像素数。Tailwind 创始人五年前把每个按钮都设为 bg-indigo-500，导致地球上每个 AI 生成的 UI 到现在还是靛蓝色的。
Google Labs 在 2026 年 4 月开源了一个叫 DESIGN.md 的东西。截至 8 月初 26,000+ Stars，2,000+ Forks，4 个月冲到设计系统赛道 GitHub Trending 的塔尖。它干的事很简单：给设计系统写一份 AI 能看懂、而且每次都看懂一样的规范文件。
你会说这不就是设计 Token 吗？不是。Token 能给 AI 精确的颜色值，但给不了”这个颜色只能用在交互元素上，绝不能当背景”这种判断。DESIGN.md 做的是 YAML Token + Markdown Prose 的双层结构，让 AI 既有精确值又有设计逻辑。说白了这个定位很有意思：它在试图用一份 Markdown 文件，解决 AI 编程时代最基础的视觉一致性问题。
打动我的几个地方
DESIGN.md 的设计有一个一眼就能看出聪明的点：它不发明新格式，而是在 Markdown 和 YAML 这两个程序员已经熟悉到肌肉记忆的东西上做组合。YAML front matter 存设计 Token，Markdown 正文写设计逻辑。Agent 读 YAML 拿到精确的色值和字号，读 prose 理解为什么主色是 #1A1C1E 而不是 #000000，为什么强调色只能用一种。
Token 给的是确定性，prose 给的是判断力。两者缺一个，Agent 就会猜。而 Agent 猜设计的结果，任何一个用过 Cursor 写过前端的人都体验过。
Token 引用的设计也很实用。组件里写 {colors.primary}，改了 primary 的值所有引用自动跟变。这不是新技术，但在设计系统和 AI Agent 之间建立这种引用关系，之前没人做过。更狠的是它对 AI 的承诺是”100% 确定”。同一个 DESIGN.md 文件，无论给 Claude Code 还是 Gemini CLI 还是 Cursor 看，按钮的颜色一定是同一个 HEX 值。
CLI 工具链比我预期的要完整。四条命令各司其职：lint 不仅检查 YAML 结构，还内置了 WCAG AA 4.5:1 的对比度校验、断开的 Token 引用检测、孤立的未引用 Token 清理。11 条 lint 规则覆盖了从格式到可访问性的完整链路。
diff 可以做 Token 级别的回归检测，改了某个颜色值会报告影响了哪些组件。export 支持 Tailwind v3、v4 和 W3C DTCG 格式的导出，意味着 DESIGN.md 不是孤立的规范文件，而是可以接入现有构建管线的。这套工具链的完整程度，对于一个上线只有 4 个月的项目来说相当扎实。
我更看重的是它零运行时依赖。CLI 工具包不需要额外装几十个 npm 包，自实现了 oklch、lab、hwb 的色值解析。在 AI 工具链本来就依赖重的环境下，这种克制很难得。Apache 2.0 协议，商业项目可以放心用。
从定位上看，DESIGN.md 精准地填补了一个空白。行业里已有的方案分两类：面向人的（Figma Variables、Storybook、设计规范文档）和面向构建工具的（Style Dictionary、W3C Design Tokens）。前者 AI 读不精确，后者缺少设计意图。DESIGN.md 恰好卡在中间层。Google 自家 Stitch 设计平台已经在用这套格式，社区也迅速跟进。awesome-design-md 仓库收录了 70+ 个真实品牌反编译的 DESIGN.md 文件，从 Apple 到 Claude 到 Notion 的风格都能直接拿来用。
但光看规格漂亮还不够，实际能不能跑起来才是关键。
上手什么感觉
安装本身不复杂，一行就搞定：
npm install @google/design.md
不过 Windows 用户会遇到一个小麻烦。因为 design.md 这个文件名在系统里会被识别为 Markdown 文件关联，用 npx 调用时得用 designmd 这个别名：
npx @google/design.md lint DESIGN.md
但你不会一上来就去装 CLI。更好的上手方式是直接看社区里已有的 DESIGN.md 文件。awesome-design-md 仓库有 70+ 个品牌的现成文件，找一个跟你项目风格接近的复制到项目根目录里，改改颜色和字体就能用。下面这个最小示例来自项目自带的 Heritage 设计系统：
---
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
components:
button-primary:
backgroundColor: "{colors.tertiary}"
textColor: "{colors.neutral}"
rounded: "{rounded.md}"
---
写完跑个 lint 验证 Token 引用有没有断开、颜色对比度够不够。导出到 Tailwind 也直接：
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
有几个实际的坑。项目还在 alpha 阶段（当前 v0.4.0），规范格式可能会变，现在深度集成的代码未来可能需要改。Issue #13（多主题/暗色模式支持）是目前最大的功能缺口，用了 4 个月还没解决。Monorepo 里想给不同子项目配不同主题会比较麻烦。
另外，DESIGN.md 不会自动让 AI 写出好看的 UI。如果你在 prose 里只写了”现代、简洁、高级”这种空话，Agent 拿到以后帮不了你太多。写 prose 这件事本身需要设计判断力，不是纯技术活。这是它推广过程中最大的隐性门槛：设计水平好的人本来也不缺这个文件，不太会的人写了效果也有限。
但说了这么多怎么用，什么场景用、什么场景别用才是更要紧的问题。
什么时候用，什么时候别用
| 场景 | 典型用户 | 优势 | 局限 |
|---|---|---|---|
| AI Agent 辅助前端开发 | 用 Cursor、Claude Code 写 UI 的开发者 | 一次配置，所有 Agent 统一输出 | prose 质量直接影响效果 |
| 小团队没有专职设计师 | 全栈开发者、独立黑客 | 从 awesome-design-md 抄一份就能用 | 复杂交互逻辑仍需人工判断 |
| 多 Agent 协作项目 | 使用 MCP + 多个编程 Agent 的团队 | 所有 Agent 共享同一份设计事实源 | 格式还在 alpha，未来可能 breaking change |
| 设计系统文档化 | 已有设计系统的团队 | 作为 Figma、Storybook 的补充层 | 需要额外维护，注意与现有资产的对齐 |
不适用的情况：
-
你只写少量页面、不追求视觉一致性 → 直接在 Prompt 里描述风格更省事 -
已有成熟组件库和 Storybook，设计很少变动 → 等 v1.0 稳定再说，目前 alpha 格式还不锁定 -
需要暗色模式或动态主题 → 等 Issue #13 解决，目前只能单主题，这是最痛的硬伤
项目热度确实在线，但社区健康度得拆开看看。
社区怎么样了
| 指标 | 数据 | 说明 |
|---|---|---|
| Stars | ~26,000+（截至 2026 年 8 月） | 4 个月增长，设计系统赛道现象级 |
| 核心维护者 | 3 人（David East + Matt Van Horn + 1） | Bus Factor 中等，David East 占约 42% 提交 |
| Open Issues | 活跃讨论中 | 主要围绕多主题、扩展 Token 类型等 |
| 协议 | Apache 2.0 | 商业友好，无 copyleft 限制 |
David East 的背景让这个项目多了一层可信度。他是 Firebase 圈的 DevRel 传奇，做过 Firebase 团队 Lead，YouTube 上做了多年的 Firecasts 系列教程。离开 Firebase 后他主导了 Google Stitch 这个 AI 设计工具，DESIGN.md 是其中抽出来的开源组件。他在开发者社区的影响力，是这个项目能在 4 个月内冲到这个热度的重要原因。
Issue 区讨论质量不低。功能需求和规范本身的讨论各占一半，社区对”这份文件应该管什么、不该管什么”的边界有共识。PR #161（v0.4.0 release）标注了规范的最新变化，但在多主题这个核心功能上进展缓慢。
Reddit 和 HackerNews 上有比较典型的讨论：“它不会自动让你的 AI 写出更好看的 UI，但它会让你写的 Prompt 从一个模糊的描述变成一个确定的文件”。这句评价其实很准。DESIGN.md 不是魔法，它就是一个确定的设计事实源。跟 Meta 同期推出的 Astryx 对比，两者的出发点相同但路径不同。Astryx 是 MCP Server + React 组件库，让 Agent 在 150+ 组件里挑。DESIGN.md 更轻，纯 Markdown，不依赖框架和运行时。如果你的技术栈是 React，可以两个都用。如果是 Vue 或 Svelte，DESIGN.md 目前是唯一的 AI 设计上下文方案。
不过热度归热度，有几个容易踩的坑得提前聊透。
我的真实看法
我对这个项目的判断不是”很棒”或”一般”，而是”时机对了”。AI 编程 Agent 从前端生成 UI 的需求正在爆发，而设计系统这块的标准化远远落后于代码生成本身。DESIGN.md 不是一个技术上特别深奥的项目，它的核心贡献不是技术突破，而是把两个已有的东西（YAML Token 和 Markdown 文档）用 AI Agent 能消费的方式组合在一起。这件事说起来简单，但在它之前没人系统性地做过。
但有一个很容易被低估的风险。DESIGN.md 的价值高度依赖 prose 的质量。一份只有 Token 没有 prose 的 DESIGN.md，跟一个普通的 JSON 设计 Token 文件没区别。Prose 的作用是给 Agent 做设计的判断依据，不是装饰性文案。如果你写 prose 的能力停留在”现代、简洁、高级”这种层级，效果跟直接写 Prompt 差别不大。用具体描述替代形容词，这是用好 DESIGN.md 的第一条准则。比如不要说”专业感”，直接写”不要渐变、不要阴影、大面积留白、只用一种强调色”。
比较现实的预期：别指望它替代 Figma 或组件库，把它当一个 Agent 可读的设计上下文文件用。项目还在 alpha，现在 fork 或深度定制为时尚早。但复制一份去试试的成本几乎为零，npm install 加上 30 行 YAML。十分钟内你就能知道它适不适合你的 workflow，比看任何评测文章都靠谱。
另一个观察：Google Stitch 的存在让 DESIGN.md 的长期存活概率远高于一般实验室项目。Stitch 是 Google 自己的 AI 设计平台，DESIGN.md 是它的核心输出格式。只要 Stitch 不关停，这份规范就会持续维护。对于还在犹豫要不要在项目里引入的人来说，这是个重要信号。Meta 的 Astryx 和社区里的 awesome-design-md 也说明这个方向不是 Google 一家的独舞。
资源地址
说到这只剩一个问题了：你要不要在自己的项目里用 DESIGN.md？
先跑起来，10 分钟的事
如果你已经在用 AI Agent 写前端，别等。找一个风格接近的 DESIGN.md 从 awesome-design-md 复制过来，改掉颜色和字体，放到项目根目录里。然后让 Agent 读这个文件再生成页面。
如果你还在观望，关注两个指标：Issue #13（多主题支持）的合并时间，和规范是否在 v1.0 正式发布时锁定格式。这两点决定了 DESIGN.md 能不能从一个好用的探索工具变成团队级的基础设施。说实话，我更期待的不是它本身，而是它打开的方向。未来每个项目根目录里可能不只有 README 和 CONTRIBUTING，还有给 Agent 读的设计说明、架构说明、测试说明。DESIGN.md 只是第一块砖。
四个月前没人想过要给 AI 写一本设计说明书。现在这本说明书有 26,000 人关心了。如果你试过效果不错、或者踩了坑翻车了，去 Issue 区看看，那里有跟你在同一条船上的开发者。AI 写代码的时代，设计从”画出来”变成了”写出来”，这份规范不过是个有意思的开头。