google-labs-code/design.md：让 AI 编程助手真正「懂」你的设计系统

当 Claude Code、Cursor、Cline 这些 AI 编程助手越来越深入我们的开发流程，一个老问题始终没解决：你给 AI 一段 prompt 让它做页面，做出来的东西和你的设计系统完全对不上 —— 颜色不对、间距不对、字体不对、组件乱造。google-labs-code/design.md 就是 Google Labs 推出的解决方案：一份给 AI 看的「设计说明书」格式规范，让 coding agent 拥有对设计系统的持久、结构化、可验证的理解。

背景：AI 写前端总是不像你

过去一年，「vibe coding」火得一塌糊涂。但凡是真正把 AI 写出的前端代码合并进生产环境的工程师都会发现一个尴尬现实：

- AI 不知道你的主色是 #1a73e8 还是 #0f62fe，它给个 blue-500 就交差
- AI 不知道你的设计系统里有 Button、Card、Modal，它现造一套带 bg-gradient-to-r 的 div
- AI 不知道你团队的间距规范是 4px 网格，它随手来个 p-[13px]
- AI 不知道 dark mode 下哪些 token 要反转，它在 dark: 前缀下瞎猜

根本原因是：AI 看到的「设计」是散落在 Figma、Storybook、Notion 文档、Slack 历史消息里的碎片信息，没有一个机器可读的「single source of truth」。

design.md 想做的事情，就是把这个 single source of truth 标准化。

它是什么

design.md（仓库全名 google-labs-code/design.md）是一个格式规范，不是某个软件或库。它的核心是一个 Markdown 文件的 schema，告诉 AI：

1. 你的设计令牌（Design Tokens）是什么 —— 颜色、字体、间距、圆角、阴影
2. 你的组件清单是什么 —— Button、Input、Card 各长什么样、什么 props
3. 你的布局规则是什么 —— 栅格、断点、留白哲学
4. 你的品牌语言是什么 —— 语气、动效、icon 风格

整个规范本身就是一个 Markdown 文件，所以：

- 人类可读：设计师和产品经理能 review
- 机器可解析：Claude Code、Cursor 都能直接读取作为上下文
- 版本可控：放在 Git 仓库里，跟着代码一起 PR review
- 零运行时：不像 Tailwind Config 那样要编译

仓库目前已经有 17k+ stars，过去 24 小时新增 600+ star，是 Google Labs 在 AI Agent 工具链方向上最被关注的项目之一。

能做什么

具体来说，design.md 文件能被 coding agent 这样使用：

1. 写新组件时遵循设计系统

你在 Claude Code 里说「给我写一个订阅按钮」，AI 会去读 design.md，然后输出：

  Subscribe

而不是随手给你一个：

  Subscribe

2. 重构时保持视觉一致

让 AI 「把这一坨 div 改成用我们的设计系统重写」，AI 会查 design.md 里有哪些 token、有哪些组件，给出符合规范的输出。

3. Figma 到代码的桥梁

设计师在 Figma 里改了一版，AI 拿到 Figma 的 export 加上 design.md，能更准确地翻译成符合你团队代码库的代码（而不是给你一堆看起来像但用不了的 div）。

4. 多 agent 协作的公共上下文

Cursor、Claude Code、Codeium、Windsurf 都可以读到同一份 design.md，整个团队的 AI 助手对「设计」有统一的理解。

为什么值得

痛点足够真实

任何在前端项目里用过 AI 助手的人都被「AI 写的东西不像我们」折磨过。这个问题不会因为模型变强而自动消失 —— 模型再强也需要 ground truth。

来自 Google Labs 的官方背书

不是社区玩具，是 Google Labs 出品，和 Gemini CLI、Firebase Studio 这套 AI 开发工具链是同一个出处。规范的设计考虑了 Claude Code、Cursor 等主流 agent 的实际读取方式。

极其轻量

