DESIGN.md：缺失的设计手册

微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署
AI模型价格对比 | AI工具导航 | ONNX模型库 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

每个 AI 编码 Agent 都有同样的盲点。它可以在几秒钟内生成一千行 React，但它不知道你的应用应该是什么样子。

AGENTS.md 告诉 Agent 如何构建。DESIGN.md 告诉它如何看。

这个区别比大多数开发者意识到的更重要，而正在想通这一点的团队正在产出看起来不像是由幻觉自动补全引擎组合的界面。那些还没有意识到的？他们仍在凌晨 2 点手动修复按钮颜色。

1、没有人警告你的"第三天墙"

这几乎是每个 AI 辅助前端项目中都会出现的模式。第一天和第二天感觉很神奇。Agent 搭建组件、连接路由、构建表单。你开始告诉朋友这改变了一切。

然后第三天来了。

Agent 忘记了你选择了哪个状态管理库。当你明确告诉它使用 pnpm 时，它安装了 npm 依赖。它生成了一个与你第一次会话中建立的平面设计语言相矛盾的卡片组件的投影。你花了一个小时重新解释两个会话前存在的上下文。

这不是模型中的 bug。这是一个文档问题。大多数 AI 编码 Agent 每个新会话开始时对之前的会话只有有限的记忆。一些工具正在添加持久记忆功能，但即使是最好的也会随着时间失去细微差别。Agent 运行一个昂贵的发现阶段，扫描你的仓库以了解路由、组件层次结构和样式模式，并在多个会话中重复大部分工作。

AGENTS.md 解决了部分问题。2025 年 8 月由 OpenAI 发布，现在由 Linux 基金会下的 Agentic AI Foundation 管理，AGENTS.md 为编码 Agent 提供了持久的、供应商无关的项目级指导来源：构建命令、测试框架、编码约定、Git 工作流规则。把它想象成一个为机器而不是为人写的 README.md。它已被超过 60,000 个开源项目采用，并被 Cursor、Copilot、Gemini CLI、Codex 和 Windsurf 原生支持。（Claude Code 使用自己的 CLAUDE.md 约定来实现相同的目的，尽管许多团队从他们的 CLAUDE.md 中引用 AGENTS.md 以保持说明的可移植性。）

但 AGENTS.md 是为代码相关事务设计的。它处理依赖安装、CI 管道和 lint 配置非常出色。问它传达你的字体排版 Scale、间距节奏或辅助按钮变体的确切悬停状态，你会得到沉默。

这个差距正是 DESIGN.md 要填补的问题。

2、DESIGN.md 实际上是什么（不是什么）

DESIGN.md 是一个用 Markdown 编写的纯文本设计系统文档，专门为约束和指导你的 AI 编码 Agent 在生成 UI 代码时做出的视觉、交互和空间决策而构建。

它不是 Figma 导出。不是 CSS 文件。不是组件库。

它是一个规范，告诉 Agent："当你生成任何界面元素时，这些是你必须遵循的精确颜色、字体大小、间距值、motion 行为和边界条件。没有例外。"

AGENTS.md 和 DESIGN.md 之间的关系创建了清晰的关注点分离。AGENTS.md 处理如何构建的指令：使用哪个包管理器、如何运行测试、遵循什么分支命名约定。DESIGN.md 管辖事物应该如何看起来、感觉如何以及对交互的响应。一个文件让 Agent 成为有能力的工程师。另一个让它成为有能力的设计师。

这符合更广泛的规范驱动开发运动，自 2025 年底以来一直在获得动力。核心思想很简单：不要通过对话提示迭代并希望 Agent 推断你的意图，你预先写一个全面的规范并将其作为权威真相来源。像 Amazon 的 Kiro、GitHub 的 Spec Kit 和各种开源 SDD 框架都有这种理念。DESIGN.md 不是官方标准（还），但它是一个基于相同逻辑的新兴实践者模式：规范驱动实现，而不是相反。

3、为什么是 Markdown 而不是 JSON

这是大多数开发者首先问的问题，答案归结为冰冷的 token 经济。

AI Agent 通过 tokenization 处理文本。每个字符、每个括号、每个引号消耗模型上下文窗口的一部分。JSON 的结构开销，所有那些花括号、逗号和重复的键名，在编码重复的设计配置时会产生显着的膨胀。

数字指向一致的方向。一个使用 tiktoken 的开发者基准显示，一个中等复杂的数据集从 JSON 的 13,869 个 token 下降到 Markdown 的约 11,612 个 token，大约减少了 16%。当你在上下文窗口中同时包含你的代码库打包整个设计系统时，這是有意义的。

