DESIGN.md 给我带来的变化

我第一版 DESIGN.md 主要包含设计 token。颜色、字体比例、间距、圆角半径，全部从我们的 Figma 设计系统中提取。我把它放在项目根目录，在 CLAUDE.md 中引用它，然后让 Claude Code 生成一个设置页面。输出结果比之前略好——主色调对了，字体也对了。但 AI 把我们的品牌色用作信息横幅的背景色，应用到装饰分割线上，并给每张卡片都添加了我们在产品中从未使用过的柔和阴影效果。token 是对的，但设计决策是错的。

在添加 DESIGN.md 之前，项目已经有一个可用的 CLAUDE.md，包含编码规范、测试命令和文件夹结构。AI 知道如何按我们想要的方式编写 TypeScript，但它完全不知道我们的产品应该是什么样子。因此每个生成的界面都带有相同的通用 Tailwind 风格：到处都是圆角、靛蓝色调、均匀间距、带阴影的卡片——这些我们根本不用。功能齐全，但完全缺乏个性。

两周后，我在 Colors 部分添加了四句话。其中一句规定我们的主色（深青色）只能用于交互元素。另一句规定卡片应使用中性背景，没有高度感，只用最浅灰色的 1px 边框。下次我让 AI 生成界面时，主色只出现在 CTA 按钮上，别处没有。卡片变得平整、带边框、安静。看起来像是我们团队会构建的东西。

这次经历让区别变得具体。自 2026 年 4 月 Google Labs 开源该规范以来，这种格式已在每个产品 Twitter 账号上出现，很多报道关注的是 token 结构、YAML 模式、CLI 工具。那只是表面部分。真正让文件有效的是散文部分：那些解释意图、设置约束、告诉 AI 在哪里保持克制的句子。一个月的日常使用反复证实了这一点。

1、文件实际包含什么

DESIGN.md 是一个纯文本文件，放在代码仓库根目录，为 AI 编码代理提供生成与产品匹配的 UI 所需的设计系统上下文。README.md 向人类贡献者解释代码库，DESIGN.md 向 AI 代理解释设计系统。

文件分为两部分。上半部分是 YAML front matter（用 --- 行围起来的结构化数据格式），包含机器可读的设计 token：颜色的十六进制值、字体族和大小、间距比例、圆角半径和组件级样式。下半部分是 Markdown 正文，解释这些 token 为什么存在、何时使用，以及 AI 不应该做什么。

---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:
  sm: 4px
  md: 8px
---

YAML 下方的 Markdown 正文使用 ## 标题，按规定的顺序排列。token 格式基于 W3C Design Tokens 标准，因此值可跨工具移植，不锁定在 Google 的生态系统中。规范定义了八个部分：概述、颜色、排版、布局、层次、组件、注意事项和代理指令。并非所有部分都是必需的，但存在的部分应遵循此顺序，因为 LLM 从上到下读取。

如果你已经有 CLAUDE.md 或 AGENTS.md（Cursor、Zed 和其他 AI 工具的等效文件），DESIGN.md 并非替代品。CLAUDE.md 告诉 AI 如何作为开发者行事：编码规范、测试命令、文件夹结构。DESIGN.md 是完全不同的层面，涵盖产品外观以及为什么做出这些视觉选择。在我的设置中，CLAUDE.md 中的一行（"对于所有 UI 生成，请遵循 DESIGN.md 中的设计系统"）桥接了两个文件。需要明确的是，DESIGN.md 也不替代 Figma。Figma 处理实时协作和视觉优化，DESIGN.md 处理规范和向 AI 代理的交接。两者共存，覆盖产品过程的不同阶段。

2、仅 Token 的陷阱

这是我第一版犯的错误，也是大多数 DESIGN.md 文件的通病。token 是完整的，十六进制值在，字体比例在，间距网格在。文件看起来很全面，但 AI 仍然生成通用输出。

原因是 token 告诉 AI 值是什么，但没有解释它们的含义。我的主色 token 是 #0D7377，但它没有说"此颜色保留用于交互元素，绝不应用于背景、装饰分割线或信息横幅。"没有这个约束，AI 将该颜色视为通用强调色，应用到它认为需要强调的任何地方。token 在技术上是正确的，但意图全部错了。

我直接测试了这一点。我让 Claude 从我们的 Figma 文件和现有 CSS 生成 DESIGN.md。结果包含了所有测量值和数值，但缺少建立产品是什么、谁使用它以及 UI 必须始终（和绝不）做什么的推理。token 全在，设计思维完全缺失。这映射到我在产品工作中反复看到的情况：只列出值的设计系统文档就像只列出功能而不解释用户问题的 PRD。两者看起来都很完整，但都没有给读者足够的上下文来在文档未明确涵盖的情况下做出好的判断。而大多数 UI 生成恰恰涉及这些情况。