不引入新的构建工具、不需要新的包管理器、不需要 Figma 插件。一个 Markdown 文件 + 一份 agent 配置就行。可以渐进式采用 —— 先用 token 部分，组件部分慢慢补。

设计 / 工程协作的新接口

过去 design system 是工程师的事（写 Tailwind config、Storybook），设计师只能交 Figma。design.md 把设计系统变成一份人和 AI 都能读的文档，设计师能直接参与编辑和 review。

快速上手

design.md 的使用非常轻量。下面是一个最小可运行流程。

1. 写一份 design.md

在你的项目根目录新建 design.md：

# Project Design System
Tokens
Colors

- primary: #1a73e8
- secondary: #34a853
- danger: #d93025
- bg: #ffffff
- text-primary: #202124
Typography

- font-family: Inter, system-ui, sans-serif
- font-size-base: 16px
- line-height-base: 1.5
Spacing (4px grid)

- xs: 4px
- sm: 8px
- md: 16px
- lg: 24px
- xl: 32px
Components

- Button: variants [primary, secondary, ghost]; sizes [sm, md, lg]
- Input: border color text-primary 1px, radius 8px
- Card: bg white, shadow md, radius 12px, padding lg
Layout

- max-width: 1200px
- breakpoints: sm 640px, md 768px, lg 1024px, xl 1280px

2. 配置 agent 能读到它

Claude Code：在 CLAUDE.md 里加一句：

Read ./design.md before writing any UI code. Treat it as the source of truth for design tokens and component primitives.

Cursor：在 .cursorrules 里加同样一句。

Gemini CLI（Google 自家）：把 design.md 放到项目根目录，Gemini CLI 会自动加载。

3. 验证一下

让 agent 写个页面：「Make a pricing page with three tiers using our design system」。看看输出是不是真的用了 primary 颜色、4px 网格的间距、你的 Button 组件。

4. 配合 Docker 部署的 agent 工具

如果你想用 self-hosted 的 AI agent 来跑设计相关的工作流（比如审核 PR 里的 UI 代码是否符合 design.md），可以参考下面这个最小 docker-compose：

# docker-compose.yml for design-review-agent
version: "3.9"
services:
  reviewer:
    image: ghcr.io/google-labs-code/agent-template:latest
    volumes:
      - ./:/workspace
    environment:
      - DESIGN_MD=/workspace/design.md
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    command: ["agent", "review-ui", "--against", "design.md"]

docker compose up -d
docker compose logs -f reviewer

这只是一个示意 —— 核心思想是 design.md 作为挂载卷传给 agent，agent 读这份文件作为上下文执行任务。

适合谁

- 前端工程师 / 全栈工程师：受够了 AI 写的代码和你设计系统对不上
- 设计系统维护者：想让设计 token 真的成为跨人 / 跨 AI 的真理
- 创业团队 CTO / 技术负责人：想让 3 个工程师 + 5 个 AI agent 的小团队保持视觉一致性
- 独立开发者 / 副业项目：一个人的时候让 AI 严格按你的设计哲学来写
- 不适用：一次性 demo、纯后端项目、对视觉一致性没要求的内部工具

局限

- Markdown 是「软规范」，不是强类型 schema，AI 可能偶尔忽略。人类 review 仍然必要。
- 对小型项目有点 overkill —— 如果你只有 3 个页面，硬编码 Tailwind class 可能更直接。
- 目前生态还在早期，没有像 Tailwind Config 那样成熟的 IDE 提示和 lint 工具。

链接

- GitHub: https://github.com/google-labs-code/design.md
- 规范文档: https://github.com/google-labs-code/design.md/blob/main/README.md
- 配套示例: https://github.com/google-labs-code/design.md/tree/main/examples
- Google Labs: https://labs.google/

一句话总结

design.md 是给 AI 编程助手的「设计圣经」—— 一份放在 Git 里的 Markdown 规范，让 Claude Code、Cursor、Gemini CLI 这些 agent 在写前端时真的遵循你的设计系统，而不是每次都从零开始瞎猜。