DESIGN.md：别再让AI猜你的UI该长什么样子

Dev.to AI 2026-07-16T09:16:42.854171

一套把视觉意图变成可版本管理、可 lint 检查的编码代理契约的实际工作流。我一开始只写了一个断掉的 token 引用：components : button-primary : backgroundColor : " {colors.action}" 这个 colors.action token 根本不存在。Google 官方的 DESIGN.md linter 立刻抓到了它：Reference {colors.action} does not resolve to any defined token.

errors: 1, warnings: 1, infos: 2
exit code: 1

这个小失败比任何精美的演示更能点明 DESIGN.md 的价值。AI 编码工具已经能生成一个能跑的页面了，但真正难的是让五个页面看起来像同一个产品——然后在新的会话、新的代理和后续修订中一直保持这种一致性。

大多数团队的解法是往提示词里堆更多形容词：“做成现代化、干净、高端、像顶级 SaaS 产品那样。” 问题不是提示词太短，而是它太模糊了。

DESIGN.md 用一份文件来取代这种模糊性：人可审阅、代理可读取、Git 可版本管理、工具可验证。

DESIGN.md 到底是什么

Google Labs 把 DESIGN.md 描述为一种把视觉身份传递给编码代理的格式。一个符合规范的文件包含两层：

YAML 头部：包含机器可读的颜色、排版、间距、圆角、组件 token。
Markdown 正文：描述设计意图、组件语义、响应式行为，以及明确的“做”与“不做”。

一份小文件大概长这样：

---
version : alpha
name : Signal Desk
colors :
  primary : " #182230"
  tertiary : " #5B5BD6"
  surface : " #FFFFFF"
rounded :
  sm : 6px
components :
  button-primary :
    backgroundColor : " {colors.tertiary}"
    textColor : " {colors.surface}"
    rounded : " {rounded.sm}"
---

概述

Signal Desk 应该像一本运行日志本加上一个安静的航空仪表盘：紧凑、实在、在压力下保持冷静。

它不是那种花哨的营销仪表盘。

做与不做

做：让发布状态在主指标之前就一目了然。
不做：不要加渐变、玻璃模糊、发光边框或装饰性图表。

标签和文字各司其职。标签定义用什么，说明解释为什么要这么用，负面约束则明确结果不能变成什么样。光有标签，设计系统就只是一套色卡；光有说明，具体的数值又留给了主观解读。二者结合，才构成一份视觉契约。

为什么这能改善 AI 生成的界面

以下解释基于公开的技术规范和后面描述的项目，不是模型厂商的评测基准，DESIGN.md 也不能保证审美不出错。它能做到的是减少四类猜测。

1. 减少隐藏的自由度

你让 AI 做一个“现代仪表盘”，模型还得自己选字体、字号、色板、间距、圆角、阴影、动效和响应式行为。每一个未指定的决策都是一次跑偏的机会。

DESIGN.md 在实现开始之前就收窄了设计空间。模型不再从整个互联网的平均视觉语言里采样，而是在一个更小、更明确的规定体系内工作。

2. 把审美转化成语义规则

#5B5BD6 只是一个颜色值。当文件里写明靛蓝色只用于唯一的主要操作和当前选中项时，它就成了规则。同理：

“不要把所有指标都做成浮动卡片”比“少用卡片”更可执行。
“状态必须包含文字，不能只依赖颜色”比“记住无障碍”更可验证。

价值不在于描述更多，而在于描述得更可操作。

3. 跨会话持久化

聊天提示词是临时的，仓库文件是持久的。一旦设计决策落入项目，下一次会话、另一个智能体、甚至代码审查者都能从同一个可信来源出发工作。Git 也让这些决策可对比、可回退。

Google 的 CLI 目前支持 lint、diff 和 token export。这相当于把设计系统维护的一部分工作从人脑中移到了常规工程流程中。

4. 创建验证循环

