万字解读 Vercel DESIGN.md：前端设计规范如何写成 AI 可读的合约

什么是 DESIGN.md

2025 年，Google Stitch 在发布时引入了一个新概念： DESIGN.md 。它不是什么复杂的新框架，就是一个 Markdown 文件，里面写清楚你项目的设计规范：颜色、字体、间距、组件、动效，以及哪些该做、哪些不该做。

为什么偏偏是 Markdown？因为这是大语言模型（LLM）读起来最舒服的格式。不需要 JSON Schema，不用 YAML 配置，更不需要任何解析器。你只需把文件丢进项目根目录，AI 编码助手就能直接理解你的设计语言。

这个思路很快被业界接纳。Vercel 最近也在 vercel.com/design.md 公开了自己完整的设计系统文件。社区项目 awesome-design-md 在 GitHub 上更是收集了 73 个品牌的 DESIGN.md，星标超过 9 万。

前端开发的协作范式，正在从“设计稿交付”转向“规范文件驱动”。

大厂是怎么写设计规范的

Vercel 的 DESIGN.md 是目前公开的、最完整的工业级范本之一。它绝不是一份“看起来好看”的文档，而是一套可以被机器精确解析的设计合约。文件主要分为两大部分：

Part One: YAML Token 定义

用结构化的 YAML 声明所有设计令牌（Design Tokens）：涵盖 8 个色阶（每个 10 级），字体规范（标题、正文、按钮、标签四族），基于 4px 基准的间距体系，圆角规则，以及组件级的复合令牌。

colors:
  primary: "#171717"
  secondary: "#4d4d4d"
  tertiary: "#006bff"

spacing:
  base: 4px
  values: [4, 8, 12, 16, 24, 32, 40, 64, 96]

rounded:
  sm: 6px
  md: 12px
  lg: 16px
  full: 9999px

Part Two: 规范文约

用人类可读的 Markdown 写成，涵盖 9 个维度：概述哲学、颜色语义、字体层级、布局节奏、阴影层级、动效规则、形状规范、组件状态、文案语气。每一条规则都带有明确的“该做”和“不该做”。

值得注意的是，Vercel 的写法有几个非常鲜明的特征：

1. 语义编码
   10 级色阶按意图编码：100 是背景，400 是边框，700 是填充，1000 是主文字。完全不按明度排列，这让 AI 能直接读懂用途。

2. 约束优先
   禁止混用圆角，限制使用两种字重，所有交互元素必须有焦点环。这些都是不可触碰的红线。

3. 文案即设计
   按钮必须用「动词 + 名词」结构，Toast 禁止出现「successfully」，错误信息必须包含下一步操作。连标点和大写都有精细规范。

4. 双色彩空间
   每个颜色同时提供 sRGB hex 和 Display P3 的 oklch 值，兼顾旧设备与广色域屏幕，这一步直接面向了未来的显示设备。

Vercel 的设计品味与哲学

读 Vercel 的 design.md，最大的感受就是克制。

整套系统建立在灰度之上。灰度是骨架，其余颜色只在确实需要表达状态或层级时才会出现。

background → border → fill → text

“Use color to signal state or hierarchy, never for decoration.” —— Vercel Geist Design System

动效规则同样克制得令人印象深刻：“0ms is often the snappiest and best choice.” 大多数交互其实不需要动画，只有在“帮助理解变化”时才加入动效。即使加入，时长也被严格限定：

• State：150ms
• Popover：200ms
• Overlay：300ms

字体系统只用两个家族：Geist Sans 和 Geist Mono。标题字重统一 600，正文统一 400。文件里甚至规定了字间距随字号增大的收紧比例（ heading-72 的 letterSpacing 是 -4.32px），这种细节通常只出现在字体设计师的笔记里。

布局节奏用三档间距来控制：组内 8px，组间 16px，段落间 32 到 40px。卡片默认内边距 24px，内容居中在 1200px 列宽内。整个系统没有一个多余的数字。

