什么是 DESIGN.md？让 AI 代理读懂设计系统的文件

DESIGN.md 是 Google Stitch 开源的 AI 编码代理设计系统文件规范，整理了 YAML 令牌与 Markdown 正文结构、lint·export CLI，以及在 Claude Code·Cursor 中的接入方式和限制。

SeokWoo Lee资深 iOS 软件工程师发布 2026年8月9日更新 2026年8月27日7 分钟阅读

如果你让 AI 代理做过 UI，应该遇到过这种情况：昨天做出的页面是蓝色圆角按钮，今天新会话做出的页面却变成紫色渐变和直角按钮。同一个项目的页面逐渐像不同品牌的应用，只能每次都在提示词里粘贴“品牌色是 #2563EB，圆角是 8px……”

DESIGN.md 是针对这一问题的文件规范。Google Labs 于 2026 年 4 月 21 日将其 AI UI 设计工具 Stitch 使用的格式开源（Google 官方公告）。一句话概括，它是**“向编码代理解释视觉识别的格式规范”**。在项目仓库放一个 Markdown 文件，让代理每次创建 UI 时读取它。

为什么是文件，而不是提示词

把品牌规则放进提示词的弱点是易失性。会话结束后规则就消失，团队成员也会各自携带不同版本。提交到仓库的文件则不同。

**可以进行版本控制。**设计规则的变化会保留在 Git 历史中，并成为 PR 的审查对象。
**与代码放在一起。**代理读取代码的位置也有设计规则，因此无需额外工具或链接，就能进入上下文。
**与工具无关。**它是纯文本，所以 Claude Code、Cursor、Copilot 等任何代理都能读取。

这个想法并不陌生。为代理提供行为规则的 CLAUDE.md·AGENTS.md 已经以相同原理运行。DESIGN.md 则把这一惯例扩展到了设计系统领域。CLAUDE.md 记录“如何在这个项目中工作”，DESIGN.md 记录“这个产品应该呈现什么样子”。为什么 CLAUDE.md 应该简短本文详细讨论了如何设计持续加载的上下文。

有一点很容易混淆。在规范驱动开发流程中，按 requirements.md → design.md → tasks.md 顺序创建的“技术设计文档 design.md”，只是名称相同的另一种东西。本文讨论的 DESIGN.md 不是架构设计文档，而是设计系统文件。

文件结构：机器读取的令牌＋人类阅读的散文

根据官方规范，DESIGN.md 由两部分组成：前面用 YAML front matter 编写机器可读的设计令牌，后面用 Markdown 正文记录人类可读的设计意图。

---
name: My Product
version: alpha
colors:
  primary: "#2563EB"
  surface: "#FFFFFF"
  onSurface: "#0F172A"
typography:
  headline:
    fontFamily: Pretendard
    fontSize: 28px
    fontWeight: 700
spacing:
  sm: 8px
  md: 16px
rounded:
  card: 12px
components:
  button:
    backgroundColor: "{colors.primary}"
    rounded: 8px
---

## Overview
沉稳而值得信赖的金融服务。优先保证信息清晰，而不是华丽装饰.

## Colors
primary只谨慎用于行动号召元素。页面中的 80%保持为 surface 系列.
...

设计的核心就在这里：令牌是规范，散文是上下文。 colors.primary: "#2563EB"这个值是代理必须遵循的标准答案。“primary 只谨慎用于行动号召元素”则是判断何时何处使用它的依据。只提供颜色代码，代理可能到处使用；只描述氛围，代理又会随意选色。因此两者被放在同一个文件中。

规范规定的几条规则如下。

在 front matter 中，name是必填项，并且至少要定义一个primary颜色。
令牌之间通过路径引用连接，例如{colors.primary}。按钮背景色引用 primary 后，只需修改 primary 就会连锁生效。
正文定义了 8 个章节：Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do’s and Don’ts。全部可选，但已添加的章节必须遵守这一顺序。
不处理的领域可以在omitted字段中连同原因说明，让代理区分“未写”与“刻意排除”。

Google Stitch 发布的 DESIGN.md 公告图片及编辑器中打开的文件画面 — 这是 Stitch 团队发布的公告图片。关键在于，它就是一个能在编辑器中打开的普通 Markdown 文件。

