DESIGN.md：用设计规范文件彻底告别AI前端的廉价模板感

把 AI 生成前端页面变得有质感的思路，正在从一个偏门技巧变成一种开源实践。如果你最近一直在用 Cursor、Claude Code 或 Copilot 这类工具做前端，大概率遇到过同一个问题：页面功能没毛病，布局也完整，但整个界面就像从同一个模板里复制出来的——大面积圆角卡片、浅灰背景、蓝紫渐变按钮、到处都是阴影。这不是你提示词写得不够好，而是 AI 在缺少设计约束时，默认会走向“廉价模板感”。

这篇文章我想重点聊一个正在被越来越多 AI 前端开发者使用的方案：DESIGN.md。简单说，它是在代码仓库里专门放一份面向 AI 阅读的设计规范文件，用结构化的方式告诉模型“这个项目的视觉语言到底是什么”。通过开源的方式把这类规范沉淀下来，可以显著改善 AI 生成前端页面的审美下限。文章会从问题根源讲起，分析 DESIGN.md 和现有主流方案的关系，然后给出一份可以直接抄走的规范模板、真实落地步骤、常见翻车点，以及团队协作时的维护建议。

1. 为什么 AI 生成的前端总有一股“廉价模板感”

先抛开 DESIGN.md 这个概念，回到一个更基础的问题：当你让 AI 用自然语言生成一个完整页面时，为什么结果总是似曾相识？

很多开发者以为是提示词不够长、不够详细。于是不断往 prompt 里塞形容词，比如“现代感”“科技感”“简约高级”，结果 AI 交出来的还是老一套。问题出在哪里？

核心原因在于，大语言模型生成前端代码时，本质是在做“概率性的模式补全”。它见过的前端代码和设计稿太多了，当你没有给出明确的设计约束时，它会默认选择概率最高、最常见的那套视觉组合：

• 卡片式布局，四角圆角 12px 到 16px；
• 背景色偏白或浅灰，配合一个主色按钮；
• 按钮爱用渐变蓝紫或品牌蓝色；
• 卡片内阴影比较重，喜欢加悬浮效果；
• 字体统一用系统字体，没有明显的层级对比。

这套组合不是不好，而是太常见。当所有人都用同一套默认审美，页面就会显得“模板化”。更重要的是，AI 在单次生成过程中是没有“设计记忆”的，它不会记得三分钟前给左边卡片用了什么圆角，也不会主动保持整个页面的间距体系。你让它“做一个和上面风格一致的信息卡片”，它很可能会生成一个风格完全不同的新组件。

所以，廉价模板感的本质不是 AI 能力差，而是设计约束缺失。AI 有能力生成符合特定设计语言的代码，但前提是你得先把设计语言定义清楚，并且放进它每轮生成时都能读到的上下文里。

2. DESIGN.md 是什么：把设计规范变成 AI 的上下文

DESIGN.md 的灵感其实来自开源项目里的 README.md。README 解决的是“人类开发者如何理解这个项目”的问题，而 DESIGN.md 解决的是“AI 模型如何理解这个项目的视觉规范”的问题。

它的核心主张非常朴素：在一个 AI 前端项目里，不要只给 AI 描述“我要什么页面”，还要给 AI 一份随时可读的视觉规范文件。这个文件放在仓库根目录或.ai/目录下，里面用 Markdown 写成，包含了项目的设计词汇、色彩、间距、字体、组件模式、反模式等结构化信息。

当 AI 编码工具被配置为“每次自动读取 DESIGN.md”时，它会像人类开发者在开工前看 Sketch / Figma 设计稿一样，先理解设计语言，再动手写代码。

这个方案能起作用的机制在于：现代 AI 编程工具普遍支持“项目级上下文文件”。例如：

• Cursor 支持.cursorrules文件；
• Claude Code 支持CLAUDE.md；
• GitHub Copilot 支持自定义指令文件；
• 新一代的 Agent 工具还支持AGENTS.md。

