DESIGN.md 必备的 9 个部分

AI 编程智能体擅长写代码。但它们在保持视觉一致性方面表现糟糕。

我的新应用写了五页之后，我有了五套不同的设计系统。每个页面单独看都还不错。干净的布局、合理的颜色、现代感。但按钮不匹配。灰色在漂移。间距没有共享逻辑。单独看都精致，合在一起却不协调。

我的 CLAUDE.md 告诉智能体如何编程。它没有告诉智能体如何看。

每个使用 AI 构建 UI 的设计师和开发者都会撞上同一堵墙。代码能用。页面不匹配。

2026 年 4 月 21 日，Google 开源了一个名为 DESIGN.md 的规范——一种用 AI 智能体能原生读取的方式描述设计系统的 Markdown 格式。没有依赖、没有 API、没有构建步骤。只有纯文本。

然后 VoltAgent 的 awesome-design-md 采用该格式并在此基础上构建了 423 个品牌设计系统的集合。五周内获得 70,000 个 GitHub 星。

70,000 名开发者选择了 Markdown 文件，而不是他们的 Figma 插件、设计令牌管道和截图工作流。这个数字告诉你 AI 生成 UI 的真正瓶颈在哪里。

1、社区实际诊断出了什么

模型并不擅长设计。它们擅长的是设计记忆。

让 Claude Code 构建一个登录页面，它会生成干净的东西。让它接下来构建仪表板，它从头开始。新的颜色选择、新的间距、新的按钮样式。不是因为第一个是错的，而是因为智能体不记得它们。每个提示词都是一张白纸。

这不是一个单独的问题。这是三个不同的失败模式，在项目中不断累积。

Bootstrap 默认值。 没有任何设计上下文，智能体会收敛到相同的外观：白色背景、蓝色主按钮、灰色文本、4px 圆角、系统字体栈。它不难看。它太通用。你的应用看起来和所有其他 AI 生成的应用一样。你的品牌消失在 Tailwind 默认值中。

颜色轮盘赌。 智能体为每个元素选择合理的颜色，但这些选择不构成系统。红色在一个页面上作为装饰强调出现，在另一个页面上作为错误指示器。三个不同的绿色用于三个不同的功能。每种颜色都是单独合理的，但整体看起来像是从调色板中随机挑选的。

风格漂移。 这是开发者抱怨最多的。同一个智能体在不同对话中为同一个应用生成不同的设计。一个会话是圆角，下一个是方角。周一是 8px 间距，周二是 16px。即使是同一个按钮在不同对话中看起来也不同。智能体不是故意不一致。它只是没有关于"你的设计"应该是什么样子的持久参考。

这些不是 bug。模型完全是在按你预期的方式工作——一个没有持久设计上下文的系统。

它们生成合理的默认值，而合理的默认值会漂移。

问题是最低限度的设计上下文是什么样的。社区的答案恰好是 Markdown 的九个章节。

2、70,000 颗星给了一个文本文件

修复不一致 AI 设计的不是更好的模型。而是更好的简报。

设计师几十年来就知道这一点。每个设计系统，从 IBM 的 Carbon 到 Shopify 的 Polaris，都编码了同一个核心理念：一致性来自共享约束，不是共享品味。

颜色角色，不是颜色偏好。间距比例，不是间距猜测。每个页面都遵守的排版层级，不是当下感觉对的字体选择。

问题是这些系统都不说 AI 智能体能读懂的语言。设计令牌存在于 JSON 管道中。品牌指南存在于 Figma 中。风格决策存在于设计师的脑海中。当你要求 AI 智能体构建页面时，它无法访问任何这些。它从零开始。

DESIGN.md 通过用 LLM 已经理解的一种格式——Markdown——编码设计系统来解决这个问题。Google 在 Stitch 内部开发了这个格式，并于 4 月 21 日以 Apache 2.0 许可开源了规范。他们声明的原则："受约束的 AI 产生比不受约束的 AI 更一致的输出。"

该格式同时捕获值和意图。YAML 中的令牌给智能体精确的十六进制代码和间距数值。Markdown 中的散文解释这些值为什么存在以及何时打破规则。一个 JSON 令牌文件说 "primary": "#635bff"。一个 DESIGN.md 说"Blurple 用于主要操作和信任信号，绝不用于装饰。"智能体得到了是什么以及判断上下文。