这种品味不是单纯的“好看”，而是极致的可预测。当每个决策都被约束在一个极小的范围内，最终产物自然会具备高度一致性。这正是 design.md 的核心价值：把品味编码成规则。在技术文档的编写中，这种思路也同样值得借鉴。

如何使用 DESIGN.md

使用方式极其简单，三步就能完成：

1. 获取文件：手动下载或从仓库获取。
2. 放入项目：直接放到根目录。
3. 引用它：告诉 AI 助手参考它。

在终端里，这三步是这样的：

# 第一步：获取文件
curl vercel.com/design.md -o DESIGN.md

# 第二步：放入项目根目录
mv DESIGN.md ./your-project/

# 第三步：告诉你的 AI 助手
# 提示词：「请参考 DESIGN.md 来构建这个页面的 UI」

你也可以从 awesome-design-md 仓库获取其他品牌的 DESIGN.md。仓库按类别整理得很清楚：AI 平台、开发者工具、设计工具、电商、金融科技、汽车品牌，甚至还有复古网站（Dell 1996, Nintendo 2001）。每个品牌都附带深浅两色的预览 HTML。

如果你想为自己公司写一份，可以直接参照 Vercel 的结构：先写 YAML token，再写规范约束，最后附上 Do's and Don'ts。尤其是做前端框架/工程化相关项目的同学，不需要一上来就覆盖所有维度，从颜色和字体开始就够了。

Vercel 对比 getdesign

这两个项目代表了 DESIGN.md 生态的两条路径，各有侧重。

维度	Vercel	getdesign
来源	官方原生	社区逆向提取
覆盖范围	仅 Vercel	73 个品牌
格式	YAML, Markdown	纯 Markdown
机器可读	✓ 工具可自动解析	✗ 需转译
P3 广色域	✓ oklch 值	✗ 仅 sRGB
文案规范	✓ 极其细致	✗ 基本缺失
预览 HTML	✗ 无	✓ 深浅两色
设计意图	✓ 语义化编码	✗ CSS 值逆向

Vercel design.md

• Strengths
  • 工业级完整度，YAML token 可直接被设计工具解析
  • 语义化颜色编码，AI 能理解用途而非仅识别色值
  • 双色彩空间 (sRGB + P3)，面向未来显示设备
  • 文案规范极其细致，覆盖标点、大小写、措辞
• Weaknesses
  • 只覆盖 Vercel 自身的设计语言，不具备通用性
  • 没有深色主题内联，需要单独获取 design.dark.md
  • YAML + Markdown 混合格式，解析需要两套逻辑

getdesign.md

• Strengths
  • 覆盖 73 个品牌，选择面极广
  • 统一的九段式结构，学习成本低
  • 每个品牌附带预览 HTML，可视化验证
  • 社区驱动，可以请求新品牌
• Weaknesses
  • 逆向提取的 CSS 值，无法覆盖设计意图
  • 缺少 YAML token 层，工具链集成弱
  • 品牌方未官方参与，规范可能滞后

Vercel 的 design.md 是“官方原生”，深度够但广度窄；getdesign.md 是“社区翻译”，广度大但精度有限。两者是互补而非替代的关系。这就像在开源实战中，官方文档和社区笔记总是相辅相成的。

写在最后

DESIGN.md 不是什么革命性技术。它做的事情，本质上和十年前的 Pattern Library、五年前的 Storybook 一样：把设计决策固化成可复用的资产。

但它赶上了对的时间点。当 AI 编码助手成为日常工具，一个机器可读的设计规范就从锦上添花的点缀，变成了不可或缺的基础设施。Markdown 作为 LLM 最熟悉的格式，天然成为了这个接口的最佳载体。

Vercel 用一份文件证明了：最好的设计规范，不是写给人看的 PPT，而是写给机器读的合约。想了解更多此类前沿范式，不妨常来云栈社区和众多开发者一起交流探讨。

References

• vercel.com/design.md — Vercel Geist Design System
• github.com/VoltAgent/awesome-design-md — 73 brands DESIGN.md
• stitch.withgoogle.com/docs/design-md/specification — Google Stitch Spec