什么是编程智能体的 design.md？
design.md 为编程智能体提供了一种理解设计系统的结构化方式。以下是它对 AI 生成 UI 工作流的重要意义。
我是 Dora。上周我让 Claude Code 为一个个人项目新增三个页面。到第二个页面时，按钮圆角已经偏移，标题字体悄悄变了，“次要”灰色也变成了另一种灰。提示词结构相同，模型相同，会话相同。输出就是不在乎之前发生了什么。
这正是coding agent 的 design.md试图消除的摩擦。它是一个普通的 Markdown 文件，以 AI agent 每次生成 UI 时都能读取的格式保存你的设计系统——不是一次性提示词，而是持久化的上下文。Stitch 读它，Claude Code 读它，Cursor 读它，任何从仓库根目录获取上下文文件的工具都能读它。
design.md 是什么，为何由 Google Labs 发布
文件格式与设计系统角色
DESIGN.md 文件是叠加在一起的两层内容。顶部是 YAML 前置数据——颜色、排版、间距、圆角、组件——以结构化的 token 形式书写。下方是 Markdown 散文，解释这些 token 的用途和使用方式。Token 为 agent 提供精确的值，散文告诉它这些值存在的原因。
以下是前置数据的大致样式，摘自 GitHub 上的官方 DESIGN.md 规范：
yaml
---
version: alpha
name: Heritage
colors:
primary: "#1A1C1E"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 48px
fontWeight: 600
lineHeight: 1.1
rounded:
sm: 4px
spacing:
sm: 8px
md: 16px
---下方是普通 Markdown 格式的 ## 概述、## 颜色、## 排版。章节顺序固定——概述、颜色、排版、布局、高度与深度、形状、组件、注意事项。章节可以跳过，但已有的章节必须按该顺序出现。重复的章节标题属于错误，会导致文件被拒绝。
Token 引用语法来自 W3C 设计 Token 格式模块——花括号路径，如 {colors.primary}。引用必须指向原始值（而非组），但在组件章节内部，允许对排版 token 进行复合引用。当前规范中颜色值仅支持 SRGB 十六进制。Display P3 和 Oklch——均受 W3C DTCG 2025.10 稳定规范支持——目前尚不被 DESIGN.md 支持，仓库通过 version: alpha 标记明确说明了这一点。如果你维护宽色域 token，这一点值得注意。
该格式附带一个 CLI——npm 上的 @google/design.md。npx @google/design.md lint 针对解析后的文件运行七条规则。我最常遇到的两条：broken-ref（错误级别）捕获无法解析的 token 引用，contrast-ratio（警告）检查组件的 backgroundColor/textColor 组合是否符合 WCAG AA 的 4.5:1 最低要求。另外三条——missing-primary、orphaned-tokens 和结构规则——会暴露大多数团队在编辑文件一周内引入的问题。CLI 还提供 diff（版本间 token 级别的回归对比）和 export（Tailwind v3 配置、Tailwind v4 @theme CSS 或 W3C DTCG JSON）。
持久化视觉上下文对 coding agent 的重要性
问题很简单。如果不给 agent 提供结构化的内容来读取，它在生成 UI 时对你的设计系统毫无记忆。你可以在提示词中描述你的调色板，得到一个按钮，然后请求一张卡片，却发现间距逻辑已经重置。模型写代码的能力并没有问题，它只是没有锚点。
design.md 就是那个锚点。Stitch 在每次生成请求时将其作为上下文传入。Claude Code 和 Cursor 获取它的方式，与获取 CLAUDE.md 或 AGENTS.md 相同——这是一个放在仓库根目录、agent 在回答前会读取的文件。Google 在开源公告中的表述是，这让 agent 能够”确切知道一种颜色的用途”，而不是从提示词中猜测意图。
我在两个项目上都测试了这一点。流程如下：在根目录放置一个 DESIGN.md，重新生成我之前出现漂移的五个页面（落地页、定价、注册、仪表盘、设置），然后对照前置数据统计 token 违规次数。有文件存在时，Claude Code 生成的 5/5 个页面都使用了精确的主色和第三色十六进制值以及声明的 rounded.sm。Cursor 生成了 4/5——仪表盘始终将卡片上的 rounded.sm（4px）覆盖为 rounded.md（8px），而 DESIGN.md 散文中没有明确禁止这一点。在”注意事项”中添加一行——“卡片圆角使用 rounded.sm，永不使用 rounded.md”——在下次重新生成时修复了这个问题。
它真正解决的问题：AI UI 生成中的一致性
跨页面与跨迭代的一致性
之前那次会话出问题的不是某个页面的质量。每个单独的页面看起来都不错。第二个页面不知道第一个页面做了什么决定。每次生成都从对”你的品牌”略有不同的解读开始。
这正是 design.md 针对的失败模式。不是”让 UI 更好看”——而是让每次生成的结果是同一套 UI。Token 是规范性的。当前置数据写明 tertiary: "#B8422E" 时，agent 没有余地将其解读为”暖橙色”。要么是那个十六进制值，要么就是错的，lint 会这样告诉你。
对于高频工作流——每周五个、十个、二十个页面，并且有人在维护它们——这比首次输出质量更重要。规模扩大后，每个页面一个不一致就变成了一项清理工作。Coding agent 设计 token，在文件中一次性定义，在清理工作开始之前就将其扼杀。
为何散文加 token 比单纯的 token 更强
我几乎忽略了这部分。既然十六进制值已经在 YAML 里了，为什么还要写”Boston Clay 是唯一的交互驱动色”这样的段落？
因为 agent 使用散文来处理 token 未能覆盖的判断。Token 说第三色是 #B8422E。散文说这种颜色仅用于交互——不用于装饰性强调，不用于标题。当提示词模糊不清时（“添加一个通知徽章”），散文决定徽章是用交互色还是中性色。在上面我的 Cursor 测试中，缺失的散文约束正是仪表盘漂移的原因。
同样的逻辑适用于注意事项——像”卡片上永远不要使用投影”或”按钮标签始终使用句子大小写”这样的明确约束。负面约束承载着纯粹的 token 无法表达的分量。这是为 agent 设计的设计规范，不是 CSS 文件。
该格式不绑定于 Stitch。规范是 Apache 2.0 授权，CLI 在 npm 上，DTCG 导出意味着 token 可以流入任何读取 W3C 标准的工具，社区已经在行动。VoltAgent 的精选 design.md 合集——收录了品牌灵感 DESIGN.md 文件——在发布后数周内就超过了 71,000 个 GitHub Star，design-md GitHub 话题现在列出了来自 Google 以外的提取工具、Chrome 扩展和配套 SKILL.md 注册表。采用度才是判断一种格式是否真实存在的依据。
谁应该关注 design.md
坦诚说明其边界，因为 design.md 并不普遍适用。
它值得使用，如果：
- 你至少每周使用 coding agent 生成 UI，且涉及多个页面
- 你有一套设计系统——哪怕是很精简的——希望在每次生成中保持一致
- 你使用多个 agent 或工具，希望在所有工具中保持相同的品牌上下文
- 你厌倦了在每个提示词中粘贴”记住我们的调色板是 X、Y、Z”
它不值得使用，如果：
- 你只生成一次性原型然后丢弃
- 你的”设计系统”就是 agent 这次生成的任何东西
- 你在以 Figma 为主导、通过 Style Dictionary 或类似工具构建成熟 DTCG 流程的工作流中——design.md 比你现有的方案更轻量，使用它是一种降级
- 你今天就需要宽色域颜色（Display P3、Oklch）——当前 alpha 规范仅支持 SRGB
对于同时运行 design.md 和其他 AI 工作流文件（CLAUDE.md、AGENTS.md）的 AI 原生产品团队，它能干净地融入其中。每种关注点一个 Markdown 文件，无需构建步骤，无需与 JSON schema 较劲。尝试它的成本只是在仓库根目录放一个文件，再运行一条 lint 命令。
对于构建 agent 驱动生成界面的平台——包括将请求路由到多个模型、需要品牌上下文在每次调用中保持一致的统一 AI 生成层——design.md 是生态系统中最接近品牌与 agent 之间可移植契约的东西。根据Google Labs 公告，该格式的构建初衷就是可跨工具导出和导入。可移植性才是关键所在。
常见问题
design.md 有什么用？
它是一个 Markdown 文件，为 coding agent 提供关于设计系统的持久化上下文——颜色、排版、间距、组件，以及解释如何应用它们的散文。Agent 每次生成 UI 时都会读取它，因此输出在跨页面和跨会话时保持一致，无需你在每个提示词中重新指定品牌规则。
它只适用于 Google Stitch 工作流吗？
不。该格式源于 Stitch，但 Google 已在 Apache 2.0 授权下开源了规范。任何读取上下文文件的 AI 工具——Claude Code、Cursor、GitHub Copilot、Antigravity、Gemini CLI——都可以使用它。CLI 可导出为 Tailwind 配置、CSS 变量或 W3C DTCG JSON，因此 token 也可以流入非 agent 工具。
为什么 AI 生成的 UI 需要设计系统文件？
因为模型在不同生成之间对你的品牌没有记忆。没有结构化的 AI 设计系统文件，每个提示词都会从头重新解读你的设计语言。有了它，token 充当硬性约束，散文覆盖判断性决策。这种差异在规模上最为明显——用 design.md 生成的五个页面风格统一；没有它生成的五个页面则会漂移。
哪些团队应该率先尝试？
已经在每周使用 coding agent 生成 UI 的团队。使用 Claude Code 或 Cursor 的独立开发者和小型产品团队受益最快——把文件放进去，重新生成，看到一致性。拥有成熟 Figma + Style Dictionary 流程的大型团队应将 design.md 视为补充而非替代：用它为 agent 提供现有系统的一个可消化的子集。
结语
design.md 不是一种革命性的文件格式。它是一个顶部有 YAML 的 Markdown 文件。这正是重点——LLM 读得最好的格式，是它训练时见得最多的格式，那就是纯文本。
它真正做的是将问题从”我如何在这个提示词中描述我的设计”转变为”我的设计放在哪里，让每个 agent 都能读到它”。一个文件，一个位置，每个获取它的工具得到相同的答案。少一件需要重新指定的事情。听起来很小，积累起来很快。
我在两个项目中使用它已经一周了。它有效。长期来看——团队是否会像维护真正的设计系统一样严格维护这些文件，还是像 README 一样腐化——这还有待验证。在你自己的项目上运行一下。那会告诉你比我说的任何话都更多的东西。
往期文章：
