AI（人工智能）coding agent 写业务代码的能力越来越强，但一旦进入 UI（User Interface，用户界面）设计，问题就会很明显：页面能跑，样式也有，但经常不像一个完整产品。
常见表现包括：
- 同一个按钮在不同页面里颜色、圆角、阴影都不一致；
- 卡片间距靠模型临场发挥，有的地方很挤，有的地方很散；
- hover、active、disabled、focus 等状态缺失；
- 字体层级混乱，标题、副标题、正文没有稳定比例；
- 页面看起来像默认模板：紫色渐变、Inter 字体、卡片网格、圆角按钮。
这不是单纯把提示词写长就能解决的问题。根源在于：agent 缺少一份稳定、明确、可执行的视觉规范。
DESIGN.md 解决的就是这个问题。它把设计系统写成 Markdown 文件，让 Claude Code、Cursor 这类 AI coding agent 在生成页面时，不再凭空决定颜色、字号、间距和组件状态，而是按照项目里的设计规则来写代码。
DESIGN.md 是什么
DESIGN.md 可以理解成“写给 AI agent 看的设计系统说明书”。
传统项目里，工程侧常见的是 README.md、AGENTS.md、CLAUDE.md 这类文件，用来说明项目怎么安装、怎么构建、怎么测试、agent 该遵守哪些开发约定。DESIGN.md 的职责不同，它描述的是项目“应该长什么样”。
| 文件 | 主要读者 | 解决的问题 |
|---|---|---|
README.md | 人类开发者 | 项目介绍、安装方式、基本用法 |
AGENTS.md | AI coding agent | 构建、测试、代码风格、协作规则 |
CLAUDE.md | Claude Code | 针对 Claude Code 的项目约束 |
DESIGN.md | AI coding agent / design agent | 色彩、字体、间距、组件、交互状态 |
Google Stitch 把 DESIGN.md 作为一种给 design agent 读取的纯文本设计规范。VoltAgent 的 awesome-design-md 开源项目则把这个思路进一步落地：它把 Stripe、Linear、Vercel、Notion、Apple 等公开网站的视觉规律整理成一组 Markdown 文件，让 agent 可以直接读取某种风格的设计约束。
关键点不在于 Markdown 文件本身，而在于它把“好看”“现代”“像某个产品”这类模糊描述，拆成了大语言模型（LLM，Large Language Model）更容易执行的结构化规则。
为什么普通提示词很难约束 UI
如果只对 agent 说：
Build a beautiful modern dashboard.
模型会生成一个它认为“现代”的界面。问题是，“现代”没有稳定定义。不同模型、不同上下文、不同文件里的结果都可能不同。
就算把提示词改得更长：
Build a beautiful modern SaaS dashboard with clean cards,
good spacing, elegant typography, subtle shadows,
and a premium Apple-like feeling.
结果仍然不可控，因为这些词大多是审美形容词，不是工程约束。agent 仍然需要自己决定：
- 背景色到底用
#ffffff、#f8fafc还是暖灰色； - 主按钮高度是 36px、40px 还是 44px；
- 卡片圆角是 8px、12px 还是 16px；
- 标题和正文之间应该差几级字号；
- hover 状态应该变深、加阴影，还是改变边框色。
DESIGN.md 的作用就是把这些隐含决策提前写清楚。
flowchart LR
A[业务需求] --> C[AI coding agent]
B[DESIGN.md 视觉规范] --> C
D[现有代码] --> C
C --> E[页面和组件代码]
E --> F[人工或 agent 视觉审查]
F -->|不符合规范| C
F -->|符合规范| G[提交代码]
没有 DESIGN.md 时，agent 只根据业务需求和已有代码推断样式；加入 DESIGN.md 后，颜色、字体、间距、组件状态都变成明确输入，生成结果自然更稳定。
一个可用的 DESIGN.md 应该写什么
DESIGN.md 不是随便写几句“简洁、高级、有质感”就够了。它应该像设计系统一样，把视觉规则拆到 agent 能执行的粒度。
一个实用的 DESIGN.md 通常包含这些部分：
| 模块 | 应该描述什么 | 例子 |
|---|---|---|
| 设计气质 | 整体视觉方向 | 温暖极简、科技感、编辑器风格、金融级稳重 |
| 色彩系统 | 背景、文字、主色、边框、状态色 | --color-bg: #f7f4ef |
| 字体系统 | 字体族、字号、行高、字重 | H1 48px / 56px / 600 |
| 间距系统 | spacing scale、页面边距、组件间距 | 4、8、12、16、24、32、48 |
| 栅格布局 | 容器宽度、列数、响应式断点 | 最大宽度 1200px，12 列 |
| 组件规范 | Button、Card、Input、Navbar 等 | 默认、hover、active、disabled 状态 |
| 阴影和层级 | elevation、popover、modal、dropdown | 卡片轻阴影，弹层强阴影 |
| 动效规则 | 过渡时间、缓动函数、动画边界 | 150ms ease-out |
| Do / Don’t | 明确允许和禁止的做法 | 不允许随机渐变，不允许新增未定义颜色 |
| 实现映射 | 对应 Tailwind、CSS 变量、组件库 token | bg-surface、text-muted |
一个简化版可以这样写：
# DESIGN.md
## 1. Design Direction
The interface should feel calm, precise, and product-focused.
Use a warm neutral background, dark readable text, restrained accent colors,
and clear spacing. Avoid flashy gradients or overly rounded consumer-app styling.
## 2. Color Tokens
| Token | Value | Usage |
|------|-------|-------|
| `bg-page` | `#f7f4ef` | Main page background |
| `bg-surface` | `#ffffff` | Cards, panels, popovers |
| `text-primary` | `#24211c` | Main text |
| `text-secondary` | `#6f6a60` | Secondary text |
| `border-subtle` | `#ded8cf` | Card and input borders |
| `accent` | `#3b6df6` | Primary actions and links |
| `success` | `#168a4a` | Success states |
| `danger` | `#d64545` | Error and destructive states |
Do not create new colors unless the design file is updated.
## 3. Typography
Use Inter as the default UI font.
| Role | Size | Line Height | Weight |
|------|------|-------------|--------|
| Display | 56px | 64px | 650 |
| H1 | 40px | 48px | 650 |
| H2 | 28px | 36px | 600 |
| Body | 16px | 24px | 400 |
| Small | 14px | 20px | 400 |
| Caption | 12px | 16px | 500 |
## 4. Spacing
Use this spacing scale only:
`4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80`
- Page horizontal padding: 24px on mobile, 40px on desktop.
- Card padding: 24px.
- Section gap: 64px.
- Form field gap: 16px.
## 5. Components
### Button
Primary button:
- Height: 40px
- Horizontal padding: 16px
- Border radius: 10px
- Background: `accent`
- Text: white, 14px, 600
- Hover: darken background by about 8%
- Active: reduce brightness and translate down 1px
- Disabled: 50% opacity, no hover effect
### Card
- Background: `bg-surface`
- Border: 1px solid `border-subtle`
- Border radius: 16px
- Padding: 24px
- Shadow: `0 8px 24px rgba(36, 33, 28, 0.06)`
## 6. Do / Don't
Do:
- Reuse existing tokens.
- Keep spacing aligned to the spacing scale.
- Define hover, active, focus, and disabled states.
- Prefer subtle borders over heavy shadows.
Don't:
- Do not use random gradients.
- Do not introduce new accent colors.
- Do not mix multiple font families.
- Do not use inconsistent border radius values.
这类内容对人也有价值，但对 agent 的价值更大。因为 agent 不需要“猜”设计系统，它可以直接把 token、组件规则和禁止事项映射到代码。
DESIGN.md 与设计系统、Design Token 的关系
DESIGN.md 不是 Figma，也不是完整的设计系统平台。它更像一层“AI 可读的解释层”。
| 方案 | 优点 | 局限 |
|---|---|---|
| 只写提示词 | 快，几乎没有准备成本 | 结果漂移严重，页面之间不一致 |
| 给 agent 看截图 | 能传达大致视觉效果 | 难以覆盖组件状态、间距规则和响应式细节 |
| Figma / 设计稿 | 视觉信息完整 | agent 不一定能稳定读取和执行全部规则 |
| Design Token | 工程映射清晰 | 缺少设计语气、组件用法和 Do / Don’t |
DESIGN.md | 纯文本、可版本控制、agent 容易读取 | 需要人工维护，细节写得差会影响结果 |
更合理的做法是把它们组合起来：
flowchart TB
A[Figma / 现有产品界面] --> B[设计规律提取]
B --> C[Design Token]
B --> D[DESIGN.md]
C --> E[CSS 变量 / Tailwind 配置 / 组件库主题]
D --> F[AI coding agent]
E --> F
F --> G[页面和组件实现]
Design Token 更适合机器执行，比如颜色变量、字号变量、间距变量；DESIGN.md 更适合给 agent 解释规则，比如“什么时候用主按钮”“什么情况下不能使用阴影”“表单错误状态应该怎么表现”。
在 Claude Code 或 Cursor 中使用 DESIGN.md
项目结构可以保持很简单：
my-app/
DESIGN.md
CLAUDE.md
package.json
src/
app/
components/
DESIGN.md 放在项目根目录，用来描述 UI 规则。CLAUDE.md 或其他 agent 配置文件负责告诉 agent 必须读取并遵守它。
可以在 CLAUDE.md 里加入这样的约束：
# UI Implementation Rules
All UI work must follow `DESIGN.md`.
Rules:
- Treat `DESIGN.md` as the source of truth for colors, typography, spacing, radius, shadows, and component states.
- Do not invent new colors, font sizes, shadows, or spacing values unless explicitly requested.
- If existing code conflicts with `DESIGN.md`, update the code to match the design spec.
- All interactive components must include hover, active, focus-visible, and disabled states when applicable.
- When a requirement is unclear, choose the option that best matches `DESIGN.md` instead of introducing a new visual pattern.
生成新页面时，可以这样要求：
Create a billing settings page.
Use DESIGN.md strictly.
Implement the page with existing components when possible.
Do not introduce colors, spacing, shadows, or typography outside the spec.
Include empty, loading, error, and disabled states.
重构旧页面时，最好明确限制业务逻辑不要被改动：
Refactor src/app/dashboard/page.tsx to follow DESIGN.md.
Do not change:
- routes
- data fetching
- component props
- business logic
- API calls
Only update layout, styling, component composition, and interaction states.
List any place where the current component API prevents full compliance with DESIGN.md.
做代码审查时，也可以让 agent 反向检查：
Audit the changed files against DESIGN.md.
Check for:
- colors not defined in DESIGN.md
- spacing values outside the spacing scale
- missing hover / active / focus / disabled states
- inconsistent border radius
- typography that does not match the defined scale
Return a patch for violations.
这种用法比“把页面变好看”稳定得多，因为 agent 有了明确的检查清单。
把 DESIGN.md 映射到 Tailwind CSS
如果项目使用 Tailwind CSS（基于实用类的 CSS 框架），DESIGN.md 里的 token 最好同步映射到 Tailwind 配置或 CSS（层叠样式表）变量中。这样 agent 不仅知道设计规则，还能使用项目里真实存在的类名。
例如先在全局 CSS 中定义变量：
:root {
--color-bg-page: #f7f4ef;
--color-bg-surface: #ffffff;
--color-text-primary: #24211c;
--color-text-secondary: #6f6a60;
--color-border-subtle: #ded8cf;
--color-accent: #3b6df6;
--radius-card: 16px;
--radius-button: 10px;
--shadow-card: 0 8px 24px rgba(36, 33, 28, 0.06);
}
再映射到 tailwind.config.js：
/** @type {import('tailwindcss').Config} */
module.exports = {
theme: {
extend: {
colors: {
page: "var(--color-bg-page)",
surface: "var(--color-bg-surface)",
primary: "var(--color-text-primary)",
secondary: "var(--color-text-secondary)",
subtle: "var(--color-border-subtle)",
accent: "var(--color-accent)",
},
borderRadius: {
card: "var(--radius-card)",
button: "var(--radius-button)",
},
boxShadow: {
card: "var(--shadow-card)",
},
},
},
};
组件实现就会更接近规范：
export function PrimaryButton({
children,
disabled,
}: {
children: React.ReactNode;
disabled?: boolean;
}) {
return (
<button
disabled={disabled}
className="
h-10 rounded-button bg-accent px-4 text-sm font-semibold text-white
transition duration-150 ease-out
hover:brightness-95
active:translate-y-px active:brightness-90
focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent
disabled:pointer-events-none disabled:opacity-50
"
>
{children}
</button>
);
}
如果 DESIGN.md 只写“按钮要高级一点”，agent 很容易自由发挥；如果规范里明确写了高度、圆角、字号、状态和 token，生成的组件就更可控。
awesome-design-md 适合怎么用
VoltAgent/awesome-design-md 的价值在于提供了一批现成的 DESIGN.md 示例。它们从真实网站中整理出颜色、字体、组件风格和视觉语气，适合用来学习 DESIGN.md 应该怎么写，也适合做早期原型的风格参考。
更推荐的用法不是直接照搬某个品牌，而是把它当作模板，然后改成自己的产品规范。
| 用法 | 适合程度 | 说明 |
|---|---|---|
学习 DESIGN.md 结构 | 很适合 | 可以观察成熟产品如何描述颜色、字体、组件和禁用规则 |
| 快速做内部原型 | 适合 | 能快速得到统一风格，便于讨论方向 |
| 生成多个风格版本做对比 | 适合 | 同一页面套不同设计规范，团队更容易选方向 |
| 直接复制知名品牌风格做商业产品 | 不建议 | 公开网站视觉规律不等于可商用品牌资产 |
| 替代设计师做完整产品设计 | 不适合 | 它约束视觉执行，不负责产品定位和用户体验决策 |
比较稳妥的流程是：
选择一个接近目标气质的 DESIGN.md
↓
删除明显属于某个品牌的表达
↓
替换成自己的颜色、字体、圆角、组件规则
↓
同步到 CSS 变量 / Tailwind / 组件库主题
↓
让 agent 按规范生成页面
↓
把人工审查中发现的新规则补回 DESIGN.md
DESIGN.md 应该随着项目迭代持续更新。只要人工审查发现某类问题反复出现，就可以把它写成更明确的规则。
例如 agent 经常生成过重阴影，可以补一条：
Do not use shadows stronger than `shadow-card` for regular cards.
Reserve stronger shadows only for popovers, dropdowns, and modal dialogs.
agent 经常乱用渐变，可以补一条：
Gradients are not part of this design system.
Do not use gradient backgrounds, gradient borders, or gradient text.
它能解决什么，不能解决什么
DESIGN.md 解决的是“视觉执行不稳定”的问题，不是所有设计问题。
| 能解决 | 具体表现 |
|---|---|
| 风格漂移 | 不同页面使用同一套颜色、字体、间距和圆角 |
| 组件状态缺失 | 按钮、输入框、菜单可以明确要求状态完整 |
| 视觉规则不可追踪 | 规范放进 Git，修改有记录，可审查 |
| agent 自由发挥过多 | 用 Do / Don’t 限制随机颜色、渐变和阴影 |
| 代码审查缺少标准 | 可以按 DESIGN.md 检查 UI 变更 |
| 不能解决 | 原因 |
|---|---|
| 产品是否好用 | 用户流程、信息架构、功能取舍仍然需要人判断 |
| 审美上限 | 规范写得粗糙，agent 只能执行粗糙规则 |
| 品牌合法性 | 学习公开界面和商业复制不是一回事 |
| 复杂动效 | 纯文本可以描述原则，但复杂动效仍需要设计和工程细化 |
| 组件库冲突 | 现有组件 API 不支持某些状态时，需要先改组件层 |
把 DESIGN.md 当成“审美护栏”会更准确。它不能自动创造一个优秀品牌，但能减少 agent 在实现层面的随机性。
写 DESIGN.md 时最容易踩的坑
只写形容词，不写数值
差的写法：
Use elegant typography and beautiful spacing.
好的写法：
Body text is 16px / 24px / 400.
Section gap is 64px.
Card padding is 24px.
Use only the spacing scale: 4, 8, 12, 16, 24, 32, 48, 64.
agent 对数值、枚举和表格的执行稳定性明显更高。
允许范围太宽
如果写：
Use blue, purple, or green accents when appropriate.
agent 很可能每个页面换一种强调色。更好的方式是固定 token：
Use `accent` for all primary actions.
Do not use purple or green for primary actions.
没有写交互状态
只写默认样式会导致组件在实际使用中粗糙。按钮、输入框、链接、菜单项至少应该写清：
- default
- hover
- active
- focus-visible
- disabled
- loading
- error（表单类组件）
没有和代码系统同步
如果 DESIGN.md 里写了 accent: #3b6df6，但项目里 Tailwind 没有 accent 这个 token，agent 可能直接写任意 hex 色值。更好的做法是让规范、CSS 变量、Tailwind 配置保持一致。
Do / Don’t 写得太软
差的写法：
Avoid using too many colors.
好的写法：
Do not introduce colors outside the Color Tokens table.
If a new color is required, stop and ask for a DESIGN.md update.
agent 更适合执行明确禁止项，而不是理解含糊建议。
一个实用检查清单
给项目加入 DESIGN.md 后，可以用这份清单做日常审查：
| 检查项 | 判断标准 |
|---|---|
| 颜色 | 是否只使用规范里的 token |
| 字体 | 标题、正文、说明文字是否符合字号和行高 |
| 间距 | padding、margin、gap 是否落在 spacing scale 上 |
| 圆角 | Button、Card、Input 是否使用固定 radius |
| 状态 | 交互组件是否包含 hover、active、focus-visible、disabled |
| 响应式 | 移动端和桌面端是否遵守容器宽度和断点 |
| 阴影 | 普通卡片、浮层、弹窗是否使用对应 elevation |
| 禁止项 | 是否出现随机渐变、未定义颜色、混乱字体 |
| 代码映射 | token 是否同步到 CSS 变量、Tailwind 或组件库主题 |
适合采用 DESIGN.md 的场景
DESIGN.md 对这些场景特别有用：
- 使用 Claude Code、Cursor、Aider 等 agent 生成前端代码；
- 团队没有完整设计系统，但希望页面风格统一；
- 需要快速做多个风格方向的原型；
- 已有产品要做 UI 重构，但不想让 agent 改业务逻辑；
- 希望把 UI code review 从“感觉不对”变成“违反了哪条规则”。
不太适合的场景也很明确：
- 项目已经有成熟设计系统、组件库和严格设计交付流程；
- UI 极度依赖定制插画、复杂 3D、品牌动效；
- 需求还停留在产品定位阶段，连目标用户和信息架构都没确定；
- 想直接复制某个知名品牌的完整视觉语言用于商业产品。
代码生成正在变得便宜，但稳定的产品审美仍然需要规则、取舍和维护。DESIGN.md 的价值就在这里：把人类定义的视觉标准，转换成 AI coding agent 能读取、能引用、能检查的工程文件。