当我添加散文约束后，变化在几次生成内就变得明显。AI 不再装饰性地使用我们的主青色，不再在我们的设计语言刻意扁平时给卡片添加阴影。每个修复都直接追溯到我添加到 Markdown 正文中的一句话，而不是我更改的 YAML 中的 token。

3、改变我输出最多的部分

该规范（GitHub 上的 google-labs-code/design.md）在 Markdown 正文中定义了八个部分。并非所有部分贡献相等。实际上，前三个部分承担了我项目中约 80% 的改进工作。

概述

此部分设定产品的个性和视觉方向。目的是在 token 未涵盖特定情况时锚定 AI 的高层决策。

我最初跳过此部分，因为它感觉很空洞。那是错误的。没有概述，AI 会将每个 token 视为同等重要，并根据训练数据中最常见的内容做出风格选择。当我添加了两句话描述我们产品的视觉个性（"简洁、专业、信息密集、无装饰元素、无渐变"）后，生成界面的整体感觉发生了转变。AI 在留白、插图风格和视觉层次方面的任意选择减少了，因为它有了"符合品牌"的参考点。

颜色

YAML front matter 给出十六进制值。这里的散文解释每种颜色的用途：哪个是主操作颜色，哪个用于背景，哪个保留用于错误状态。语义命名在这里比任何地方都重要。primary: "#0D7377" 是一个 token，"保留用于交互元素，绝不用于装饰或背景"是一个设计决策。

颜色部分是我看到散文添加与输出变化之间最直接因果关系的地方。每次 AI 错误应用颜色，我就在本部分添加一句话，错误应用在下次生成中停止。一个月后，此部分的字数比文件中任何其他部分都多，而且大部分是约束。

注意事项

负面约束在此部分发挥作用，它们比看起来更强大。"绝不在交互元素上使用渐变。""不要在同一视图中混合圆角和尖角。""主色每个屏幕最多出现在一个 CTA 上。"

此部分完全源于观察 AI 犯错。AI 不断给我们的卡片添加微妙阴影，所以我添加了"卡片无阴影。使用 neutral-100 的 1px 边框进行包围。"它不断生成与主按钮视觉重量相同的次级按钮，所以我添加了"次级按钮应感觉安静：中性背景、微妙边框、无填充。"每一行有用的约束都追溯到输出偏离的特定生成。这个反馈循环使文件实用而非理想化。

其余五个部分（排版、布局、层次、组件、代理指令）重要程度各不相同，但前三个部分大约占我所见改进的 80%。

4、编写 AI 能实际使用的散文

散文是大多数文件不足的地方。一个有用的框架：假设你正在引导一个拥有完美 CSS 技能但对品牌毫无了解的前端开发者。那就是你的散文受众。

具体优于描述。"极简美学"不如"扁平设计、无渐变、neutral-200 中一致的 1px 边框、无装饰元素"有用。在我自己的文件中，我最初在概述部分写了"简洁现代"。这产生了与没有概述相同的通用输出。当我改为"信息密集、无装饰元素、无渐变、无插图、专业基调更接近金融终端而非消费应用"后，生成的界面变得明显更克制。

在影响决策的地方解释意图。当我在布局部分添加一句话解释我们的产品优先考虑信息密度而非留白时，AI 开始生成更紧凑的表格布局和更密集的表单字段，而无需我为每个组件指定像素值。意图比指令传播更远，因为它适用于文件未明确涵盖的情况。

涵盖边缘情况。空状态、错误消息、受限空间中的长文本、多行标签。AI 生成的 UI 在边缘情况上最容易失败，因为 AI 对不适合整齐的情况没有指导。我只在 AI 生成了一个空白白色屏幕、中心只有微小灰色"无数据"标签的 400px 空白后才添加了空状态指南。一句话（"空状态应包含描述性消息、相关时的微妙插图，以及解决状态的主要操作"）修复了后续每个生成的模式。如果你的系统对文本截断或加载状态行为有意见，请写下来。AI 不会猜对。

明确说明你不想要什么。"此颜色绝不应用于背景"比"此颜色用于交互元素"更可操作。LLM 似乎强烈重视负面约束，根据我的经验，"绝不做 X"的指令比"优先做 Y"的指令被更一致地遵循。这适用于每个部分，而不仅是注意事项部分。

保持简洁。这是配置文件，不是品牌圣经。AI 的上下文窗口（单次会话中可以推理的总文本量）是有限的，DESIGN.md 中的每个词都占据了可用于推理实际生成组件的空间。我的文件目前约 180 行。我修剪了两次，删除了没有发挥作用的句子。最有效的文件赢得了它们的长度。

5、将第一个文件放入仓库

文件放在仓库根目录，与 README.md 相邻。它像任何其他代码工件一样提交到版本控制，并通过拉取请求进行审查。对于 Claude Code，在 CLAUDE.md 中引用它就是所需的全部设置。对于其他代理（Cursor、Kiro、Windsurf），你在各自的配置文件中引用它。该格式与代理无关，因为它是纯 Markdown。

