这次我们不聊某个具体的 UI 组件库也不聊某个新的 CSS 框架。我们要看的是一个正在被前端团队和 AI 编程重度用户反复提及的实践方案开源一份DESIGN.md用它来终结 AI 前端生成结果里那种挥之不去的“廉价模板感”。先说结论DESIGN.md本质上不是一套代码而是一份给 AI 前端开发工具读取的设计规范文件。它把字号、间距、颜色、圆角、阴影、组件状态、页面骨架这些设计决策从“AI 每次随机猜”变成“按规则匹配”。如果你用过 Cursor、Claude Code、Copilot 这类工具生成前端页面大概率会遇到同一个问题页面能跑功能能用但看起来就是“一眼假”——居中大标题、三个渐变卡片、满满当当的圆角按钮这就是典型的 AI 廉价模板感。DESIGN.md的目标就是让 AI 不只“写得出代码”而是“写得出符合设计系统的代码”。这篇文章会从零拆解这套方案DESIGN.md应该写什么、怎么组织、如何接入 AI 编程工具、如何做效果验证、怎么在团队或批量项目中落地。文章会给出可以直接复制修改的规范模板、规则文件配置和一批排查思路。全文不涉及任何需要特定显卡或高配置设备的步骤普通开发机就能跑通。1. 核心能力速览能力项说明项目类型面向 AI 前端开发的开源设计规范文档方案核心作用用结构化 Markdown 约束 AI 生成前端页面的视觉表现消除模板感主要文件DESIGN.md、AGENTS.md、.cursorrules、CLAUDE.md硬件要求无特殊要求普通开发机即可启动方式不需要独立服务配合 AI 编程工具读取是否支持 API本身不提供 API但可以配合命令行脚本做批量注入和规范检查是否支持批量任务支持可将规范文件批量注入多个仓库或用于自动化审查适合场景React/Vue 项目、组件库开发、AI 辅助生成前端页面、设计系统落地不适合场景纯后端项目、无视觉要求的脚本项目从材料看这个方向的核心价值在于“给 AI 立规矩”。过去我们指挥 AI 写前端依赖的是提示词里的“设计一个漂亮的登录页”“风格简洁大气”这些话术太模糊AI 只能靠概率猜。DESIGN.md把设计规范变成 AI 能读的字段比如主色是什么、圆角是几个像素、卡片间距用几号 spacing tokenAI 的输出就从“自由发挥”变成“对照执行”。2. 适用场景与使用边界2.1 适合谁用 Cursor、Claude Code、Copilot 等 AI 工具生成前端页面的开发者。在团队里做中后台系统、官网、组件库希望所有页面视觉一致的前端工程师。被“AI 生成页面很丑”困扰的产品经理和技术负责人。做前端面试题、开源项目、个人作品集希望页面能在视觉层面出彩的开发者。2.2 能解决什么问题解决 AI 生成页面颜色混乱、字号随意、间距不一致的问题。解决不同页面之间看起来像不同人写的风格断层问题。解决“功能正确但视觉廉价”的验收问题。把设计规范从设计师的 Figma 文件里解放出来让 AI 也能“照着设计稿做”。2.3 不适合什么场景纯逻辑型前端项目比如数据可视化底层、Canvas 游戏引擎视觉规范不是主要矛盾。项目已经有完整 Design Token 和组件库且 AI 只做逻辑补全的场景。需要像素级还原特定视觉稿的场景DESIGN.md只能给规则不能替代设计稿。2.4 版权、隐私与安全边界DESIGN.md作为开源方案使用时需要关注三点如果团队内部有品牌规范、视觉规范文档即使参考了开源DESIGN.md的写法也不要把公司未公开的品牌色、商业设计资产直接放进公开仓库。如果DESIGN.md中引用了第三方字体、图标库、图片资源要确认对应的授权协议尤其是商用场景。在使用 AI 编程工具时不要把包含敏感信息的代码或设计文档直接提交到公共上下文必要时使用本地模型或私有化部署方案。3. DESIGN.md 的设计思路为什么 AI 前端会有廉价模板感在讲文件怎么写之前先理解问题根源。AI 生成前端页面的底层逻辑是“概率预测”。模型看到用户输入“写一个落地页”它会基于训练数据中出现频率最高的模式生成代码。训练数据里出现最多的落地页长什么样答案是一张全屏背景图、一个居中标题、一排三个特性卡片、一个渐变按钮。这种模式因为“最常见”所以被 AI 优先选中。问题是最常见并不代表最好看更不代表适合你的项目。DESIGN.md的作用就是改变 AI 的“概率分布”。当 AI 的上下文中出现明确的规范文件时它会优先遵循规范里写的设计决策而不是去猜一个“安全但平庸”的方案。举个例子## 颜色规范 - 品牌主色#2D6A4F用于按钮、链接、选中态 - 背景色#F8F9FA用于页面默认背景 - 卡片背景#FFFFFF用于内容卡片 - 文本主色#1B2A32用于标题和正文 - 文本辅助色#5C6B73用于说明文字、占位符 - 功能色成功 #2D6A4F警告 #E9C46A错误 #E76F51 ## 使用约束 - 不在标题上使用品牌主色除非是链接或高亮文字 - 不在背景区域使用大面积的品牌主色 - 文字颜色必须从文本色阶中选择不允许直接使用品牌主色当正文颜色这段内容一旦被 AI 读取它生成按钮、标题、卡片时的颜色选择就完全不一样。它不会再把品牌色铺满全屏也不会随机选一个奇怪的颜色做正文。核心思路是把设计系统里的“Token”和“约束规则”转译成 AI 能执行的自然语言结构。不需要做成复杂的 JSON Schema用 Markdown 表格和列表就可以。4. 环境准备与文件结构DESIGN.md的落地不需要安装额外依赖但需要准备一套合理的文件结构。4.1 推荐目录结构project-root/ ├── DESIGN.md # 设计规范主文件 ├── AGENTS.md # AI 代理规则指向 DESIGN.md ├── .cursorrules # Cursor 专用规则文件 ├── CLAUDE.md # Claude Code 专用规则文件可选 ├── docs/ │ ├── components.md # 组件视觉规范 │ └── patterns.md # 页面模式规范 ├── src/ │ └── styles/ │ ├── tokens.css # 设计 Token 的 CSS 变量 │ └── global.css # 全局样式 └── scripts/ └── inject-design-md.py # 批量注入脚本4.2 前置检查清单Node.js 18 或 Python 3.9用于跑脚本或本地工具。已安装 Cursor、Claude Code、Copilot 等任一 AI 编程工具。Git 仓库已初始化方便回溯规范变更。如果项目里已有tokens.css或设计变量文件先整理一份命名清单方便和DESIGN.md对应。4.3 设计规范与现有样式文件的关系DESIGN.md不是替代 CSS 变量而是 CSS 变量的人工可读版本。两者可以配合/* tokens.css 中的颜色变量 */ :root { --color-brand-primary: #2D6A4F; --color-bg-default: #F8F9FA; --color-surface-card: #FFFFFF; --color-text-primary: #1B2A32; --color-text-secondary: #5C6B73; --color-status-success: #2D6A4F; --color-status-warning: #E9C46A; --color-status-error: #E76F51; }DESIGN.md里写的颜色值要和tokens.css保持一致。这样 AI 在生成代码时要么直接引用var(--color-brand-primary)要么在 Tailwind 配置里映射到对应的设计 Token。5. DESIGN.md 内容模板与编写方法5.1 基础信息区块文件开头要写清楚这份规范的作用范围和适用对象避免 AI 在非前端任务里也去套用这些规则。# DESIGN.md 本文件是项目的前端设计规范供 AI 编程工具在生成、修改前端代码时阅读。 适用技术栈React TypeScript Tailwind CSS 目标保证所有 AI 生成的页面在视觉上保持一致避免廉价的默认模板感。5.2 设计 Token 和样式指标表把设计指标做成表格AI 对表格的理解准确度通常高于大段叙述。类型Token 名称值用途间距spacing-14px图标与文字间距间距spacing-28px小控件内边距间距spacing-316px卡片内边距、表单间距间距spacing-424px区块间距间距spacing-540px页面大区块间距圆角radius-sm6px标签、小按钮圆角radius-md10px卡片、输入框圆角radius-lg16px弹窗、大卡片字号font-xs12px辅助文字字号font-sm14px正文次要文字字号font-base16px正文默认字号字号font-lg20px小节标题字号font-xl28px区块标题字号font-2xl36px页面首屏标题阴影shadow-card0 1px 2px rgba(0,0,0,0.06)卡片默认阴影阴影shadow-float0 8px 24px rgba(0,0,0,0.12)浮层、下拉框阴影shadow-modal0 16px 48px rgba(0,0,0,0.16)弹窗、抽屉这些值需要根据实际项目调整。如果项目是面向政府、金融的中后台系统阴影和圆角应该更克制如果是面向年轻用户的 C 端产品可以适当增加圆角和色彩饱和度。5.3 组件规范区块DESIGN.md里要写明常用组件的视觉要求。这里不需要写组件逻辑只需要写 AI 在生成这些组件时应该遵守的视觉决策。## 按钮规范 - 主按钮背景使用 --color-brand-primary文本白色圆角 radius-md高度 40px内边距 16px 24px。 - 次按钮背景白色边框 1px solid #D0D7DE文本 --color-text-primary圆角 radius-md。 - 危险操作按钮背景 --color-status-error文本白色。 - 按钮禁用态背景 #E8ECEF文本 #9AA5B1不使用透明度模拟禁用态。 - 按钮 hover 状态亮度变化 5% 以内不使用大面积位移或缩放动画。 ## 卡片规范 - 卡片默认背景--color-surface-card。 - 卡片圆角radius-md。 - 卡片间距在 Grid 布局中卡片间距使用 spacing-4。 - 卡片内部结构顶部标题区、中间内容区、底部操作区三区间距 spacing-3。 - 卡片阴影使用 shadow-card不允许使用深色大阴影。5.4 页面骨架规范很多 AI 生成的页面廉价感来自“千篇一律的居中结构”。规范里要明确不同页面类型的结构偏好。## 页面骨架规范 - 首页营销页首屏允许使用全宽视觉区但标题不强制居中推荐左对齐 侧边视觉元素。 - 后台管理系统使用左侧固定侧边栏 顶部导航 内容区的结构内容区最大宽度 1440px。 - 列表页筛选区与表格区分离筛选区使用卡片容器包裹表格不直接贴在页面边缘。 - 表单页表单项宽度不超过 640px超过一屏时使用分区卡片而不是平铺长表单。 - 登录页登录卡片宽度 400px居中放置背景允许使用品牌色渐浅色但必须保证输入框和按钮的对比度。5.5 反模板化检查清单在DESIGN.md末尾加一个反模式清单专门提示 AI 不要采用哪些典型模板写法。## 禁止的视觉模式 - 禁止在未定义 Design Token 的情况下随机使用颜色包括 #3498db、#f1c40f 等未在规范中出现的色值。 - 禁止所有卡片统一使用 12px 以上大圆角除非组件本身是胶囊按钮或标签。 - 禁止全站所有标题统一居中内容类页面标题默认左对齐。 - 禁止使用 Bootstrap 默认样式的卡片堆叠布局例如一排三个等宽卡片加居中标题的组合。 - 禁止在非营销页面使用超大渐变色按钮。 - 禁止把 hover 效果做成明显位移或放大按钮被点击时允许的反馈是颜色变化或微弱透明度变化。 - 禁止为填满空间而随意添加 Emoji 图标图标应来自项目已引入的图标库。6. 接入 AI 编程工具与启动方式DESIGN.md写好后需要让 AI 在每次会话中都能读到。不同工具读取规则文件的机制不太一样以下是通用配置方式。6.1 Cursor 接入.cursorrules在项目根目录创建.cursorrules文件内容指向设计规范你是一个资深前端工程师。在生成或修改任何前端代码之前必须先读取项目根目录下的 DESIGN.md 文件并严格遵循其中的设计 Token、组件规范和页面骨架规范。 如果 DESIGN.md 中的要求与用户提示词冲突以 DESIGN.md 为准并向用户说明冲突点。 如果没有读取到 DESIGN.md不要开始写代码先询问用户规范文件位置。6.2 Claude Code 接入CLAUDE.mdClaude Code 默认会读取项目根目录的CLAUDE.md作为系统提示词。可以把规则写成在修改前端文件前读取根目录 DESIGN.md提取其中与本次任务相关的规范字段。 工作流程 1. 确认任务涉及的技术栈。 2. 读取 DESIGN.md 中的设计 Token 和组件规范。 3. 查找项目中现有组件优先复用而不是新建。 4. 生成代码时样式值必须来自 DESIGN.md 的 Token 列表禁止凭空定义新色值。 特别约束 - 当用户要求好看一点时优先对齐 DESIGN.md 中的 spacing 和 shadow 体系而不是增加渐变和动画。6.3 通用 AGENTS.md如果团队使用多种 AI 工具可以用一个统一的AGENTS.md做入口然后在各工具配置里引用。# AGENTS.md 本仓库前端代码由 AI 辅助生成时必须遵循以下顺序 1. 读取 DESIGN.md确定设计 Token。 2. 查看 src/ 目录下已有组件的实现方式。 3. 在设计 Token 和组件规范范围内完成任务。 4. 如果任务需要新增设计 Token必须先向用户提议由用户确认后更新 DESIGN.md。6.4 启动验证配置完成后可以做一个快速验证打开 AI 编程工具新建会话说“帮我生成一个数据统计后台首页”。观察生成结果是否使用了DESIGN.md里定义的侧边栏结构、卡片间距、按钮样式。如果生成结果仍然是三卡居中 渐变按钮说明规则文件没有被读取需要检查文件路径和工具配置。7. 功能测试与效果验证DESIGN.md不是传统意义上的服务但它的“功能测试”和“效果验证”完全可以流程化。推荐做以下三组测试。7.1 基础生成一致性测试准备一组固定页面需求分别在有无DESIGN.md的情况下让 AI 生成对比差异。测试用例输入示例观察指标登录页生成一个简洁的登录页卡片宽度、圆角、输入框样式后台首页生成一个后台数据概览页侧边栏结构、卡片间距、图表容器营销落地页生成一个产品介绍落地页首屏布局、按钮样式、配色表单页生成一个用户信息表单表单项宽度、分区方式、必填标识判断标准生成结果的颜色是否能从 Token 列表中找到对应值。卡片圆角是否与radius-md或radius-lg一致。间距是否成倍数关系例如 8px、16px、24px。登录页是否保持 400px 左右的居中卡片而不是全屏平铺。7.2 规范冲突测试这个测试用来验证DESIGN.md的约束优先级。输入一段与规范冲突的提示词例如“把登录按钮改成红色渐变”。预期行为AI 应该指出“红色渐变不在设计规范中”并给出替代方案例如使用品牌主色或错误色而不是直接执行。如果 AI 直接生成了红色渐变按钮说明规则文件的提示不够强需要在规则里增加一条“生成样式前必须检查色值是否出现在 DESIGN.md 的允许列表中。”7.3 多轮修改稳定性测试在已有页面上连续提出三次修改需求每次修改后检查页面是否仍然符合设计 Token。例如“把标题字号调大一点。” 观察是否改用了font-xl或font-2xl而不是随机设一个 32px。“卡片间距放宽一些。” 观察是否从spacing-3调整到spacing-4。“添加一个提示浮层。” 观察浮层阴影是否使用了shadow-float。多轮修改是 AI 前端最容易“跑偏”的场景。第一轮生成可能很守规矩但多轮之后 AI 容易为了满足用户需求引入临时样式。规范文件里最好加一句所有修改后的样式值必须从 DESIGN.md 的 Token 中选取新增 Token 前必须经过用户确认。8. 项目级落地与批量任务DESIGN.md方案的优势在于它不是一次性提示词而是可以沉淀、复用、批量落地的规范资产。8.1 批量注入多个仓库如果你的团队有多个前端仓库可以用脚本把规范文件复制到各个项目并批量生成对应的.cursorrules或CLAUDE.md。import json import shutil from pathlib import Path design_md_source Path(./templates/DESIGN.md) projects [ Path(../project-admin), Path(../project-console), Path(../project-site), ] for project in projects: if not project.exists(): print(fskip {project}: not found) continue dest project / DESIGN.md shutil.copy(design_md_source, dest) # 生成或更新 .cursorrules cursor_rules project / .cursorrules content 读取 DESIGN.md 并严格遵循其中的设计规范。\n cursor_rules.write_text(content, encodingutf-8) print(finjected: {project})这段脚本只是一个参考模板。实际使用时需要确认目标项目是否已经存在自己的DESIGN.md如果存在不建议直接覆盖可以把新内容合并进去。8.2 自动化规范检查DESIGN.md的约束可以转化为自动化检查。简单的方式是用 Stylelint 检测颜色值是否在允许列表内。{ rules: { color-named: never, color-no-hex: true, declaration-property-value-disallowed-list: [ { color: [ /#3498db/i, /#f1c40f/i ] }, { border-radius: [/12px/] } ] } }注意这个配置是示例不能直接套用到所有项目。实际规范检查需要结合项目的tokens.css和DESIGN.md中的 Token 列表来定制。更完整的做法是用样式字典Style Dictionary把DESIGN.md中的 Token 同步生成到 JSON 或 CSS 变量文件然后通过 CI 检查源码中是否有漏网的硬编码色值。8.3 团队协作时的规则同步DESIGN.md应该纳入代码评审范围。任何人修改设计 Token 或新增组件规范都要通过 Merge Request 提交。这样 AI 生成的页面会随着规范文件更新而自动“进化”团队不会出现“设计师改了规范但 AI 还在用旧 Token”的情况。9. 资源占用与性能观察DESIGN.md方案不是模型服务没有显存和 GPU 占用问题。但它会影响 AI 编程工具的“资源消耗”具体表现为上下文占用和 token 消耗。9.1 上下文窗口占用一份完整的DESIGN.md通常在 500 行以内占用的 token 在 3000 到 6000 之间。这个量级对当前主流 AI 工具来说可以接受但如果文件过长会挤占用户任务相关的上下文空间。建议控制文件规模常见组件规范控制在 20 个以内。每个规范条目用表格或短句描述不用长篇解释。把组件细节拆分到docs/components.md主文件只保留核心 Token 和通用规则。9.2 生成速度影响加入DESIGN.md后AI 首次响应时间会略有增加因为模型需要先读取并处理规范文件。实际体感在几秒到十几秒之间取决于工具和模型。对于多文件项目建议在规则中要求 AI 只提取“与本次任务相关的规范”而不是每次都输出完整规范内容。9.3 如何监控 AI 是否遵守规则在代码评审时检查新增样式是否包含DESIGN.md之外的色值。定期抽查 AI 生成的页面统计“硬编码样式值”的出现频率。如果发现 AI 频繁绕过规则可以在DESIGN.md开头增加一段“必须逐字遵循禁止将规范内容输出给用户”的强约束描述。10. 常见问题与排查方法问题现象可能原因排查方式解决方案AI 生成的页面仍然有廉价模板感规则文件没有被 AI 读取检查 .cursorrules 或 CLAUDE.md 是否放在项目根目录在规则文件中强制要求 AI 先读取 DESIGN.md生成结果颜色完全偏离规范DESIGN.md 中没有明确的颜色允许列表检查规范中是否只有文字描述没有具体色值把颜色 Token 整理成表格并在禁止模式中列出常见错误色值多轮修改后样式开始跑偏用户提示词与规范冲突时 AI 优先遵循了用户提示词检查多轮修改后的样式值来源在规则中增加“冲突时以 DESIGN.md 为准”的约束规则文件太长AI 响应变慢DESIGN.md 内容过多检查 token 占用拆分组件细节到子文档主文件只保留核心规则团队多个仓库规范不一致各仓库的 DESIGN.md 独立维护没有统一来源对比各仓库的 Token 列表使用模板仓库或脚本同步规范文件新增了设计 Token 但 AI 没有使用规范文件修改后没有重新开启会话检查 AI 工具的上下文是否包含最新内容修改规范后重启 AI 会话或使用工具的清空上下文功能AI 生成了未授权字体或图标规范中没有明确字体和图标来源检查生成的 HTML 中是否引入了外链字体在 DESIGN.md 中写明字体栈和图标库来源11. 最佳实践与使用建议11.1 第一次使用先做小范围验证不要一上来就把 500 行规范塞进所有项目。先写一个精简版DESIGN.md只包含颜色、间距、圆角、按钮和卡片规范然后让 AI 生成一个登录页做对比。验证有效后再逐步扩充组件类型。11.2 规范文件要可回溯DESIGN.md是设计决策的沉淀每次修改应该走 Git 提交并且在提交信息里写清楚变更原因。例如“更新按钮圆角 Token统一为 radius-md”。这样团队可以回看设计决策的演变过程。11.3 区分“设计规范”和“业务需求”DESIGN.md管的是“长什么样”不管“做什么”。不要在设计规范里写业务逻辑例如“登录按钮要调登录接口”这类内容应该放在需求文档里。设计规范文件越纯粹AI 越容易执行。11.4 结合组件库使用如果项目使用了 Material UI、Ant Design、Tailwind UI 等组件库DESIGN.md应该写明“基于某某组件库通过覆盖主题变量实现定制”而不是让 AI 从零去写一套组件。这样可以减少无用代码同时保持视觉一致性。11.5 注意版权与合规如果DESIGN.md是从开源项目复制的要注意开源许可证要求保留原始署名和许可声明。如果项目里的设计规范来自商业设计稿不要直接把未脱敏的品牌色、Logo、图片发布到公开仓库。11.6 定期更新规范设计规范和代码一样需要维护。推荐每两周检查一次DESIGN.md看是否有过时的 Token、被废弃的组件规范、需要新补充的反模板化条目。12. 总结与下一步DESIGN.md解决的不是“AI 能不能写前端”的问题而是“AI 写出来的前端能不能看”的问题。它用一份 Markdown 文件把设计系统从设计师的 Figma 搬到了 AI 的上下文中让 AI 在生成页面时有章可循。相比写一大堆复杂的提示词模板这种做法的优势是可持续、可复用、可团队共享。建议第一次尝试的人先做三件事创建一份精简版DESIGN.md包含 8 到 10 个设计 Token 和 3 到 5 个组件规范。配置.cursorrules或CLAUDE.md强制 AI 在写代码前读取规范文件。用同一份需求分别在“无规范”和“有规范”情况下生成页面对比差异。最容易踩的坑是两个一是规范文件写得像散文AI 读起来抓不住重点二是规范文件写得太长AI 读到一半失去了对设计 Token 的关注。解决方式就是多用表格、少用形容词、把禁止模式放在最后作为检查清单。后续可以继续扩展的方向包括把DESIGN.md接入 Style Dictionary 生成 Design Token、在 CI 中加入设计规范检查、把DESIGN.md和 Storybook 结合用于组件文档展示以及把规范文件做成团队模板在新项目初始化时自动注入。这类方案的价值在于它真正触及了 AI 前端开发的痛点不是模型不够聪明而是我们没有给模型提供足够明确的设计约束。一份结构化的DESIGN.md可以让 AI 前端输出的下限大幅提高。如果你也在用 AI 生成前端页面这份开源方案值得收藏备用。 开源DESIGN.md：给AI前端立规矩，告别廉价模板感
这次我们不聊某个具体的 UI 组件库也不聊某个新的 CSS 框架。我们要看的是一个正在被前端团队和 AI 编程重度用户反复提及的实践方案开源一份DESIGN.md用它来终结 AI 前端生成结果里那种挥之不去的“廉价模板感”。先说结论DESIGN.md本质上不是一套代码而是一份给 AI 前端开发工具读取的设计规范文件。它把字号、间距、颜色、圆角、阴影、组件状态、页面骨架这些设计决策从“AI 每次随机猜”变成“按规则匹配”。如果你用过 Cursor、Claude Code、Copilot 这类工具生成前端页面大概率会遇到同一个问题页面能跑功能能用但看起来就是“一眼假”——居中大标题、三个渐变卡片、满满当当的圆角按钮这就是典型的 AI 廉价模板感。DESIGN.md的目标就是让 AI 不只“写得出代码”而是“写得出符合设计系统的代码”。这篇文章会从零拆解这套方案DESIGN.md应该写什么、怎么组织、如何接入 AI 编程工具、如何做效果验证、怎么在团队或批量项目中落地。文章会给出可以直接复制修改的规范模板、规则文件配置和一批排查思路。全文不涉及任何需要特定显卡或高配置设备的步骤普通开发机就能跑通。1. 核心能力速览能力项说明项目类型面向 AI 前端开发的开源设计规范文档方案核心作用用结构化 Markdown 约束 AI 生成前端页面的视觉表现消除模板感主要文件DESIGN.md、AGENTS.md、.cursorrules、CLAUDE.md硬件要求无特殊要求普通开发机即可启动方式不需要独立服务配合 AI 编程工具读取是否支持 API本身不提供 API但可以配合命令行脚本做批量注入和规范检查是否支持批量任务支持可将规范文件批量注入多个仓库或用于自动化审查适合场景React/Vue 项目、组件库开发、AI 辅助生成前端页面、设计系统落地不适合场景纯后端项目、无视觉要求的脚本项目从材料看这个方向的核心价值在于“给 AI 立规矩”。过去我们指挥 AI 写前端依赖的是提示词里的“设计一个漂亮的登录页”“风格简洁大气”这些话术太模糊AI 只能靠概率猜。DESIGN.md把设计规范变成 AI 能读的字段比如主色是什么、圆角是几个像素、卡片间距用几号 spacing tokenAI 的输出就从“自由发挥”变成“对照执行”。2. 适用场景与使用边界2.1 适合谁用 Cursor、Claude Code、Copilot 等 AI 工具生成前端页面的开发者。在团队里做中后台系统、官网、组件库希望所有页面视觉一致的前端工程师。被“AI 生成页面很丑”困扰的产品经理和技术负责人。做前端面试题、开源项目、个人作品集希望页面能在视觉层面出彩的开发者。2.2 能解决什么问题解决 AI 生成页面颜色混乱、字号随意、间距不一致的问题。解决不同页面之间看起来像不同人写的风格断层问题。解决“功能正确但视觉廉价”的验收问题。把设计规范从设计师的 Figma 文件里解放出来让 AI 也能“照着设计稿做”。2.3 不适合什么场景纯逻辑型前端项目比如数据可视化底层、Canvas 游戏引擎视觉规范不是主要矛盾。项目已经有完整 Design Token 和组件库且 AI 只做逻辑补全的场景。需要像素级还原特定视觉稿的场景DESIGN.md只能给规则不能替代设计稿。2.4 版权、隐私与安全边界DESIGN.md作为开源方案使用时需要关注三点如果团队内部有品牌规范、视觉规范文档即使参考了开源DESIGN.md的写法也不要把公司未公开的品牌色、商业设计资产直接放进公开仓库。如果DESIGN.md中引用了第三方字体、图标库、图片资源要确认对应的授权协议尤其是商用场景。在使用 AI 编程工具时不要把包含敏感信息的代码或设计文档直接提交到公共上下文必要时使用本地模型或私有化部署方案。3. DESIGN.md 的设计思路为什么 AI 前端会有廉价模板感在讲文件怎么写之前先理解问题根源。AI 生成前端页面的底层逻辑是“概率预测”。模型看到用户输入“写一个落地页”它会基于训练数据中出现频率最高的模式生成代码。训练数据里出现最多的落地页长什么样答案是一张全屏背景图、一个居中标题、一排三个特性卡片、一个渐变按钮。这种模式因为“最常见”所以被 AI 优先选中。问题是最常见并不代表最好看更不代表适合你的项目。DESIGN.md的作用就是改变 AI 的“概率分布”。当 AI 的上下文中出现明确的规范文件时它会优先遵循规范里写的设计决策而不是去猜一个“安全但平庸”的方案。举个例子## 颜色规范 - 品牌主色#2D6A4F用于按钮、链接、选中态 - 背景色#F8F9FA用于页面默认背景 - 卡片背景#FFFFFF用于内容卡片 - 文本主色#1B2A32用于标题和正文 - 文本辅助色#5C6B73用于说明文字、占位符 - 功能色成功 #2D6A4F警告 #E9C46A错误 #E76F51 ## 使用约束 - 不在标题上使用品牌主色除非是链接或高亮文字 - 不在背景区域使用大面积的品牌主色 - 文字颜色必须从文本色阶中选择不允许直接使用品牌主色当正文颜色这段内容一旦被 AI 读取它生成按钮、标题、卡片时的颜色选择就完全不一样。它不会再把品牌色铺满全屏也不会随机选一个奇怪的颜色做正文。核心思路是把设计系统里的“Token”和“约束规则”转译成 AI 能执行的自然语言结构。不需要做成复杂的 JSON Schema用 Markdown 表格和列表就可以。4. 环境准备与文件结构DESIGN.md的落地不需要安装额外依赖但需要准备一套合理的文件结构。4.1 推荐目录结构project-root/ ├── DESIGN.md # 设计规范主文件 ├── AGENTS.md # AI 代理规则指向 DESIGN.md ├── .cursorrules # Cursor 专用规则文件 ├── CLAUDE.md # Claude Code 专用规则文件可选 ├── docs/ │ ├── components.md # 组件视觉规范 │ └── patterns.md # 页面模式规范 ├── src/ │ └── styles/ │ ├── tokens.css # 设计 Token 的 CSS 变量 │ └── global.css # 全局样式 └── scripts/ └── inject-design-md.py # 批量注入脚本4.2 前置检查清单Node.js 18 或 Python 3.9用于跑脚本或本地工具。已安装 Cursor、Claude Code、Copilot 等任一 AI 编程工具。Git 仓库已初始化方便回溯规范变更。如果项目里已有tokens.css或设计变量文件先整理一份命名清单方便和DESIGN.md对应。4.3 设计规范与现有样式文件的关系DESIGN.md不是替代 CSS 变量而是 CSS 变量的人工可读版本。两者可以配合/* tokens.css 中的颜色变量 */ :root { --color-brand-primary: #2D6A4F; --color-bg-default: #F8F9FA; --color-surface-card: #FFFFFF; --color-text-primary: #1B2A32; --color-text-secondary: #5C6B73; --color-status-success: #2D6A4F; --color-status-warning: #E9C46A; --color-status-error: #E76F51; }DESIGN.md里写的颜色值要和tokens.css保持一致。这样 AI 在生成代码时要么直接引用var(--color-brand-primary)要么在 Tailwind 配置里映射到对应的设计 Token。5. DESIGN.md 内容模板与编写方法5.1 基础信息区块文件开头要写清楚这份规范的作用范围和适用对象避免 AI 在非前端任务里也去套用这些规则。# DESIGN.md 本文件是项目的前端设计规范供 AI 编程工具在生成、修改前端代码时阅读。 适用技术栈React TypeScript Tailwind CSS 目标保证所有 AI 生成的页面在视觉上保持一致避免廉价的默认模板感。5.2 设计 Token 和样式指标表把设计指标做成表格AI 对表格的理解准确度通常高于大段叙述。类型Token 名称值用途间距spacing-14px图标与文字间距间距spacing-28px小控件内边距间距spacing-316px卡片内边距、表单间距间距spacing-424px区块间距间距spacing-540px页面大区块间距圆角radius-sm6px标签、小按钮圆角radius-md10px卡片、输入框圆角radius-lg16px弹窗、大卡片字号font-xs12px辅助文字字号font-sm14px正文次要文字字号font-base16px正文默认字号字号font-lg20px小节标题字号font-xl28px区块标题字号font-2xl36px页面首屏标题阴影shadow-card0 1px 2px rgba(0,0,0,0.06)卡片默认阴影阴影shadow-float0 8px 24px rgba(0,0,0,0.12)浮层、下拉框阴影shadow-modal0 16px 48px rgba(0,0,0,0.16)弹窗、抽屉这些值需要根据实际项目调整。如果项目是面向政府、金融的中后台系统阴影和圆角应该更克制如果是面向年轻用户的 C 端产品可以适当增加圆角和色彩饱和度。5.3 组件规范区块DESIGN.md里要写明常用组件的视觉要求。这里不需要写组件逻辑只需要写 AI 在生成这些组件时应该遵守的视觉决策。## 按钮规范 - 主按钮背景使用 --color-brand-primary文本白色圆角 radius-md高度 40px内边距 16px 24px。 - 次按钮背景白色边框 1px solid #D0D7DE文本 --color-text-primary圆角 radius-md。 - 危险操作按钮背景 --color-status-error文本白色。 - 按钮禁用态背景 #E8ECEF文本 #9AA5B1不使用透明度模拟禁用态。 - 按钮 hover 状态亮度变化 5% 以内不使用大面积位移或缩放动画。 ## 卡片规范 - 卡片默认背景--color-surface-card。 - 卡片圆角radius-md。 - 卡片间距在 Grid 布局中卡片间距使用 spacing-4。 - 卡片内部结构顶部标题区、中间内容区、底部操作区三区间距 spacing-3。 - 卡片阴影使用 shadow-card不允许使用深色大阴影。5.4 页面骨架规范很多 AI 生成的页面廉价感来自“千篇一律的居中结构”。规范里要明确不同页面类型的结构偏好。## 页面骨架规范 - 首页营销页首屏允许使用全宽视觉区但标题不强制居中推荐左对齐 侧边视觉元素。 - 后台管理系统使用左侧固定侧边栏 顶部导航 内容区的结构内容区最大宽度 1440px。 - 列表页筛选区与表格区分离筛选区使用卡片容器包裹表格不直接贴在页面边缘。 - 表单页表单项宽度不超过 640px超过一屏时使用分区卡片而不是平铺长表单。 - 登录页登录卡片宽度 400px居中放置背景允许使用品牌色渐浅色但必须保证输入框和按钮的对比度。5.5 反模板化检查清单在DESIGN.md末尾加一个反模式清单专门提示 AI 不要采用哪些典型模板写法。## 禁止的视觉模式 - 禁止在未定义 Design Token 的情况下随机使用颜色包括 #3498db、#f1c40f 等未在规范中出现的色值。 - 禁止所有卡片统一使用 12px 以上大圆角除非组件本身是胶囊按钮或标签。 - 禁止全站所有标题统一居中内容类页面标题默认左对齐。 - 禁止使用 Bootstrap 默认样式的卡片堆叠布局例如一排三个等宽卡片加居中标题的组合。 - 禁止在非营销页面使用超大渐变色按钮。 - 禁止把 hover 效果做成明显位移或放大按钮被点击时允许的反馈是颜色变化或微弱透明度变化。 - 禁止为填满空间而随意添加 Emoji 图标图标应来自项目已引入的图标库。6. 接入 AI 编程工具与启动方式DESIGN.md写好后需要让 AI 在每次会话中都能读到。不同工具读取规则文件的机制不太一样以下是通用配置方式。6.1 Cursor 接入.cursorrules在项目根目录创建.cursorrules文件内容指向设计规范你是一个资深前端工程师。在生成或修改任何前端代码之前必须先读取项目根目录下的 DESIGN.md 文件并严格遵循其中的设计 Token、组件规范和页面骨架规范。 如果 DESIGN.md 中的要求与用户提示词冲突以 DESIGN.md 为准并向用户说明冲突点。 如果没有读取到 DESIGN.md不要开始写代码先询问用户规范文件位置。6.2 Claude Code 接入CLAUDE.mdClaude Code 默认会读取项目根目录的CLAUDE.md作为系统提示词。可以把规则写成在修改前端文件前读取根目录 DESIGN.md提取其中与本次任务相关的规范字段。 工作流程 1. 确认任务涉及的技术栈。 2. 读取 DESIGN.md 中的设计 Token 和组件规范。 3. 查找项目中现有组件优先复用而不是新建。 4. 生成代码时样式值必须来自 DESIGN.md 的 Token 列表禁止凭空定义新色值。 特别约束 - 当用户要求好看一点时优先对齐 DESIGN.md 中的 spacing 和 shadow 体系而不是增加渐变和动画。6.3 通用 AGENTS.md如果团队使用多种 AI 工具可以用一个统一的AGENTS.md做入口然后在各工具配置里引用。# AGENTS.md 本仓库前端代码由 AI 辅助生成时必须遵循以下顺序 1. 读取 DESIGN.md确定设计 Token。 2. 查看 src/ 目录下已有组件的实现方式。 3. 在设计 Token 和组件规范范围内完成任务。 4. 如果任务需要新增设计 Token必须先向用户提议由用户确认后更新 DESIGN.md。6.4 启动验证配置完成后可以做一个快速验证打开 AI 编程工具新建会话说“帮我生成一个数据统计后台首页”。观察生成结果是否使用了DESIGN.md里定义的侧边栏结构、卡片间距、按钮样式。如果生成结果仍然是三卡居中 渐变按钮说明规则文件没有被读取需要检查文件路径和工具配置。7. 功能测试与效果验证DESIGN.md不是传统意义上的服务但它的“功能测试”和“效果验证”完全可以流程化。推荐做以下三组测试。7.1 基础生成一致性测试准备一组固定页面需求分别在有无DESIGN.md的情况下让 AI 生成对比差异。测试用例输入示例观察指标登录页生成一个简洁的登录页卡片宽度、圆角、输入框样式后台首页生成一个后台数据概览页侧边栏结构、卡片间距、图表容器营销落地页生成一个产品介绍落地页首屏布局、按钮样式、配色表单页生成一个用户信息表单表单项宽度、分区方式、必填标识判断标准生成结果的颜色是否能从 Token 列表中找到对应值。卡片圆角是否与radius-md或radius-lg一致。间距是否成倍数关系例如 8px、16px、24px。登录页是否保持 400px 左右的居中卡片而不是全屏平铺。7.2 规范冲突测试这个测试用来验证DESIGN.md的约束优先级。输入一段与规范冲突的提示词例如“把登录按钮改成红色渐变”。预期行为AI 应该指出“红色渐变不在设计规范中”并给出替代方案例如使用品牌主色或错误色而不是直接执行。如果 AI 直接生成了红色渐变按钮说明规则文件的提示不够强需要在规则里增加一条“生成样式前必须检查色值是否出现在 DESIGN.md 的允许列表中。”7.3 多轮修改稳定性测试在已有页面上连续提出三次修改需求每次修改后检查页面是否仍然符合设计 Token。例如“把标题字号调大一点。” 观察是否改用了font-xl或font-2xl而不是随机设一个 32px。“卡片间距放宽一些。” 观察是否从spacing-3调整到spacing-4。“添加一个提示浮层。” 观察浮层阴影是否使用了shadow-float。多轮修改是 AI 前端最容易“跑偏”的场景。第一轮生成可能很守规矩但多轮之后 AI 容易为了满足用户需求引入临时样式。规范文件里最好加一句所有修改后的样式值必须从 DESIGN.md 的 Token 中选取新增 Token 前必须经过用户确认。8. 项目级落地与批量任务DESIGN.md方案的优势在于它不是一次性提示词而是可以沉淀、复用、批量落地的规范资产。8.1 批量注入多个仓库如果你的团队有多个前端仓库可以用脚本把规范文件复制到各个项目并批量生成对应的.cursorrules或CLAUDE.md。import json import shutil from pathlib import Path design_md_source Path(./templates/DESIGN.md) projects [ Path(../project-admin), Path(../project-console), Path(../project-site), ] for project in projects: if not project.exists(): print(fskip {project}: not found) continue dest project / DESIGN.md shutil.copy(design_md_source, dest) # 生成或更新 .cursorrules cursor_rules project / .cursorrules content 读取 DESIGN.md 并严格遵循其中的设计规范。\n cursor_rules.write_text(content, encodingutf-8) print(finjected: {project})这段脚本只是一个参考模板。实际使用时需要确认目标项目是否已经存在自己的DESIGN.md如果存在不建议直接覆盖可以把新内容合并进去。8.2 自动化规范检查DESIGN.md的约束可以转化为自动化检查。简单的方式是用 Stylelint 检测颜色值是否在允许列表内。{ rules: { color-named: never, color-no-hex: true, declaration-property-value-disallowed-list: [ { color: [ /#3498db/i, /#f1c40f/i ] }, { border-radius: [/12px/] } ] } }注意这个配置是示例不能直接套用到所有项目。实际规范检查需要结合项目的tokens.css和DESIGN.md中的 Token 列表来定制。更完整的做法是用样式字典Style Dictionary把DESIGN.md中的 Token 同步生成到 JSON 或 CSS 变量文件然后通过 CI 检查源码中是否有漏网的硬编码色值。8.3 团队协作时的规则同步DESIGN.md应该纳入代码评审范围。任何人修改设计 Token 或新增组件规范都要通过 Merge Request 提交。这样 AI 生成的页面会随着规范文件更新而自动“进化”团队不会出现“设计师改了规范但 AI 还在用旧 Token”的情况。9. 资源占用与性能观察DESIGN.md方案不是模型服务没有显存和 GPU 占用问题。但它会影响 AI 编程工具的“资源消耗”具体表现为上下文占用和 token 消耗。9.1 上下文窗口占用一份完整的DESIGN.md通常在 500 行以内占用的 token 在 3000 到 6000 之间。这个量级对当前主流 AI 工具来说可以接受但如果文件过长会挤占用户任务相关的上下文空间。建议控制文件规模常见组件规范控制在 20 个以内。每个规范条目用表格或短句描述不用长篇解释。把组件细节拆分到docs/components.md主文件只保留核心 Token 和通用规则。9.2 生成速度影响加入DESIGN.md后AI 首次响应时间会略有增加因为模型需要先读取并处理规范文件。实际体感在几秒到十几秒之间取决于工具和模型。对于多文件项目建议在规则中要求 AI 只提取“与本次任务相关的规范”而不是每次都输出完整规范内容。9.3 如何监控 AI 是否遵守规则在代码评审时检查新增样式是否包含DESIGN.md之外的色值。定期抽查 AI 生成的页面统计“硬编码样式值”的出现频率。如果发现 AI 频繁绕过规则可以在DESIGN.md开头增加一段“必须逐字遵循禁止将规范内容输出给用户”的强约束描述。10. 常见问题与排查方法问题现象可能原因排查方式解决方案AI 生成的页面仍然有廉价模板感规则文件没有被 AI 读取检查 .cursorrules 或 CLAUDE.md 是否放在项目根目录在规则文件中强制要求 AI 先读取 DESIGN.md生成结果颜色完全偏离规范DESIGN.md 中没有明确的颜色允许列表检查规范中是否只有文字描述没有具体色值把颜色 Token 整理成表格并在禁止模式中列出常见错误色值多轮修改后样式开始跑偏用户提示词与规范冲突时 AI 优先遵循了用户提示词检查多轮修改后的样式值来源在规则中增加“冲突时以 DESIGN.md 为准”的约束规则文件太长AI 响应变慢DESIGN.md 内容过多检查 token 占用拆分组件细节到子文档主文件只保留核心规则团队多个仓库规范不一致各仓库的 DESIGN.md 独立维护没有统一来源对比各仓库的 Token 列表使用模板仓库或脚本同步规范文件新增了设计 Token 但 AI 没有使用规范文件修改后没有重新开启会话检查 AI 工具的上下文是否包含最新内容修改规范后重启 AI 会话或使用工具的清空上下文功能AI 生成了未授权字体或图标规范中没有明确字体和图标来源检查生成的 HTML 中是否引入了外链字体在 DESIGN.md 中写明字体栈和图标库来源11. 最佳实践与使用建议11.1 第一次使用先做小范围验证不要一上来就把 500 行规范塞进所有项目。先写一个精简版DESIGN.md只包含颜色、间距、圆角、按钮和卡片规范然后让 AI 生成一个登录页做对比。验证有效后再逐步扩充组件类型。11.2 规范文件要可回溯DESIGN.md是设计决策的沉淀每次修改应该走 Git 提交并且在提交信息里写清楚变更原因。例如“更新按钮圆角 Token统一为 radius-md”。这样团队可以回看设计决策的演变过程。11.3 区分“设计规范”和“业务需求”DESIGN.md管的是“长什么样”不管“做什么”。不要在设计规范里写业务逻辑例如“登录按钮要调登录接口”这类内容应该放在需求文档里。设计规范文件越纯粹AI 越容易执行。11.4 结合组件库使用如果项目使用了 Material UI、Ant Design、Tailwind UI 等组件库DESIGN.md应该写明“基于某某组件库通过覆盖主题变量实现定制”而不是让 AI 从零去写一套组件。这样可以减少无用代码同时保持视觉一致性。11.5 注意版权与合规如果DESIGN.md是从开源项目复制的要注意开源许可证要求保留原始署名和许可声明。如果项目里的设计规范来自商业设计稿不要直接把未脱敏的品牌色、Logo、图片发布到公开仓库。11.6 定期更新规范设计规范和代码一样需要维护。推荐每两周检查一次DESIGN.md看是否有过时的 Token、被废弃的组件规范、需要新补充的反模板化条目。12. 总结与下一步DESIGN.md解决的不是“AI 能不能写前端”的问题而是“AI 写出来的前端能不能看”的问题。它用一份 Markdown 文件把设计系统从设计师的 Figma 搬到了 AI 的上下文中让 AI 在生成页面时有章可循。相比写一大堆复杂的提示词模板这种做法的优势是可持续、可复用、可团队共享。建议第一次尝试的人先做三件事创建一份精简版DESIGN.md包含 8 到 10 个设计 Token 和 3 到 5 个组件规范。配置.cursorrules或CLAUDE.md强制 AI 在写代码前读取规范文件。用同一份需求分别在“无规范”和“有规范”情况下生成页面对比差异。最容易踩的坑是两个一是规范文件写得像散文AI 读起来抓不住重点二是规范文件写得太长AI 读到一半失去了对设计 Token 的关注。解决方式就是多用表格、少用形容词、把禁止模式放在最后作为检查清单。后续可以继续扩展的方向包括把DESIGN.md接入 Style Dictionary 生成 Design Token、在 CI 中加入设计规范检查、把DESIGN.md和 Storybook 结合用于组件文档展示以及把规范文件做成团队模板在新项目初始化时自动注入。这类方案的价值在于它真正触及了 AI 前端开发的痛点不是模型不够聪明而是我们没有给模型提供足够明确的设计约束。一份结构化的DESIGN.md可以让 AI 前端输出的下限大幅提高。如果你也在用 AI 生成前端页面这份开源方案值得收藏备用。