design.md 调研：给 AI 编程代理一份”设计宪法”，让 UI 风格不再飘

调研时间：2026-06-11
调研对象：Google Labs / Stitch / 第三方品牌库的 design.md 实践
目标读者：用 Cursor / Claude Code / Copilot Workspace 生成 UI 的工程师

上周我让 Claude Code 给一个开源硬件项目加三个监控面板。

第一个面板，蓝色主调、Inter 字体、8px 圆角、阴影用 box-shadow: 0 1px 2px。漂亮。

第二个面板，蓝色还是蓝色，但圆角悄悄变成了 12px。第三个面板更好笑——主色调不知道哪儿去了，灰不灰蓝不蓝，字体也跟着换成了 Source Sans Pro。

同样的对话、同样的模型、同样的提示结构。 输出就是不在乎之前发生过什么。

这就是 design.md 要解决的事。

design.md（也写作 DESIGN.md）是 Google Labs 2026 年开源 的一套面向 AI 编码代理的纯文本设计系统规范格式。最早由 Google Stitch 项目随设计稿一起自动生成，2026 年 Q1 独立成开放规范，社区已经围绕它做了 70+ 个世界级品牌的范例库。

它的核心创新是 双层结构：

层	格式	谁读	干什么
设计令牌层	YAML	机器（Agent）	提供精确的十六进制色值、像素值、字号
设计原理层	Markdown	人 + Agent	解释 ” 为什么 ”，比如 ” 主色保持冷静的科技感 ”

双层一起，AI 代理既知道 ” 用什么值 ”，也知道 ” 为什么用 ”，从而在每一次生成 UI 时都贴回品牌。

下面是我为 Otto Robot 桌面端控制台写的一份精简版（只保留核心字段）：

# Otto Console Design System

## 1. 设计令牌（YAML）palette:
  primary: "#1E5AE8"        # 主操作蓝
  primary_hover: "#1648C0"  # 悬浮态
  danger: "#E5484D"          # 设备掉线告警
  success: "#30A46C"         # 连接成功
  surface: "#FFFFFF"
  surface_alt: "#F7F8FA"     # 卡片 / 分隔区
  border: "#E4E7EB"
  text_primary: "#101828"
  text_secondary: "#475467"
  text_disabled: "#98A2B3"

typography:
  font_family_sans: "Inter, 'PingFang SC', sans-serif"
  font_family_mono: "JetBrains Mono, monospace"
  size_xs: "12px"
  size_sm: "14px"
  size_base: "16px"
  size_lg: "20px"
  size_xl: "28px"
  weight_regular: 400
  weight_medium: 500
  weight_bold: 700

spacing:
  unit: 4                   # 所有间距都是 4 的倍数
  xs: 4
  sm: 8
  md: 16
  lg: 24
  xl: 32

radius:
  sm: 4                     # 输入框、徽标
  md: 8                     # 按钮、卡片
  lg: 12                    # 弹窗
  pill: 9999                # 标签

shadow:
  card: "0 1px 2px rgba(16,24,40,0.06), 0 1px 3px rgba(16,24,40,0.10)"
  modal: "0 12px 16px rgba(16,24,40,0.08), 0 4px 8px rgba(16,24,40,0.03)"

motion:
  duration_fast: 120ms      # 悬浮 / 点击反馈
  duration_base: 200ms      # 状态切换
  duration_slow: 320ms      # 弹窗进出
  easing: "cubic-bezier(0.2, 0, 0, 1)"

冷静的科技感，但不冷冰。Otto 是陪伴型桌面机器人，所以界面要有 ” 工具的克制 ”+” 陪伴的柔软 ” 两层气质——主色冷静、字号偏大、间距偏松。

主操作蓝（#1E5AE8）：仅用于核心 CTA（连接、配网、保存）。一个屏幕最多出现 2 次。
危险红（#E5484D）：仅用于设备掉线、连接失败、数据丢失告警。出现时必须配图标，不能只靠颜色。
禁用灰（#98A2B3）：禁用态必须显著低于 text_secondary（#475467），保证可访问性 ≥ 4.5:1。