诱惑是让 Claude 为你生成文件。结果会很全面，但会缺少使文件有用的部分。自动生成的文件跳过建立产品上下文的问题。在我们的团队中，设计师指出次级按钮需要感觉低调而非张扬，这是自动生成文件完全错过的区别。从产品经理的角度，我知道入职流程应该感觉鼓励而非高效，这以 Figma 导出无法实现的方式塑造了概述。当我们的 QA 工程师在设备测试期间标记错误状态几乎不可见时，这成为了一个关于高对比度错误颜色的注意事项条目。这些都不会出现在自动导出的 token 转储中。

一个月后的建议：使用自动生成作为格式指南和 token 提取起点，然后自己重写散文。Google Stitch、VoltAgent/awesome-design-md 仓库和 designmd.app（按垂直领域和视觉风格索引超过 400 个文件）都是结构的有用参考。但使文件有效的散文来自了解产品的人。

无论选择哪条路，提交前运行 linter：

npx @google/design.md lint DESIGN.md

这会验证结构，捕获损坏的 token 引用，并检查 WCAG 颜色对比度以确保可访问性合规。

6、局限性和规范现状

Atlassian 发表了一篇详细文章，测试 DESIGN.md 与其专用 MCP 服务器（Model Context Protocol，连接 AI 代理与外部工具的标准）。对于生成登录屏幕等任务，DESIGN.md 需要大约多 92% 的 LLM 处理 token（衡量模型计算的单位，不是设计 token），且运行间差异约为 2.7 倍。Atlassian 自己描述这些结果为非结论性的，测试是在具有现有组件库和严格 linting 的生产代码库中进行的。对于没有这种基础设施的五人团队，Markdown 文件是可用的最高杠杆选项。

规范本身仍处于 alpha 阶段。动画、深色模式 token 和响应式断点都是空白。Google Stitch 原生支持 DESIGN.md，但 Claude Code、Cursor 和 Copilot 使用它仅仅是因为它们读取仓库中的 Markdown 文件，而不是因为它们具有一流的 DESIGN.md 解析。要使该格式成为行业标准，Figma 等工具需要提供原生支持。这尚未发生。

AI 也可能忽略该文件，特别是在复杂的多组件屏幕上。根据我的经验，它大约 85-90% 的时间遵循散文约束，这比没有文件有显著改善，但不是确定性的。审查生成的输出仍然很重要。

对于评估采用的团队：如果你正在用 Claude Code 或 Cursor 发布单个产品，回报很快显现。如果你运营具有既定 token 管道的多品牌设计组织，观察规范成熟一个季度是合理的。

7、一个月后我的文件样子

我的 DESIGN.md 自第一版以来已经改变形状。YAML front matter 几乎没变，Markdown 正文大约增加了三倍。

概述从空白增加到我重写了两次的三句话。第一版太模糊（"简洁现代"），第二版用听起来不错但没有给 AI 可操作内容的品牌哲学浪费了上下文窗口空间，当前版本是三个具体、明确的句子。颜色部分的约束句比描述句多。注意事项部分是文件中最长的部分，让我惊讶的是不同角色贡献了不同类型的约束。设计师添加了大部分颜色和排版规则。QA 驱动的条目关于对比度和触摸目标尺寸。产品经理的线条在概述中，定义产品在高层应该给人的感觉。文件在没有人计划的情况下成为了跨职能工件。

我们的新前端开发者在第一周阅读了该文件，说它比 Figma 库更清晰地展示我们的视觉方向，因为 Figma 库展示事物的外观，而 DESIGN.md 告诉他为什么。这不是我为 AI 代理编写的文件所期望的。它迫使我们写下通常留在人们头脑中的推理，那种团队中每个人都有但没有人记录的知识，因为感觉太明显了。事实证明，对新员工来说这并不明显，对 AI 模型来说肯定也不明显。

文件仍然无法做的事情。响应式行为是一个空白，我们的移动布局需要不同的间距和层次选择，当前规范没有清晰的方式表达。深色模式 token 未定义。AI 仍然偶尔在复杂屏幕上忽略该文件，生成遵循 token 字面意义但错过整体感觉的内容。我仍然在每个生成的屏幕接近 PR 之前审查它。

关于 DESIGN.md 是否使设计师不必要的争论错过了我使用它的基本观察。文件中有效的部分是设计师编写的部分：意图、约束、"这应该感觉安静而非张扬"的决策。提取 token 是机械的。知道要编写哪些约束以及为什么，需要理解产品和使用它的人。

下个月，我计划添加一个响应式行为部分，即使规范尚未正式支持它，因为我们的移动布局不断偏移。文件没有完成。我不确定它是否会完成。

原文链接：I Used DESIGN.md for 30 days With Claude Code. Here's What Actually Changed.

汇智网翻译整理，转载请标明出处