“颜色感觉不统一”这种问题很难写进 CI（持续集成）配置里。但一个未解析的 {colors.action} 引用就不一样了。一旦视觉规则变成结构化数据，工具就能在智能体拿着有问题的契约生成更多代码之前，自动抓出引用断裂、排版缺失、对比度问题以及结构错误。

四文件结构

有用的设置不是四份互相重叠的操作手册。每个文件应该回答一个不同的问题。

project/
├── README.md
├── AGENTS.md
├── DESIGN.md
├── CLAUDE.md
└── src/

文件	它回答的问题	应该放什么内容
README.md	我们在构建什么？	用户、产品目标、范围、环境搭建、验收标准
AGENTS.md	代码应该怎么改？	架构、命令、测试、边界、安全规则
DESIGN.md	产品应该是什么样子、什么感觉？	设计令牌、设计理由、组件语义、响应式规则、反模式
CLAUDE.md	消费项目上下文时，Claude Code 应该怎么做？	共享规则导入、Claude 特定的工作流笔记

这里有个细节需要注意：Claude Code 的官方文档说它读取的是 CLAUDE.md，而不是 AGENTS.md。如果仓库已经用了 AGENTS.md，Anthropic 建议直接导入它，而不是再维护一份重复的：

@AGENTS.md

## Claude Code

- 在修改 UI 代码前，先总结 README.md 和 DESIGN.md 中的约束条件。
- 不要用通用的“现代 SaaS”样式替换具体的设计规则。

Codex 会自动发现 AGENTS.md 文件，并按目录层级合并指令。这样 CLAUDE.md 就成了一个合适的适配层。如果把 AGENTS.md 全部复制到 CLAUDE.md，就会产生两个真相源。当只更新其中一份时，模型接收到的上下文就会互相矛盾。

一个实际例子：Signal Desk

我用一个名叫 Signal Desk 的小型发布状态网站测试了这个方法。实现只用了 HTML 和 CSS，没有 React、Tailwind、组件库、外部字体或生成的产品截图。把技术栈缩到最小，更容易区分项目上下文带来的效果和框架自身的能力。

第1步：定义产品边界

README.md 描述了目标和验收标准：

# Signal Desk

面向独立开发者的一页式发布状态仪表盘。

用户应在十秒内理解当前版本、未解决的风险、
近期发布和下一步行动。

## 验收标准

- 使用原生 HTML 和 CSS，不依赖第三方资源。
- 支持 375px 移动端和 1440px 桌面端宽度。
- 保持页面键盘可访问，焦点状态可见。
- 遵循 DESIGN.md 中的信息层级。

这样安排是有原因的。一套详细的设计系统无法拯救一个未定义的产品——它只能让智能体更一致地构建出错误的产品。

第2步：定义工程契约

AGENTS.md 负责实现和验证规则：

## 实现

- 使用语义化 HTML

## 验证

- 每次编辑设计契约后，运行 `npx @google/design.md lint DESIGN.md` 进行检查。
- 验证操作、警告和状态标签是否不仅依赖颜色区分。

注意这里没有写什么：背景颜色、圆角、卡片样式。这些属于 DESIGN.md，不应放在工程指令里。

第3步：给设计一个具体的参照

Overview 里没有写“现代、专业、高端”。它写的是：Signal Desk 应该像一本运维笔记本与一块安静的航空电子面板的结合体——紧凑、务实、压力下保持冷静。

它不是光鲜的营销仪表盘。这个参照自然带来了温暖的纸质感画布、深色墨水、稀疏的状态颜色、紧凑的信息密度、克制的圆角，没有玻璃拟态或装饰性图表。Google 的 DESIGN.md 哲学也表达了同样的观点：一个具体的参照能比一堆宽泛的形容词传递更多有用信息。

第4步：实现并检查结果

最终页面的发布状态位于层级顶部，首屏内保留一个主要操作。版本号和时间戳使用等宽字体。成功和回滚状态结合了颜色与标签。边框和色调变化创造了结构感，而没有浮动卡片效果。

