用DESIGN.md设计契约，从源头消除AI前端的模板感

用 AI 生成前端页面，最头疼的不是报错，而是一眼就能看穿的“模板感”。对这种廉价感，开源社区里开始流行一种解法：项目里放一份 DESIGN.md，把设计规则写成 AI 能读懂的设计契约，从源头约束 AI 的默认审美。这个方案解决的核心问题是——为什么 AI 生成的前端总像复制粘贴，以及怎么用一份文档把模板感压下去。下面按问题成因、文件怎么写、工具怎么接入、最后怎么验收这个顺序完整拆一遍。适合正在用 Cursor、Claude Code 这类 AI 编程工具做前端，或者准备把 AI 编码流程规范化的团队。如果你只是随手让 AI 生成一个 demo，看完前两节就能先改掉一半问题。

1. 先搞明白“AI 模板感”到底从哪来的

1.1 不是模型不行，是约束不够

先说结论：模板感是信息缺失的必然结果，不是模型能力不够。大语言模型生成 HTML、CSS 时，本质上是在做概率预测。当你的指令里没有任何设计约束时，它选择的一定是训练数据里出现频率最高的组合。高频组合意味着什么？意味着被全世界几千上万个项目反复用过的那套样式：Bootstrap 风格按钮、Tailwind 默认色板、通用卡片布局、Hero 区块、三列功能卡片。

如果你只告诉 AI“做一个仪表盘”，它确实能生成十个不同配色方案，但结构一定逃不出标签页、统计卡片、表格、图表这个“标准答案”。模板感不是 AI 没有创意，而是你给的信息不足，它只能走最大概率路径。想明白这一点，就不会抱怨模型不行了。

所以解决思路不是换一个更聪明的模型，而是改变输入结构。把“一句话需求”改成“需求 + 设计规范 + 反例清单”，让 AI 从做选择题变成做填空题。DESIGN.md 就是用来承载这部分额外信息的。

1.2 一眼识破 AI 模板的几大特征

这些年我和同事经常拿“能不能一眼看出这是 AI 写的”当检验标准，总结下来有这么几个高频特征：

• 主按钮是紫色渐变，hover 再变深一点
• 整个页面字重体系单一，标题和正文字号差异不够
• 卡片清一色白底、圆角 8 到 12px、浅灰细边框
• 顶部喜欢放全宽 Hero 区，左边大标题右边插图
• 特性展示永远三栏，每栏都是图标加标题加一段话
• 空状态、加载状态、错误状态经常缺失
• 文案空洞，“强大的”“智能的”“一站式”这类词堆砌

这些特征不是不能单独出现，而是它们同时出现且毫无取舍的时候，就形成了廉价感。真正有设计规范的产品，每个选择都有逻辑：为什么用这个配色、为什么卡片更扁、什么时候不用玻璃拟态。AI 没有这套逻辑，就只能输出“平均脸”。

1.3 为什么越通用的提示词越容易翻车

很多人习惯在 AI 里写“帮我做一个现代简洁的官网”，然后得到和模板相似度 80% 的页面。原因很简单：越通用的输入，给 AI 留出的搜索空间越大，它越倾向于输出最大众化答案。“现代简洁”这四个字在不同人脑子里含义完全不同：有人理解成大量留白的杂志风，有人理解成深色科幻风，有人理解成数据密集的后台风。

模板感的核心成因是信息熵太高。你只有降低指令的熵值，把约束一条条讲清楚，AI 才能在合理范围内输出差异化的结果。DESIGN.md 做的事情，就是把“现代简洁”翻译成可执行的具体规则。

2. DESIGN.md 是什么：把设计规则变成 AI 能执行的“设计契约”

2.1 它和普通需求文档的差异

项目里的 README 是给人看的，DESIGN.md 的主要读者是 AI，当然人和 AI 都能看更好。普通需求文档侧重于“要做什么功能”，DESIGN.md 侧重于“做成什么样、哪些样式允许、哪些样式禁止”。