所有正文用 size_base（16px）。监控数据用 size_lg（20px）加 weight_medium。
中文使用 PingFang SC，西文使用 Inter；混排时按字符自动切换。

radius_md（8px）是默认值。任何按钮、卡片默认 8px，不要 ” 有的圆有的方 ”。
radius_pill 只用于状态徽章（在线 / 离线 / 连接中）。

shadow_card 用于所有静态卡片。
shadow_modal 仅用于弹窗和抽屉。禁止把 shadow_modal 用在卡片上——会显得太 ” 飘 ”。

所有过渡 ≤ 320ms。超过 320ms 用户会以为卡了。
不使用旋转、抖动、闪烁等 ” 卖萌 ” 动画——这跟 Otto 的工具型气质冲突。

这份文件丢给 Cursor / Claude Code 之后，只要你每次都在对话开头贴一下：” 请按 design.md 的规范生成 ”，生成的三个面板圆角、字号、色值就会一致。

社区里 *.md 文件太多，新人容易混。我整理了一张对照表：

文件	解决什么问题	谁读	示例
README.md	项目是什么 / 怎么跑起来	人类开发者	“Otto Robot 是开源桌面 AI 机器人，BOM 在 docs/bom.md”
*SPEC.md / specs/SPEC-.md**	一个功能模块的业务规格（EARS 语法、验收标准）	人类 + Agent	“ 设备配网功能：WHEN 用户按下配网按钮，THEN 系统进入 AP 模式 ”
design.md	整个项目的视觉 / 交互规范	人类 + Agent	“ 主色 #1E5AE8，圆角 8px 默认，所有间距 4 的倍数 ”
requirements.md	用户故事、验收标准（瀑布流式）	人类	不带 EARS，但有清晰的需求列表

三者在 ” 规范驱动开发（Spec-Driven Development）” 里是配套的：

requirements.md  →  design.md  →  tasks.md（做什么）（怎么做 UI）（拆成什么步骤）

design.md 不是 README 也不是 SPEC，它只管一件事：让 UI 在多次生成后仍然看起来是同一个产品。

工具	角色	怎么用 design.md
Google Stitch	生成器	设计稿生成后自动产出 design.md
Cursor	AI 编辑器	把 design.md 放到项目根目录，每次 @design.md 引用
Claude Code	CLI Agent	对话开头粘贴，或写入 CLAUDE.md 自动读取
Copilot Workspace	云端 IDE	作为系统提示的一部分
design-md（OpenClaw 技能）	自动生成	分析 Stitch 项目并产出语义化的 design.md
code-generator（CAF v0.6.5）	代码生成	优先读 specs/SPEC-*.md，复杂场景读 design.md

多页面 / 多组件的产品：第二个组件开始风格飘了，就该上 design.md
多 Agent 协作：一个 Agent 写前端、一个写后端，前端必须有自己的 ” 宪法 ”
品牌敏感型项目：客户对色彩、字体有强约束（咨询 / 电商 /SaaS）
AI 编程重度用户：每天让 AI 生成 5+ 组件，不沉淀规范就是浪费 tokens

一次性脚本 / 命令行工具：没有 UI，规范无处落地
纯后端 / 嵌入式项目：直接读芯片手册就够了
早期原型 / 探索阶段：设计令牌还在快速迭代，写 design.md 是负担
完全无品牌需求的项目：纯内部工具，浏览器默认样式即可

如果你正在做以下项目，建议立刻补 design.md：

项目	为什么需要
SBTI 测评导航站	多页面（SBTI 介绍 / 测评 / 结果），需要统一品牌
AI 玩具市场调研	后续要做落地页，风格一致性影响转化率
Otto Robot 控制台	多端（桌面 / Web / 小程序），design.md 是统一锚点
OpenClaw 文档站	后续会有十几个技能页，没有规范会乱