这是项目在本地浏览器中的真实截图。界面文字是中文，但设计契约的行为与语言无关。这个截图并不能证明 DESIGN.md 能击败所有可能的提示。它证明了一个更窄的论断：四文件契约可以产出一个可运行的产物，且其设计决策可以追溯到版本化的项目文件。

失败比首次渲染更有用

故意写错的 {colors.action} 引用如期触发了 lint 失败。修复后，linter 仍然报了四个警告。neutral、line、success、warning 这些 token 存在，但没有任何组件引用它们。这暴露了设计系统中一个常见错误：更多 token 并不自动意味着更多控制。未被使用的 token 只是库存，不是工作规则。我添加了针对 page、divider、status-success 和 status-warning 的语义组件映射。最终结果是：

errors: 0, warnings: 0, infos: 1
exit code: 0

从这个循环中得到了三个实用教训：

DESIGN.md 必须随真实组件一起演化。它不应脱离产品独立膨胀。
少量高价值的 token 加上语义组件映射，比几百个复制的变量要好。
通过 lint 只证明结构有效性，不证明视觉质量。响应式检查、无障碍测试和人工审查仍然重要。

不要复制其他公司的视觉标识

awesome-design-md 仓库有助于研究详细设计文档的结构。其文件从公开可见的网站中提取并按原样提供。仓库明确声明不拥有这些视觉标识的所有权。安全的使用方式是学习设计决策，而非克隆品牌：

如何用少量颜色区分主次操作？
字号和间距如何建立层级？
如何描述交互状态、响应行为和可访问性？
哪些规则是通用原则，哪些属于特定公司？

Vercel 公开的 /design.md 是一个有用的大例子。它通过色阶、排版、圆角、间距和组件 token 记录了浅色版 Geist 系统。它还指向了一个独立的暗色主题文档。它不是一个通用的入门模板。Vercel 自己的 Web 界面指南明确区分了通用界面指导和 Vercel 特有的偏好。学习约束如何表达，但不要复制他们保护的视觉身份。

实际采用步骤

如果你想在现有应用或网站中引入 DESIGN.md，请按此顺序：

选择一个有边界的界面。从登录页、设置页、仪表盘或详情页开始。
从当前产品中提取事实。记录实际存在的颜色、字体、间距、圆角和状态。
先写 Overview 和 Don'ts 部分。定义一个具体的参照，以及智能体最常重复的五到十种失败模式。
添加最小有用的 token。只添加第一个界面会用到的值，然后将它们映射到语义组件。
将验证步骤放入 AGENTS.md。说明何时运行 lint，以及需要检查哪些视口、状态和可访问性规则。
保持 CLAUDE.md 精简。导入共享规则，只添加工具特有的指令。
通过 diff 审查设计变更。在接受 token 或语义变更之前，先运行官方命令：

npx @google/design.md diff DESIGN.md DESIGN-v2.md

设计系统的变更应该像 API 变更一样被审查。它们不应悄无声息地出现在一次生成之中。

DESIGN.md 无法解决的问题

DESIGN.md 不能替代 Figma、用户研究、信息架构、内容设计或交互原型。它也只是上下文，而非强制机制。Anthropic 在 CLAUDE.md 中明确指出了这一点：指令引导模型行为，但它们不是硬配置层。同样的提醒适用于智能体读取的任何文件。具体、简洁、无冲突的规则能提高遵循的概率，但不能保证。

其有效范围更窄：

减少隐含的视觉决策。
跨页面和会话保持设计语言稳定。
将视觉意图置于版本控制下并接受审查。
在契约错误扩散到实现之前捕获部分错误。

真正的收获不在于 DESIGN.md 提升了模型的美学上限。它提升的是模型周围约束的质量。README.md 定义了构建什么。AGENTS.md 定义了如何工作。DESIGN.md 定义了结果应该看起来和感觉像什么。CLAUDE.md 将这些共享规则适配到 Claude Code。这就是如何将一次性提示变为可维护的项目上下文。

参考资料

查看原文