但真正的节省在 Markdown 和 HTML 之间比较時出現。Cloudflare 自己的分析发现，一篇需要原始 HTML 16,180 个 token 的博客文章转换为 Markdown 时缩减到约 3,150 个 token，大约减少了 80%。一个简单的 ## About Us 标题在 Markdown 中花费约 3 个 token。带有类名、ID 和语义包装器的 HTML 等价物在你甚至计算周围 DOM 结构之前就消耗了 12-15 个 token。

Webex 的开发团队认为，Markdown 的清晰结构比 HTML 和纯文本提高了 RAG 检索准确性。一个独立基准测试多个 LLM 的嵌套数据发现，Markdown 一致地是最省 token 的格式，比测试模型上的 JSON 使用大约少 34-38% 的 token。这些数字因模型和任务而异，但方向性发现成立：对于设计系统产生的扁平、重复数据，Markdown 是一个强有力的默认。

还有训练数据的论点。LLM 在预训练期间消耗大量 Markdown，因为 GitHub 仓库、Stack Overflow 帖子和技术文档都是大量使用 Markdown 格式的。该格式的标题层次结构、表格语法和列表结构与这些模型学习解析结构化信息的方式紧密相似。

所以当你在构建需要编码颜色调色板、字体层次结构、间距 Scale、组件状态和 motion 规范的 DESIGN.md 文件时，Markdown 不仅仅更高效。它也是大多数 AI 编码 Agent 最擅长解析的格式。

值得注意的是，即使有 Markdown 的效率收益，一个巨大的设计系统仍会消耗大量上下文窗口空间。如果你的 DESIGN.md 增长到几千个 token 以上，考虑将其拆分为专注的文件（一个 designtokens.md 用于原始值，一个 components.md 用于交互规范）并有选择地引用它们。一些团队将这些输入向量数据库，以便他们的 RAG 管道只在每项任务中检索相关部分。

4、实际工作的 DESIGN.md 的剖析

一个结构良好的 DESIGN.md 遵循与编译应用程序相同的组织逻辑。标题从 H1 流到 H2 到 H3 不跳级别，因为 AI Agent 使用标题层次结构来分配语义权重和确定范围。

这是核心部分在实践中的样子，以及为什么每一个都很重要。

4.1 视觉主题和氛围

这是最高级别的部分，它比大多数人想象的更重要。它确立了美学哲学，当 Agent 在文件中其他地方未明确覆盖的边缘情况遇到概率决策时指导它们。

写"干净、现代的设计"和"粗野主义与强烈的排版焦点和最大的 60% 视口密度"之间的区别是生成通用 Material Design 组件的 Agent 和产生具有实际视觉身份的 Agent 之间的区别。

要具体。要有自己的观点。Agent 读不到你的 mind，但它可以遵循明确表达的美学方向。

4.2 具有语义角色的颜色调色板

这是大多数 DESIGN.md 文件失败的地方。团队倾倒十六进制代码列表并称之为完成。那给 Agent 零上下文的原始值，关于什么时候或在哪里使用它们。

相反，按它们的功能角色定义颜色：

## Color Palette
- color.bg.surface → #FFFFFF — Default background for standard containers
- color.bg.surface-raised → #F8FAFC — Elevated cards and modal backgrounds
- color.fg.primary → #0F172A — Primary text on light surfaces
- color.fg.muted → #64748B — Secondary text; meets WCAG contrast on surface
- color.action.primary → #2563EB — Primary CTA buttons and links
- color.action.danger → #DC2626 — Destructive actions and error states

注意 token 命名约定：它从系统（color）开始，移动到类（bg, fg, action），然后指定功能角色（surface, primary, danger）。这种语义结构让 Agent 理解意图，而不仅仅是外观。当主题改变时，Agent 可以智能地交换值，因为它知道 color.bg.surface 意味着"默认容器背景"，而不是"碰巧是白色的颜色"。