因此 DESIGN.md 的语言要尽量接近机器指令，多用确定性表达。比如“所有按钮的主色必须取自色板令牌中定义的主色”“卡片圆角固定 6px”“禁止用渐变作为主按钮默认态”。这里的“必须”“禁止”对 AI 来说不是语气词，而是优先级标记。

打个比方：需求文档是告诉 AI 要去哪，DESIGN.md 是告诉 AI 走哪条路、穿什么衣服、什么话不能说。少掉后者，AI 也能到达目的地，但穿得像复制粘贴。

2.2 一份合格的 DESIGN.md 应该覆盖哪些模块

按实测经验，一份能真正约束 AI 的 DESIGN.md 至少要覆盖这几块：

1. 设计原则：3 到 5 条，每条一句话，说明这个产品设计上最不能妥协的点。
2. 设计令牌：颜色、字体、字号、间距、圆角、阴影、层级、动效时长。
3. 组件规范：按钮、输入框、卡片、表格、弹窗、提示等主要组件的默认样式和禁止样式。
4. 页面范式：每种页面类型的默认骨架，比如列表页、详情页、表单页、空状态页。
5. 交互约定：hover、focus、loading、error、成功提示分别怎么表现。
6. 文案语气：品牌或产品该用什么语气，禁止出现哪些词。
7. 反例清单：明确写出“不要做”的事。

这七块里，最容易写、见效最快的是设计令牌和反例清单。先把这两块补上，通常一轮就能看到明显改变。

2.3 开源的含义：规范公开、模板可复用

标题里“开源 DESIGN.md”可以理解为两层。

第一层是方案本身的形态：设计规范以 Markdown 文件形式放在项目仓库里，全员可审阅、可提 issue、可回退历史版本，设计决策变成了公开记录，而不是藏在某个人脑子里。

第二层是模板的复用价值。如果去社区搜索，能看到不少开发者把自己整理的 DESIGN.md 模板公开出来，可以拿来当起点，按自己产品调整，不需要从零开始。但我的建议是别直接抄别人的完整内容，设计规范天然和产品绑定。更合理的做法是拿现成模板当目录框架，把你自己产品真正需要的规则填进去。开源的价值在于框架和写法的共享，而不是把别人的设计决策照单全收。

3. 手写一份能约束 AI 的 DESIGN.md

3.1 动笔之前先做三件事

第一件事，收集参考。找 3 到 5 个和你产品气质相近的已有产品，截屏存下来，写清楚你欣赏它们的哪一点：配色节奏、留白密度、卡片处理方式，还是交互细节。这一步是为了让 DESIGN.md 里每一个词都有现实参照，不是凭空造词。

第二件事，提炼关键形容词。把你期望的产品气质控制在 5 个以内，比如“紧凑、直接、数据优先、低装饰”。然后给每个词下定义，别让它停在感觉层面。比如“数据优先”可以定义为“列表页首屏优先展示关键数据字段，次要操作默认折叠”。

第三件事，写反例。列出你绝对不能接受的效果，反例越具体越好。比如“不要用浅蓝色渐变背景”“不要用圆角大于 12px 的卡片”“Hero 标题字号不要超过 64px”。反例清单会在后面单独讲，但收集工作要从一开始就做。

3.2 设计原则怎么写才不抽象

写设计原则有个简单可行的办法：每条原则必须包含“是什么”和“怎么做”两个部分。

抽象写法：追求简洁。 合格写法：界面保持低装饰，所有装饰元素必须有信息价值；默认不添加背景纹理、渐变、粒子等纯视觉元素，除非用于状态区分。

抽象写法：重视数据密度。 合格写法：列表页默认展示 12 个字段以上，字段优先级按页面范式定义；卡片容器只用于分组，不用于单条数据展示。

原则不是口号，而是 AI 做判断时的规则。写完每条原则后反问一句：如果 AI 只看这一条，它能确定某个按钮要不要加阴影吗？如果不能，说明还是写得太抽象，继续拆解，直到规则能直接指导一个具体决定。

3.3 设计令牌：颜色、字体、间距、圆角、阴影、层级

设计令牌是 DESIGN.md 里最机械也最有效的一部分，建议直接用表格形式呈现：