DESIGN.md 不是要取代这些文件，而是提供了一套更聚焦的内容标准。你可以把 DESIGN.md 看作是“项目设计规范的内容层”，把.cursorrules、CLAUDE.md看作是“AI 的行为配置层”。前者负责告诉 AI 什么是好看、适合这个项目的设计；后者负责告诉 AI 怎么读、什么时候必须遵守。

从材料来看，前端 AI 生态里已经有大量关于 Skill、规则文件、上下文工程的开源讨论。DESIGN.md 的意义在于：它把散落在各种配置文件里的设计约束抽离成一份可复制的开源资产，让不同项目、不同团队甚至不同 AI 工具之间，能够共享同一套设计语言。

这样一解释，DESIGN.md 就不难理解了：它是连接设计系统与 AI 编码工具之间的协议文件。

3. 它和现有 AI 前端方案到底有什么关系

很多前端开发者第一次听说 DESIGN.md 时，第一反应是：这个和.cursorrules有什么区别？和 Tailwind 主题配置、组件库规范又有什么关系？

要回答这个问题，需要先厘清目前在 AI 前端开发中处于不同层级的几种方案。

可以看到，.cursorrules和CLAUDE.md更像是一个“AI 助手的行为准则”，里面通常包含“用 TypeScript 写代码”“错误处理要完整”“不要在线上使用 console.log”这类指令。它们很重要，但它们缺少对视觉细节的覆盖。

Tailwind 主题配置能定义颜色和间距 token，但它只能影响 AI 生成的代码用到的 token 值，无法约束 AI 在多个组件之间保持一致的设计决策。比方说，你定义了primary颜色，但 AI 还是可能写出一堆奇怪的rounded-[18px]或shadow-[0_8px_30px_rgb(...)]。

组件库能保证组件风格统一，但如果 AI 生成的是新组件，依然需要有一个设计依据。

DESIGN.md 正好补充了中间层：它告诉 AI 在“视觉决策”层面应该怎么做。比如这个项目的圆角半径体系是 4/8/16 三档，而不是任意值；卡片默认不是用阴影来表达层级，而是用边框；主色调饱和度控制在一定范围内。

从实际工程角度看，比较推荐的组合是：

CLAUDE.md / .cursorrules（AI 行为规则） + DESIGN.md（设计规范内容） + Tailwind 主题 token（实现层约束）

三者各管一段，缺一不可。如果你只配了 DESIGN.md 但没有在 AI 工具里告诉它要读取，效果为零；如果你只配了行为规则但缺少视觉规范，AI 写出来的代码还是会有廉价模板感。

4. DESIGN.md 到底该写什么：九个核心模块

很多开发者在第一次尝试写 DESIGN.md 时会陷入两个极端：要么写太少，只有一句“风格要现代、简约”；要么写太多，把整个设计系统的说明文档都塞进去。这两者都有问题。

写太少，AI 没有足够的约束信息；写太多，AI 的上下文窗口被占满，而且会抓不住重点。

结合主流 AI 编程工具的上下文推理能力，一份可落地的 DESIGN.md 通常包含以下模块。

4.1 项目定位与目标用户

这一节让 AI 理解这个产品给谁用、解决什么问题。同样是“资讯页面”，面向金融从业者和面向二次元用户的设计语言完全不同。

## 项目定位 这是一个面向中小型 SaaS 团队的数据分析看板。 目标用户是运营和产品经理，他们需要快速定位数据异常。 设计目标是：信息密度高、数据清晰、弱化装饰。

4.2 设计词汇

设计词汇是最容易被忽略的模块。它用 5 到 10 个关键词定义这个项目的“视觉气质”，并且最好给出反例。

## 设计词汇 - 关键词：克制、数据感、清晰、专业 - 避免：卡通化、强渐变、重阴影、玻璃拟态

