一次前端重构实践中我遇到了一个几乎每个 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 技术本身而在于它在生成代码时缺少两样东西品牌层面的气质定义。实现层面的视觉约束。简单说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.md3.1 四大核心板块一份能有效约束 AI 的 DESIGN.md不建议写成散文而应该拆成可执行的规则。我通常按四个板块组织板块解决什么问题典型内容品牌气质页面传递的情绪与风格关键词、语气、照片风格视觉令牌颜色、字体、间距等基础变量CSS Variables、色板、字体栈组件风格具体 UI 组件的形态倾向按钮、卡片、表格、导航行为与实现动效、响应式、代码质量交互动效、断点、禁止事项接下来逐个拆解。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-md8px。 - 主要按钮填充 --color-primary 背景白色文字悬停时背景变为 --color-primary-hover。 - 次要按钮白色背景1px 边框使用 --color-border文字使用 --color-text-secondary。 - 禁止使用大面积渐变背景允许 --color-primary 到 --color-accent 的悬停渐变但仅限主按钮。 ### 卡片 - 默认背景--color-surface。 - 边框1px solid var(--color-border)。 - 圆角--radius-lg12px。 - 阴影只在需要强调层级时使用 --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 中配置 RulesCursor 支持项目级 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.mdClaude 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.css4.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 vitelatest . -- --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 预期效果与验收清单生成后对照以下清单验收检查项通过标准色彩规范页面中不存在未在 tokens.css 中定义的颜色值字体规范代码相关文本使用 --font-mono圆角规范按钮 8px、卡片 12px没有大圆角组件库未引入额外 UI 组件库语义化使用 header、main、section、footer 等标签响应式窄屏单列宽屏三列动效过渡在 150ms-300ms没有弹跳动画如果全部通过说明 DESIGN.md 已经有效发挥作用。6. 常见问题与排查思路问题现象常见原因解决思路AI 完全不读 DESIGN.md规则文件路径不对或命名不匹配检查 .cursor/rules/ 或 CLAUDE.md 是否被正确加载读是读了但生成结果还是旧模板风格DESIGN.md 写得太抽象补充具体视觉令牌和禁止清单颜色总是会硬编码十六进制tokens.css 没有在规则中被引用在规则中显式要求引用 CSS 变量多轮对话后风格漂移上下文过长或规则被遗忘在提示词末尾追加“请再次对照 DESIGN.md 检查”多个 AI 工具输出不一致没有统一的项目入口文件统一维护 AGENTS.md 并在各工具中引用排查顺序建议先确认 AI 确实读取到了 DESIGN.md。再确认 DESIGN.md 是否有可执行规则。最后检查是否在任务提示词中显式引用。如果读了还是不行问题通常出在“文档写得不够具体”而不是“AI 能力不行”。7. 工程化建议与开源文化7.1 DESIGN.md 如何与设计系统配合DESIGN.md 不是要替代设计系统而是作为 AI 编码工具理解设计系统的“翻译层”。一个可复用的思路是设计系统维护设计令牌和组件代码。DESIGN.md 用自然语言描述“AI 应该如何使用这些令牌”。规则文件AGENTS.md、CLAUDE.md、Cursor Rules告诉 AI “先去读 DESIGN.md”。三者形成闭环文档约束 AIAI 生成代码代码回补设计系统。7.2 开源项目维护 DESIGN.md 的注意事项如果你在开源项目中维护 DESIGN.md有几个点需要特别关注保持文档简洁避免超过 300 行。AI 上下文有长度限制太长反而会稀释关键约束。将“禁止事项”放在显眼位置。AI 对禁止事项的敏感度通常高于建议项。DESIGN.md 目录变更时同步更新所有引用它的规则文件。在提交信息中标注设计规范变更方便追踪。7.3 从“AI 生成页面”到“AI 符合设计气质”使用 DESIGN.md 的真正收益是让 AI 从“生成能看的页面”进化到“生成符合项目气质的页面”。这背后是开发流程的变化从依赖人工反复修改提示词变成通过项目文件持续传递设计意图。开源项目的协作场景中这份文档还能帮助新贡献者快速理解项目视觉约束减少评审来回。如果你正在被 AI 前端的模板感困扰下一次迭代不妨先停下写页面的手花一小时整理一份 DESIGN.md。它不一定让 AI 一次性输出惊艳的设计但一定能让每次生成的页面更接近你真正想要的样子。
用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 技术本身而在于它在生成代码时缺少两样东西品牌层面的气质定义。实现层面的视觉约束。简单说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.md3.1 四大核心板块一份能有效约束 AI 的 DESIGN.md不建议写成散文而应该拆成可执行的规则。我通常按四个板块组织板块解决什么问题典型内容品牌气质页面传递的情绪与风格关键词、语气、照片风格视觉令牌颜色、字体、间距等基础变量CSS Variables、色板、字体栈组件风格具体 UI 组件的形态倾向按钮、卡片、表格、导航行为与实现动效、响应式、代码质量交互动效、断点、禁止事项接下来逐个拆解。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-md8px。 - 主要按钮填充 --color-primary 背景白色文字悬停时背景变为 --color-primary-hover。 - 次要按钮白色背景1px 边框使用 --color-border文字使用 --color-text-secondary。 - 禁止使用大面积渐变背景允许 --color-primary 到 --color-accent 的悬停渐变但仅限主按钮。 ### 卡片 - 默认背景--color-surface。 - 边框1px solid var(--color-border)。 - 圆角--radius-lg12px。 - 阴影只在需要强调层级时使用 --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 中配置 RulesCursor 支持项目级 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.mdClaude 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.css4.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 vitelatest . -- --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 预期效果与验收清单生成后对照以下清单验收检查项通过标准色彩规范页面中不存在未在 tokens.css 中定义的颜色值字体规范代码相关文本使用 --font-mono圆角规范按钮 8px、卡片 12px没有大圆角组件库未引入额外 UI 组件库语义化使用 header、main、section、footer 等标签响应式窄屏单列宽屏三列动效过渡在 150ms-300ms没有弹跳动画如果全部通过说明 DESIGN.md 已经有效发挥作用。6. 常见问题与排查思路问题现象常见原因解决思路AI 完全不读 DESIGN.md规则文件路径不对或命名不匹配检查 .cursor/rules/ 或 CLAUDE.md 是否被正确加载读是读了但生成结果还是旧模板风格DESIGN.md 写得太抽象补充具体视觉令牌和禁止清单颜色总是会硬编码十六进制tokens.css 没有在规则中被引用在规则中显式要求引用 CSS 变量多轮对话后风格漂移上下文过长或规则被遗忘在提示词末尾追加“请再次对照 DESIGN.md 检查”多个 AI 工具输出不一致没有统一的项目入口文件统一维护 AGENTS.md 并在各工具中引用排查顺序建议先确认 AI 确实读取到了 DESIGN.md。再确认 DESIGN.md 是否有可执行规则。最后检查是否在任务提示词中显式引用。如果读了还是不行问题通常出在“文档写得不够具体”而不是“AI 能力不行”。7. 工程化建议与开源文化7.1 DESIGN.md 如何与设计系统配合DESIGN.md 不是要替代设计系统而是作为 AI 编码工具理解设计系统的“翻译层”。一个可复用的思路是设计系统维护设计令牌和组件代码。DESIGN.md 用自然语言描述“AI 应该如何使用这些令牌”。规则文件AGENTS.md、CLAUDE.md、Cursor Rules告诉 AI “先去读 DESIGN.md”。三者形成闭环文档约束 AIAI 生成代码代码回补设计系统。7.2 开源项目维护 DESIGN.md 的注意事项如果你在开源项目中维护 DESIGN.md有几个点需要特别关注保持文档简洁避免超过 300 行。AI 上下文有长度限制太长反而会稀释关键约束。将“禁止事项”放在显眼位置。AI 对禁止事项的敏感度通常高于建议项。DESIGN.md 目录变更时同步更新所有引用它的规则文件。在提交信息中标注设计规范变更方便追踪。7.3 从“AI 生成页面”到“AI 符合设计气质”使用 DESIGN.md 的真正收益是让 AI 从“生成能看的页面”进化到“生成符合项目气质的页面”。这背后是开发流程的变化从依赖人工反复修改提示词变成通过项目文件持续传递设计意图。开源项目的协作场景中这份文档还能帮助新贡献者快速理解项目视觉约束减少评审来回。如果你正在被 AI 前端的模板感困扰下一次迭代不妨先停下写页面的手花一小时整理一份 DESIGN.md。它不一定让 AI 一次性输出惊艳的设计但一定能让每次生成的页面更接近你真正想要的样子。