很多团队开始把 DESIGN.md 放进项目根目录，是因为 AI 编程工具越来越像一个“临时加入项目的前端同事”。你希望 Claude Code、Cursor 这类工具看完设计规范后，能写出接近产品气质的界面，而不是每次都靠截图、Prompt 和反复返工来校准。
但这里有个很现实的问题：大多数 DESIGN.md 写得像一份从 Figma 导出的样式清单。颜色、字号、间距、圆角，全都列得很完整，看起来专业，实际喂给 AI 后，生成结果还是容易飘。按钮大小有了，页面气质没了；色号没错，信息层级乱了；组件都在，使用场景却不对。
原因并不复杂。AI 不缺“看见样式”的能力，尤其是 Claude 这类模型，提取视觉细节已经很强。真正缺的是约束：这个产品为什么这么设计，哪些地方不能变形，什么时候该用某个组件，什么时候绝对不能用。DESIGN.md 的价值，不是把设计系统抄一遍，而是把设计决策背后的判断写出来。
一、色板开头通常是坏信号
很多不太能用的 DESIGN.md，第一行就是 Color Palette。
比如：
Primary Blue: #1B4DFF
Background: #FFFFFF
Text Primary: #111111
Text Secondary: #666666
Border: #E5E5E5
这类内容当然有用，但它解决的是“取值”问题，不解决“决策”问题。
Claude 看到 #1B4DFF，知道这是蓝色；看到 Primary，大概知道它重要。但它不知道：
- 这个蓝色是不是只能用于主按钮？
- 能不能拿来做大面积背景？
- 一个页面能不能同时出现两个 primary CTA？
- 激活态、选中态、品牌露出是不是都共用它？
- 在错误、警告、成功状态里，它有没有业务含义？
人类开发者在团队里待久了，往往会自然吸收这些隐性规则。AI 不会。它只能从文档里推断，如果文档没写，它就会补全。麻烦也在这里：AI 补全出来的东西，通常语气很自信，但未必符合你的产品逻辑。
更好的写法是把 Token 写成“数值 意图 边界”。
primary: #1B4DFF
用途：
- 仅用于主按钮、关键激活状态、当前步骤高亮。
- 一个视口内原则上只允许出现一个 primary CTA。
禁止：
- 禁止作为大面积背景色。
- 禁止用于纯装饰图形。
- 禁止和 error / warning / success 状态混用。
决策依据：
primary 代表用户当前最应该执行的动作，而不是品牌装饰色。
如果一个页面需要两个 primary 按钮，优先重新梳理操作优先级。
这段并不复杂，但信息密度完全不同。它告诉 Claude 的不是“蓝色长什么样”，而是“蓝色在这个系统里承担什么责任”。
这就是写 DESIGN.md 的第一个工程判断：Token 不是变量表，而是约束入口。
二、AI 需要限制，不只需要描述
设计规范通常有两种写法。
一种是描述型：
Card 使用 16px 圆角，白色背景，浅灰色边框，24px padding。
另一种是限制型：
Card 用于承载一个独立任务或一个清晰的信息分组。
允许：
- 展示假期余额、行程建议、单个申请状态等聚焦内容。
- 卡片内部最多包含一个主操作。
禁止：
- 禁止把多个无关任务塞进同一张卡片。
- 禁止用卡片嵌套卡片制造层级。
- 禁止为了压缩空间减少核心留白。
当内容只是普通记录列表时，优先使用 List Row，而不是 Card。
两者都会提到卡片，但后者才更接近 AI 能执行的规则。
很多 UI 还原失败，并不是因为 Claude 不知道圆角是多少，而是它不知道什么时候该用 Card，什么时候该用 List，什么时候该把信息拆开，什么时候该合并。视觉系统的稳定性，很多时候来自“不要乱用”。
这和前端组件库很像。你只给组件 API，不给使用约定，项目用久了必然长出各种“祖传变体”。AI 只是把这个问题放大了：它没有团队上下文，也没有设计评审记忆，只能依赖文档里的显式规则。
所以 DESIGN.md 要少写一点“它看起来如何”，多写一点“它在什么条件下成立”。
三、产品简介必须放在最前面
好的 DESIGN.md 第一节不该是色板，也不该是字体，而是产品简介。
不是那种市场稿式的介绍，而是能约束界面决策的背景信息：
Oooff 是一款旅游规划 Web 应用，帮助用户结合所在国家的年假和公共假期规划休假。
用户通常在短时间内打开应用，快速确认：
- 自己还剩多少假期；
- 已规划休假是否和公共假期重叠；
- 当前请假申请处于什么状态。
界面必须让假期余额、日历状态和申请状态在几秒内可读。
产品支持国家本地化，因此日期、假期名称和状态展示不能依赖单一地区假设。
这段信息会影响很多下游选择。
比如，同样是一个日历工具，如果它服务的是企业 HR 后台，信息密度可以更高，操作可以更复杂；如果它服务的是普通用户快速查看假期余额，就要降低认知负担。再比如，支持多国家本地化，意味着日期格式、节假日名称、工作日规则都不能写死。
产品简介不是装饰性开头，而是整个文档的上下文根节点。
Claude 这类模型很擅长沿着上下文生成。如果一开始给它的是业务目标，它后续生成组件、布局、状态、空页面时，会有更大概率围绕目标收敛。如果一开始给它的是色号，它只能围绕色号编故事。
这里有个很关键的边界：AI 可以从截图里推断视觉规律，但不能可靠推断业务意图。
它可能看见绿色按钮，就推断绿色代表“积极操作”；看见日历，就推断这是“时间管理应用”；看见卡片，就写出“卡片用于聚焦用户注意力”。这些话听起来都对，但很可能只是通用设计话术。真正的产品逻辑，还是要由人写进去。
用户原文里给到的 Oooff 设计参考图，可以放在产品背景附近，帮助读者理解案例上下文：
四、Token 要写出意图和失控边界
设计 Token 最容易被写成账本：
colors:
canvas: #FFFFFF
canvasMuted: #F5F5F7
textPrimary: #111111
textSecondary: #6B7280
这种写法对工程接入有帮助，但对 AI 生成 UI 的帮助有限。因为 AI 需要的不只是变量名，还需要变量的语义边界。
可以按这样的结构写：
## Color Tokens
### canvas / #FFFFFF
用途：
- 主内容区域背景。
- 表单、日历、详情页的基础画布。
禁止：
- 禁止用于悬浮层遮罩。
- 禁止用于需要区分层级的嵌套区域。
### canvas-muted / #F5F5F7
用途：
- 页面分区背景。
- 低强调的信息区块。
- 与纯白卡片形成轻微层级差。
禁止：
- 禁止作为按钮背景。
- 禁止和 disabled 状态混用，避免用户误判可操作性。
### brand-green / #1FA971
用途：
- 表示“属于用户自己的时间、假期、已确认计划”。
- 可用于当前用户相关的高亮标记。
禁止：
- 禁止用于成功状态的通用反馈，除非反馈内容明确与假期确认相关。
- 禁止用于装饰插画。
注意这里的细节：同一个颜色，可能既有视觉意义，也有业务意义。一旦颜色承载了业务语义，就不能随便拿去做装饰。否则 AI 很容易生成“看起来还行，但语义污染”的界面。
状态色尤其要写清楚：
| Token | 用途 | 禁止 | 说明 |
|---|---|---|---|
| success | 操作成功、申请通过 | 禁止表达普通品牌高亮 | 状态色只服务反馈语义 |
| warning | 临近截止、假期冲突风险 | 禁止表达推荐内容 | 避免把提醒和营销混在一起 |
| error | 错误、失败、不可提交 | 禁止只靠颜色提示 | 必须配合文字或图标 |
| info | 中性提示、系统说明 | 禁止承载关键阻断信息 | 阻断信息应使用 warning/error |
这里有一个很实用的工程取舍： 如果文档过度细，会增加维护成本；如果文档过粗，AI 会自由发挥。我的建议是，高频 Token 和语义 Token 必须写边界，低频装饰 Token 可以简写。别追求每个变量都写成论文，真正容易导致界面跑偏的地方才值得重墨。
五、Typography 不只是字号表
字体排版也经常被写坏。
常见写法：
H1: 32px / 40px / 700
H2: 24px / 32px / 700
Body: 16px / 24px / 400
Caption: 12px / 16px / 400
这只能保证 Claude 用对大小，不能保证信息层级正确。
更有效的写法要讲清楚每一级文字的使用条件：
## Typography
### Display / 32px / 40px / 700
用途：
- 仅用于页面级核心数字或核心结论。
- 例如：剩余假期天数、年度假期总览中的关键指标。
禁止：
- 禁止用于普通标题。
- 禁止在同一屏幕出现超过一次。
- 禁止用于营销口号。
### Section Title / 20px / 28px / 600
用途：
- 用于卡片标题或页面分区标题。
- 标题必须描述当前区域承载的任务，而不是抽象口号。
### Body / 16px / 24px / 400
用途：
- 普通说明文本、表单内容、列表主文本。
### Caption / 12px / 16px / 400
用途：
- 辅助说明、时间戳、次级元信息。
禁止：
- 禁止承载关键状态。
- 禁止用于错误信息主体。
这类规则对 AI 很重要。比如“禁止 Caption 承载关键状态”，能避免它把错误提示写得又小又灰。前端同学应该很熟悉这种问题：UI 看起来没坏，但可用性已经坏了。
Typography 的核心不是让字号统一，而是让信息优先级稳定。
六、组件说明要写决策逻辑
组件章节最容易写成“组件长什么样”。
但对 Claude 来说，更重要的是“为什么用它”。
比如 Card、List、Modal、Toast、Empty State，这些组件的选择本身就是产品决策。文档里应该明确它们的适用条件。
## Component Logic
### Card
用于承载一个独立任务或一个需要用户聚焦的信息单元。
适合：
- 假期余额概览；
- 单个行程建议；
- 当前申请状态；
- 日历旁的摘要信息。
不适合：
- 大量同构数据记录；
- 简单导航入口；
- 多个无关操作的集合。
规则：
- 每张卡片最多一个主操作。
- 卡片标题必须能说明任务，不使用泛化标题。
- 卡片内部不嵌套卡片。
再看 List Row：
### List Row
用于展示可重复、同构、可快速扫描的数据项。
适合：
- 请假申请记录；
- 公共假期列表；
- 行程项目列表。
不适合：
- 页面核心指标；
- 需要强视觉聚焦的任务；
- 多步骤操作。
规则：
- 每行只表达一个对象。
- 状态必须靠文本 色彩/图标组合表达。
- 可点击区域必须覆盖整行，不能只让小图标可点。
这类内容会直接影响 AI 生成页面结构。否则它可能为了“好看”，把所有东西都塞进 Card；或者为了“简洁”，把关键状态压成列表里的灰色小字。
一个成熟的 DESIGN.md，应该让 Claude 在组件选择时少猜一点。
七、Don’ts 章节比很多人想得更值钱
“禁止事项”听起来像补充，但在 AI 编程场景里，它往往是最有价值的一章。
因为生成式模型天然倾向于补全常见模式。它见过太多渐变按钮、玻璃拟态卡片、营销式大标题、五颜六色状态标签。如果你的产品不需要这些东西，必须明确写出来。
示例：
## Don’ts
- 全站禁止使用渐变色，除非后续设计系统明确新增 gradient token。
- 禁止使用没有语义的装饰性色块。
- 状态表达禁止只依赖颜色，必须同时提供文字或图标。
- 一个视口内原则上只允许一个主按钮。
- 禁止为了节省空间压缩卡片内边距到 12px 以下。
- 禁止在导航栏区域放置页面主体操作。
- 禁止用弹窗承载低优先级提示，优先使用 inline message 或 toast。
- 禁止把 error 色用于强调重要信息，error 只表达错误或阻断。
这些规则看着强硬，但对 AI 很友好。模型不怕限制，怕的是模糊。
写 Don’ts 的难点在于，你必须真的理解自己的设计系统。很多团队平时靠设计师口头评审维持一致性，一旦要求写成“绝对不做什么”，就会发现很多规则其实没有沉淀下来。
这也是 DESIGN.md 的副作用：它会倒逼团队把隐性共识显性化。对 AI 有帮助，对新人接手、跨团队协作、设计债治理也有帮助。
八、强制访谈是必要流程
如果用 Claude 来辅助生成 DESIGN.md，不要一上来就让它“根据截图生成设计规范”。
更稳的流程是先问问题：
在生成 DESIGN.md 前，必须先确认以下信息：
1. 产品是干什么的？
- 目标用户是谁？
- 使用场景是什么？
- 用户打开界面时最想快速完成什么？
2. 是否已有设计变量？
- 色板、字阶、间距、圆角、阴影是否已存在？
- 哪些是稳定规范，哪些只是当前稿件里的临时样式？
3. UI 必须坚持的核心原则是什么？
- 快速读状态？
- 降低非技术用户认知负担？
- 强化专业感？
- 支持高密度操作？
4. 系统绝对不会做什么？
- 不用渐变？
- 不用大面积品牌色？
- 不让状态只靠颜色表达？
- 不在一个页面放多个主 CTA？
这一步不能省。
如果省掉，Claude 很可能根据截图自己编产品故事。它会写得很顺，甚至很像专业设计文档，但底层逻辑可能是错的。
这类错误很隐蔽。Hex 值、圆角、阴影都对，产品原则却是假的。后续 AI 继续基于这份文档生成代码时，错误会被放大，最后变成一套“看起来一致，但方向不对”的界面。
这也是 AI 协作里一个常见坑：数据提取可以自动化，设计判断不能完全外包。
九、一份可落地的 DESIGN.md 骨架
可以按这个顺序组织文件：
# DESIGN.md
## Product Brief
用 2-4 句话说明产品、用户、场景、核心任务。
## Design Principles
列 3-5 条设计原则，每条都要能影响具体 UI 决策。
## Tokens
### Colors
每个关键颜色写清：
- value
- purpose
- allowed usage
- forbidden usage
### Typography
每个字阶写清：
- size / line-height / weight
- usage
- forbidden usage
### Spacing
说明间距系统如何服务密度和层级。
重点写组件内边距、区块间距、列表密度边界。
### Radius / Shadow
说明圆角和阴影代表什么层级。
禁止滥用阴影制造层级。
## Component Logic
按组件写：
- 适用场景
- 不适用场景
- 状态规则
- 交互规则
- 响应式规则
## States
统一说明：
- loading
- empty
- error
- success
- disabled
- selected
- active
## Layout Rules
说明页面结构、导航、栅格、移动端适配规则。
## Don’ts
列出系统级禁止事项。
越具体越好。
如果项目比较小，不必每节都写很长。重点是别缺失前几块：产品简介、设计原则、Token 意图、组件决策、禁止事项。
小项目里可以压缩成：
# DESIGN.md
## Product Brief
## Core UI Rules
## Tokens With Usage
## Component Decisions
## States
## Don’ts
文档的目标不是显得完整，而是让 AI 在关键决策点上别乱来。
十、它最终服务的是工程稳定性
从工程角度看，DESIGN.md 其实像一层“生成约束协议”。
它不替代组件库，也不替代 Figma，更不替代设计评审。它解决的是另一个问题：当 AI 参与编码时，怎样把团队原本散落在设计稿、口头沟通、PR Review、历史代码里的规则，压缩成一份模型能消费的上下文。
这里有几个现实判断：
| 做法 | 优点 | 问题 | 适用场景 |
|---|---|---|---|
| 只给截图 | 快速，成本低 | AI 容易脑补业务逻辑 | 临时 Demo、低保真原型 |
| 只给 Token | 工程接入方便 | 缺少使用边界 | 已有成熟组件库的补充说明 |
| 给完整 DESIGN.md | 稳定性更高，可复用 | 初始编写成本高 | 长期项目、多人协作、AI 高频参与 |
| DESIGN.md 组件代码 | 最接近生产约束 | 维护成本最高 | 中大型前端项目、设计系统成熟团队 |
取舍也很明确：如果只是做一个一次性页面，写一份完整 DESIGN.md 可能过重；如果 AI 已经开始持续参与产品迭代，那这份文档很快会回本。否则每次生成、修正、再生成，成本会转移到人工 Review 上。
更重要的是，DESIGN.md 写得好，受益者不只有 Claude。
新来的前端能更快理解组件边界，设计师能减少重复解释，技术负责人也能更清楚地看到 UI 系统有没有被规则化。很多团队的设计债，不是没有规范，而是规范停留在“样式是什么”，没有沉淀到“为什么这样用”。
一份真正能让 Claude 看懂的 DESIGN.md，应该讲清楚产品故事，也应该写清楚工程边界。
色号、字号、间距只是材料。 产品意图、组件决策、状态语义和禁止事项，才是 AI 生成稳定 UI 的护栏。[DONE]