为什么还提供验证工具

公开的不只有格式规范，还有官方 CLI 工具（@google/design.md，Apache-2.0 许可证）。共有四个命令。

命令	作用
`lint`	验证文件结构＋检查令牌引用＋检查 WCAG 对比度
`diff`	比较两个版本并报告令牌级别的变更
`export`	将令牌转换为 Tailwind 配置或 W3C DTCG 格式
`spec`	输出完整规范——用于注入代理提示词

lint 的有趣之处在于，它会在内部把颜色值转换为 sRGB，再检查 WCAG（Web Content Accessibility Guidelines，网页内容无障碍指南）对比度。即使代理生成了“看起来合理”的配色，只要不符合无障碍标准，就会被机械地拦截。这样，设计规则的遵循就不再依赖代理是否认真，而是可以在 CI 中验证；Google 也在公开文档中特别强调了这一点。借用官方公告的说法，目标是让代理不靠猜测，而是“准确知道颜色的用途，并依据 WCAG 无障碍规则验证选择”。

在实际工作中，能用 export 导出 Tailwind 配置也很重要。这使 DESIGN.md 可以作为唯一事实来源，实际 CSS 配置则由它派生。

实际如何使用

开始方式有两种。

**在 Stitch 中生成。**在Stitch中完成设计后，可以导出为 DESIGN.md。先设计几个页面，把视觉语言提取到文件中，再交给编码代理。

**手动编写。**它是普通 Markdown，可以直接在编辑器中编写。如果团队已经整理好设计令牌，就把现有令牌移到 front matter，再把设计指南中解释“为什么”的部分移到正文章节。

创建文件后，将它放在仓库根目录，让代理引用。注意：DESIGN.md 不像 CLAUDE.md，不会由代理自动加载到会话中。由于它仍是 alpha 阶段的新规范，最好在 CLAUDE.md 或 AGENTS.md 中加入“进行 UI 工作时先读取 DESIGN.md 并遵循令牌”这样的一行。没有 UI 工作的会话不必让完整设计系统占用上下文；按需读取在上下文成本上也更划算。

DESIGN.md 的 YAML 令牌和 Markdown 正文流向编码代理与 CLI 验证的流程图 — 令牌和散文位于同一文件中，随后分别流向代理端和 CLI 验证端。

限制与展望

也有一些地方需要冷静看待。

目前仍处于 alpha。 规范的 version 值本身就是“alpha”，字段结构仍可能变化。现在采用它，就要做好跟进规范变更的准备。

**代理遵循规则仍然具有概率性。**即使文件中的令牌写得再准确，也无法保证代理完全照做，毕竟这是 LLM 执行指令。原理与 CLAUDE.md 的指示偶尔被忽略相同。因此 lint 等确定性验证工具才会配套发布。在实践中，应把“文件指示＋CI 验证”视为一个整体。

**覆盖范围仍然有限。**当前规范主要关注颜色、排版、间距、圆角和组件。动效、图标集、响应式断点等领域虽然可以用正文散文描述，但没有令牌模式。

不过，方向已经很明确。提供给代理的上下文正从提示词转移到仓库中受版本控制的文件；继 CLAUDE.md、AGENTS.md 之后，这一趋势如今也延伸到了设计领域。即使工具更换，文件仍会保留，因此这也是不依赖特定代理的投资。如果你一直为了解决 UI 一致性而把品牌规则复制进提示词，不妨先把内容移到一个 DESIGN.md 文件中。

来源与验证

Stitch's DESIGN.md format is now open-sourceGoogle (2026-04-21) · 官方公告 · 核查 2026年8月8日依据: DESIGN.md 开源事实、公开目的（让代理了解颜色用途并可进行 WCAG 验证）、Stitch 中的生成支持
google-labs-code/design.mdGoogle Labs · 官方文档 · 核查 2026年8月8日依据: Apache-2.0 许可证、alpha 状态，以及 @google/design.md CLI 的 lint·diff·export·spec 命令与功能
DESIGN.md SpecificationGoogle Labs · 标准或规范 · 核查 2026年8月8日依据: front matter 字段（name 必填、primary 颜色必填）、正文 8 个章节、令牌引用语法、omitted 字段、WCAG 对比度检查方式