这也是你将可访问性合规直接嵌入 token 定义的地方。注意 `color.fg.muted"满足 WCAG 对表面的对比度"，你给了 Agent 一个可以无需额外指令就能执行的约束。

4.3 字体排版规则

不要只列出字体家族。构建一个不可变的层次结构：

## Typography
- Display → Inter, 700, 48px, line-height 1.1, letter-spacing -0.02em
- H1 → Inter, 700, 36px, line-height 1.2, letter-spacing -0.01em
- H2 → Inter, 600, 28px, line-height 1.3, letter-spacing 0
- Body → Inter, 400, 16px, line-height 1.6, letter-spacing 0
- Caption → Inter, 400, 12px, line-height 1.4, letter-spacing 0.01em

这个层次结构防止 Agent 在组件生成时幻觉任意的字体大小。每个文本元素映射到特定条目。不需要猜测。

4.4 布局原则和间距 Scale

定义一个数学间距系统并坚持它：

## Spacing Scale
Base unit: 4px
- space-1 → 4px — Tight gaps between related elements
- space-2 → 8px — Default inline spacing
- space-3 → 12px — Component internal padding
- space-4 → 16px — Standard section gap
- space-6 → 24px — Container padding
- space-8 → 32px — Major section separation
- space-12 → 48px — Page-level breathing room

当 Agent 使用此列表中的值构建每个组件时，你消除了使 AI 生成的界面看起来有点"不对劲"的微观间距不一致，即使单个组件看起来很好。

4.5 注意部分（最重要的部分）

对数千个 Agent 配置文件的一致分析显示了一个发现：告诉 Agent 不要做什么比告诉它 要做什么更有效。

这是你定义硬边界的部分：

## Do's
- Use CSS Grid for page-level layout
- Use Flexbox for component-level alignment
- Prefer `gap` over margin for spacing between siblings
- Use CSS custom properties for all design tokens
## Don'ts
- NEVER use `!important`
- NEVER use inline styles
- NEVER animate `width`, `height`, `margin`, or `box-shadow`
- NEVER use `transition: all` (list properties individually)
- NEVER add box shadows to base-plane elements
- NEVER use `px` for font sizes (use `rem`)
- NEVER nest more than 3 levels of CSS selectors

"永不提交秘密"指令被确定为广泛 AGENTS.md 分析中最有效的单一约束。同样的原则适用于这里。明确的禁止创造了约束模型概率输出空间的刚性边界。与其从无限可能的方法中选择，Agent 在定义的沙箱中操作。

4.6 处理 Motion 而不破坏性能

静态样式对于从结构良好的 Markdown 规范推断的 Agent 来说相对容易。Motion 设计是事情变得危险的地方。

没有明确的约束，AI Agent 经常为 width、height 和 margin 等昂贵的布局属性设置动画。这些触发布局重绘并破坏渲染性能，尤其是在移动设备上。Agent 不知道这一点，因为它优化的是"它是否动画？"而不是"它是否好地动画？"

你的 DESIGN.md 需要无情的规定性 motion 规范：

## Motion Tokens
- motion-micro → 75ms — Button press, toggle switch (ease-out)
- motion-short → 150ms — Hover states, input focus (ease-in-out)
- motion-medium → 200ms — Page crossfade, modal entry (ease-out)
- motion-long → 400ms — Sidebar reveal, dropdown (ease-in-out)
### Hard Rules
- ONLY animate `transform` and `opacity` (GPU-accelerated properties)
- NEVER use `transition: all`
- ALL animations MUST respect `prefers-reduced-motion` media query
- Wrap all motion in accessibility fallbacks

这些约束让 Agent 保持在 GPU 加速的合成路径上，在大多数情况下绕过主线程布局重计算。transform 和 opacity 规则是大多数 UI 转换的强力默认，尽管有合法的例外（颜色转换通常没问题）。可访问性 mandate 确保生成的代码适用于在操作系统级别禁用了动画的用户。

4.7 基于文本的图表：教 AI 看架构

这是一个问题。你的 DESIGN.md 需要传递组件层次结构、状态转换和事件流。但是，虽然现代 LLM 可以处理图像，但将 PNG 架构图表输入它们比基于文本的替代方案对于这种结构化数据要昂贵得多，而且可靠性更低。

解决方案：直接嵌入 Markdown 的 Mermaid.js 语法。

因为 Mermaid 图表完全由文本字符构建，它们自然地与你的 token 定义和代码示例并排。Agent 同时处理视觉架构和样式规则，确保结构和外观之间的一致性。

对于组件层次结构，使用流程图：

flowchart TD
    App --> Header
    App --> MainContent
    App --> Footer
    MainContent --> Sidebar
    MainContent --> ContentArea
    ContentArea --> ArticleList
    ContentArea --> Pagination

对于交互式组件生命周期，使用状态图：

stateDiagram-v2
    [*] --> Idle
    Idle --> Hover: mouseenter
    Hover --> Active: click
    Active --> Loading: async request
    Loading --> Success: response ok
    Loading --> Error: response fail
    Success --> Idle: timeout
    Error --> Idle: dismiss

这消除导致界面损坏的大量模糊性。Agent 不必猜测按钮组件的有效状态转换。它们被明确映射。它不会每次都产生完美的代码，但 LMs 处理结构化基于文本的图表比处理相同逻辑的非结构化散文描述可靠得多。

还有版本控制的好处。与在 Git 中显示为不透明二进制变化的图像文件不同，Mermaid 块显示可读的 diff。当有人更新状态转换时，拉取请求显示准确改变了什么。Agent 在下次上下文检索期间获取更新的架构，无需任何额外提示。

5、将 DESIGN.md 连接到更广泛的 Agent 工作流

DESIGN.md 不孤立运行。它是你 AI 编码 Agent 在每个任务期间导航的更大知识图谱中的一个节点。

典型设置看起来像这样：AGENTS.md 坐在项目根目录并作为主要路由器。当 Agent 收到 UI 相关任务时，AGENTS.md 明确告诉它在生成任何界面代码之前获取和解析 DESIGN.md。一些团队更进一步，将他们的 DESIGN.md 嵌入向量数据库，以便 RAG 管道只能检索特定于给定任务的 token 和组件定义，而不是将整个文件加载到上下文窗口。

对于使用 Figma 的团队，Code Connect 弥合了设计工具和仓库之间的差距。它将抽象设计组件直接映射到生产代码文件，因此 Agent 不必仅从 Markdown 描述中重新发明按钮组件。它可以参考你代码库中实际存在的组件。

对于面向公众的文档，新兴的 llms.txt 约定与 DESIGN.md 配合工作，作为 AI 爬虫的策划站点地图。放置在你的文档站点根目录，它将外部 Agent 指向你的设计系统文档的优化 Markdown 端点。Cloudflare 现在通过他们的"Markdown for Agents"功能原生支持这一点，在 AI Agent 通过内容协商标头请求它们时自动将 HTML 页面转换为 Markdown。

6、如何开始构建你自己的 DESIGN.md

你不需要一次坐在那里从头写完整个。从最痛苦的开始，然后从那里扩展。

从基础开始。 在你的项目根目录创建一个包含三部分的 DESIGN.md：视觉主题（2-3 句描述美学）、颜色调色板（具有功能角色的语义 token 表）和字体排版（具有精确值的层次结构表）。在你的 AGENTS.md 或 CLAUDE.md 中放一个引用，这样编码 Agent 就知道去找它。

然后添加约束。 Do's 和 Don'ts 部分是你获得最快回报的地方。专注于你的 Agent 一直做错的模式。如果它到处添加 box shadows，明确禁止它们。如果它默认为 transition: all，写一个硬规则反对它。禁止比添加更多积极规范会有更直接的影响。

然后分层间距和 motion。 定义你的间距 Scale 和 motion token。这些消除了 AI 生成 UI 中"看起来有点不对劲"的两个最常见来源：不一致的空白和笨拙的动画���

最后，映射组件状态和架构。 为你最复杂的交互式组件添加 Mermaid 图。映射表单、模态和导航元素的状态转换。这才是长期维护回报真正开始的地方，因为 Agent 停止猜测交互逻辑。

你最终会得到一个涵盖 Agent 需要做出的大约 80% 视觉决策的工作 DESIGN.md。其余的 20% 在开发过程中遇到新的边缘情况时自然会出现。

7、诚实的权衡

DESIGN.md 增加了前期工作。无法回避这一点。你在写代码之前写规范，这意味着把时间花在文档上而不是发布功能。

对于小型个人项目或快速原型，这可能有点过度。如果你正在构建一个周末黑客，默认的 Tailwind 样式就可以了，跳过它。

但对于任何视觉一致性很重要的项目、对于多个人接触前端的项目、或者对于你经常与 AI Agent 讨论界面决策的项目，投资在第一周内就收回了成本。你停止了重新解释上下文。你停止了修复同样的样式错误。你停止了对抗 Agent 生成通用、cookie-cutter 接口的倾向。

这里的更广泛的转变是真实的。规范驱动的开发正在从实验实践走向主流采用，尽管它还处于早期阶段，工具和约定发展得很快。在机器可读格式中记录他们意图的团队已经比单纯依赖对话提示的团队构建得更快、产出更一致。DESIGN.md 是更大转变的视觉层，虽然它仍然是实践者模式而不是正式标准，但底层逻辑足以今天投入实践。

你的 AI 编码 Agent 准备好了成为好设计师。它只需要正确的简报。

原文链接：DESIGN.md: The Missing Instruction Manual Your AI Coding Agent Actually Needs

汇智网翻译整理，转载请标明出处