这里给一个实测建议：颜色不要只给十六进制就完事，必须同时写明“用在什么地方、不用于什么地方”。AI 对色值的识别很准，但它容易滥用，场景限制比色值本身更重要。间距也建议固定成 4px 的倍数体系，AI 在生成布局时，倍率关系比随机像素值更容易保持一致。

3.4 组件规范与页面范式怎么写

组件规范不是把你项目里组件库文档复述一遍，而是告诉 AI“在你的体系里默认长什么样”。

比如按钮：

默认按钮高 32px，横向 padding 12px，圆角 4px。主按钮用 color-primary 纯色填充，次按钮用白底加 1px color-border 边框。禁止按钮使用渐变填充或发光阴影。

再比如表格：

表头背景用 color-bg，文字用 color-text-secondary，字号 12px；单元格上下 padding 8px；行 hover 背景用浅灰。禁止表格行使用斑马纹样式、禁止表头使用深色背景。

页面范式是更高一层的结构约束。比如列表页默认骨架：顶部是标题加操作区，标题字号 20px，操作区按钮右对齐；中间是筛选区；接着是数据表格；底部是分页。禁止在列表页左侧放二级导航、禁止用卡片式布局逐个展示单条数据。

组件管局部，页面范式管整体。两者配合，AI 生成的结构才会稳定。

3.5 红线与反例清单

红线清单是 DESIGN.md 里投入产出比最高的一部分。建议放在文件最后单独一节，命名为“禁止事项”或“Red Lines”。每条都写成明确动作，而不是形容词：

• 禁止使用渐变作为主按钮背景或页面主背景
• 禁止使用玻璃拟态作为默认容器样式
• 禁止使用未在设计令牌中出现的颜色，特殊情况需注明理由
• 禁止给所有区块都加阴影，阴影只用于浮层和层级最高的浮动容器
• 禁止使用“强大的”“智能的”“一站式”等空泛文案
• 禁止在首屏使用超过 48px 的标题字号，除非是独立品牌页面
• 禁止生成与页面范式不一致的布局骨架

有人担心 AI 对“禁止”的处理能力弱，实测下来其实还好。关键是禁令要足够具体，直接指向一个可判断的行为，而不是一句“不要很丑”。

3.6 一份最小可用的 DESIGN.md 示例

如果现在就想开始，可以直接参考这个简化结构：

# DESIGN.md ## 1. 设计原则 - 低装饰：装饰元素必须有信息价值。 - 数据优先：列表页优先展示关键字段，次要操作折叠。 - 直接：默认不使用渐变、玻璃拟态、复杂动效。 ## 2. 设计令牌 - 主色：#2F6BFF，用于主按钮、选中态、链接 - 背景：#F5F6F8，页面底色 - 卡片底色：#FFFFFF - 边框：#E3E5E8，1px - 正文：#1A1D24 标题；#5C616B 次要文本 - 圆角：卡片 6px，按钮 4px - 阴影：0 1px 2px rgba(0,0,0,0.04) ## 3. 组件规范 - 按钮高度 32px，主按钮纯色填充，次按钮白底加边框 - 表格表头浅灰背景，行 hover #F2F4F7 ## 4. 页面范式 - 列表页：标题 + 操作区 + 筛选区 + 表格 + 分页 ## 5. 禁止事项 - 禁止渐变按钮、玻璃拟态、未定义色值、空泛文案

这份模板不复杂，但已经能把 AI 输出从“通用模板”拉到“有约束的定制”这一档。后续再按自己的产品继续加模块就行。

4. 把 DESIGN.md 接进 AI 编码工具

4.1 项目根目录放置与引用方式

DESIGN.md 一般放在项目根目录，和 README、CLAUDE.md、AGENTS.md 同级。这样 AI 在做工作区扫描时能看到它，不需要额外指定路径。

但“能看到”不等于“会主动读”。多轮对话里，AI 的上下文是逐步清理的，DESIGN.md 如果不在会话一开始注入，后面很可能被遗忘。更稳妥的做法是三步：

