这篇帖子想聊聊一个我自己压箱底的工具思路：用一个 Markdown 文件，把 AI 从“瞎编界面”的状态里拽回来。项目名字叫 awesome-design-md，一句话说，它就是把设计规范、组件清单、页面结构全部写进一个结构化的 Markdown 文档里，让 AI 在生成界面时按图索骥，而不是自由发挥。
先说我为什么需要它。这两年我用 AI 写前端、搭后台、做落地页，最头疼的不是 AI 写不出代码，而是它太能“脑补”了。你让它做个表格，它给你配个跑马灯轮播图；你让它做深色主题，它在某个角落给你吐出一块高饱和荧光绿。尤其是用 Cursor、Claude、Codex 这类工具生成完整页面时，AI 经常把“好看”理解成“堆满”，把“示例”当成“最终稿”。后来我试着把界面设计的所有约束写进 Markdown，效果立竿见影——AI 的输出稳定了不止一个档次。
这篇文章我会从底层逻辑讲起，拆解为什么 Markdown 能当 AI 的“界面约束协议”，然后一步步展示我自己在用的设计系统模板结构、接入 AI 工作流的具体姿势、以及踩过的坑和排查方法。整个内容基于我在多个实际项目里的实践沉淀，直接照抄就能跑，不用二次发明轮子。
1. 先拆清楚：为什么 Markdown 能治得住 AI 的“自由发挥”
1.1 AI 生成界面的最大痛点不是“不会写”，而是“没有边界”
很多人觉得 AI 写界面代码写得差，是因为模型能力不行。我最早也这么以为，后来用同一个模型、同一个 prompt，换了不同的“约束方式”，效果天差地别，才想明白问题不在模型，在于我们给模型划定的“搜索空间”太大了。
AI 在生成代码的时候，本质是在做概率采样：它在你给的上下文里，寻找最“像样”的下一步。你只给一句“帮我做一个后台管理页面”，它的概率空间里既有简洁的 SaaS 风格，也有花里胡哨的营销页风格，还有不知哪来的 2015 年风格模板。模型在庞大风格空间里随机游走，结果就是“平均化”的丑陋，或者随机选中某个极端风格。
Markdown 文件在这里干的事，就是强制压缩这个概率空间。当你把“颜色只能用这几个色值”“间距只用 4、8、16、24px”“组件只有表格、表单、按钮、标签这四种”全部写清楚，AI 的可选范围被锁死了，它就没机会在边界外瞎折腾。
1.2 Markdown 相比 JSON、YAML 的独特优势：人类可读，模型更好理解
有人可能会问，为啥不直接用 JSON 或 YAML 传结构化配置？我也试过。JSON 确实严格，但问题在于：
- 在 AI 对话上下文里，JSON 的信息密度低，嵌套层级一深，模型的注意力很容易分散到花括号和缩进上，反而忽略语义。
- 人类阅读体验差。你自己要维护这套“设计协议”的时候，打开 JSON 文件，满眼都是引号和逗号，改起来心累。
- AI 对自然语言的理解能力远强于对形式化语法的理解。Markdown 的标题、列表、表格，天然是语义化的，模型在训练语料里见过海量 Markdown 文档，它对这种格式的“条件反射”比 JSON 强得多。
实际测试下来，同一套设计约束，用 Markdown 写，AI 遵守的程度大概有 85% 到 90%；用 JSON 写，只有 60% 到 70%。因为模型经常在嵌套 JSON 的某一行漏掉一个字段。
所以我个人认为：Markdown 就是 AI 界面控制的“甜点位”，它足够结构化的同时，又保留了自然语言的容错空间。
1.3 awesome-design-md 的核心理念：把设计系统变成“给 AI 的说明书”
awesome-design-md 提供的不是一套固定模板，而是一种思路：你的设计系统不是只给人类看的 Figma 组件库，它应该也是一份给 AI 读的说明书。说明书要回答三个问题：
- 这个界面有哪些“零件”（组件）？
- 这些零件怎么组合（布局模式）？
- 组合的时候有哪些“禁忌”（不要做什么）？
有了这三块内容，任何支持文件上下文的 AI 编程工具，都能真正读懂你的设计意图。我把这个思路用在多个项目之后，最大的感受是：AI 从“自由设计师”变成了“严格按照施工图作业的工程队”，而且你换不同 AI 工具，输出的界面风格依然能保持统一。
2. 核心细节拆解：一份能约束 AI 的 Markdown 到底要写什么
2.1 这份 Markdown 文件的最小骨架：四件事必须说清楚
我自己打磨过很多版本，最后沉淀下来，一份能有效约束 AI 的 Markdown 设计文档，至少包含四个部分：
第一，全局设计规范。包括颜色、字体、圆角、间距、阴影。这部分要给出明确的 token 值，别写“用好看的蓝色”，要写“主色 #2563EB，Hover 加深为 #1D4ED8，禁用态用 #93C5FD”。AI 对十六进制颜色值的把握，比对“好看”这种模糊词的把握稳定得多。
第二，组件清单。列出当前项目中允许使用的组件，每个组件一句话说清职责，比如“Input 组件：用于单行文本输入，input 内禁止嵌套按钮”。组件清单的意义在于，AI 经常凭记忆生成自己“知道”的组件，但那些组件在你的项目里根本不存在。用 Markdown 锁死组件列表，AI 就不会擅自引入一个你没安装过的图表库。
第三，布局规则。说清楚页面的结构模式，比如“后台页一律采用左侧边栏+顶部头+右侧内容区三段式”“内容区最大宽度 1200px，卡片间距 16px”。这块最容易写，也最容易让 AI 的布局稳定下来。
第四，负面清单（Do Not Do）。这块是关键中的关键，我单独在 2.2 详说。
2.2 负面清单是灵魂：AI 瞎编的根源是“没人告诉它什么不能干”
我发现绝大多数 AI 界面翻车现场，问题都不出在“它不知道怎么做”，而是“没人告诉它什么不能做”。大模型没有常识里的“克制感”，它就像是第一天入职的设计师，充满热情但完全没有项目背景，什么风格都想试。
所以在 awesome-design-md 这个模式里，我强烈建议留一个角落专门写负面清单。比如：
- 禁止使用未在组件清单中出现过的组件。
- 禁止出现三个以上的主色之外的颜色。
- 禁止使用圆角大于 16px 的卡片。
- 禁止自行添加字体图标库（如 Font Awesome）。
- 禁止在移动端布局中使用固定宽度。
你可能觉得这些条目写出来有点“弱智”——这不是明摆着的吗？但 AI 就是会把明摆着的事做错。Write down everything you don't want, and the model will actually listen.
2.3 用表格和代码块固化“AI 最容易跑偏”的设计参数
Markdown 里的表格是我认为最有用的“AI 约束工具”，没有之一。表格天然适合表达“属性-值”的映射关系，而且模型对表格的解析成功率极高。我一般会把颜色、字体、间距体系全部做成表格，比如：
| Token 名称 | 属性 | 值 | 使用场景 |
|---|---|---|---|
| color-primary | 颜色 | #2563EB | 按钮、链接、选中态 |
| color-bg | 颜色 | #F9FAFB | 页面背景 |
| color-text | 颜色 | #111827 | 主文本 |
| spacing-md | 间距 | 16px | 卡片内边距、列表项间距 |
| radius-sm | 圆角 | 6px | 按钮、输入框 |
AI 对这种格式几乎零障碍理解。它看到表格，就会把表格里的值当作“标准答案”。
还有一个小技巧：设计规范里的值，尽量用代码块包裹一份完整示例。比如：
:root { --color-primary: #2563EB; --color-bg: #F9FAFB; --color-text: #111827; --radius-md: 8px; }AI 对代码块的“执行力”远高于自然语言描述。你给一段 CSS 变量定义，它生成的 Tailwind 配置、内联样式，都会不自觉地往这套值上靠。语言会模糊，代码不会。
3. 实操过程：从零到一把 awesome-design-md 接入自己的 AI 工作流
3.1 第一步：盘点你自己的“设计惯性”，把它变成规范
任何工具落地第一步都是盘自己的存量。打开你最近做的三个项目，问自己几个问题:
- 你一直用的主色、辅助色到底是什么？不要看设计稿里标的，去代码里截图取色，用取色器吸一遍，你会发现真实值和你脑子里的值经常对不上。
- 你项目里用得最多的十个组件是什么？是 Button、Input、Table、Modal 还是别的？
- 你的页面布局是不是有统一模板？后台页面是不是都有侧边栏？落地页是不是都有顶部导航？
把这些问题回答了，你就有了自己专属设计规范的一手素材。别去抄别人的设计系统，因为不同项目的基因不同，抄来的规范约束不了你的 AI，反而会干扰它。
3.2 第二步：按 awesome-design-md 的模板，生成你自己的 md 文件
我自己用的模板在实际项目里迭代了很多次，这里给出一份可以直接改用的精简骨架：
# 项目设计规范（AI 约束文档） ## 1. 全局规范 ### 颜色 | Token | 值 | 用途 | | primary | #2563EB | 主操作按钮、链接 | | ... | ... | ... | ### 字体 - 字体栈: Inter, PingFang SC, sans-serif - 字号: 12 / 14 / 16 / 20 / 24 / 32 - 标题一律使用 600 以上字重 ### 间距与圆角 - 间距体系: 4 / 8 / 12 / 16 / 24 / 32 - 圆角: 6(按钮) / 8(卡片) / 12(弹窗) ## 2. 组件清单 ### 允许使用的组件 - Button: 主要操作触发 - Input: 单行文本输入 - ... ### 禁止使用的组件 - Carousel: 本项目不使用轮播图 - Chart: 图表采用后端出图，前端不引入图表库 ## 3. 页面布局 - 后台页面: 侧边栏 240px + 内容区自适应 - 移动端: 单栏布局，最大宽度 480px ## 4. 负面清单 - 禁止使用未在组件清单中的组件 - 禁止出现渐变背景 - 禁止使用超过两种字体这个文件本身不需要很长，一页到两页足矣。我见过有人把设计规范写成 50 页，结果 AI 根本看不过来，关键信息全淹没在冗余描述里。给 AI 看的文档，贵在精简，核心 token 必须稀疏散布，让它一眼能扫完。
3.3 第三步：把 md 文件“塞”进 AI 工具的上下文
不同 AI 编程工具的接入方式略有不同，但底层思路是一致的：让这个 md 文件出现在 AI 的上下文窗口里。
如果你用的是 Cursor 或 Trae 这类 IDE 工具，直接把 设计规范.md 放在项目根目录，然后在对话里告诉它“先读一下设计规范.md，再按里面的要求生成页面”。如果你的 AI 工具支持 MCP 文件读取，就更好了，可以自动让其感知。
如果你用的是 Claude、ChatGPT 这类纯对话工具，就在每次让它设计界面时，把 md 文件的核心内容直接粘贴进提示词，放在“你是一个前端工程师，请按照下面的设计规范工作”和实际任务描述之间。
这里有个很重要的实操心得：md 文件一定要放在对话的前部而不是后部。AI 对开头的上下文注意力分配最强，你把设计规范放在 prompt 中段或尾部，它生成代码的时候可能已经“忘了”。放在开头，相当于帮 AI 先进入“工程模式”。
3.4 第四步：第一次实测——让 AI 按规范生成一个完整页面
规范文件写好了，接入方式也搞定了，接下来就是验货。我建议第一次测试时，选一个中等复杂度的页面，比如一个带侧边栏、数据表格、筛选表单、分页器的后台管理页，这类页面组件类型丰富，最容易暴露问题。
测试时给 AI 的任务描述要简短，只描述功能需求，比如“生成一个用户管理页面，包含筛选区、表格、分页，表格展示用户名、邮箱、注册时间、状态”。然后观察它是否完全按照 md 文件里的规范执行。重点检查：
- 颜色是不是严格走你定义的 token，有没有自己发挥的色值。
- 组件有没有超出组件清单，是否凭空造了组件。
- 布局是不是按你定义的骨架来，有没有自作主张加东西。
第一次测试通常不会 100% 完美，但这没关系。这一步的核心目的不是一次生成完美页面，而是发现 md 文件里的“漏洞”——你没写清楚的规则，AI 就会钻空子。看到它在哪里钻空子，你就往负面清单里补一条。这也是我用下来觉得最有效的一个迭代闭环：生成、审查、补规范、再生成。
3.5 第五步：把 md 文件变成团队协作的“活文档”
如果只是自己一个人用，md 就算写得再好，价值也有限。真正让它发挥威力的是团队协作场景。你自己维护好这份文档，然后约定：所有成员在让 AI 生成界面时，都必须引用同一份 设计规范.md。
这样做的直接好处是，团队五个人用 AI 生成出来的页面，风格是一致的。以前靠人工 code review 去纠正各种“AI 味”风格不一致的改动，现在前置到 AI 生成阶段就解决了。
还有一个衍生的好处：这份 Markdown 文档既是给 AI 看的，也是给新人看的。新人入职，不用翻设计稿、看代码，把这篇文章读一遍，就能知道项目的设计语言是什么，哪些能做哪些不能做。
4. 常见问题与排查技巧实录
4.1 问题一：AI 完全无视规范文档，还是我行我素
这是遇到最多的情况，文章反馈里十个有九个是这个问题。但排查下来，绝大多数都不是 md 本身的问题，而是上下文顺序或文档长度的问题。
优先检查三件事：第一，规范文档是不是放在 prompt 的最前面了？第二，文档是不是太长、信息过密？如果你把 30 个组件的详细说明全塞进去，AI 能记住的只有前面的 10 个，后面的组件清单基本就是摆设。第三，任务描述里是不是有和规范冲突的信息？比如规范里写明“禁止渐变”，但你在任务里补了一句“让页面更现代一点”，AI 就会认为“现代”的优先级高于规范，最终生成一个渐变页面。
我的排查手段很简单：做个消融测试。把任务描述里的所有修饰词全删掉，只留功能需求。如果 AI 这时能严格遵守规范，说明问题出在任务描述和规范互相打架；如果连纯功能描述都执行偏了，那才是规范文档本身的问题。
4.2 问题二：AI 遵守了 90%，但总在某个细节上偏离
这种情况最磨人。大方向都对，就是某个颜色、某个圆角、某个组件永远不听话。我遇到过一个项目，规范里明确了表格的分页器用简单文本样式，AI 每次生成的都是完整带跳页按钮的分页条。
这种问题本质上是“规范没有触及到那个具体层级”。你写了“表格统一样式”，但 AI 生成的 pager 组件默认就是带跳页的，它自己的训练数据里，表格分页器长那个样子，你的规范没直接说“分页器只保留上一页/下一页”这种更细的颗粒度，它就默认按自己的惯性走。
解决方案也很粗暴：把那个反复出问题的细节，单独写一条负面清单。不要只写“表格统一”，要写“表格分页器仅显示上一页/下一页按钮，禁止跳页输入框和页码数字”。颗粒度越细，AI 的遵从度越高。
4.3 问题三：多人协作时，md 文件改来改去，AI 的行为不稳定
团队协作中遇到的一个经典场景：周一你更新了规范文件的主色，周二同事用 AI 生成页面，发现颜色还是旧的。原因多半是 AI 工具的上下文缓存，它可能读取了旧的规范版本，或者同事的会话里已经沉淀过旧规范的上下文。
解决办法是规范文件更新后，在 AI 对话里明确重置上下文，可以新建会话，并在提示词里注明“忽略你之前对设计规范的所有了解，以下面的版本为准”。还可以在 md 文件头部加一个版本号，让不同版本的规范可以被显式引用：
> 当前版本：v2.3.0，最后更新日期：2025-06-15有了版本号，对话里一句话就能锁定规范版本：“按 设计规范.md v2.3.0 执行”。
4.4 问题四：规范文件本身写得很好，但 AI 生成的页面“太素了”
有的读者反馈，加了规范之后，AI 生成的页面稳是稳了，但整体感觉没有以前“灵性”了。这个问题我觉得需要分开看。
如果你的页面是后台系统、工具类产品，素和稳定恰恰是优点。后台界面要的是信息密度和操作效率，不是视觉表演。如果你的页面是营销落地页、品牌官网，那确实不能靠一份严格的 Markdown 把设计自由度完全锁死，太过约束等于抹杀了创意空间。
这类项目我给的建议是：把规范分成两层，一层是硬性规范，比如颜色、字体、间距，必须遵守；另一层是软性指引，比如“允许在 Hero 区域使用渐变背景装饰”“允许在卡片 hover 时增加轻微上浮动画”。硬性规范锁住底线，软性指引给 AI 留一点发挥空间，这样既不翻车，也不呆板。
5. 一个进阶思路：把 md 文件变成“多 AI 协作”的公用语言
最近很多人在研究多 AI 协作，就是让几个不同角色的 AI 一起完成复杂任务，比如一个写界面、一个写逻辑、一个做数据 mock。我试过之后发现，让多个 AI 协同不打架的最大难点，不是各自的模型能力，而是它们彼此之间没有统一的信息底座。而 Markdown 恰好是天然适合做这种“单一事实源”的格式。
我目前的组合方式是这样的：在一个会话里同时挂上三份文档——设计规范.md、业务说明.md、API 接口文档.md。然后明确分工：Agent A 负责根据规范生成前端页面结构，Agent B 负责根据接口文档生成数据交互逻辑，Agent C 负责对 A 和 B 的输出做整合校验。三个 Agent 都从同一套 Markdown 文档里取信息，产出的风格自然就统一了。
用这种方式做过一个比较复杂的项目，三个 Agent 各司其职，最终整合出来的页面，几乎不需要人工返工。而以前我人工把一个前端从设计到交互一点点敲出来，怎么也要一两天；现在用这套流程，半天就能拿出一个逻辑自洽、视觉统一的高保真原型。
这背后的逻辑不复杂：所谓协作，本质是信息对齐。信息对齐做得越好，协作效率就越高。而 Markdown 是目前信息对齐成本最低的载体。
6. 聊几句大实话：这套方案不是万能的，但一定好用
客观说一句，awesome-design-md 这套思路不是银弹，它有自己的适用边界。如果你的项目是一个强视觉驱动的品牌页面，指望靠一份 Markdown 让 AI 产出惊艳的创意视觉，那大概率会失望，因为创意这件事，无限自由的脑暴空间才有趣，而 Markdown 的核心价值恰恰是“约束”。反过来，如果你做的项目是后台系统、中台工具、内部系统、SaaS 产品这类“结构大于形式”的界面，那这套方案几乎是成本最低的提效手段。
我自己在实际项目里，最大的体感变化是：以前让 AI 生成界面，每一次都要把设计细节像教小孩一样反复叮嘱，它还是会在某个角落发挥一手；现在只要把 设计规范.md 挂上去，基本可以做到“一次生成，微调即用”。尤其是遇到那种临时要出个 demo、做个原型、验证交互方案的需求，这套流程节省的时间是肉眼可见的。
我建议所有频繁用 AI 写界面的朋友，都花个半天，认认真真为自己最常做的项目类型写一份专属的 Markdown 设计规范。不需要一次写全，可以从“颜色、字体、组件清单、负面清单”这四块起步，然后在日常使用中不停往里补内容。这份文件用得越久，AI 的产出就越稳定，你对“AI 瞎编界面”的烦恼也会降到最低。
最后再多说一句经验，规范文档不是用来“管住”AI 的，它是用来和 AI 对齐预期的。你把它当成沟通工具，AI 交付的质量自然就上来了。
