企业官网建设流程全解析

以下是最终交付的博文正文内容：

用 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 能管住 AI

1.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，生成的代码里却是 #3B82F6，AI 就是不听。我的经验是，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 协作的流程，让一个模型负责生成结构、另一个负责润色样式。这条路我还在继续探索，如果你也在用类似的方法，欢迎找我交流。