用DESIGN.md约束AI，告别前端生成页面的廉价模板感

一次前端重构实践中，我遇到了一个几乎每个 AI 前端开发都会碰到的问题：AI 生成的页面“能看但不能细看”。单屏效果尚可，页面整体拼起来却像同一个工厂出来的模板产品——圆角卡片、渐变按钮、毛玻璃导航、灰白交替的区块背景，连标题和文案的排布方式都高度相似。这种“廉价模板感”并不是 AI 画不出更好的页面，而是它缺少一套来自项目本身的设计约束。后来在一次开源项目协作中，我发现不少团队开始尝试用一份 DESIGN.md 作为“设计宪法”，让 AI 编码工具在动手写代码之前先阅读设计规范。本文就围绕这个方式展开，从模板感的成因讲起，再到 DESIGN.md 的写法、接入流程和完整实战，帮助你从“AI 生成页面”走向“AI 生成有气质的页面”。

1. 为什么 AI 生成的前端页面总是“模板感”严重

1.1 模板感的来源：概率选择与上下文缺失

先解释一个现象：同样是“帮我做一个产品介绍页”，Cursor、Claude Code、Copilot 输出的结果往往非常相似。其中一个关键原因是，这些 AI 编码工具在训练阶段见过大量开源项目、模板仓库和组件库示例，当上下文里没有明确的设计约束时，模型会倾向于输出“概率上最稳妥”的方案。

“概率上最稳妥”具体到视觉层面就是：

• 使用 Tailwind CSS 加一套现成组件库，比如 shadcn/ui、DaisyUI。
• 背景默认用bg-gray-50或bg-slate-50，区块之间用灰白做层级区分。
• 卡片默认rounded-xl，按钮默认蓝色渐变或紫色渐变。
• 导航栏默认顶部固定，加上一个轻微的毛玻璃效果。
• 首屏默认左侧文案、右侧插图，或者居中大标题加三个特性卡片。

这些组合在单个页面上没有问题，但放到多个页面、多个迭代里，就会形成强烈的“模板感”。问题不在于 AI 技术本身，而在于它在生成代码时缺少两样东西：

1. 品牌层面的气质定义。
2. 实现层面的视觉约束。

简单说，AI 不是不会设计，而是不知道你的项目长什么样。

1.2 真正缺的不是 AI，而是一份项目级设计规范

很多开发者应对模板感的方式是“写更长的提示词”，比如“不要用太常见的组件风格”“用更有设计感的方式排版”“参考某某产品的风格”。这种方式的问题是：

• 提示词随着迭代不断膨胀，维护成本高。
• 每次新开对话都要重新粘贴，内容容易漂移。
• 提示词里描述的是“不要什么”，很少定义“要什么”。
• 同一个提示词在不同模型、不同版本下效果差异极大。

而项目级设计规范可以把“这个项目的视觉应该是什么样”固化成一份文档，让 AI 在每次生成代码前都能稳定读取。这也正是 DESIGN.md 的核心价值：把零散的设计要求变成可复用、可审查、可继承的项目资产。

设计规范在传统前端团队里通常叫 Design Token、Style Guide 或者 Design System。DESIGN.md 相比它们的差异在于，它不仅是给人类设计师看的，更是给 AI 编码工具看的机器可读上下文。

1.3 DESIGN.md 解决什么，不解决什么

DESIGN.md 能解决：

• 色彩、字体、间距、圆角等基础视觉元素的统一。
• 组件风格倾向的定义，比如按钮是圆角还是直角、卡片是否带边框。
• 动效与交互的克制程度。
• AI 在实现页面时的技术选型倾向。
• 多轮迭代中的风格稳定性。

DESIGN.md 不能解决：

• 交互逻辑和产品功能设计。
• 复杂业务状态管理。
• 后端接口设计。
• 独立的视觉创意发散。

所以更准确地说，DESIGN.md 是“约束 AI 的设计边界”，而不是“替代设计师”。理解这一点后，再看它的具体用法。

2. DESIGN.md 的本质与运行原理

2.1 它是什么：从文档到 AI 上下文

DESIGN.md 本质上是一个 Markdown 文档，通常放在项目根目录或者docs/目录下。它的内容是围绕“视觉与交互”的规范集合，包含但不限于：

