DESIGN.md：AI 生成 UI 时最需要一个文件

一年前，PM 还在担心怎么把想法变成界面。现在他们可以在十分钟内得到十个界面，问题变成了这些界面看起来是不是同一个产品。

让 Agent 做一个设置页面、一个新手引导弹窗、一个仪表盘和一个定价页。每个页面单独看可能都不错，但把它们放在一起，你会得到四个顶着同一个 Logo 的不同产品。

设计师多年前就用设计系统解决了这个问题。

Agent 也需要类似的东西，但 Figma 对它们来说几乎不可见，品牌 PDF 更是毫无用处。DESIGN.md 把规则放在 Agent 真正会看的地方：纯文本，放在 repo 里。

Google 的 Stitch 团队将其描述为"面向 AI Agent 的纯文本设计系统文档"。它位于你的项目中，告诉 Agent 产品应该长什么样、给人什么感觉：颜色、字体、间距、组件规则、布局原则，以及那些防止界面跑偏的做与不做。

最接近的类比是 AGENTS.md。

README.md 告诉人类这个项目是什么。AGENTS.md 告诉编码 Agent 如何在 repo 中工作。DESIGN.md 告诉设计和编码 Agent 产品应该长什么样。

DESIGN.md 文件有两个层次。

第一层是机器可读的 YAML：颜色、字体、圆角、间距、组件引用，以及精确的组件属性。

第二层是人类可读的 Markdown：界面应该给人什么感觉、每种颜色扮演什么角色、布局如何运作、允许哪些组件模式，以及哪些模式绝不应该出现。

Agent 需要的是具体的值，以及背后的理由。

纯散文给 Agent 的只是一些情绪词："干净"、"高级"、"友好"、"现代"。这些词大多没有用处，除非你把它们和具体决策绑定在一起。

纯 token 给 Agent 的只是没有判断的值。一个十六进制颜色代码并不能告诉 Agent 这个颜色应该出现在每个按钮上、只出现在主操作上、还是永远不应该作为背景色。

两者结合，Agent 得到精确的值，人类得到背后的理由，PM、设计师、工程师和 Agent 有了一个可以争论的对象。

你不需要假装自己是设计师。你只需要写下来足够的产品判断，让 Agent 停止自作主张。

大多数 PM 已经深知这种痛。

你要一个原型，输出看起来"还不错"。然后设计师一看，问题全出来了：圆角不对、字重不对、CTA 层级不对、强调色太多、凭空发明了一个新的卡片样式、表单字段和产品不匹配、移动端布局崩得像电子表格、空状态的文案像 SaaS 宣传页。

单独看都不是灾难。但合在一起，产品就觉得是假的。

Agent 完成了你要求的事情，但它拿到的上下文是不完整的。

我认为这是 PM 需要适应的部分。当 AI 把做 UI 变得廉价之后，难点从生成界面转移到了判断这个界面是否属于这个产品。

一旦 AI 承担了更多制作工作，PM 的判断力就变得更加重要。

此外，很多 UI 的末端工作——如果每个人都知道"好的"应该是什么样子——恰恰是 Agent 可以草拟的那类工作。

在让 Agent 构建 UI 之前，先创建一个 DESIGN.md。

实际操作中，我会这样做。

1. 从真实来源开始

从比"做得好看"更具体的地方入手。使用一个具体的来源：你现有的 App、一个公开的营销网站、一个 Figma 文件、一张你喜欢的界面截图，或者一个来自 awesome-design-md 或 getdesign.md 等合集的参考 DESIGN.md。如果产品已经存在，让 Agent 从当前 UI 推断初稿。如果产品是新的，先选一个参考方向。

2. 记录决策，而不是感觉

一份弱的 DESIGN.md 写的是：极简、高级、干净、友好。

一份更强的 DESIGN.md 写的是：每个界面只用一种强调色，保留给主操作。正文保持在 15-16px，行高在 1.4 以上。卡片使用边框和表面颜色对比，而不是厚重阴影。主按钮填充，次要操作用文字或描边。空状态应该直接、实用，克制俏皮元素。表格优先考虑扫描速度，而不是装饰性间距。移动端优先折叠次要元数据，而不是主要操作。

PM 在这里能帮上忙，因为即使没有最终的阴影 token，他们也能说出产品的判断：密集还是宽松、活泼还是严肃、操作偏重还是审核偏重、消费级感觉还是企业级感觉、张扬还是克制。

3. 填充 Agent 会用到的章节

Google 的基本框架：概览、颜色、字体、布局。层级、形状、组件。做与不做。这个规范允许自定义章节，这很有用，因为产品总有一些奇怪的约束。比如一个 B2B 工作流产品可能需要：数据密度规则、表格行为规范、错误状态语气、AI 置信度显示规则。一个消费级 App 可能需要：图片处理方式、动效规则、空状态个性。当规则写下来之后，糟糕的输出更容易被发现。

4. 让 Agent 把文件引用回给你

被低估的做法是让 Agent 把文件引用回给你。附上 DESIGN.md 然后祈祷，这太被动了。在 Agent 生成界面之后，让它对照文件审查自己的输出。

使用这样的 prompt：列出这个界面遵循了 DESIGN.md 的哪些规则。列出这个界面在哪些地方发明了新模式。对比按钮、卡片、输入框、字体、间距和移动端行为是否与 DESIGN.md 一致。在修改 UI 之前，说明 DESIGN.md 的哪个章节支持这个修改。如果 DESIGN.md 没有覆盖这个情况，说出来并询问是否扩展文件。

最后一个 prompt 是文件活起来的地方。当一个新的产品决策出现时，你可以把它当作一次性处理，也可以把它加回系统中。

5. 配合人工审查

把 DESIGN.md 看作写下你不想让 Agent 反复重做的那些决策。

当以下情况出现时更新它：一个新的组件模式出现了两次、设计师改变了视觉方向、PM 注意到 Agent 反复犯同样的错误、一个审查意见反复出现、某个功能区域需要不同的密度规则、移动端的模式和桌面端产生了分歧、团队决定一个一次性模式应该成为标准。

不要因为每一次审美分歧就更新它。一个人不喜欢某个卡片圆角，那是反馈。三个界面发明了三种不同的卡片圆角，那就是系统问题了。

失败模式

大多数糟糕的 DESIGN.md 以可预测的方式失败：太模糊——"现代且干净"、"好看的企业 UI"、"简单直观"；太视觉化但缺乏可操作性——颜色没有角色、字体没有使用规则、组件没有状态描述；太僵化——每个部分都过度规定，没有为产品特定例外留空间，没有规定文件未覆盖时该怎么办；与真实界面脱节——从品牌理论出发写，从未对照 Agent 输出测试过，没有记录坏案例。

无聊在这里是一种优点。常见的设计决策应该重复出现，而真正困难的产品决策仍然属于人类。

我认为核心观点很简单：PM 会给 Agent 更多 UI 工作，而优秀的团队会停止把品味当作每个人都能记住的东西。

DESIGN.md 是一种把它写下来的方式，而不需要把每个 prompt 变成一段 900 字的提醒。

Repo 里的一个文件意味着人类可以读它，Agent 可以用它，产品可以变化而不用每个人依赖记忆。

选一个你负责的产品界面，让 Agent 从现有 UI 草拟一份 DESIGN.md。然后和你的设计师或工程伙伴一起审阅，修正太模糊的部分。之后，用它在一个小的 UI 任务上试一试。如果输出改善了，继续推进。如果没有改善，也好，现在你能清楚地看到你的设计系统从未明确定义过的那些东西。