第一，把 DESIGN.md 放在根目录，路径固定。 第二，在 CLAUDE.md 或 AGENTS.md 里写一句“开始新任务前，必须先读取 DESIGN.md，并遵循其中所有规范”。 第三，在涉及新页面的指令里，显式写上“参考根目录 DESIGN.md”，或者用工具支持的引用语法把文件挂到当前对话。

4.2 在 Cursor 和规则文件里怎么用

Cursor 这类工具支持项目级规则文件。你可以创建一个.cursor/rules/design.md，内容就是 DESIGN.md 的核心部分，并注明这是设计规范，优先级高于通用代码风格。这样即使在一个很大的项目里，AI 也会持续把设计规范当作约束之一。

如果团队用的是 Claude Code 或类似命令行工具，可以在 CLAUDE.md 开头把 DESIGN.md 引用进来，明确“所有 UI 相关代码都必须符合 DESIGN.md”。这种规则文件本质相同，都是把人的判断提前注入 AI 的上下文。

不同工具的规则加载机制、上下文长度、优先级处理不完全一样。落地时先看工具的官方说明，再结合项目实际情况调整。这里给的是通用做法，不针对某个具体版本。

4.3 在 AI Agent 对话里怎么引用

如果是临时对话，不依赖项目文件，可以先用一条指令让 AI 读文件：

请先阅读项目根目录的 DESIGN.md，然后基于其中的设计原则、令牌、组件规范和禁止事项，输出本次页面的设计要点，再开始写代码。

注意这个指令里的顺序：先读规范，再输出设计要点，最后写代码。让 AI 先复述设计要点，你才能在代码开始前检查它有没有真读懂规范。如果它输出的要点里还是出现了渐变按钮或三栏特性卡片，当场就能纠正，不用等代码生成完再返工。

4.4 先让 AI 出设计说明，再出代码

这是最容易被跳过的一步。很多人把 DESIGN.md 丢给 AI 后，直接说“生成页面”，结果 AI 嘴上说遵守规范，实际代码仍然跑偏。

我习惯固定走三步：

1. 让 AI 复述 DESIGN.md 里与本页面相关的约束。
2. 让 AI 输出页面设计骨架：配色方案、区块顺序、组件清单、状态处理。
3. 确认没问题后，再让它写完整代码。

三步成本很低，收益很大。第二步就能看出 AI 有没有理解约束，相当于用一份廉价的前置方案，替代了昂贵的整页返工。

4.5 版本管理与团队协作

DESIGN.md 本质上是一份持续演进的设计决策记录。产品改版、组件升级、新的设计决策，都要同步回写到 DESIGN.md。改完走一次评审，让所有 AI 生成的新页面都依据新版本，而不是旧规范。

如果团队里有好几个人在维护这份文件，建议把它当一个正经代码文件对待：用 pull request 提交，变更记录写进 commit message，必要时加 review 关卡。否则很容易出现两个版本互相覆盖，AI 参考的规则和产品实际设计不一致的情况。这个问题在多人协作里出现频率比我预想的高很多。

5. 怎么验证“模板感”真的消失了

5.1 视觉维度逐项检查

页面生成后，不要只看“好不好看”，要逐项对照 DESIGN.md 检查：

• 颜色：页面里出现的色值，是否都在设计令牌范围内？
• 字体：是否只用了 DESIGN.md 定义的字体和字号级别？
• 间距：区块间距是否有节奏，是否落在 4px 倍率上？
• 圆角：卡片、按钮、输入框是否分别符合规范？
• 阴影：是否只出现在需要层级区分的容器上？
• 装饰：有没有出现规范里没定义过的渐变、玻璃拟态、背景纹理？

凡是有一项不符合，先别急着改代码。回到 DESIGN.md 看是 AI 读漏了，还是规范本身写得不够清楚。两种情况的处理方式完全不同。

5.2 代码维度逐项检查

视觉没问题，不代表实现正确。还要看代码层面有没有真正落地规范：

• CSS 变量：颜色和间距是否用变量维护，而不是写死魔数？
• 组件复用：相同元素是否复用了统一组件，还是每个页面新写一份？
• Tailwind 配置：设计令牌是否同步到了 tailwind.config 的扩展字段？
• 状态覆盖：按钮、空状态、加载态、错误态是否都有定义？
• 响应式：断点行为是否符合页面范式的定义？

