DESIGN.md用纯文本描述产品的视觉身份，让AI锚定既有设计系统而非从零发明样式。从YAML前置的设计token，到品牌、颜色、组件等章节结构，这套由Google Stitch团队开源的规范，正成为AI辅助UI设计的标准配置。

DESIGN.md 正在迅速成为 AI 辅助 UI 设计项目中最实用的文件之一。在本文中，我将分享一系列最佳实践，帮助你为特定产品打磨出最优质的 DESIGN.md 文件。

什么是 DESIGN.md 及为什么重要

DESIGN.md 是一个纯文本文件，用于描述产品的视觉身份，为 AI 工具提供持久、结构化的设计指引——明确告诉 AI 产品应该长什么样、如何运作。它依托于团队已有的设计系统（design system），直接复用沉淀下来的视觉决策、设计token 和组件规则，让 AI 无需从零发明样式，输出即符合预期。

DESIGN.md 由 Google Stitch 团队引入，并作为文件规范开源。其设计初衷是让 AI 智能体（agent）将设计决策锚定于既有设计系统之上，而非输出空泛、抽象的通用 UI。由于采用开放格式，这套方法论能轻松复用到其他 AI 辅助设计与编码工作流中。

DESIGN.md 结构

DESIGN.md 是一个 markdown 文件，里面装着定义「你的设计长什么样、怎么运作」的信息…

下面是我在 Google Stitch 里为一个落地页设计用的 DESIGN.md 示例…

这个 markdown 文件由几层组成：

图：DESIGN.md层次结构

YAML frontmatter（又称前置数据或前辅文）

YAML frontmatter 由两部分组成：

1.设计系统名称（在我这里是「Roxy Tech Modernism」）

2.用于原子级视觉决策的设计 token，如颜色、字体、圆角半径和间距。

Markdown 正文

接下来是 Markdown 正文。这一部分通常包含以下章节：

1. 品牌与风格（Brand & Style）：解释品牌应该如何被感知。
2. 颜色、字体、间距与形状（Colors， Typography， Spacing， and Shapes）：解释系统中使用的视觉样式。
3. 组件（Components）：解释 UI 组件应如何基于上面定义的令牌和视觉规则构建。

每个章节都应描述产品的观感，并在可能的情况下引用 YAML frontmatter 中定义的 token …这能帮 AI 把「人话指引」和精确的 token 值连起来，从根上减少偏离…

你可以看到，Colors 章节里提到的「深靛蓝（Deep Indigo）」颜色，用的就是上面定义的 primary 值…

DESIGN.md 背后的核心思想其实很简单：它应该让任何阅读者——不管是人还是 AI 智能体——都能一眼看懂你的产品该如何呈现、如何运作…对 AI 智能体来说，它给的是最珍贵的东西：上下文（context）…

不管你是用 Google Stitch、Claude Code 还是 Cursor 生成 UI，智能体都能基于你的真实设计系统做决策，而不是套一堆通用默认值…

DESIGN.md 应该讲述你产品的故事…

下面这 3 条核心规则，照着做就能写出最好的 DESIGN.md：

1. Token 不只是变量，而是决策

DESIGN.md 里的每个 token 都代表一个设计决策…

比如我们用 primary 这个 token 名，不只是给颜色起名，而是在定义这个颜色在界面里扮演的角色…AI 会按 token 名做假设，所以 Markdown 正文要把每个token的意图、用途和边界讲清楚…

此外，别只按外观命名 token ，例如 blue 或 gray-1…这些命令只说了颜色长什么样，没说它在你设计里是什么角色…所以我们要基于功能来写命令，就比如：primary、surface、surface-dim、border-subtle、text-muted、radius-card…

写 token 这一节，你正好可以做一次视觉审计（visual audit），定下产品真正需要哪些 token …比如审完颜色，你可以干掉：

• 不必要的颜色（系统里根本没用的）
• 重复的颜色（用途撞车的）
• 无关的颜色（在设计里用错地方的）

这一切，都是因为你开始把 token 当作设计决策来对待…

2. 设计决策应该有理由

有了设计决策，下一步就是补理由。可以这样理解：

原始样式值（比如 HEX 颜色）→ 在设计中用它的意图（目的）→ 理由（为什么、怎么做）→ 约束与边界（什么时候用、什么时候不用）

当然最后别忘记约束与边界这一部分，它专门告诉 AI 智能体什么时候别用某种样式…

我们来看一下 DESIGN.md 正文里的 Colors 章节：

你会发现，它不光解释了颜色怎么用，更重要的是，不只给个「大概意思」，还给了应该用的实际颜色值（深靛蓝 Deep Indigo）…

这样能大幅减少「设计系统现状」和「AI 生成结果」之间的偏离——因为 AI 智能体对「什么、为什么、怎么做」理解得更透了…

3. 在token与设计决策之上构建组件

组件是 DESIGN.md 的最后一个章节，它建立在你前面给的 token 与理由之上…比如按钮组件，用的就是主色（深靛蓝 Deep Indigo）那套理由…

很多 DESIGN.md 只描述组件的默认状态，但这远远不够…AI 智能体还需要组件所有可能状态的指引…比如按钮，就要有清晰的默认（default）、悬停（hover）、激活（active）、禁用（disabled）、加载（loading）和聚焦（focus）状态…