以下是最终交付的博文正文内容用 Markdown 写界面这是我跟 AI 协作大半年后觉得最值得分享的一件事。做前端的朋友应该都有过这种体验让 AI 生成一个页面prompt 写得再详细出来的东西总像“开盲盒”——颜色是它自己编的、布局是它随手排的、间距毫无章法明明说了要一个简洁后台它给你整出五彩斑斓的霓虹风。后来我换了个思路把“用自然语言描述界面”改成“用 Markdown 文件直接定义界面”AI 的生成质量直接上了一个台阶。这个项目叫 awesome-design-md核心就一句话用一个结构化的 Markdown 文件把界面的骨架、样式、交互意图全部写清楚AI 照着这份“图纸”去生成前端代码基本不会再瞎编。这篇文章就把我整理这份规范文件、跟 AI 协作落地页面的完整思路和踩坑记录写下来适合正在用 AI 写前端、或者对 AI 生成 UI 质量不满意的开发者参考。先说清楚这个东西能解决什么问题。我们现在日常用 AI 生成界面最常见的痛点是“描述偏差”——你脑子里的界面是一回事AI 理解的界面是另一回事。你写“加一个好看的侧边栏”AI 可能给你一个占了半个屏幕的色块你写“简洁一点”它直接给你整成毛坯房。问题不在于 AI 不够聪明而在于自然语言本身就是模糊的。而 Markdown 恰好是一种“半结构化”的文本格式它有明确的层级、列表、表格、引用块这些结构天然对应界面的区块、列表、卡片和提示条。把 UI 需求写成 Markdown本质上就是给 AI 画了一张带标注的户型图它照着施工自然不容易跑偏。1. 这个项目的核心思路为什么 Markdown 能管住 AI1.1 从“描述需求”到“定义结构”的转变先打个比方。你请一个装修师傅来家里如果你说“我想要一个温馨的客厅”师傅大概率会自由发挥出来的效果你可能并不满意。但如果你给师傅一张户型图上面标注好哪里放沙发、哪里放电视墙、用什么颜色的乳胶漆他就能基本按照你的想法落地。AI 生成界面也是一回事自然语言是“感受”Markdown 是“图纸”。awesome-design-md 的核心做法就是把 UI 设计需求转化成一个约定的 Markdown 文档结构。这个文件通常包含几个固定的区块项目概览、页面清单、组件定义、样式令牌、交互规则。我实测下来只要这个文件写得足够细AI 生成的页面在结构还原度上基本能到九成以上剩下的细节偏差靠微调 prompt 就能解决。这里有个很关键的认知转变以前我们是在“告诉 AI 我想要什么”现在是在“告诉 AI 这个界面是什么”。看似差别不大实际上是完全不同的协作方式。前者依赖 AI 的理解力和想象力后者依赖我们的表达力和结构化能力。作为人类我们最擅长的恰恰是后者——把模糊的想法变成清晰的规格说明这本来就是产品经理和设计师每天都在做的事情。1.2 为什么是 Markdown 而不是 JSON 或者别的格式有人可能会问既然要结构化为什么不用 JSON 或者 YAML 这种更严谨的格式我一开始也试过用 JSON 定义 UI 结构后来放弃了。原因有三个。第一JSON 的“噪音”太多。一个稍微复杂点的页面用 JSON 描述光括号和逗号就占了一半篇幅AI 读起来费劲人也写起来痛苦。Markdown 天生的可读性优势非常明显它本身就是给人看的文档格式AI 训练语料里 Markdown 的占比又极高模型对这种格式的理解天然更准确。第二Markdown 的容错性更好。JSON 只要少一个逗号或者多一个引号解析就挂了AI 输出的时候特别容易在这些细节上翻车。Markdown 不一样它容错性很强有些地方格式乱了一点也不影响理解AI 在处理这种格式的时候明显更稳定。第三Markdown 可以直接承载“设计说明”。JSON 只能装数据你想在 JSON 里写一段“这个页面尽量走简洁风参考 Notion 的质感”这种话非常别扭。Markdown 里可以随意穿插文字说明、列表、引用块这些自然语言描述和结构化定义混排在一起AI 反而更容易理解上下文。1.3 这份规范文件在协作流程中的位置我目前的 AI 前端工作流大概是这样的我先在 Markdown 里写界面的结构定义然后把这个文件直接丢给 AI通常是作为对话的上下文再加上一小段生成指令AI 直接吐出前端代码。整个过程不再需要反复调 prompt 描述 UI 细节因为细节都被 Markdown 文件锁死了。这个流程最大的好处是“需求即文档文档即上下文”。以前我们写 prompt 写几百字AI 生成完就丢了下次想改还得重新描述。现在有了这份 Markdown 文件它就是项目的活文档AI 每次生成都以它为基准。改界面就是改 Markdown然后重新生成整个过程非常可控。对于团队协作来说这个好处更明显。以前设计师和前端沟通需求靠口头加截图现在直接对齐 Markdown 文件。文件里写清楚了每个区块的定位和样式设计师看这个文件能明白布局意图前端看这个文件能知道要做什么AI 看这个文件能直接生成代码。一份文件三用协作链路短了很多。2. 手把手教你写一个“AI 能读懂”的 UI 定义文件2.1 项目头部让 AI 先建立全局认知一份合格的 awesome-design-md 文件开头必须是项目的整体说明。这部分内容看起来简单但非常影响 AI 输出的一致性。我一般会在文件头部写清楚三件事项目是什么类型的后台管理系统、营销落地页、移动端 H5、整体视觉风格倾向简洁、商务、活泼、科技感、目标用户是谁内部员工、C 端用户、开发者。举个例子如果我在文件头部写“这是一个面向企业客户的 SaaS 数据分析后台希望整体风格偏简洁商务参考 Linear 和 Notion 的质感”那么 AI 在生成后续所有组件的时候都会带着这个基调。如果我不写AI 就会随机发挥可能这次出来是暗黑风下次出来是糖果风毫无一致性。我还有一个习惯在项目头部写“一句话定位”。比如“这个页面要用 5 秒让用户看懂产品核心价值”这句话会强烈影响 AI 对页面布局的判断——它会把最重要的信息放到首屏而不是把一堆次要内容堆在最上面。这个技巧实测非常有效强烈推荐。2.2 页面区块定义用标题层级画出页面骨架Markdown 的标题层级天然适合描述页面的区块结构。我在规范文件里会用二级标题表示页面里的主要区块三级标题表示区块内部的子模块列表项表示具体的组件和元素。这样 AI 一眼就能看出页面的嵌套关系。比如我要写一个产品落地页文件里大概是这样的结构## 首屏 Hero 区 ### 主标题 - 一句话说明产品价值字体偏大加粗 ### 副标题 - 两到三句话解释产品解决什么问题 ### 行动按钮 - 主按钮文案免费试用 - 次按钮文案查看演示这段描述在 AI 看来非常清晰首屏有三个模块每个模块的层级和职责都一目了然。它知道主标题应该大、副标题应该小、按钮该放在哪里不会再把标题和按钮混为一谈。这里有个我踩过很多次的坑不要在一个列表里塞太多内容。比如“主标题一句话说明产品价值字体偏大加粗颜色深一些背景浅灰左侧留白”——这种写法 AI 虽然能看懂但它的注意力会被均分输出的结果往往哪个重点都没抓住。更好的做法是拆成多个列表项每个列表项只描述一个方面重点信息单独用引用或者加粗强调。2.3 样式令牌把“感觉”翻译成“参数”AI 生成 UI 最容易翻车的地方就是样式。你说“鲜艳一点”它给你饱和度拉满你说“素雅一点”它给你整成黑白报纸。解决这个问题我强烈建议在 Markdown 文件里加一节“样式令牌”Design Tokens把颜色、字体、圆角、间距这些基础样式先定义好。样式令牌其实就是一套变量AI 生成代码的时候直接引用这套变量而不是自己临场发挥选颜色。我的规范文件里样式令牌部分长这样## 样式令牌 - 主色#4F46E5 - 辅助色#10B981 - 背景色#F9FAFB - 文本主色#1F2937 - 文本辅助色#6B7280 - 字体Inter, system-ui, sans-serif - 圆角小 4px / 中 8px / 大 12px - 间距紧凑 4px / 常规 8px / 宽松 16px有了这组令牌AI 生成出来的页面至少在“色彩系统”和“空间系统”上是统一的。不会出现按钮是紫色的、标题是蓝色的、背景是米黄色这种灾难现场。我后来发现与其在 prompt 里反复说“颜色要协调”不如直接在文件里硬性规定色值AI 更愿意遵守明确的数值而不是抽象的描述。但要注意样式令牌不要列太多。我第一次写了二十多个颜色变量结果 AI 生成代码的时候经常张冠李戴把辅助色当主色用。现在我的经验是主色、辅助色、背景色、文本色各一两个就够了控制在五到八个变量内AI 的遵循度最高。2.4 交互意图说明补上 Markdown 表达不了的动态信息Markdown 毕竟是静态格式它不能很好地表达交互行为。比如“点击按钮弹出下拉菜单”“鼠标悬停显示 tooltip”“表单提交后跳转到成功页”——这些动态行为在 Markdown 里是写不出来的。我的做法是在文件底部单独加一节“交互规则”用自然语言描述关键交互。交互规则部分我会尽量避免描述“怎么做”那是代码层面的逻辑而是描述“发生什么”那是用户体验层面的结果。比如我不会写“用 JavaScript 监听 click 事件然后 toggle 一个 class”而是写“用户点击筛选按钮后筛选面板从右侧滑出同时遮罩层变暗”。AI 收到这种描述后会自己判断用什么技术实现而且输出效果往往更自然。这里要额外提醒一下交互规则不要写太多条我一般控制在五条以内只写最关键的用户路径。交互规则写多了AI 的注意力会被分散反而容易把主次搞混。如果页面确实很复杂建议按页面维度拆成多个 Markdown 文件而不是一个文件里塞满所有内容。3. 完整示例从 Markdown 文件到可直接运行的页面3.1 一个实际落地页的规范文件全貌为了让你直观感受这份规范文件长什么样我直接贴一个我之前做过的 AI 工具落地页的完整示例。这个页面最后生成出来的效果非常接近我的预期你可以照着这个结构去改自己的项目。# 项目智能写作助手落地页 一句话定位让用户在 10 秒内理解产品的核心价值并完成注册 ## 首屏 Hero 区 ### 主标题H1 - 文案用 AI 把写作效率提升 3 倍 - 字体大小最大层级加粗 ### 副标题H2 - 文案自动生成大纲、优化措辞、一键改写支持中英文 - 颜色辅助色不加粗 ### 行动按钮 - 主按钮免费开始写作主色背景白色文字 - 次按钮观看 2 分钟演示透明背景主色边框 ## 产品功能三卡片区 - 第一个卡片智能大纲生成解决用户“不知道写什么”的问题 - 第二个卡片实时语法纠错解决用户“写出来不够专业”的问题 - 第三个卡片一键风格改写解决用户“语气不合适”的问题 - 整体布局三列等宽卡片之间有 16px 间距 - 卡片样式白底、圆角 8px、浅灰色边框、阴影极浅 ## 用户评价区 - 用引用块展示三段用户评价每条评价包含评价内容和用户身份 - 背景色使用浅灰色背景与上方区块区分 ## 底部注册引导区 - 标题立即体验 AI 写作助手 - 表单字段邮箱地址、姓名 - 提交按钮主色背景文案“免费注册” - 注册成功后跳转到工作台首页 ## 样式令牌 - 主色#4F46E5 - 辅助色#10B981 - 背景色#F9FAFB - 文本主色#1F2937 - 文本辅助色#6B7280 - 字体Inter, system-ui, sans-serif - 圆角8px - 间距16px ## 交互规则 - 用户悬停在功能卡片上时卡片轻微上移并加深阴影 - 点击“观看 2 分钟演示”按钮页面滚动到产品功能卡片区 - 表单提交时按钮显示 loading 状态并禁用防止重复提交这个文件的巧妙之处在于它把“页面结构、样式参数、交互行为”三层信息全部用 Markdown 的天然语义表达出来了。一级标题告诉 AI 这是什么项目二级标题定义区块列表项定义细节最后集中给样式令牌和交互规则。AI 拿到这个文件几乎不需要再猜任何东西。3.2 给 AI 的生成指令如何把这个文件变成代码文件写好之后你还需要给 AI 一段简短的生成指令。我实测下来指令不需要太长关键是告诉 AI“严格按这个 Markdown 文件生成”。我的指令通常长这样请严格按照我提供的 Markdown 设计规范文件生成一个完整的落地页。 使用 HTML Tailwind CSS 实现输出单个 HTML 文件。 样式参数必须使用文件中的样式令牌不要自行修改颜色和字号。 交互规则中的行为需要使用 JavaScript 实现。这里有几个细节值得注意。第一我明确说“使用 HTML Tailwind CSS”这是因为 Tailwind CSS 的类名和 Markdown 的语义有一定的对应关系AI 生成的时候更顺手。第二我说“严格按文件生成”这句话对 AI 来说是一个强遵循指令比“帮我做一个类似的页面”有效得多。第三我不贪多一次只让 AI 生成一个页面而不是“顺便把响应式和暗黑模式都做了”那样反而容易出错。生成完之后我一般会让 AI 自测一遍“请检查这个页面是否符合 Markdown 文件中的所有要求特别是样式令牌和交互规则。”这一步很有用AI 会自己找出一些之前忽略的细节比如某个按钮颜色用错了、某个交互没实现。3.3 拿到代码后还需要做什么人工校正清单AI 生成的代码虽然还原度很高但直接上线还是不现实。我拿到生成结果之后会对照 Mind 里那份 Markdown 文件逐项做校正。这里分享一下我的检查清单。首先检查视觉还原度主色是否正确、背景色是否是 #F9FAFB、圆角是否是 8px、字体是否用了系统字体栈。这些硬性参数错误率比较低但万一 AI 自作主张改了一个整个页面的统一性就崩了。其次检查布局逻辑三个功能卡片是否等宽、间距是否都是 16px、区块之间的层级是否清晰。然后检查交互行为hover 效果有没有实现、点击按钮有没有执行对应的跳转或 loading 逻辑。最后一步是检查 AI“自由发挥”的部分。AI 生成的文案、图标选择、装饰元素有时候会跟你的意图有偏差这些不影响大局但值得看一眼。比如我上面那个示例里AI 给三个功能卡片配了三个图标其中一个选得不太合适我手动换掉了。这种微调在所难免但比从零开始调整个页面的布局容易太多了。4. 常见问题与避坑指南写给正在尝试的人4.1 AI 不遵守 Markdown 文件怎么办这是大家问得最多的一个问题。明明文件里写了主色是 #4F46E5生成的代码里却是 #3B82F6AI 就是不听。我的经验是AI 不遵守规范文件通常有三个原因。第一文件太长AI 的注意力窗口被稀释了。如果我的 Markdown 文件超过三百行AI 在生成代码的时候很可能漏掉中间部分的样式令牌。解决办法是把样式令牌挪到文件开头或者单独发一遍给 AI确保它被注意到。第二指令里没有强调“严格遵循”AI 默认你只是“参考”这个文件。解决办法是在生成指令开头就写明“严格按以下设计规范文件生成不允许修改任何样式参数”。第三上下文里混入了其他干扰信息。如果你在同一个对话里既给它看了别的项目页面又给它这个设计文件AI 很容易串味。我会把设计文件放最后一条单独发送让它成为距离生成指令最近的上下文。如果这三个原因都排除了 AI 还是不听话我还有一个笨办法把关键样式令牌直接写进生成指令里。比如“主色是 #4F46E5背景色是 #F9FAFB圆角是 8px间距是 16px”这样即使 AI 没认真读文件指令里的参数它也会遵守。4.2 Markdown 文件写得太细或太粗都不行这里有个度的把握问题。文件写得太粗比如只有区块标题没有具体内容AI 还是会自由发挥文件写得太细比如把每一段文字的字体大小都规定死了AI 反而容易在细节里迷路整体布局反而失控。我给的建议是关键结构必须细非关键细节保持粗。关键结构包括区块的层级关系、每个区块的核心内容、样式令牌、关键交互。这些必须写清楚。非关键细节包括装饰性文案、图标的精确大小、按钮的 hover 动画细节。这些让 AI 自由发挥反而更好过度定义反而扼杀了 AI 生成结果的“灵气”。我见过有人把规范文件写成了一本 UI 设计规范手册结果 AI 生成的页面四平八稳但毫无惊喜那就失去意义了。4.3 不同 AI 模型对这份文件的理解差异我实测过几个主流模型的反应发现不同模型对 Markdown 设计文件的理解能力有明显差异。能力强一些的模型比如 Claude 的较新版本基本一次就能还原出结构能力弱一些的模型可能需要你追加一轮修正 prompt 才能达到理想效果。这不是说规范文件没用恰恰相反规范文件能在最大程度上缩小模型之间的差距。如果用的模型理解能力一般我建议文件写得更“啰嗦”一点。比如在区块标题下面加一行注释“这是一个三列等宽的卡片布局每一列宽度相同”这种明确的补充说明对弱模型尤其有效。如果用的模型理解能力强反而可以精简文件给它留出更多发挥空间。我现在的做法是保留一版完整版和一版精简版根据模型的强弱选择合适的版本。注意不要指望一份 Markdown 文件彻底消灭 UI 生成的不确定性。它能做到的是把不确定性大幅缩小从“盲盒级别”降到“微调级别”这本身就是巨大的效率提升。如果 AI 偶尔还是给了你一个“惊喜”不用怀疑这个方案的可行性把它当成一次 prompt 调试就好。4.4 一些容易忽略但很影响结果的细节最后分享几个容易被忽略的细节。第一个是 Markdown 语法要规范列表的层级缩进一定要用 Tab 或者统一空格数量如果层级混乱AI 理解的区块嵌套关系也会乱。第二个是尽量使用常见的中英文对照描述不要用太晦涩的设计术语“留白”可以写成“区块之间要有足够间距”AI 更容易准确理解。第三个是文件命名和版本管理我会把不同版本的规范文件存在项目目录里用版本号区分这样每次 AI 生成乱了可以回到上一个稳定版本重新来。还有一个很多人会问的问题这份规范文件需不需要遵守某个公开的 awesome-design-md 标准格式我的答案是只要你能为自己定义出一套清晰、稳定的结构不需要拘泥于任何具体格式。这个项目叫 awesome-design-md但我更愿意把它理解成一种“用 Markdown 驯化 AI 生成 UI”的思路而不是一个死板的模板。每个人都有自己的表达习惯找到适合你自己的结构化描述方式比套用任何模板都重要。如果你刚开始尝试我的建议是从一个小页面开始写起比如一个简单的登录页。先感受一下“定义结构 → AI 生成 → 人工校正”这个循环的节奏再逐步扩展到大页面和复杂交互。我在实际使用中最大的体会是跟 AI 协作写前端最重要的能力不是写 prompt 的能力而是把你脑子的界面翻译成结构化文档的能力。一旦你掌握了这种翻译能力AI 就不再是那个“乱来的实习生”而是一个真正能按图施工的熟练工。这个项目后续还可以继续扩展比如把样式令牌定义成可切换的主题文件、把交互规则沉淀成可复用的行为组件库、或者结合多 AI 协作的流程让一个模型负责生成结构、另一个负责润色样式。这条路我还在继续探索如果你也在用类似的方法欢迎找我交流。 用 Markdown 定义界面规范，让 AI 生成前端代码不再开盲盒
以下是最终交付的博文正文内容用 Markdown 写界面这是我跟 AI 协作大半年后觉得最值得分享的一件事。做前端的朋友应该都有过这种体验让 AI 生成一个页面prompt 写得再详细出来的东西总像“开盲盒”——颜色是它自己编的、布局是它随手排的、间距毫无章法明明说了要一个简洁后台它给你整出五彩斑斓的霓虹风。后来我换了个思路把“用自然语言描述界面”改成“用 Markdown 文件直接定义界面”AI 的生成质量直接上了一个台阶。这个项目叫 awesome-design-md核心就一句话用一个结构化的 Markdown 文件把界面的骨架、样式、交互意图全部写清楚AI 照着这份“图纸”去生成前端代码基本不会再瞎编。这篇文章就把我整理这份规范文件、跟 AI 协作落地页面的完整思路和踩坑记录写下来适合正在用 AI 写前端、或者对 AI 生成 UI 质量不满意的开发者参考。先说清楚这个东西能解决什么问题。我们现在日常用 AI 生成界面最常见的痛点是“描述偏差”——你脑子里的界面是一回事AI 理解的界面是另一回事。你写“加一个好看的侧边栏”AI 可能给你一个占了半个屏幕的色块你写“简洁一点”它直接给你整成毛坯房。问题不在于 AI 不够聪明而在于自然语言本身就是模糊的。而 Markdown 恰好是一种“半结构化”的文本格式它有明确的层级、列表、表格、引用块这些结构天然对应界面的区块、列表、卡片和提示条。把 UI 需求写成 Markdown本质上就是给 AI 画了一张带标注的户型图它照着施工自然不容易跑偏。1. 这个项目的核心思路为什么 Markdown 能管住 AI1.1 从“描述需求”到“定义结构”的转变先打个比方。你请一个装修师傅来家里如果你说“我想要一个温馨的客厅”师傅大概率会自由发挥出来的效果你可能并不满意。但如果你给师傅一张户型图上面标注好哪里放沙发、哪里放电视墙、用什么颜色的乳胶漆他就能基本按照你的想法落地。AI 生成界面也是一回事自然语言是“感受”Markdown 是“图纸”。awesome-design-md 的核心做法就是把 UI 设计需求转化成一个约定的 Markdown 文档结构。这个文件通常包含几个固定的区块项目概览、页面清单、组件定义、样式令牌、交互规则。我实测下来只要这个文件写得足够细AI 生成的页面在结构还原度上基本能到九成以上剩下的细节偏差靠微调 prompt 就能解决。这里有个很关键的认知转变以前我们是在“告诉 AI 我想要什么”现在是在“告诉 AI 这个界面是什么”。看似差别不大实际上是完全不同的协作方式。前者依赖 AI 的理解力和想象力后者依赖我们的表达力和结构化能力。作为人类我们最擅长的恰恰是后者——把模糊的想法变成清晰的规格说明这本来就是产品经理和设计师每天都在做的事情。1.2 为什么是 Markdown 而不是 JSON 或者别的格式有人可能会问既然要结构化为什么不用 JSON 或者 YAML 这种更严谨的格式我一开始也试过用 JSON 定义 UI 结构后来放弃了。原因有三个。第一JSON 的“噪音”太多。一个稍微复杂点的页面用 JSON 描述光括号和逗号就占了一半篇幅AI 读起来费劲人也写起来痛苦。Markdown 天生的可读性优势非常明显它本身就是给人看的文档格式AI 训练语料里 Markdown 的占比又极高模型对这种格式的理解天然更准确。第二Markdown 的容错性更好。JSON 只要少一个逗号或者多一个引号解析就挂了AI 输出的时候特别容易在这些细节上翻车。Markdown 不一样它容错性很强有些地方格式乱了一点也不影响理解AI 在处理这种格式的时候明显更稳定。第三Markdown 可以直接承载“设计说明”。JSON 只能装数据你想在 JSON 里写一段“这个页面尽量走简洁风参考 Notion 的质感”这种话非常别扭。Markdown 里可以随意穿插文字说明、列表、引用块这些自然语言描述和结构化定义混排在一起AI 反而更容易理解上下文。1.3 这份规范文件在协作流程中的位置我目前的 AI 前端工作流大概是这样的我先在 Markdown 里写界面的结构定义然后把这个文件直接丢给 AI通常是作为对话的上下文再加上一小段生成指令AI 直接吐出前端代码。整个过程不再需要反复调 prompt 描述 UI 细节因为细节都被 Markdown 文件锁死了。这个流程最大的好处是“需求即文档文档即上下文”。以前我们写 prompt 写几百字AI 生成完就丢了下次想改还得重新描述。现在有了这份 Markdown 文件它就是项目的活文档AI 每次生成都以它为基准。改界面就是改 Markdown然后重新生成整个过程非常可控。对于团队协作来说这个好处更明显。以前设计师和前端沟通需求靠口头加截图现在直接对齐 Markdown 文件。文件里写清楚了每个区块的定位和样式设计师看这个文件能明白布局意图前端看这个文件能知道要做什么AI 看这个文件能直接生成代码。一份文件三用协作链路短了很多。2. 手把手教你写一个“AI 能读懂”的 UI 定义文件2.1 项目头部让 AI 先建立全局认知一份合格的 awesome-design-md 文件开头必须是项目的整体说明。这部分内容看起来简单但非常影响 AI 输出的一致性。我一般会在文件头部写清楚三件事项目是什么类型的后台管理系统、营销落地页、移动端 H5、整体视觉风格倾向简洁、商务、活泼、科技感、目标用户是谁内部员工、C 端用户、开发者。举个例子如果我在文件头部写“这是一个面向企业客户的 SaaS 数据分析后台希望整体风格偏简洁商务参考 Linear 和 Notion 的质感”那么 AI 在生成后续所有组件的时候都会带着这个基调。如果我不写AI 就会随机发挥可能这次出来是暗黑风下次出来是糖果风毫无一致性。我还有一个习惯在项目头部写“一句话定位”。比如“这个页面要用 5 秒让用户看懂产品核心价值”这句话会强烈影响 AI 对页面布局的判断——它会把最重要的信息放到首屏而不是把一堆次要内容堆在最上面。这个技巧实测非常有效强烈推荐。2.2 页面区块定义用标题层级画出页面骨架Markdown 的标题层级天然适合描述页面的区块结构。我在规范文件里会用二级标题表示页面里的主要区块三级标题表示区块内部的子模块列表项表示具体的组件和元素。这样 AI 一眼就能看出页面的嵌套关系。比如我要写一个产品落地页文件里大概是这样的结构## 首屏 Hero 区 ### 主标题 - 一句话说明产品价值字体偏大加粗 ### 副标题 - 两到三句话解释产品解决什么问题 ### 行动按钮 - 主按钮文案免费试用 - 次按钮文案查看演示这段描述在 AI 看来非常清晰首屏有三个模块每个模块的层级和职责都一目了然。它知道主标题应该大、副标题应该小、按钮该放在哪里不会再把标题和按钮混为一谈。这里有个我踩过很多次的坑不要在一个列表里塞太多内容。比如“主标题一句话说明产品价值字体偏大加粗颜色深一些背景浅灰左侧留白”——这种写法 AI 虽然能看懂但它的注意力会被均分输出的结果往往哪个重点都没抓住。更好的做法是拆成多个列表项每个列表项只描述一个方面重点信息单独用引用或者加粗强调。2.3 样式令牌把“感觉”翻译成“参数”AI 生成 UI 最容易翻车的地方就是样式。你说“鲜艳一点”它给你饱和度拉满你说“素雅一点”它给你整成黑白报纸。解决这个问题我强烈建议在 Markdown 文件里加一节“样式令牌”Design Tokens把颜色、字体、圆角、间距这些基础样式先定义好。样式令牌其实就是一套变量AI 生成代码的时候直接引用这套变量而不是自己临场发挥选颜色。我的规范文件里样式令牌部分长这样## 样式令牌 - 主色#4F46E5 - 辅助色#10B981 - 背景色#F9FAFB - 文本主色#1F2937 - 文本辅助色#6B7280 - 字体Inter, system-ui, sans-serif - 圆角小 4px / 中 8px / 大 12px - 间距紧凑 4px / 常规 8px / 宽松 16px有了这组令牌AI 生成出来的页面至少在“色彩系统”和“空间系统”上是统一的。不会出现按钮是紫色的、标题是蓝色的、背景是米黄色这种灾难现场。我后来发现与其在 prompt 里反复说“颜色要协调”不如直接在文件里硬性规定色值AI 更愿意遵守明确的数值而不是抽象的描述。但要注意样式令牌不要列太多。我第一次写了二十多个颜色变量结果 AI 生成代码的时候经常张冠李戴把辅助色当主色用。现在我的经验是主色、辅助色、背景色、文本色各一两个就够了控制在五到八个变量内AI 的遵循度最高。2.4 交互意图说明补上 Markdown 表达不了的动态信息Markdown 毕竟是静态格式它不能很好地表达交互行为。比如“点击按钮弹出下拉菜单”“鼠标悬停显示 tooltip”“表单提交后跳转到成功页”——这些动态行为在 Markdown 里是写不出来的。我的做法是在文件底部单独加一节“交互规则”用自然语言描述关键交互。交互规则部分我会尽量避免描述“怎么做”那是代码层面的逻辑而是描述“发生什么”那是用户体验层面的结果。比如我不会写“用 JavaScript 监听 click 事件然后 toggle 一个 class”而是写“用户点击筛选按钮后筛选面板从右侧滑出同时遮罩层变暗”。AI 收到这种描述后会自己判断用什么技术实现而且输出效果往往更自然。这里要额外提醒一下交互规则不要写太多条我一般控制在五条以内只写最关键的用户路径。交互规则写多了AI 的注意力会被分散反而容易把主次搞混。如果页面确实很复杂建议按页面维度拆成多个 Markdown 文件而不是一个文件里塞满所有内容。3. 完整示例从 Markdown 文件到可直接运行的页面3.1 一个实际落地页的规范文件全貌为了让你直观感受这份规范文件长什么样我直接贴一个我之前做过的 AI 工具落地页的完整示例。这个页面最后生成出来的效果非常接近我的预期你可以照着这个结构去改自己的项目。# 项目智能写作助手落地页 一句话定位让用户在 10 秒内理解产品的核心价值并完成注册 ## 首屏 Hero 区 ### 主标题H1 - 文案用 AI 把写作效率提升 3 倍 - 字体大小最大层级加粗 ### 副标题H2 - 文案自动生成大纲、优化措辞、一键改写支持中英文 - 颜色辅助色不加粗 ### 行动按钮 - 主按钮免费开始写作主色背景白色文字 - 次按钮观看 2 分钟演示透明背景主色边框 ## 产品功能三卡片区 - 第一个卡片智能大纲生成解决用户“不知道写什么”的问题 - 第二个卡片实时语法纠错解决用户“写出来不够专业”的问题 - 第三个卡片一键风格改写解决用户“语气不合适”的问题 - 整体布局三列等宽卡片之间有 16px 间距 - 卡片样式白底、圆角 8px、浅灰色边框、阴影极浅 ## 用户评价区 - 用引用块展示三段用户评价每条评价包含评价内容和用户身份 - 背景色使用浅灰色背景与上方区块区分 ## 底部注册引导区 - 标题立即体验 AI 写作助手 - 表单字段邮箱地址、姓名 - 提交按钮主色背景文案“免费注册” - 注册成功后跳转到工作台首页 ## 样式令牌 - 主色#4F46E5 - 辅助色#10B981 - 背景色#F9FAFB - 文本主色#1F2937 - 文本辅助色#6B7280 - 字体Inter, system-ui, sans-serif - 圆角8px - 间距16px ## 交互规则 - 用户悬停在功能卡片上时卡片轻微上移并加深阴影 - 点击“观看 2 分钟演示”按钮页面滚动到产品功能卡片区 - 表单提交时按钮显示 loading 状态并禁用防止重复提交这个文件的巧妙之处在于它把“页面结构、样式参数、交互行为”三层信息全部用 Markdown 的天然语义表达出来了。一级标题告诉 AI 这是什么项目二级标题定义区块列表项定义细节最后集中给样式令牌和交互规则。AI 拿到这个文件几乎不需要再猜任何东西。3.2 给 AI 的生成指令如何把这个文件变成代码文件写好之后你还需要给 AI 一段简短的生成指令。我实测下来指令不需要太长关键是告诉 AI“严格按这个 Markdown 文件生成”。我的指令通常长这样请严格按照我提供的 Markdown 设计规范文件生成一个完整的落地页。 使用 HTML Tailwind CSS 实现输出单个 HTML 文件。 样式参数必须使用文件中的样式令牌不要自行修改颜色和字号。 交互规则中的行为需要使用 JavaScript 实现。这里有几个细节值得注意。第一我明确说“使用 HTML Tailwind CSS”这是因为 Tailwind CSS 的类名和 Markdown 的语义有一定的对应关系AI 生成的时候更顺手。第二我说“严格按文件生成”这句话对 AI 来说是一个强遵循指令比“帮我做一个类似的页面”有效得多。第三我不贪多一次只让 AI 生成一个页面而不是“顺便把响应式和暗黑模式都做了”那样反而容易出错。生成完之后我一般会让 AI 自测一遍“请检查这个页面是否符合 Markdown 文件中的所有要求特别是样式令牌和交互规则。”这一步很有用AI 会自己找出一些之前忽略的细节比如某个按钮颜色用错了、某个交互没实现。3.3 拿到代码后还需要做什么人工校正清单AI 生成的代码虽然还原度很高但直接上线还是不现实。我拿到生成结果之后会对照 Mind 里那份 Markdown 文件逐项做校正。这里分享一下我的检查清单。首先检查视觉还原度主色是否正确、背景色是否是 #F9FAFB、圆角是否是 8px、字体是否用了系统字体栈。这些硬性参数错误率比较低但万一 AI 自作主张改了一个整个页面的统一性就崩了。其次检查布局逻辑三个功能卡片是否等宽、间距是否都是 16px、区块之间的层级是否清晰。然后检查交互行为hover 效果有没有实现、点击按钮有没有执行对应的跳转或 loading 逻辑。最后一步是检查 AI“自由发挥”的部分。AI 生成的文案、图标选择、装饰元素有时候会跟你的意图有偏差这些不影响大局但值得看一眼。比如我上面那个示例里AI 给三个功能卡片配了三个图标其中一个选得不太合适我手动换掉了。这种微调在所难免但比从零开始调整个页面的布局容易太多了。4. 常见问题与避坑指南写给正在尝试的人4.1 AI 不遵守 Markdown 文件怎么办这是大家问得最多的一个问题。明明文件里写了主色是 #4F46E5生成的代码里却是 #3B82F6AI 就是不听。我的经验是AI 不遵守规范文件通常有三个原因。第一文件太长AI 的注意力窗口被稀释了。如果我的 Markdown 文件超过三百行AI 在生成代码的时候很可能漏掉中间部分的样式令牌。解决办法是把样式令牌挪到文件开头或者单独发一遍给 AI确保它被注意到。第二指令里没有强调“严格遵循”AI 默认你只是“参考”这个文件。解决办法是在生成指令开头就写明“严格按以下设计规范文件生成不允许修改任何样式参数”。第三上下文里混入了其他干扰信息。如果你在同一个对话里既给它看了别的项目页面又给它这个设计文件AI 很容易串味。我会把设计文件放最后一条单独发送让它成为距离生成指令最近的上下文。如果这三个原因都排除了 AI 还是不听话我还有一个笨办法把关键样式令牌直接写进生成指令里。比如“主色是 #4F46E5背景色是 #F9FAFB圆角是 8px间距是 16px”这样即使 AI 没认真读文件指令里的参数它也会遵守。4.2 Markdown 文件写得太细或太粗都不行这里有个度的把握问题。文件写得太粗比如只有区块标题没有具体内容AI 还是会自由发挥文件写得太细比如把每一段文字的字体大小都规定死了AI 反而容易在细节里迷路整体布局反而失控。我给的建议是关键结构必须细非关键细节保持粗。关键结构包括区块的层级关系、每个区块的核心内容、样式令牌、关键交互。这些必须写清楚。非关键细节包括装饰性文案、图标的精确大小、按钮的 hover 动画细节。这些让 AI 自由发挥反而更好过度定义反而扼杀了 AI 生成结果的“灵气”。我见过有人把规范文件写成了一本 UI 设计规范手册结果 AI 生成的页面四平八稳但毫无惊喜那就失去意义了。4.3 不同 AI 模型对这份文件的理解差异我实测过几个主流模型的反应发现不同模型对 Markdown 设计文件的理解能力有明显差异。能力强一些的模型比如 Claude 的较新版本基本一次就能还原出结构能力弱一些的模型可能需要你追加一轮修正 prompt 才能达到理想效果。这不是说规范文件没用恰恰相反规范文件能在最大程度上缩小模型之间的差距。如果用的模型理解能力一般我建议文件写得更“啰嗦”一点。比如在区块标题下面加一行注释“这是一个三列等宽的卡片布局每一列宽度相同”这种明确的补充说明对弱模型尤其有效。如果用的模型理解能力强反而可以精简文件给它留出更多发挥空间。我现在的做法是保留一版完整版和一版精简版根据模型的强弱选择合适的版本。注意不要指望一份 Markdown 文件彻底消灭 UI 生成的不确定性。它能做到的是把不确定性大幅缩小从“盲盒级别”降到“微调级别”这本身就是巨大的效率提升。如果 AI 偶尔还是给了你一个“惊喜”不用怀疑这个方案的可行性把它当成一次 prompt 调试就好。4.4 一些容易忽略但很影响结果的细节最后分享几个容易被忽略的细节。第一个是 Markdown 语法要规范列表的层级缩进一定要用 Tab 或者统一空格数量如果层级混乱AI 理解的区块嵌套关系也会乱。第二个是尽量使用常见的中英文对照描述不要用太晦涩的设计术语“留白”可以写成“区块之间要有足够间距”AI 更容易准确理解。第三个是文件命名和版本管理我会把不同版本的规范文件存在项目目录里用版本号区分这样每次 AI 生成乱了可以回到上一个稳定版本重新来。还有一个很多人会问的问题这份规范文件需不需要遵守某个公开的 awesome-design-md 标准格式我的答案是只要你能为自己定义出一套清晰、稳定的结构不需要拘泥于任何具体格式。这个项目叫 awesome-design-md但我更愿意把它理解成一种“用 Markdown 驯化 AI 生成 UI”的思路而不是一个死板的模板。每个人都有自己的表达习惯找到适合你自己的结构化描述方式比套用任何模板都重要。如果你刚开始尝试我的建议是从一个小页面开始写起比如一个简单的登录页。先感受一下“定义结构 → AI 生成 → 人工校正”这个循环的节奏再逐步扩展到大页面和复杂交互。我在实际使用中最大的体会是跟 AI 协作写前端最重要的能力不是写 prompt 的能力而是把你脑子的界面翻译成结构化文档的能力。一旦你掌握了这种翻译能力AI 就不再是那个“乱来的实习生”而是一个真正能按图施工的熟练工。这个项目后续还可以继续扩展比如把样式令牌定义成可切换的主题文件、把交互规则沉淀成可复用的行为组件库、或者结合多 AI 协作的流程让一个模型负责生成结构、另一个负责润色样式。这条路我还在继续探索如果你也在用类似的方法欢迎找我交流。