DESIGN.md 正迅速成为 AI 辅助 UI 设计项目中最有价值的文件之一。本文将分享帮助你为产品打造高质量 DESIGN.md 文件的实践经验。
什么是 DESIGN.md 以及为什么重要
DESIGN.md 是一个纯文本文件，用于描述产品的视觉身份，并为 AI 工具提供持久性的结构化指导，帮助其理解产品的外观和交互方式。这个文件基于现有的设计系统，因此特别实用：AI 不需要从零开始发明样式，而是可以直接依赖团队已有的视觉设计决策、设计令牌和组件规则。
DESIGN.md 最初在 Google Stitch 中引入，随后作为开放规范发布。Google Stitch 团队希望通过这个文件，让 AI 将设计决策建立在现有的设计系统之上，而不是生成毫无根据的抽象界面。这种开放格式使得这一理念可以在其他 AI 辅助设计和开发工作流程中复用。
DESIGN.md 结构
DESIGN.md 是一个 markdown 文件，包含定义产品外观和行为的信息。该文件由几层构成：
YAML 前置元数据
YAML 前置元数据包含两部分：
- 设计系统名称（在我这里是"Roxy Tech Modernism"）
- 原子级别的视觉决策设计令牌，如颜色、排版、圆角半径和间距。
---
name: Roxy Tech Modernism
colors:
surface: '[#f9f9ff](#f9f9ff)'
surface-dim: '[#d3daea](#d3daea)'
primary: '[#3525cd](#3525cd)'
inverse-primary: '[#c3c0ff](#c3c0ff)'
secondary: '[#c3c0ff](#c3c0ff)'
...
typography:
display:
fontFamily: Inter
..
rounded:
sm: 0.25rem
DEFAULT: 0.5rem
md: 0.75rem
...
spacing:
base: 4px
xs: 0.25rem
---
Markdown 正文
接下来是 Markdown 正文，通常包括以下几个部分：
- 品牌与风格：解释品牌应该被感知的方式。
- 颜色、排版、间距和形状：解释系统中使用的视觉样式。
- 组件：解释如何根据上面定义的令牌和视觉规则构建 UI 组件。
每个部分都应该描述产品的外观和感觉，并且尽可能引用 YAML 前置元数据中定义的令牌。这有助于减少设计偏差，因为 AI 可以将人类可读的指导与确切的令牌值联系起来。
你可以看到颜色部分中的"Deep Indigo"使用了上面定义的"primary"值。
---
## Brand & Style
The brand identity focuses on reliability, clarity, and effortless efficiency.
The design system adopts a **Corporate / Modern** aesthetic that leans heavily
into **Minimalism**. The objective is to reduce cognitive load by utilizing
generous whitespace and a restricted color palette, ensuring the user feels
a sense of calm and control.
...
## Colors
The palette is anchored by Deep Indigo (`primary`),
which serves as the main brand color and the primary action color.
Use Deep Indigo for primary buttons,
selected states, and key calls to action.
Do not use it for large background areas,
decorative illustrations, or
secondary content, because it can overpower the interface.
- **Primary:** Deep Indigo for core UI elements.
...
## Components
- **Buttons:** Primary buttons use a Deep Indigo fill
with white text. Secondary buttons use a Teal outline (`secondary`).
Padding should be consistent (e.g., (`base`)).
DESIGN.md 最佳实践
DESIGN.md 的核心理念很简单：它应该让任何阅读它的人——无论是人类还是 AI ——都能清晰理解产品的设计意图。对于 AI 来说，这提供了一个关键要素：context。无论使用哪种 AI 工具进行 UI 生成——Google Stitch、Claude Code 或 Cursor——都能基于实际的设计系统做出决策，而不是依赖通用默认值。
DESIGN.md 应该讲述你的产品故事。
以下是打造优质 DESIGN.md 的三个关键原则：
1、令牌代表决策，而非变量
DESIGN.md 文件中的每个令牌都代表一个设计决策。
例如，当使用
primary
这样的令牌名称时，我们不仅是在命名一种颜色，更在定义它在界面中的角色。AI 会根据令牌名称做出假设，因此 Markdown 正文需要澄清每个令牌的意图、使用场景和限制。
避免仅从外观命名令牌，如
blue或
gray-1。这些名称描述颜色的外观，但无法传达其在设计中的作用。相反，使用基于角色的名称，如
primary、
surface、
surface-dim、
border-subtle、
text-muted或
radius-card。
---
name: Roxy Tech Modernism
colors:
primary: '[#3525cd](#3525cd)'
在处理令牌部分时，这是一次很好的机会进行视觉审计，确定产品真正需要的令牌。例如在审计颜色后，可以移除：
- 不必要的颜色（系统中未使用的颜色）
- 重复的（服务相同目的的相似颜色）
- 不相关的颜色（在设计中被误用的颜色）
这一切都源于将令牌视为设计决策而非简单的变量。
2、设计决策需要推理
拥有设计决策后，下一步是添加推理。可以这样理解：
原始样式值（如 HEX 颜色） → 使用该值的意图（目的） → 推理（为什么和如何） → 约束边界（何时使用和何时不使用）
不要忽略最后一部分——约束边界，因为它告诉 AI 何时不应使用特定样式。
参考 DESIGN.md 正文中的颜色部分：
## Colors
调色板以 Deep Indigo (`primary`) 为核心，
作为主要品牌色和主要操作色。
将 Deep Indigo 用于主要按钮、
选中状态和关键行动号召。
不要用于大面积背景、
装饰性插图或
辅助内容，因为会过于抢眼。
..
- **Primary:** Deep Indigo for core UI elements.
它不仅解释了颜色的使用方式，更重要的是提供了具体的颜色值（Deep Indigo)，而不仅是一般性描述。
---
name: Roxy Tech Modernism
colors:
surface: '[#f9f9ff](#f9f9ff)'
surface-dim: '[#d3daea](#d3daea)'
primary: '[#3525cd](#3525cd)'
...
这有助于减少设计系统与 AI 生成内容之间的偏差，因为 AI 能够更清晰地理解what、why和how。
3、在令牌和设计决策之上构建组件
组件是 DESIGN.md 的最后一部分，建立在之前提供的令牌和推理之上。例如，按钮组件应用了 Deep Indigo 颜色的推理（Deep Indigo）。
## Components
- **Buttons:** Primary buttons use a Deep Indigo fill with { colors.white } text.
Secondary buttons use a Teal outline or subtle gray ghost style.
Padding should be consistent (e.g., {base}).
许多 DESIGN.md 文件只描述组件的默认状态这远远不够，AI 还需要各组件的所有可能状态指导。以按钮为例，应该明确其默认、悬停、激活、禁用、加载和焦点状态。
上面是使用 DESIGN.md 从 Google Stitch 生成的输出示例。
总结
DESIGN.md 不是另一个设计文档，而是连接设计系统和 AI 生成之间的桥梁。它的价值不在于格式多么完美，而在于是否真正传递了设计决策的意图。
回顾本文的三个原则：令牌代表决策而非变量；设计决策需要推理；组件建立在令牌之上。这其实是一个从抽象到具体、从一般到特殊的过程。只有这样层层递进、逻辑清晰的结构，AI 才能真正理解你的设计，而不是在你的设计系统外瞎猜。
如果你还没有为项目创建 DESIGN.md，不妨从现有的设计系统入手，提取关键令牌和组件规范，逐步完善。这个过程本身就是一次设计审查，有助于发现和消除系统中的不一致和冗余。
当 AI 生成的结果逐渐贴近你的预期，你就会体会到 DESIGN.md 的价值。
by Nick Babich