• 设计原则与品牌气质。
• 色彩令牌（Color Tokens）。
• 字体令牌（Typography Tokens）。
• 间距、圆角、阴影规则。
• 组件风格描述。
• 动效与交互规范。
• 响应式行为。
• 禁止事项与技术实现约束。

当 AI 编码工具在工作时，它会读取项目上下文文件（如 CLAUDE.md、AGENTS.md、Cursor Rules 等），并在其中找到对 DESIGN.md 的引用，或者直接读取该文件。随后在生成代码时，AI 会把 DESIGN.md 中的规则视为“必须遵守的项目级约束”，从而降低对训练数据中常见模板的依赖概率。

2.2 为什么文档比提示词更稳定

提示词在每一轮对话中都是一次性的，用户可能删掉重写、改写、缩写，导致约束不连续。文档则不同：

• 文件写入仓库后，所有协作者和 AI 工具都能看到。
• 文档的修改需要走代码评审流程，变更可追溯。
• 文档可以版本化，一个标签对应一套设计语言。
• 多个 AI 编码工具可以在同一套规范下工作，输出一致性更高。

这里有一个容易混淆的概念：DESIGN.md 不等于 README。README 解决“项目是什么、怎么跑起来”，DESIGN.md 解决“界面应该长什么样、交互应该怎么做”。两者服务对象和内容范围完全不同。

2.3 开源项目里的 DESIGN.md 该放在哪里

以一个常见的开源前端项目为例，推荐的结构是：

my-awesome-ui/ ├── docs/ │ ├── DESIGN.md │ └── CONTRIBUTING.md ├── src/ ├── public/ ├── .cursor/ │ └── rules/ │ └── design.md ├── AGENTS.md ├── CLAUDE.md ├── package.json └── README.md

其中docs/DESIGN.md是规范全文，.cursor/rules/design.md和AGENTS.md是给 AI 工具的“读取入口”。这样设计的好处是：规范文档集中管理，AI 工具入口只做引用，不复制内容。

2.4 环境与工具建议

本文的示例会涉及多款主流 AI 编码工具，包括 Cursor、Claude Code、GitHub Copilot 等。由于这些工具更新速度很快，版本号无法固定，建议以你当前安装的最新版本为准。重点不是某个工具的独有配置，而是通用思路：

• 找到 AI 工具读取上下文规则的文件位置。
• 在规则文件中引用 DESIGN.md。
• 在关键任务中要求 AI 先阅读规范再生成代码。

下面从编写一份 DESIGN.md 开始。

3. 从零编写一份高效 DESIGN.md

3.1 四大核心板块

一份能有效约束 AI 的 DESIGN.md，不建议写成散文，而应该拆成可执行的规则。我通常按四个板块组织：

接下来逐个拆解。

3.2 品牌气质与视觉词表

AI 最不擅长理解“高级感”“科技感”“优雅”这类抽象词，因为这些词缺乏可操作的视觉映射。为了让 AI 能执行，需要把抽象词转成“视觉词表”。

示例：

## 品牌气质 本项目的核心关键词：克制、技术感、信息密度高。 翻译成视觉语言： - 克制：不使用大面积高饱和色；渐变最多出现在按钮悬停状态。 - 技术感：优先使用等宽字体展示代码相关文本；允许网格线背景。 - 信息密度高：卡片间距松散但卡片内部不留大面积空白；一屏尽量展示核心信息。

同时可以给出反面清单：

## 禁止的视觉风格 - 禁止使用大圆角（超过 16px）的卡片和按钮，默认圆角为 8px。 - 禁止使用紫色到蓝色的霓虹渐变作为主按钮背景。 - 禁止使用玻璃拟态作为导航栏默认样式。 - 禁止使用 emoji 作为功能图标。 - 禁止在未指定时引入 DaisyUI、Material-UI 等重型组件库。

3.3 色彩与字体令牌

建议直接给出一份可复制的 CSS 变量定义，AI 在生成样式时就会优先引用这些变量。