DESIGN.md 不能只在 prompt 层面生效，最好同步到代码基础设施里，形成 CSS 变量、组件库配置、页面骨架三层约束。光靠对话约束，多轮之后一定会衰减。

5.3 做一个简单的验收清单

我通常会在每个页面交付前跑一遍这个清单，全部通过才算完成：

这个清单也可以直接写进 DESIGN.md 末尾，让 AI 在交付前自检。让 AI 先自查一轮，能过滤掉大半低质量输出，你只需要检查剩下的少量问题。

6. 常见的坑和排查顺序

6.1 写得太抽象

最常见的坑：DESIGN.md 里全是“简洁、大气、高级感、科技感”这类词。这些词对 AI 不是约束，而是自由发挥的许可。解决办法是把每个形容词改写成可执行规则。如果自己都改不动，说明你还没想清楚产品到底要什么感觉，这时候先别急着写 DESIGN.md。

6.2 写得太长

DESIGN.md 太长会挤占上下文，AI 在长文档里抓重点的能力有限。文档超过一定长度后，它会优先记住开头和结尾，中间内容容易被忽略。我的经验是控制在 150 到 300 行以内，核心信息前置，详细示例放附录。

如果规范确实很多，建议拆成两个文件：DESIGN.md 放核心规则，DESIGN_DETAILS.md 放组件级细节。常规任务只加载前者，只有遇到复杂页面时才把后者也读进去。

6.3 只给正面要求，不给反例

很多人的 DESIGN.md 只写“要什么”，不写“不要什么”。但 AI 生成时最容易踩的坑，恰好是那些你没写“不要”的情况。反例清单的作用是压缩 AI 的搜索空间，比正面描述更省 token，效果也更直接。建议每个核心模块后面跟 2 到 3 条反例，哪怕只是简要一句。

6.4 上下文被覆盖

多轮对话中，即使一开始让 AI 读了 DESIGN.md，继续聊下去它也可能忘记。这不是工具的问题，而是上下文管理的固有限制。解决方式：

• 新开会话时重新引入 DESIGN.md
• 关键指令里再次引用
• 把 DESIGN.md 写进项目规则文件，让工具自动加载
• 重要页面的生成单独开一个会话，不要在一个会话里连续生成十几个页面

6.5 没有把 DESIGN.md 当代码维护

设计规范是活的。产品改版、组件升级、新的设计决策都会让规范失效。如果 DESIGN.md 半年不更新，AI 生成的东西就会和团队实际设计越走越远。建议把“更新 DESIGN.md”写进设计评审流程，改动设计时同步改规范，而不是等出了问题再补。

6.6 模板感还在时，按这个顺序排查

如果 AI 生成的页面仍然有模板感，按下面的顺序排查：

1. 先确认 DESIGN.md 有没有被 AI 读到。在对话里直接问“DESIGN.md 里对按钮样式是怎么规定的”，如果答不上来，说明根本没加载。
2. 再查规范颗粒度。打开你的 DESIGN.md，看每一条是否都具体到颜色、尺寸、位置、状态这一级。如果还有“大气、优雅”这类词，说明颗粒度不够。
3. 再看反例数量。缺少反例的规范，AI 大概率会踩你没想过的坑。
4. 再看代码基础设施。CSS 变量、Tailwind 扩展、组件库是否已同步设计令牌。
5. 最后反思产品定位是否清晰。如果连你自己都说不清这个产品在视觉上要区别于谁，DESIGN.md 写得再好也没用。

最后留一个个人建议：先用一份最小可用的 DESIGN.md 跑通一个真实页面，感受约束前后的差异，再逐步扩展。不要一上来就写一份 500 行的规范，指望一次解决所有问题。DESIGN.md 的精髓不是文档越长越好，而是每个字都能让 AI 少一次自由发挥，离产品真实设计更近一步。真正落地之后你会发现，模板感消失不是被某一条规则禁止掉的，而是 AI 终于有了足够清晰的判断依据，不再需要押注那条最大概率的默认路径。