这种正反约束比“高级感”这种抽象词汇有效得多，因为它是可判断的。

4.3 色彩体系

不要只写色值，要写“每种颜色的使用场景”。

## 色彩体系 - 主色：#2563EB，用于主按钮、激活状态、关键链接 - 中性色：#F8FAFC 背景， #0F172A 主文字， #64748B 辅助文字 - 成功/警告/错误：#16A34A / #D97706 / #DC2626 - 语义色使用规则：只能用于语义反馈，不用于装饰

4.4 间距与布局

约定栅格体系、间距倍数、最大内容宽度。

## 间距与栅格 - 间距使用 4px 基准倍数：4、8、12、16、24、32、48 - 页面最大内容宽度 1200px，内容区左右 padding 24px - 卡片内边距统一 24px

4.5 字体与排版

约定字体栈、字号层级、行高。

## 字体与排版 - 字体：Inter / PingFang SC / Microsoft YaHei - 字号层级：12 辅助 / 14 正文 / 16 强调 / 20 卡片标题 / 28 页面标题 - 行高：正文 1.6，标题 1.3

4.6 组件模式

这是最核心的部分。它不只是描述组件长什么样，而是描述 AI 在生成新组件时必须遵守的结构模式。比如卡片：边框 1px、圆角 12px、内边距 20px、不使用阴影。

4.7 状态设计

AI 生成的静态页面经常忽略 hover、disabled、loading 等状态。设计规范里要明确这些状态的表现方式。

4.8 动效

约定动效时长和缓动曲线，避免 AI 乱加花哨动画或完全不写动画。

4.9 反模式

列出“绝对不要做的事”，这往往比正向要求更有效。

## 反模式 - 不要使用重阴影表达层级 - 不要使用超过两种字体 - 不要使用蓝紫渐变按钮 - 不要使用随机圆角数值

5. 实战：用一份 DESIGN.md 约束 AI 生成页面

前面讲了概念，这一节直接实操。我们从一个最小项目入手，演示 DESIGN.md 如何影响 AI 生成的前端代码。

5.1 项目结构

假设我们要做一个“数据分析仪表盘”的前端页面，项目结构如下：

saas-dashboard/ ├── .ai/ │ └── DESIGN.md ├── CLAUDE.md ├── index.html └── src/ ├── main.js └── style.css

在 Claude Code 或支持项目指令的 AI 编辑器中，AI 会优先读取CLAUDE.md和.ai/DESIGN.md。

5.2 一份可直接运行的示例 DESIGN.md

为了让示例更完整，我写了一份精简但可用的 DESIGN.md，你可以直接复制到自己的项目里改装。

# 设计规范（DESIGN.md） > 本文件供 AI 编码助手阅读。生成任何页面或组件前，必须先阅读并遵守本规范。 ## 项目定位 数据分析仪表盘，目标用户为运营与产品经理。 页面需要突出数据本身，减少装饰性元素。 ## 设计词汇 - 关键词：克制、清晰、专业、数据感 - 避免：卡通插画、强渐变、玻璃拟态、大面积阴影 ## 色彩体系 - 主色：#2563EB，仅用于主要操作按钮和激活状态 - 背景：#F8FAFC - 卡片背景：#FFFFFF - 主文字：#0F172A - 辅助文字：#64748B - 边框：#E2E8F0 - 语义色：#16A34A 成功 / #D97706 警告 / #DC2626 错误 ## 间距与栅格 - 间距基准为 4px：4、8、12、16、24、32、48 - 内容区最大宽度 1200px，左右 padding 24px - 卡片内边距 20px，卡片间距 16px ## 字体与排版 - 字体栈：Inter, "PingFang SC", "Microsoft YaHei", sans-serif - 字号：12 辅助 / 14 正文 / 16 强调 / 20 卡片标题 / 28 页面标题 - 行高：正文 1.6，标题 1.3 ## 组件模式 - 卡片：白底、1px 边框 #E2E8F0、圆角 12px、内边距 20px、无阴影 - 按钮：主按钮主色底白字；次按钮白底 1px 边框；圆角 8px - 数据指标卡片：顶部小标题，中间大数字，底部辅助说明 - 表格：表头浅灰背景，分隔线 1px，行高 40px ## 状态设计 - hover 态：背景从白到 #F8FAFC 过渡 - disabled：背景 #E2E8F0，文字 #94A3B8 - 加载中：骨架屏使用 #E2E8F0 底色，可加轻微闪烁 ## 动效 - 过渡时长 150ms 至 200ms - 缓动函数 ease-out - 不引入页面级复杂动画 ## 反模式 - 禁止使用重阴影表达层级 - 禁止使用蓝紫渐变按钮 - 禁止使用随机圆角值，如 rounded-[18px] - 禁止在同一页面使用两种以上字体 - 禁止放大数字时添加无意义的跳跳动效