VoltAgent 的 awesome-design-md 采用这个格式并大放异彩。提取并格式化了 423 个品牌设计系统，从 Stripe 到 Linear 到 Notion 到 Vercel，每个都忠实提取，结构统一。五周内 70,000 颗星。

洞见不在于仓库本身。而在于其下的原则：使人类设计团队一致的相同约束也使 AI 智能体一致。 颜色角色。间距比例。排版层级。该做和不该做的事。

这些不是新想法。它们是新格式中的旧想法。

3、9 个章节

以下是九个章节，以 Stripe 的 DESIGN.md 作为贯穿示例。每个章节的存在是因为没有它，智能体会产生特定的、可预测的失败。

这些章节分为三个集群。前三个设定品牌。接下来三个构建组件。最后三个保持一切一致。

3.1 基础：设定品牌

1. 视觉主题与氛围 描述的是设计的感觉，不是数值。Stripe 的文件以"技术和奢华、精确和温暖"开头。没有这个，智能体没有北极星。它默认为通用的干净现代风格，因为那是最安全的选择。这个章节是将"一个仪表板"与"一个 Stripe 仪表板"区分开的东西。

2. 调色板与角色 是颜色轮盘赌消亡的地方。这个章节不仅列出十六进制值。它分配语义角色。Stripe 的文件映射了 7 个类别中的 30 多种颜色：主色、强调色、交互状态、中性色阶、表面、边框、阴影。关键词是角色。一个 JSON 设计令牌文件给你 "primary": "#635bff"。一个 DESIGN.md 给你"Blurple (#635bff) 用于主要操作和信任信号。绝不用于装饰，绝不用于错误状态。"智能体不仅知道颜色。它知道何时使用它，何时不使用。

