让 AI 前端生成结果摆脱“廉价模板感”，很多团队第一反应是写更长更细的提示词，但真正值得先做的是在仓库根目录放一份 DESIGN.md。这里所说的 DESIGN.md，是一种面向 AI 编码工具的设计约束文档，它把视觉规范从人的脑子里、设计稿里、Figma 文件里，翻译成 AI 在生成代码时能读取和校验的规则。如果 README 回答的是“这个项目怎么启动”，DESIGN.md 回答的是“这个项目的界面为什么好看、应该长成什么样、不能出现什么”。
廉价模板感并不是某一种具体样式的专利。默认蓝色链接、紫色渐变按钮、大圆角卡片、随机间距、没有层级感的标题、杂乱的阴影，这些问题单独出现时都能被接受，一旦同时出现，就会让人一眼判断“这是模板生成的”。更关键的是，AI 生成这类界面时并不觉得自己错了，因为它没有被明确告知这个项目的设计规则。
所以，与其继续堆砌提示词，不如把设计规则沉淀成一份开源、纯 Markdown、可复用、可评审的 DESIGN.md。下面从 AI 生成结果为什么容易“翻车”开始，逐步说明 DESIGN.md 应该写什么、怎么接入 AI 工作流、怎么验证效果，以及常见问题怎么排查。
1. 为什么 AI 生成的前端总有一种“廉价模板感”
1.1 廉价感不是“样式问题”，而是“规则缺失”
很多人把 AI 生成界面的廉价感归结为“模型审美不行”，这个判断并不准确。同一个模型，给它一段没有约束的需求，它能生成一套看起来像后台管理模板的页面；给它一套明确的设计约束，它也能生成风格统一、层级清晰的界面。差别不在模型能力，而在任务定义。
当一个需求只写到“做一个用户管理页”时，AI 会默认选择自己训练数据里出现频率最高的模式：顶部一条导航栏、左侧菜单、右侧表格、蓝色按钮、白色卡片。这种模式本身没有错，但它没有和具体项目的品牌、目标用户、内容结构发生关系，所以结果必然是“通用”的，而“通用”在视觉上经常约等于“廉价”。
真正的问题是没有规则。没有规则意味着颜色可以随手写，间距可以随手定，字体层级可以随意调，组件状态可以缺一半。AI 每一次生成都会“重新发明一遍设计”，甚至同一次会话里两次生成同一个页面，结果都会不一致。缺少规则才是廉价感的根源。
这里的规则不是“界面要优雅、要高级、要大气”这类形容词，而是可执行的约束。例如：
- 主色只有哪几个，色值分别是什么。
- 间距必须从 4px 的倍数刻度里选。
- 标题字号、正文字号分别是多少。
- 卡片圆角、按钮圆角、阴影分别使用什么 token。
- 哪些组件必须有 hover、focus、disabled 状态。
- 哪些视觉元素被禁止使用。
这些约束写成普通文档会显得琐碎，但交给 AI 前端生成时，它们是决定输出质量的关键。
1.2 AI 编码工具当前能读到的上下文太少
目前主流的 AI 编码工具在生成代码时，主要依赖三类上下文：当前打开的文件、项目目录中的相关文件、用户对话中的指令。也就是说，AI 能看到 README、代码、配置文件，但不一定能看到设计语言、品牌规范、UI 组件设计原则。
如果项目里只有 README，AI 了解的是怎么安装依赖、怎么启动服务。这些信息对它生成“登录页该用什么主色”“卡片之间该留多大间距”毫无帮助。结果就是 AI 只能靠训练数据中的通用模式做猜测。
更糟糕的是，很多设计规范散落在人的脑子里，或者沉淀在 Figma、即时设计等工具里。这些内容 AI 编码工具默认读取不到。就算你把设计稿截图发给 AI，它也只能模糊理解视觉风格，很难精确生成与设计令牌一致的颜色、间距和圆角。
DESIGN.md 的价值就在于它是一个 AI 能读、能检索、能引用的纯文本文件。它不需要 PDF，不需要私有设计平台，不需要额外权限。只要放在仓库里，AI 就能把它作为生成代码时的硬性约束。
1.3 DESIGN.md 解决的是“任务定义”问题
AI 生成前端的本质，是把“用户需求的自然语言描述”翻译成“实现代码”。如果描述本身缺少设计层面的定义，AI 就只能靠猜测补全。DESIGN.md 不是一份更长的需求说明书，而是一份“设计契约”，它把审美偏好转译成规则，把主观判断转译成可检查项。
例如，“页面要看起来很专业”是主观表达，AI 无法稳定执行；“页面使用单一主色、中性背景、统一按钮高度、间距对齐到 4px 刻度”就是可执行规则。AI 可以通过代码判断自己是否违反规则，人也能在审查代码时确认规则是否被遵守。
开源项目尤其适合使用 DESIGN.md。当一个开源仓库有明确的设计规范时，外部贡献者提交 UI 代码前能自动对齐风格，维护者审查代码时也有了统一标准。和常见开源项目里的 CONTRIBUTING.md 不同，DESIGN.md 更聚焦于界面生成和样式约束，两者配合起来，可以让 AI 生成、人工贡献、代码审查三个阶段都遵循同一套设计语言。
2. 用 DESIGN.md 为 AI 前端生成建立“设计契约”
2.1 DESIGN.md 的核心章节和写作原则
一份真正有用的 DESIGN.md 不需要特别长，但结构必须清楚。建议从下面几个维度组织内容：
- 设计价值观：用两三句话说明项目界面追求什么、避免什么。
- 色彩系统：列出主色、辅助色、背景色、文字色、状态色。
- 字体系统：定义默认字体栈、标题字号、正文字号、辅助文字字号。
- 间距系统：定义基础单位、可用间距刻度、禁止使用的间距。
- 圆角与阴影：定义组件通用圆角、阴影 token。
- 组件状态：规定按钮、输入框等组件必须覆盖的状态。
- 布局与响应式：定义内容宽度、栅格、响应式断点。
- 禁止事项：把常见的“廉价感来源”直接列为禁令。
- 验收清单：列出生成完成后必须逐项检查的内容。
写作原则可以归纳为三条。
第一，规则必须可检查。写“卡片要有层次感”不如写“卡片阴影使用 shadow-card，不使用描边”。后者在代码中能确认，前者不能。
第二，限制数量要克制。一份 DESIGN.md 如果包含 200 条规则，AI 很可能记不住，人在评审时也不会逐条对照。先保证核心 20 条规则被严格执行，比堆 100 条无效规则更重要。
第三，文档要与代码中的设计令牌保持一致。DESIGN.md 描述“为什么这样设计”，tokens.css描述“具体值是什么”，两者必须同步，否则 AI 会不知道该信哪个。
2.2 一个最小可用的 DESIGN.md 模板
下面是一份可以直接复制的精简模板。它不追求覆盖所有项目，而是给 AI 一个明确的“设计基线”。
# DESIGN.md 本文档是前端生成时的设计约束。AI 每次生成或修改 UI 前，必须阅读本文档并遵守其中规则。 ## 设计价值观 - 优先使用克制的中性色，不使用大面积渐变。 - 信息层级靠排版和间距建立，不能只靠颜色。 - 同一个语义在不同页面必须一致。 ## 色彩系统 - 主色：`#2563EB` - 主色悬停：`#1D4ED8` - 背景：`#F8FAFC` - 卡片表面：`#FFFFFF` - 正文：`#0F172A` - 次要文字：`#64748B` - 错误：`#DC2626` - 成功：`#16A34A` 所有颜色必须从 `src/styles/tokens.css` 中引用，组件代码不允许直接写十六进制色值。 ## 字体 - 默认字体栈：见 tokens.css 中的 `--font-sans`。 - 页面标题：20px。 - 卡片标题：16px。 - 正文：14px。 - 辅助文字：12px。 ## 间距 - 基础单位：4px。 - 常用间距刻度：4、8、12、16、24、32、48、64。 - 不允许出现 13px、17px 等不对齐到刻度的间距。 ## 组件规则 - 按钮高度统一 36px，小尺寸按钮 28px。 - 卡片圆角使用 10px。 - 按钮圆角使用 6px。 - 卡片阴影只使用 tokens.css 中的 `--shadow-card`。 - 输入框必须有 hover、focus、disabled 三种状态。 ## 布局与响应式 - 页面最大内容宽度：1200px。 - 断点：768px 以下为移动端，768px 到 1024px 为平板，1024px 以上为桌面端。 - 移动端不允许直接缩放桌面端布局。 ## 禁止事项 - 不使用与 tokens.css 无关的十六进制颜色。 - 不使用默认表单样式。 - 不随意给组件叠加渐变、描边和阴影。 - 不把说明性文案写成 Lorem ipsum。 - 不为了“看起来丰富”而添加无信息量的装饰元素。 ## 生成验收清单 - [ ] 所有颜色来自 tokens.css。 - [ ] 所有间距来自间距刻度。 - [ ] 标题、正文、辅助文字字号符合字体系统。 - [ ] 响应式断点遵循 768px / 1024px。 - [ ] 按钮、输入框包含 hover、focus、disabled 状态。 - [ ] 没有重复定义样式常量。这份模板的重点在于“禁止事项”和“生成验收清单”。禁止事项直接告诉 AI 哪些行为是错误示范，验收清单则让 AI 在完成任务后能自我检查。两者都服务于同一个目标：把设计质量从主观审美变成可验证的工程行为。
2.3 设计令牌：让文档中的规则可以被代码引用
DESIGN.md 只是文本规范，真正落地到代码中需要一套设计令牌。最轻量的方式是维护一份tokens.css，把颜色、间距、圆角、阴影、字体统一成 CSS 变量。
:root { --color-primary: #2563eb; --color-primary-hover: #1d4ed8; --color-bg: #f8fafc; --color-surface: #ffffff; --color-text: #0f172a; --color-text-secondary: #64748b; --color-error: #dc2626; --color-success: #16a34a; --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-6: 24px; --space-8: 32px; --space-12: 48px; --space-16: 64px; --radius-sm: 6px; --radius-md: 10px; --shadow-card: 0 1px 2px rgb(15 23 42 / 0.06), 0 8px 24px rgb(15 23 42 / 0.06); --font-sans: "Inter", "PingFang SC", "Microsoft YaHei", system-ui, sans-serif; --text-base: 14px; --text-title: 20px; }设计令牌和 DESIGN.md 之间是相互校验的关系：
| 层面 | 作用 | 举例 |
|---|---|---|
| DESIGN.md | 描述设计规则和禁止事项 | “主色为 #2563EB” |
| tokens.css | 提供代码可引用的变量 | var(--color-primary) |
| 组件代码 | 只消费变量，不直接定义样式常量 | background: var(--color-primary) |
这样的分层有一个明显好处：AI 在生成组件时不需要“记住”每一个色值，只需要知道“颜色必须从 tokens.css 里引用”。即使 AI 对色值不敏感，只要它遵守“不写死颜色”这一条规则，最终视觉效果也不会偏离太多。
3. 把 DESIGN.md 接入 AI 前端工作流
3.1 文件放哪里，AI 才更容易读到
DESIGN.md 放在仓库根目录是最稳妥的做法。根目录文件更容易被 AI 编码工具检索，也符合开发者的直觉：打开仓库第一眼能看到。如果放在docs/design这样的深层目录，AI 在浏览项目结构时可能会跳过，或者需要额外提示才会去查找。
推荐的结构是：
design-md-demo/ ├── AGENTS.md ├── DESIGN.md ├── index.html ├── package.json └── src/ ├── App.jsx ├── main.jsx └── styles/ └── tokens.css这里的AGENTS.md是给 AI 看的协作说明文件。它不需要很长，核心作用是告诉 AI：生成前端代码前，先读哪些文档，必须遵什么规则。
需要说明的是，不同 AI 编码工具对项目规则文件的命名和路径要求不完全一致。有的支持AGENTS.md，有的支持.cursor/rules，有的支持.github/copilot-instructions.md。落地前要先确认自己使用的工具支持哪种方式。但无论工具怎么变，“把规则放在项目里”这个思路是一致的。
3.2 用 AGENTS.md 与 IDE 规则文件建立引用链
只放一份 DESIGN.md 还不够，最好再写一份 AGENTS.md，把它作为 AI 的“工作入口”。
# AI 协作规则 ## 前端生成前 - 必须阅读根目录 `DESIGN.md` 和 `src/styles/tokens.css`。 - 如果任务涉及 UI，先查看项目里是否已有可复用组件。 - 先理解页面信息结构，再决定布局，不要先写样式。 ## 前端生成时 - 所有颜色、间距、圆角、阴影必须引用 tokens.css 中的变量。 - 组件类名使用统一命名风格。 - 不新增与 tokens.css 重复的样式语义。 - 交互状态至少包含 hover、focus。 - 不生成无信息量的装饰元素。 ## 生成完成后 - 对照 DESIGN.md 中的“生成验收清单”逐项自检。 - 在回复中列出哪些项通过，哪些项无法通过及原因。这份文件的价值在于，它把“AI 阅读 DESIGN.md”从用户的临时要求变成默认行为。哪怕用户只输入“生成一个登录页”，AI 也会先按 AGENTS.md 的要求去读 DESIGN.md，而不是直接凭感觉写代码。
3.3 生成时的指令写法：把规则变成强制约束
有了 DESIGN.md 和 AGENTS.md，仍然建议在每个具体任务里主动引用设计规则。原因是 AI 对话是上下文敏感的，任务越具体，规则越容易生效。
可以这样写：
读取项目根目录 DESIGN.md 和 src/styles/tokens.css。 请按 DESIGN.md 中的规则生成“数据概览 Dashboard”页面。 页面包含侧边栏、顶部栏、统计卡片、最近订单列表。 必须使用 tokens.css 中的变量，不得写死颜色和间距。 组件必须覆盖 hover、focus 状态。 完成前先对照 DESIGN.md 的生成验收清单逐项自检。这里的核心是“把规则转换成强制约束”。不需要把 DESIGN.md 全部内容复制进提示词，只需要写出最容易犯错的几条，然后让 AI 自己对照完整文档。这样既能控制提示词长度，又能让 AI 的注意力集中在关键规则上。
4. 实战：用 DESIGN.md 生成一个 Dashboard 页面
4.1 准备一个最小前端项目
下面用一个 React 项目演示。命令以 Vite 官方模板为例：
npm create vite@latest design-md-demo -- --template react cd design-md-demo npm install然后按照前文结构创建DESIGN.md、AGENTS.md和src/styles/tokens.css。这三个文件是让 AI 生成结果产生质变的输入，项目本身的业务代码可以保持最小。
创建完成后，项目目录应该类似：
design-md-demo/ ├── AGENTS.md ├── DESIGN.md ├── index.html ├── package.json └── src/ ├── App.jsx ├── main.jsx └── styles/ └── tokens.css在开始让 AI 生成页面之前，先在src/main.jsx中引入 tokens.css：
import React from 'react'; import ReactDOM from 'react-dom/client'; import App from './App.jsx'; import './styles/tokens.css'; ReactDOM.createRoot(document.getElementById('root')).render( <React.StrictMode> <App /> </React.StrictMode> );这一步的目的是让设计令牌成为全局样式，AI 生成的组件可以直接通过var(--color-primary)等方式引用。
4.2 为 Dashboard 编写精简 DESIGN.md
前面 2.2 的模板已经覆盖了通用规则，如果目标是 Dashboard，可以补充页面级约束：
## 页面级约束 - 页面最大内容宽度 1200px，水平居中。 - 顶部标题统一使用 20px，辅助描述使用 14px 次要文字色。 - 统计卡片使用浅色背景 `--color-bg`，卡片内不允许再嵌套卡片。 - 数据为空时显示空状态文案，不使用破图占位。 - 表格行高 44px，表头使用次要文字色。 - 所有操作按钮放置在同一水平线，不单独散落在页面角落。这些规则比“页面要美观”更具体。AI 看到“统计卡片使用浅色背景”，就能确定背景色是var(--color-bg)而不是任意灰；看到“表格行高 44px”，就不会生成过挤或过松的表格。
4.3 给 AI 的生成指令与自检要求
在 AI 对话窗口输入：
读取 DESIGN.md 和 src/styles/tokens.css。 生成一个 Dashboard 主页，包含： 1. 左侧导航栏 2. 顶部栏 3. 4 个统计卡片 4. 最近订单表格 硬性要求： - 所有颜色、间距、圆角、阴影使用 tokens.css 变量。 - 统计卡片布局使用 grid，至少三列，移动端一列。 - 表格、按钮、输入框必须有 hover 和 focus 状态。 - 生成完成后，对照 DESIGN.md 的验收清单逐项检查，并说明哪些项通过、哪些项未通过。这里的关键是最后一条。要求 AI “说明哪些项通过、哪些项未通过”，能显著减少 AI 直接回答“已完成”的敷衍行为。如果验收项没有通过，AI 会尝试修复，或者在回复中暴露问题，这比生成完就结束更容易定位质量问题。
4.4 有无 DESIGN.md 的输出差异
同一个 AI 模型、同一个需求，有无 DESIGN.md 的输出通常会产生以下差异：
| 维度 | 无 DESIGN.md 时常见输出 | 有 DESIGN.md 后更可能出现 |
|---|---|---|
| 颜色 | 主色不统一，出现多个蓝色或随机装饰色 | 所有颜色来自 token，页面色调一致 |
| 间距 | 10px、13px、18px 随机出现 | 间距对齐到 4 / 8 / 12 / 16 / 24 / 32 |
| 字体 | 标题字号随机放大，层级混乱 | 标题、正文、辅助文字字号稳定 |
| 卡片 | 大圆角、大阴影、渐变背景叠加 | 圆角和阴影统一，视觉更安静 |
| 响应式 | 只在桌面端好看，移动端挤压 | 按断点重排，移动端结构清晰 |
| 交互状态 | 只有 hover 改变颜色，focus 缺失 | hover、focus、disabled 状态完整 |
实际效果会受模型能力、工具版本和项目复杂程度影响，但方向是一致的：DESIGN.md 把“审美”从玄学变成规则，把“随机发挥”变成“受约束生成”。
5. 常见问题：为什么加了 DESIGN.md 还是生成得不像样
5.1 规则写了但 AI 没读到
现象：DESIGN.md 已经放在仓库里，但 AI 生成结果仍然使用随机颜色、随机间距，看起来和没读文档一样。
可能原因：AI 在会话中没有主动读取 DESIGN.md；文件路径太深；AGENTS.md 没有建立引用；用户提问时没有要求 AI 阅读文档。
检查方式：直接问 AI “DESIGN.md 里主色是什么？”如果它答不出来，说明没有读到。也可以查看 AI 工具的输出日志或上下文列表，确认哪些文件被加载。
解决方案：把 DESIGN.md 放到根目录，在 AGENTS.md 中明确要求“生成 UI 前必须阅读 DESIGN.md”；每次新会话开始时，先让 AI 阅读文档再提需求；如果工具支持，把 DESIGN.md 作为项目文件加入上下文。
预防建议：把“必读文档”写进 AGENTS.md，而不是依赖每次手动提醒。
5.2 规则太抽象，AI 无法转成具体样式
现象：DESIGN.md 写了“界面要克制、要有质感、要高级”，但 AI 生成出来的界面仍然是模板风。
可能原因：文档中的规则不可执行。AI 能理解“克制”这个词，但无法把它转成具体的颜色、间距、圆角。
检查方式：把每一条规则拿出来问自己：这条规则能否通过查看代码判断是否满足？“有质感”不能，“卡片阴影使用 shadow-card”能。
解决方案：把抽象描述翻译成可验证项。例如“克制”可以落成“主色只使用一个，不使用渐变”“一个页面最多出现两个强调色”“深色文字只能在正文和标题中出现”。
预防建议：写作 DESIGN.md 时坚持“一条规则对应一个可检查行为”的原则。
5.3 文档与代码脱节，AI 生成的内容违反现有设计
现象：DESIGN.md 里写的色值和tokens.css不一致；AI 按文档生成了，却和项目现有组件风格冲突。
可能原因：文档维护滞后，设计令牌改过，但 DESIGN.md 没有同步更新。AI 面对两份冲突信息时不知道以谁为准。
检查方式：搜索 DESIGN.md 中的色值，再和 tokens.css 对比；检查组件中是否有硬编码样式。
解决方案：明确令牌唯一来源。建议把 DESIGN.md 中的颜色描述写成“使用 tokens.css 中的 --color-primary”，而不是维护一份独立的十六进制色值表。这样色值变化时只需要改一处。
预防建议：代码审查时要求，改 tokens.css 必须同步检查 DESIGN.md；或者用脚本从 tokens.css 自动生成设计色板文档。
5.4 缺少验收清单，AI 不知道“做完”的标准
现象：AI 生成完页面后直接说“完成”，但页面上按钮高度不统一、focus 样式缺失、间距乱七八糟。
可能原因：DESIGN.md 只写了规则，没写“完成标准”。AI 的任务目标只是“生成代码”，而不是“生成符合设计验收的代码”。
检查方式：看 DESIGN.md 里是否存在“生成验收清单”或“完成定义”这类章节。
解决方案：在 DESIGN.md 末尾增加验收清单，并要求 AI 在生成后逐项自检。关键验收项包括颜色来源、间距刻度、组件状态、响应式断点、禁止事项。
预防建议：在没有验收清单之前，不要指望 AI 自己判断“是否完成”。验收清单是给 AI 的完成条件，也是给人看的审查清单。
5.5 文档过长，被上下文窗口截断
现象：DESIGN.md 写得很完整，但 AI 有时候只遵守了前半部分，后半部分的规则没有生效。
可能原因：当文档过长、对话历史过多、代码量过大时，AI 的上下文窗口可能无法完整覆盖文档内容，导致后半部分被忽略。
检查方式：观察 AI 回复中引用的设计规则，确认它是否读过文档末尾的章节；也可以让 AI 复述 DESIGN.md 最后几段内容。
解决方案：把核心规则控制在尽量精简的篇幅，放在文档开头；详细设计、组件规范、示例代码可以拆分成子文档，在主文档中通过链接或文件引用关联。AI 不一定要一次读完全部文档，但必须读到最关键的规则。
预防建议：为主文档设置“最小必要内容”，比如颜色、间距、禁令、验收清单，其余内容放子文档。按任务类型指定不同文档，避免每次生成都加载全部设计文档。
6. 把 DESIGN.md 作为前端团队的日常工程资产
6.1 维护流程：文档与代码同源
DESIGN.md 不是一次写完之后就固定不变的文件。当设计迭代、品牌升级、组件库调整时，它必须跟着更新。推荐维护流程是：
- 修改 tokens.css 时，同步检查 DESIGN.md 是否需要更新。
- 每一次 UI 相关的 Pull Request，都要求作者自查 DESIGN.md 与代码一致。
- 设计评审时，把 DESIGN.md 作为讨论对象，而不是只对着页面截图讨论。
- 新增组件类型时，在 DESIGN.md 中补充组件状态和约束。
如果团队有设计系统，DESIGN.md 可以和设计系统文档打通。组件库的 API 可以独立，但设计规范必须保持同源。
6.2 用自动化检查兜底
DESIGN.md 能约束 AI，但人也会犯错。更稳妥的做法是在 CI 中加入样式规则检查。一个简单的思路是扫描组件代码，禁止出现设计令牌之外的硬编码颜色。
下面是一个最小示例脚本，用于扫描src目录下组件文件中是否出现十六进制颜色字面量：
import { readFileSync, readdirSync } from 'node:fs'; import { join } from 'node:path'; const root = process.cwd(); const files = []; function walk(dir) { for (const entry of readdirSync(dir, { withFileTypes: true })) { const full = join(dir, entry.name); if (entry.isDirectory()) { walk(full); } else if (/\.(jsx?|tsx?|css|vue|svelte)$/.test(entry.name)) { files.push(full); } } } walk(join(root, 'src')); const colorLiteral = /#[0-9a-fA-F]{3,8}\b/g; let failed = false; for (const file of files) { if (file.endsWith('/tokens.css')) continue; const content = readFileSync(file, 'utf8'); const matches = content.match(colorLiteral) || []; if (matches.length) { failed = true; console.log(`${file}: ${matches.join(', ')}`); } } if (failed) { process.exit(1); }这个脚本不够完整，比如它不处理tokens.css在其他目录的场景，也不检查间距、圆角的硬编码。但它展示了一种思路：通过简单的静态扫描，让 AI 生成代码和人工提交代码都接受同样的规则校验。后续可以接入 stylelint、ESLint 或自定义插件，把更多 DESIGN.md 规则转成自动化断言。
6.3 从单页规范扩展到组件库与多端规范
当项目从单个页面扩展到组件库时，DESIGN.md 的结构也需要演进。此时可以把一份大文档拆成多个子文档：
DESIGN.md：全局设计价值观、色彩、字体、间距、禁止事项、验收清单。docs/components/button.md：按钮的尺寸、状态、使用场景。docs/components/form.md：表单的布局、校验状态、错误提示。docs/patterns/empty-state.md：空状态、加载状态、错误状态的统一写法。
多端项目还需要补充平台差异。比如移动端触摸目标最小 44px，桌面端 hover 状态更重要，Web 端和 App 端的阴影层级也可能不同。这部分内容同样可以写进 DESIGN.md 的子章节，或者单独维护一份DESIGN.mobile.md。
扩展时仍然坚持一个原则：先有规则，再让 AI 生成。没有组件库时，DESIGN.md 可以用来约束页面生成；有组件库后，DESIGN.md 可以用来约束组件使用方式，让 AI 优先复用已有组件，而不是每次生成新的按钮和卡片。
6.4 落地建议与练习路线
如果团队或新手想从零开始落地，可以参考下面这份检查清单：
| 阶段 | 要完成的事项 | 检查标准 |
|---|---|---|
| 第一阶段 | 梳理现有项目用的颜色、间距、字体 | 能列出一份设计令牌清单 |
| 第二阶段 | 创建src/styles/tokens.css | 组件中不再新增硬编码色值 |
| 第三阶段 | 编写精简 DESIGN.md | 包含价值观、颜色、间距、组件状态、禁止事项、验收清单 |
| 第四阶段 | 创建 AGENTS.md 并引用 DESIGN.md | 新会话中 AI 能复述设计规则 |
| 第五阶段 | 让 AI 按 DESIGN.md 生成页面 | 输出符合验收清单中的关键项 |
| 第六阶段 | 在 CI 中加入静态规则检查 | 硬编码颜色能在合并前被发现 |
| 第七阶段 | 根据反馈持续迭代 DESIGN.md | 每次设计评审后文档有更新记录 |
对于个人开发者，最直接的练习不是从零写一份大而全的规范，而是先拿一个已经让 AI 生成的页面，反向提炼它的问题，再写成 DESIGN.md，然后重新生成一遍，对比前后差异。这个流程能快速建立对“规则如何影响 AI 输出”的体感。
如果只能记住一条结论，可以这样理解：不要试图让 AI 理解你审美上想要什么，而是用 DESIGN.md 把审美翻译成它能够校验的规则。文档越稳定、越可检查，AI 前端生成的质感就越能从“碰运气”变成“可重复的生产行为”。