/* src/styles/tokens.css */ :root { /* 品牌色 */ --color-primary: #2563eb; --color-primary-hover: #1d4ed8; --color-accent: #0ea5e9; --color-background: #ffffff; --color-background-subtle: #f8fafc; --color-surface: #ffffff; --color-border: #e2e8f0; --color-text: #0f172a; --color-text-secondary: #475569; --color-text-muted: #94a3b8; /* 字体 */ --font-sans: "Inter", system-ui, -apple-system, sans-serif; --font-mono: "JetBrains Mono", "Fira Code", monospace; /* 间距 */ --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-6: 24px; --space-8: 32px; --space-12: 48px; /* 圆角 */ --radius-sm: 4px; --radius-md: 8px; --radius-lg: 12px; /* 阴影 */ --shadow-sm: 0 1px 2px rgb(15 23 42 / 0.06); --shadow-md: 0 4px 12px rgb(15 23 42 / 0.08); --shadow-lg: 0 12px 32px rgb(15 23 42 / 0.12); }

在 DESIGN.md 中，可以这样描述：

## 色彩与字体 所有页面必须引用 src/styles/tokens.css 中的 CSS 变量。 禁止在组件中硬编码十六进制颜色值。 - 主色：--color-primary，用于主要按钮、链接、选中态。 - 强调色：--color-accent，用于提示、数据高亮。 - 背景层次：页面背景使用 --color-background 或 --color-background-subtle。 - 字体：正文使用 --font-sans；代码、API 路径、数字统一使用 --font-mono。

这一段看似简单，却能极大减少 AI 生成颜色时“自由发挥”的概率。

3.4 组件风格约束

组件风格约束是整个 DESIGN.md 中对观感影响最大的一部分。AI 生成模板感最重的正是按钮、卡片、导航这三大件，因此要写得足够具体。

## 组件风格 ### 按钮 - 默认圆角：--radius-md（8px）。 - 主要按钮：填充 --color-primary 背景，白色文字；悬停时背景变为 --color-primary-hover。 - 次要按钮：白色背景，1px 边框使用 --color-border，文字使用 --color-text-secondary。 - 禁止使用大面积渐变背景；允许 --color-primary 到 --color-accent 的悬停渐变，但仅限主按钮。 ### 卡片 - 默认背景：--color-surface。 - 边框：1px solid var(--color-border)。 - 圆角：--radius-lg（12px）。 - 阴影：只在需要强调层级时使用 --shadow-md，默认不要叠加阴影。 - 卡片内部间距：上下至少 --space-6，左右至少 --space-4。 ### 导航栏 - 默认模式：白色背景、底部 1px 边框。 - 当前项：文字颜色使用 --color-primary，可加 2px 下划线。 - 禁止默认使用毛玻璃效果；如果要用，必须通过 backdrop-blur-sm 且背景透明度不低于 90%。

3.5 动效与交互规范

动效写不写，直接影响 AI 生成的交互质感。如果自动态效果缺失，页面会显得很生硬；如果 AI 自由发挥，又很容易变成“到处都是动画”的炫技页面。

## 动效与交互动效 - 页面首次加载：允许一次轻微的淡入，持续时间不超过 300ms。 - 按钮悬停：过渡时长 150ms，使用 ease-out。 - 卡片悬停：只允许轻微上移 2px 或边框变色，禁止缩放动画。 - 列表进入视口：不允许默认的逐项弹跳动画。 - 数据加载中：必须提供骨架屏或 loading 状态，禁止直接空白。 - 减少动效：如果用户系统开启 prefers-reduced-motion，必须关闭所有非必要动画。

3.6 技术实现约束

技术约束的作用是让画面更规范，也让代码质量更高。这部分不仅约束样式，还约束实现方式。

## 技术实现约束 - 优先使用 Tailwind CSS，但禁止在 JSX 中堆叠超过 8 个的 className。 - 必须使用语义化 HTML 标签：header、main、section、article、footer。 - 所有图片必须包含 alt 属性。 - 断点：sm 640px、md 768px、lg 1024px、xl 1280px。 - 禁止使用内联 style 定义色彩和间距。 - 交互组件必须支持键盘操作，焦点样式不能移除。 - 响应式优先采用移动端优先写法。

3.7 反面写法示例

很多 DESIGN.md 效果差，是因为写得太“虚”。来看一个典型的反面例子：

## 设计风格（反面示例） 我们的设计应该高端大气上档次，颜色要好看，按钮要精致，整体要有科技感。注意用户体验，多使用留白，不要弄得太花哨。

这段内容 AI 读完等于没读，因为缺少可执行的信息。对比来看：

## 设计风格（正面示例） 我们的品牌气质是“技术、克制、高信息密度”。必须使用 tokens.css 中的颜色变量。按钮默认圆角 8px，主按钮使用 --color-primary。禁止出现霓虹渐变、大圆角卡片、毛玻璃导航、emoji 图标。

写 DESIGN.md 的核心原则是：把形容词翻译成变量和值，把“感觉”翻译成“规则”。

4. 让 AI 编码工具真正读进 DESIGN.md

写好文档只是第一步，关键在于让 AI 编码工具在生成代码时真正读取这些规范。不同工具接入方式不同，但整体思路一致：在项目级的 AI 规则文件中引用 DESIGN.md。

4.1 在 Cursor 中配置 Rules

Cursor 支持项目级 Rules，目录结构如下：

.cursor/ └── rules/ └── design.md

在.cursor/rules/design.md中写入：

# 项目设计规范入口 在开始任何前端页面、组件、样式相关任务之前，必须先阅读 docs/DESIGN.md，并严格遵守其中的视觉令牌、组件风格和技术约束。 关键要求： 1. 禁止使用 DESIGN.md 中未定义的颜色值。 2. 按钮、卡片、导航必须按 DESIGN.md 的组件风格实现。 3. 如果 DESIGN.md 与当前需求冲突，先向用户说明，再执行。

Cursor 会在会话启动时自动加载.cursor/rules/下的规则文件。这样 AI 就知道项目里存在设计规范，并且应当在生成代码时遵守。

4.2 在 Claude Code 中配置 CLAUDE.md

Claude Code 默认读取项目根目录下的CLAUDE.md。可以这样写：

# CLAUDE.md ## 项目概览 这是一个开源前端项目，提供产品落地页与组件库。 ## 设计规范 本项目使用 docs/DESIGN.md 作为唯一设计规范来源。 在实现任何界面之前： 1. 先阅读 docs/DESIGN.md。 2. 所有颜色、字体、圆角、间距必须使用 tokens.css 中的 CSS 变量。 3. 生成组件时，按照 DESIGN.md 中“组件风格”一节的描述实现。 ## 禁止事项 - 不得引入未在 package.json 中声明的 UI 组件库。 - 不得生成与 DESIGN.md 视觉风格冲突的页面。

当 Claude Code 启动时，会自动把CLAUDE.md加入系统上下文。即使新开对话，约束也不会丢失。

4.3 在通用 Agent 中使用 AGENTS.md

随着 Agent 类工具增多，AGENTS.md成为一种更通用的“AI 说明书”约定。它和CLAUDE.md定位类似，可以被多种 AI 编码工具识别。

# AGENTS.md ## 工作流程 所有前端界面任务必须遵守以下流程： 1. 阅读 docs/DESIGN.md。 2. 阅读 src/styles/tokens.css。 3. 在代码中引用设计令牌。 4. 完成后检查是否违反 DESIGN.md 中的禁止事项。 ## 设计令牌位置 - DESIGN.md: docs/DESIGN.md - CSS Variables: src/styles/tokens.css

4.4 在提示词中显式引用

即使工具支持自动读取，我也建议在关键任务的提示词中再次显式引用：

请先阅读 docs/DESIGN.md 和 src/styles/tokens.css，然后参考这两个文件中的设计规范，为以下需求实现一个产品介绍页：...

显式引用的好处是，它能让 AI 在“当前任务”这一层面明确意识到需要参考设计规范，而不只是依赖系统上下文。

5. 完整实战：让 AI 按 DESIGN.md 生成一个落地页

这一节看一个完整闭环：从项目结构、DESIGN.md 内容、规则文件，到实际生成页面和验收清单。

5.1 创建项目结构

先创建一个演示项目：

mkdir ai-design-demo cd ai-design-demo npm create vite@latest . -- --template react-ts npm install tailwindcss @tailwindcss/vite

版本说明：Vite、Tailwind CSS 版本更新较快，实际安装以官方提示的版本为准。下面重点看文件内容。

5.2 编写完整的 DESIGN.md

文件路径：docs/DESIGN.md

以下是一份可在真实开源项目中直接改造的缩写完整版：

# DESIGN.md ## 1. 设计原则 本项目面向开发者工具场景，追求“技术、克制、高信息密度”的视觉风格。 - 克制：少用装饰性元素，不用大面积的渐变和发光效果。 - 技术感：代码相关文本使用等宽字体，允许使用网格线背景增强结构感。 - 高信息密度：保证核心信息在首屏可读，卡片内不留过量空白。 ## 2. 视觉令牌 所有颜色、字体、间距必须引用 src/styles/tokens.css 中的 CSS 变量。 - 主要操作色：--color-primary - 强调色：--color-accent - 页面背景：--color-background / --color-background-subtle - 正文：--color-text - 次要用例：--color-text-secondary - 字体：正文 --font-sans，代码 --font-mono ## 3. 组件风格 ### 按钮 - 圆角 8px。 - 主按钮：填充 --color-primary，悬停变 --color-primary-hover。 - 次按钮：白底 + 1px 边框。 ### 卡片 - 默认 12px 圆角，1px 边框，不默认加阴影。 ### 导航栏 - 白底 + 底部 1px 边框，不使用毛玻璃。 ## 4. 动效 - 过渡统一 150ms ease-out。 - 首屏淡入不超过 300ms。 - 尊重 prefers-reduced-motion。 ## 5. 技术实现 - 语义化 HTML。 - Tailwind CSS 原子类不超过 8 个。 - 移动端优先。 - 不使用内联 style 定义颜色和间距。 - 不使用 MODEL 之外的前端框架，不使用默认模板中的演示组件。

5.3 编写项目级 rules 文件

文件路径：.cursor/rules/design.md

# 设计规范入口 生成前端代码前必须阅读 docs/DESIGN.md。 遵守原则： - 颜色统一从 src/styles/tokens.css 引用。 - 不引入额外 UI 组件库。 - 使用语义化标签。 - 结束后自查 DESIGN.md 禁止项。

5.4 向 AI 发起设计任务

准备好上述文件后，在 Cursor 或 Claude Code 中发起任务：

请基于 docs/DESIGN.md 和 src/styles/tokens.css 的设计规范，制作一个开发者工具产品介绍落地页。 要求： 1. 首屏包含产品名称、一句话介绍、主按钮和次按钮。 2. 下方包含 3 个核心特性卡片。 3. 全部颜色、间距、圆角使用 tokens.css 中的变量。 4. 移动端优先，桌面端呈现三列布局。 5. 不引入额外组件库。

5.5 预期效果与验收清单

生成后对照以下清单验收：

如果全部通过，说明 DESIGN.md 已经有效发挥作用。

6. 常见问题与排查思路

排查顺序建议：

1. 先确认 AI 确实读取到了 DESIGN.md。
2. 再确认 DESIGN.md 是否有可执行规则。
3. 最后检查是否在任务提示词中显式引用。

如果读了还是不行，问题通常出在“文档写得不够具体”，而不是“AI 能力不行”。

7. 工程化建议与开源文化

7.1 DESIGN.md 如何与设计系统配合

DESIGN.md 不是要替代设计系统，而是作为 AI 编码工具理解设计系统的“翻译层”。一个可复用的思路是：

• 设计系统维护设计令牌和组件代码。
• DESIGN.md 用自然语言描述“AI 应该如何使用这些令牌”。
• 规则文件（AGENTS.md、CLAUDE.md、Cursor Rules）告诉 AI “先去读 DESIGN.md”。

三者形成闭环：文档约束 AI，AI 生成代码，代码回补设计系统。

7.2 开源项目维护 DESIGN.md 的注意事项

如果你在开源项目中维护 DESIGN.md，有几个点需要特别关注：

• 保持文档简洁，避免超过 300 行。AI 上下文有长度限制，太长反而会稀释关键约束。
• 将“禁止事项”放在显眼位置。AI 对禁止事项的敏感度通常高于建议项。
• DESIGN.md 目录变更时，同步更新所有引用它的规则文件。
• 在提交信息中标注设计规范变更，方便追踪。

7.3 从“AI 生成页面”到“AI 符合设计气质”

使用 DESIGN.md 的真正收益，是让 AI 从“生成能看的页面”进化到“生成符合项目气质的页面”。这背后是开发流程的变化：从依赖人工反复修改提示词，变成通过项目文件持续传递设计意图。开源项目的协作场景中，这份文档还能帮助新贡献者快速理解项目视觉约束，减少评审来回。

如果你正在被 AI 前端的模板感困扰，下一次迭代不妨先停下写页面的手，花一小时整理一份 DESIGN.md。它不一定让 AI 一次性输出惊艳的设计，但一定能让每次生成的页面更接近你真正想要的样子。