这是值得花时间的章节。每种颜色都有一个工作描述，而不仅仅是十六进制代码。错误状态使用 Ruby (#ea2261)。成功使用 Emerald。背景使用精心分级的中性色。当智能体伸手拿颜色时，它有理由选择一个而不是另一个，而不是掷骰子。

3. 排版规则 防止使 AI 生成页面看起来业余的字体混乱。该章节定义了完整的层级：字体族、从 Display Hero (56px) 到 Nano (8px) 的 14+ 尺寸级别、字重、行高、字母间距，甚至 OpenType 特性。Stripe 的文件指定 weight 300 作为标志性标题字重，并明确说"标题绝不使用 700"。这就是那种防止智能体使用粗体黑体作为一切标题的约束。

3.2 组件：构建 UI

4. 组件样式 给智能体一个零件词汇表。带有悬停、活动、禁用和加载状态的按钮变体。带有圆角、阴影和边框值的卡片规格。输入框、徽章、导航模式。没有这个章节，每个按钮都是没有状态的蓝色矩形，每张卡片都是带有 box-shadow: 0 2px 4px rgba(0,0,0,0.1) 的白色盒子，没有东西感觉是可交互的。

5. 布局原则 定义了空间节奏。基础间距单位（Stripe 使用 8px）、最大内容宽度、网格结构、圆角比例、留白理念。这就是防止困扰 AI 生成布局的拥挤表单和不一致填充的东西。智能体学到间距不是任意的。它遵循一个比例。

6. 深度与高度 防止智能体粘贴在所有东西上的扁平、通用阴影。Stripe 的文件定义了从 Flat 到 Deep 的五级阴影系统，使用蓝灰色调阴影（绝不使用中性灰）。"蓝色调阴影，绝不使用中性色"的指令正是智能体在你明确说明时会可靠遵循、在不说明时会可靠忽略的那种约束。

3.3 护栏：保持一致

7. 该做和不该做的事 是反幻觉层。这是你告诉智能体什么不该做的地方，因为智能体被优化为产生合理的输出，而合理的输出经常以微妙的方式违反品牌规则。Stripe 的文件有八个该做的事和七个不该做的事。"绝不使用超过 8px 的圆角。""绝不使用药丸形按钮。""标题绝不使用粗字重。"这些正是智能体在没有被告知的情况下会做出的"合理"选择。

这个章节比大多数人预期的更重要。智能体在设计上不会狂野地幻觉。它们保守地幻觉。 它们伸手拿安全、熟悉的模式，而这些安全模式对你特定的品牌通常是错的。

药丸形按钮是一个完全合理的默认选择。它们只是不是 Stripe。该做和不该做的事章节是你编码"好设计"和"你的设计"之间差异的方式。

8. 响应式行为 定义了带有像素范围的断点、每种组件类型的折叠策略和触摸目标调整。没有它，移动端输出是桌面端挤进手机。导航不会折叠。排版不会缩放。在 1200px 看起来优雅的卡片在 375px 变得拥挤。这个章节告诉智能体移动端不是更小的桌面端。它是不同的设计上下文。

9. 智能体提示指南 解决了冷启动问题。它提供快速参考颜色代码、即用型组件提示和迭代清单，智能体可以直接插入其工作记忆。没有这个，每次新对话开始时，智能体都要重新解析完整的设计系统。这个章节是一个索引——一个预先消化的入口点，让智能体立即生效。

4、设计鸿沟

这就是当前 AI 编码的奇怪之处。模型可以推理 TypeScript 泛型，推断复杂的类型层级，并将 500 行函数重构为整洁的模块。但它们不能保持按钮在两个页面上是同一色调的蓝色。

这不是因为设计比代码更难。 而是因为工具在一个上面投入了一切，在另一个上面几乎没有投入。

代码有 CLAUDE.md、.cursorrules、copilot-instructions.md、代码检查器、格式化器、类型检查器、CI 管道。堆栈的每一层都告诉智能体什么是"正确的代码"。

设计什么都没有。没有等价的文件。没有护栏。没有持久的上下文。智能体在真空中生成每个页面，然后希望最好。

这就是设计鸿沟：AI 编码工具为代码一致性开发了深度基础设施，为视觉一致性开发了零基础设施。

模型在两者上同样有能力。工具链不是。

Google 开源 DESIGN.md 规范承认这个鸿沟是结构性的，不是暂时的。它不会通过让模型更聪明来弥合。GPT-5 写出比 GPT-4 更好的代码，但在没有设计上下文的情况下生成同样不一致的 UI。这个鸿沟是一个输入问题。 模型需要设计简报，就像它们需要编码指南一样。

Markdown 弥合这个鸿沟而其他格式没有的原因归结为智能体如何处理信息。JSON 中的设计令牌在相同语义内容上令牌成本高出 40-55%。而且它们只携带值，不携带推理。JSON 文件不能说"绝不将此颜色用于装饰。"Markdown 文件可以，而且智能体比遵循结构化数据更可靠地遵循散文指令。

这也是基于截图的方法不能扩展的原因。将参考图像粘贴到提示词中对单个组件有效，但它给智能体的是像素而不是原则。它可以尝试匹配视觉，但它不理解设计为什么看起来是那样的。改变屏幕尺寸、添加新的组件类型，智能体又在猜测了。DESIGN.md 给智能体的是推理，不仅仅是参考。

在你的项目中实际放什么

三条路径，取决于你从哪里开始。

路径 A：从集合中选择一个品牌。

最快的选项。浏览 awesome-design-md，找到一个与你的审美匹配的品牌，然后放入：

# 示例：使用 Stripe 的设计系统
curl -o DESIGN.md https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/stripe.com/DESIGN.md

423 个品牌可用。Stripe、Linear、Notion、Vercel、Airbnb、Spotify 以及数百个更多。这对于原型和副项目出奇地有效，当你想要精致的东西而不需要雇一个设计师时。

路径 B：从你现有的网站生成。

如果你已经有一个在线产品，Google Stitch 可以从你的 URL 自动提取 DESIGN.md。它免费，不需要账户。Stitch 读取你网站的 CSS，识别下面的设计系统，并输出一个结构化的 DESIGN.md 你可以放入你的仓库。

提取的文件不会完美。你会想要特别审查该做和不该做的事章节，因为 Stitch 推断它能观察到的规则但不能读取你设计师的心思。把它当作一个强有力的起点，而不是一个完成的规范。

路径 C：自己写。

你不需要在第一天就有全部九个章节。从四个开始：

1. 视觉主题与氛围 — 两句话描述感觉
2. 调色板与角色 — 你的主色、强调色、错误色和中性色及其语义角色
3. 组件样式 — 至少是按钮变体和卡片规格
4. 该做和不该做的事 — 智能体绝不应违反的五条规则

这四个章节覆盖了最高影响的失败模式。随着你遇到不一致之处，添加排版、布局和其余部分。一个不完整的 DESIGN.md 比没有好。

放在哪里： 项目根目录，紧挨着你的 CLAUDE.md 或 .cursorrules。智能体会自动拾取它。

5、9 个章节不够的地方

DESIGN.md 解决了上下文问题。它没有解决所有问题。

令牌成本是真实的。 一个完整的 DESIGN.md 每次查询大约消耗 30,000 个令牌。那是你的智能体无法用于代码推理的上下文窗口空间。JSON 设计令牌在大约少 80% 的令牌数中携带相同的值，但失去了意图层。对于上下文预算紧张的大型项目，你可能需要将 DESIGN.md 精简到四个基本章节（主题、颜色、组件、该做/不该做的事），并将其余部分留作智能体按需查阅的参考文档。

设计漂移尚未解决。 从在线网站提取的 DESIGN.md 是一个快照。当网站的设计演进时，文件会过时。你的在线 CSS 和你的 DESIGN.md 之间没有自动同步机制。必须有人手动更新文件，而在实践中，更新会滞后。这是设计令牌一直面临的版本控制挑战，只是换了一种新格式。

没有运行时强制执行。 智能体读取规范并尝试遵循它。但没有什么能阻止它在你的该做和不该做的事说"绝不超过 8px"时输出 border-radius: 16px。DESIGN.md 是指导，不是代码检查器。如果你需要硬性强制执行，你仍然需要 CSS 检查规则或之上的设计审查步骤。

团队扩展是一个协调问题。 一个开发者的 DESIGN.md 很容易。让 20 人的团队在他们的 Figma 工作流旁边维护一个 Markdown 文件是一个完全不同的挑战。大多数设计团队以 Figma 为优先，而不是 Markdown 为优先。在有更好的工具保持 DESIGN.md 和 Figma 同步之前，团队将面临两个真相来源的问题。

规范仍是 alpha 版。 Google 的官方规范是一个草案。缺失的部分包括动画和运动令牌、图标标准和无障碍检查。社区正在快速填补空白，但如果你需要运动设计或 WCAG 验证，你需要自己添加这些约束。

关于 70,000 颗星的一个诚实注记：它们是共鸣的信号，不是效果的证明。我们没有对照研究准确显示 DESIGN.md 相比没有文件的良好提示的智能体改善了多大程度的输出一致性。社区共识很强，但它是轶事的。在称其为定论之前，我想看到正式的基准测试。

6、视觉瓶颈

Markdown 文件集合上的 70,000 颗星告诉你产品公告没有说的东西：AI 辅助开发的瓶颈从来不是模型写 CSS 的能力。而是设计上下文。

模型可以生成任何你想要的视觉风格。它们可以产生 Stripe 的精确、Linear 的极简、Notion 的温暖。但前提是你告诉它们是哪一个。没有持久的设计简报，每个页面都是一次新的猜测。而新的猜测会漂移。

这与我们在代码行为上看到的模式相同。

• CLAUDE.md 的四条行为线不是通过让模型更聪明来解决编码瓶颈，而是通过给它约束。
• DESIGN.md 的九个章节不是通过让模型成为更好的设计师来解决设计瓶颈，而是通过给它上下文。

两者都击败了复杂的工具链。两者都有效，因为它们匹配了智能体实际消费信息的方式：以模型训练过的格式携带值和意图的结构化散文。

设计工具链竞赛——Figma 插件、令牌管道、Stitch 工作流——正在解决能力层。

但约束条件一直是上下文层。 你项目根目录中的一个 Markdown 文件。九个章节。没有依赖。

Google 开源规范标志着这种格式正走向标准。问题不是 AI 智能体会不会读取设计简报。它们已经在读了。问题是你的是否有一个。

如果你想开始，仓库在 github.com/VoltAgent/awesome-design-md。选一个品牌，放下文件，构建一个页面。差异在第一次渲染时就显现。

原文链接: The 9 Sections Every DESIGN.md Needs

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