近期出现了完全通过 AI 制作的网站，家具展示区域支持 360 度拖拽和放大查看细节。

关于 Design.md，给 AI 一份设计规范让它生成代码时有章可循。但实际动手写时，很多人会卡住——不知道写什么、写到什么粒度、怎么组织结构？

Vercel 近期完整公开了自家设计系统的 design.md（https://vercel.com/design.md），这是目前公开可见最完整、最成熟的范本。

01 整体结构：Token 值 + 解释性指导

Vercel 的 design.md 分为两大块：

• 前半部分是 YAML 格式的结构化数据：颜色色值、字号行高、间距数值、圆角大小、组件尺寸
• 后半部分是设计指导：解释这些 token 该怎么用、怎么选择

如果只有数据没有解释，AI 知道有 10 个灰色但不知该挑哪个；只有解释没有数据，AI 理解了意图但生成的色值靠猜。两者缺一不可。

02 颜色写法：语义编号 + 用途映射

Vercel 为每种色彩建立了 100 到 1000 的十级色阶，并明确定义每一级的交互语义：

• 100～300：背景色
• 400～600：边框色
• 700～800：实心填充色
• 900～1000：文字和图标色

所有色系（蓝、红、绿、琥珀、紫、粉、青）都遵循同一套映射规则。精妙之处在于把颜色选择从美学判断变成了查表问题——AI 只需要知道当前是什么状态和层级，对应取哪个编号即可。

灰色的"双轨制"：不透明灰（gray*）用于文字和填充，半透明灰（gray-alpha*）用于边框和覆盖层。

03 字号写法：角色分类而非尺寸罗列

Vercel 把文字样式分成四类角色：Heading（标题）、Label（标签）、Copy（正文）、Button（按钮）。每个角色下再按尺寸展开。

这比传统 h1/h2/h3/body/caption 分法更清晰，因为它直接回答了 AI 最常面对的决策："这段文字是干嘛的"。确定了角色，尺寸范围就自动缩小了。

04 组件写法：引用而非硬编码

Vercel 定义组件时，所有属性值都是对底层 token 的引用：

button-primary:
  backgroundColor: "{colors.primary}"
  textColor: "{colors.background-100}"
  typography: "{typography.button-14}"
  rounded: "{rounded.sm}"
  height: 40px

这让 AI 理解"这个按钮的背景色就是系统主色"的语义联系。如果将来主色更换，AI 有能力全局自动改变。

05 动效规范：尽力可量化

Vercel 用时长和缓动数值来量化动效，避免了"过渡要自然、动画要克制"这种正确废话。

文档明确规定：只对 opacity 和 transform 做动画，禁止对 width、height、margin、padding 等元素做动效——后者会触发重排造成卡顿。不写进 design.md，AI 经常会写出 transition: all 0.3s 这种糟糕效果。

06 最被低估的部分：文案规范

文档包含 "Voice & Content" 章节，规定了按钮文案、错误信息、Toast 提示、加载状态的写法：

• 按钮要写具体动作："Deploy Project"，不要写"Confirm"
• 错误信息要包含"出了什么事 + 该怎么办"
• Toast 不说"Successfully"，直接写"Project deleted"

大家都在纠结颜色和布局的 token，但 AI 生成界面时的文案同样需要指导。

07 Do's & Don'ts：划定边界

• 不要仅用颜色表达状态（考虑色盲）
• 不要在一个视图中混用圆角和直角
• 不要同时超过两种字重
• 保持 WCAG AA 对比度

思考与总结

Vercel 的 design.md 粒度拿捏得很好——没有事无巨细地定义每种可能的 UI 场景，但把最高频的决策点都覆盖了。

写自家 design.md 时不必追求一步到位，先把核心 token 和最高频的组件覆盖就够。一份设计系统好不好，过去看设计师和开发者能不能遵守；现在多了一个评判标准：AI 读了它之后，能不能生成合格的界面。