5.3 给 AI 下达任务时的提示词

配置好文件后，给 AI 的下一次指令可以这样写：

基于 .ai/DESIGN.md 中的设计规范，在 index.html 中实现一个数据分析仪表盘首页。 页面需要包含： 1. 顶部导航栏（logo、菜单、用户头像） 2. 四个数据指标卡片 3. 一个最近订单表格 4. 一个简单的趋势图表区域（用 CSS/SVG 实现即可，不需要引入图表库） 要求： - 严格遵守 DESIGN.md 中的色彩、间距、字体和组件模式 - 不要使用未在规范中出现的颜色 - 不要给卡片加阴影

这里的重点不是把提示词写得花哨，而是明确告诉 AI“设计规范文件是第一优先级”。

5.4 一个符合规范的最小组件示例

在遵守上述 DESIGN.md 的前提下，AI 生成的数据指标卡片大概长这样：

<!-- 文件路径：src/components/metric-card.html --> <div class="metric-card"> <p class="metric-card__label">本月新增用户</p> <p class="metric-card__value">12,480</p> <p class="metric-card__footer"> <span class="metric-card__trend">+12.5%</span> 较上月同期 </p> </div>

/* 文件路径：src/style.css */ .metric-card { display: flex; flex-direction: column; gap: 8px; padding: 20px; background: #ffffff; border: 1px solid #e2e8f0; border-radius: 12px; box-shadow: none; } .metric-card__label { font-size: 14px; line-height: 1.6; color: #64748b; } .metric-card__value { font-size: 28px; line-height: 1.3; font-weight: 600; color: #0f172a; } .metric-card__footer { font-size: 12px; line-height: 1.6; color: #64748b; } .metric-card__trend { font-size: 12px; color: #16a34a; }

这段代码没有使用任何魔法类的 CSS 变量，也没有依赖 Tailwind，但它严格遵循了规范里定义的色彩、间距、卡片模式，视觉上非常贴近一个真实 B 端产品，而不是 AI 默认生成的“渐变阴影卡片”。

5.5 运行与验证

在浏览器中直接打开index.html，或者本地启动一个静态服务器：

cd saas-dashboard python3 -m http.server 8080

浏览器访问http://localhost:8080。验证重点不是“功能是否正常”，而是“视觉是否统一”。可以对照以下清单检查：

- 页面是否出现规范之外的新颜色？ - 卡片是否使用了阴影？ - 按钮是否为蓝紫渐变？ - 圆角是否超出了 8px/12px 两档？ - 字体是否存在两种以上？

如果任意一项不合格，不是让 AI“重新生成”，而是建议把违规点添加到 DESIGN.md 的反模式中，然后指示 AI 修正。

6. 为什么 AI 还是不遵守 DESIGN.md：常见问题与排查

越是实际操作，越会发现 AI 经常“嘴上答应，手上不听”。明明给了 DESIGN.md，它还是生成了一堆渐变阴影。遇到这种情况不要急着骂模型，先按以下维度排查。

6.1 上下文窗口被截断

AI 编程工具实际会把系统提示、用户指令、项目文件内容、对话历史拼在一起。如果项目文件很多，DESIGN.md 可能根本没进上下文。

排查方式是直接问 AI：“请完整复述 .ai/DESIGN.md 中的色彩体系。”如果它答不上来，说明文件没有被读取。

6.2 指令优先级冲突

如果CLAUDE.md或.cursorrules里写着“使用 Tailwind 的 shadow-lg 实现卡片层级”，而DESIGN.md里写着“禁止阴影”，AI 会陷入指令冲突。这时候需要统一配置，让 DESIGN.md 在设计决策上的优先级更高。

# CLAUDE.md 示例 ## 设计规范 项目所有视觉设计决策必须遵循 .ai/DESIGN.md。 如果本文件与 DESIGN.md 冲突，以 DESIGN.md 为准。

6.3 模型审美倾向过强

有些模型在训练数据中见过大量“现代 SaaS 模板”，默认输出倾向非常强。即使有规范，它也可能在个别组件上回归默认风格。这种情况下，建议：

• 把反模式写得更加具体，例如“禁止使用 shadow-lg、shadow-xl”；
• 在每次任务开始前要求 AI 复述关键约束；
• 对生成结果做代码审查，把违规点再次写回规范。

6.4 排查表

7. 在团队与开源中维护 DESIGN.md

DESIGN.md 不是一次性写完后就能一劳永逸的文件。前端项目会迭代，设计语言会调整，AI 的能力也会变化。把 DESIGN.md 当成团队内部的“设计宪法”来维护，工程上会更可持续。

7.1 版本管理

DESIGN.md 本身要纳入 Git 版本管理。每次修改不应该直接覆盖，而是类似于设计 token 的版本发布。可以在文件顶部维护一个变更记录：

## 变更记录 - 2026-03：调整卡片圆角从 8px 到 12px，统一所有卡片的内边距 - 2026-02：新增禁用状态的颜色规范 - 2026-01：明确禁止使用蓝紫渐变按钮

7.2 团队评审流程

建议把 DESIGN.md 的改动和设计评审联动。当设计师更新了 Figma 中的设计 token 时，同步更新 DESIGN.md；当开发者在 AI 生成结果中发现反复出现的风格偏差时，把修复补丁写回 DESIGN.md。

7.3 开源的价值

DESIGN.md 之所以值得开源，是因为设计规范本质上是一种可复用的知识资产。不同团队虽然产品不同，但许多 B 端页面的设计约束是高度相似的：信息密度要高、色彩不能太花哨、卡片需要统一、状态设计要完整。这些规范一旦沉淀成 Markdown 文件，就可以以开源项目、GitHub Gist 甚至 npm 包的形式共享出去。

从相关行业讨论来看，“AI 前端编程工具 + 设计规范文件”正逐渐成为显性需求。社区里除了.cursorrules和CLAUDE.md之外，需要一份更通用的、与工具无关的设计规范内容标准。DESIGN.md 恰好是这个定位：它不绑定具体工具，只约定内容结构。你可以把它用于 Cursor、Claude Code、Copilot，也可以把它交给后续任何支持项目上下文的 AI 工具。

这种“AI 上下文文件”本身也可以开源共建。例如在 GitHub 上创建一个仓库，按行业划分收集不同产品类型的 DESIGN.md 模板：SaaS 仪表盘、电商前台、内容社区、企业官网等。每个模板都有完整的色彩体系、组件模式、反模式，以及对应的示例代码片段。这比从零开始写要高效得多。

8. 最佳实践与避坑指南

根据当前 AI 前端开发的实际使用经验，下面这几点在接入 DESIGN.md 时最有价值。

8.1 保持规范短小精悍

设计规范不是越详细越好。AI 的上下文窗口有限，而且长篇大论会稀释重点。建议 DESIGN.md 控制在 150 到 250 行 Markdown，核心是让 AI 快速建立对这个项目的视觉判断。

8.2 使用“正向描述 + 反模式”双通道

只写正向描述，AI 容易自由发挥；只写反模式，AI 可能会生成过于保守、呆板的页面。最好的方式是两者结合：明确“卡片用什么样式”的同时，也说清楚“禁止用什么样式”。

8.3 为每个组件提供代码示例

一份全是文字的规范，效果不如一份带代码示例的规范。AI 很擅长模仿示例代码。在规范文件里加入一两个符合规范的组件示例，会大幅提高 AI 输出的稳定度。这正是开源 DESIGN.md 项目需要持续积累的核心资产。

8.4 让规范文件和 AI 工具配置联动

DESIGN.md 不是孤立文件。使用 Cursor 时，在.cursorrules里引用它；使用 Claude Code 时，在CLAUDE.md里引用它。这样无论以后换什么工具，设计规范都能被读取。

# .cursorrules 示例 你是一个资深前端工程师。在生成任何界面代码前，必须阅读项目根目录下的 .ai/DESIGN.md。 所有设计决策必须优先遵守该文件，当用户指令与 DESIGN.md 冲突时，先提醒用户，再决定是否执行。

8.5 把规范评审纳入代码审查

AI 生成的前端代码同样需要 code review。在设计这块，review 的第一关就是“是否遵守 DESIGN.md”。可以建立一个简单的 checklist：

- [ ] 色值是否全部来自规范？ - [ ] 间距是否为 4px 倍数？ - [ ] 卡片是否使用了规范以外的阴影？ - [ ] 按钮是否使用规范定义的类型？ - [ ] 是否包含 hover / disabled / loading 状态？

8.6 不要指望 DESIGN.md 取代设计师

最后也是最重要的边界：DESIGN.md 是一个约束工具，不是创造力工具。它能保证 AI 输出的下限，但无法替你完成真正的设计创新。如果项目需要突破性的视觉风格，核心还是由人来定义设计方向，然后再把方向提炼成规范文档交给 AI 执行。

这句话放到工程语境里就是：DESIGN.md 让 AI 从“可能生成任何风格”变成“只能在你的风格边界内生成”，它把质量控制权重新拉回人类这边。

9. 总结与下一步实践

DESIGN.md 解决的问题非常具体：AI 生成前端页面时，视觉缺乏约束、不同组件之间风格割裂、整体观感趋于廉价模板化。它的思路是把设计规范当作代码仓库里的一等公民，让 AI 编码工具在生成页面时先读设计规范，再写代码。与其他 AI 配置方案相比，它更聚焦于视觉层，同时高度可移植、可开源、可复用。

如果你想马上开始实践，建议按下面几步做：

1. 在现有 AI 前端项目里新建.ai/DESIGN.md，把本文里的模板复制进去，按项目实际修改色彩和组件模式。
2. 在CLAUDE.md或.cursorrules里增加一行引用指令，确保 AI 每次生成前先读取设计规范。
3. 让 AI 按规范生成一个现有页面，对比改造前后的视觉差距。
4. 把发现的“AI 仍不遵守的项”追加到反模式里，形成你自己的规范版本。

接下来的深入学习方向有两个：一是研究如何把 DESIGN.md 与 Design Token 生产流程打通，让设计师在 Figma 里维护 token，自动同步生成规范文件；二是关注社区中开源 DESIGN.md 模板的积累，尤其是针对不同行业、不同组件库的前端项目，整理出更细分的规范模板。

AI 前端生成能力的瓶颈，正在从“能不能写”转向“写得好不好看、是否符合品牌调性”。DESIGN.md 提供了一个轻量、开源、可落地的切入点，在这条路上先跑通的人，会享受到更高质量的 AI 辅助开发体验。