最低成本的起步：

从 design.md 品牌范例库找一个最像你产品的（比如 Linear / Vercel / Stripe）
复制它的 design.md，改 5 个字段：主色、字体、Logo 引用、Slogan、最大圆角
丢到项目根目录
之后每次让 AI 写 UI 都 @design.md

第一份完整的 design.md 应该包含（最少 8 个章节）：

设计令牌（颜色 / 排版 / 间距 / 圆角 / 阴影 / 动效）
品牌基调（一段话讲清楚 ” 我们要什么气质 ”）
颜色使用规则（什么时候用什么颜色，禁用场景）
排版规则（字号 / 字重 / 行高 / 中英混排）
组件规则（按钮 / 卡片 / 输入框 / 弹窗的默认值）
可访问性（最低对比度 4.5:1）
反模式（明确禁止的样式，比如 ” 不许用阴影模态卡 ”）

调研过程中我也踩了几个坑，提前讲：

design.md 不是银弹：Agent 在 ” 创意性 UI”（比如登录页首屏）上仍然会跑偏。design.md 守的是 ” 系统页 ”（监控、列表、表单），不是 ” 营销页 ”。
YAML 写太细反而坑 ：把 100 个色值全列出来，Agent 会选择困难。 经验值：色板控制在 12 个以内，超出等于没规范。
不要写 ” 看起来现代 ” 这种主观词：” 现代 ”” 简洁 ”” 高级感 ” 对 Agent 没用。要写就写 ” 圆角 8px，间距 4 的倍数，主色只在 CTA 出现 ”。
design.md 必须和实际代码同步：你改了主色但忘了改 design.md，下一个 Agent 会读到旧值。建议把 design.md 跟设计令牌（CSS Variables / Tailwind config）做单向同步——代码改了自动更新文档，或者文档改了强制审视代码。
品牌库范例未必能直接用：那些 70+ 品牌的 design.md 多是营销稿，重点展示自己品牌有多好。要拆结构、看字段、别抄设计。

Google Stitch：https://stitch.withgoogle.com（设计稿 → design.md 自动产出）
design.md 品牌范例库（70 个）：https://yijiebuyi.com/blog/tags/design-md
Hermes Agent DESIGN.md 项目（9.8K+ stars）：https://github.com/nousresearch/hermes-agent
WaveSpeed 解读：https://wavespeed.ai/blog/zh-TW/posts/what-is-design-md-for-coding-agents
OpenClaw design-md 技能：https://clawindex.app/zh/skills/design-md-foolhardy45-portfolio
规范驱动开发三件套：requirements.md + design.md + tasks.md（CAF v0.6.5 体系）

design.md 是 AI 编程时代的 ” 设计宪法 ”。 它不能解决所有 UI 一致性问题，但能在 80% 的工程场景里把 AI 生成的 UI 拉回品牌轨道。

成本：写一份 300-500 行的 design.md，耗时 2-4 小时。
收益：之后每次 AI 生成 UI 风格都稳定，省下来的 ” 调样式时间 ” 远超投入。

建议：每个有 UI 的项目根目录都该有一份 design.md。 不写就是赌 Agent 每次都记得。

调研人：增长运营官
调研日期：2026-06-11
适用版本：design.md 规范 v1.x（Google Labs 2026 Q1）

design.md 调研：给 AI 编程代理一份”设计宪法”，让 UI 风格不再飘

一、先说痛点：AI 写 UI，第二个组件就开始跑偏

二、design.md 是什么

三、一个真实的 design.md 示例

2. 设计原理（Markdown）

品牌基调

颜色使用规则

排版规则

圆角语义

阴影语义

动效规则

四、design.md vs SPEC.md vs README.md

五、工具链现状（2026-06）

六、什么时候用 / 不要用

适合用 design.md 的场景

不适合的场景

七、实践建议（飞熊项目视角）

八、局限与陷阱

九、资源清单

十、结论

近期文章

近期评论