DESIGN.md：把 AI 的“设计品味”变成可版本化的工程能力

一、AI 缺的不是 CSS，而是设计上下文

让 AI 生成一个登录页并不困难。

困难的是，让它生成的登录页与产品现有的控制台、设置页、移动端页面保持一致；让它知道主色为什么只能用于关键操作，卡片为什么不能出现厚重阴影，按钮为什么应该“克制地响应”，以及什么时候应该保持留白而不是继续填充内容。

缺少这些上下文时，AI 通常会回到统计意义上的安全答案：

• 蓝紫色渐变；
• 大号 Hero 标题；
• 白色圆角卡片；
• 柔和阴影；
• 胶囊按钮；
• 看起来像某个通用组件库的默认主题。

这些设计未必错误，却容易失去品牌辨识度。

“鬼哥的空间”将 DESIGN.md 概括为给 AI Design Agent 阅读的设计说明：AGENTS.md 负责告诉编码代理“项目应该怎样构建”，DESIGN.md 则负责告诉它“项目应该长什么样”。文章进一步指出，AI 真正缺少的不是孤立的设计数值，而是能够支持迁移和推理的“设计语义”。

因此，可以把 DESIGN.md 理解为：

DESIGN.md
= 精确的设计参数
+ 参数背后的理由
+ 面对未知场景时的判断原则
+ 明确的设计边界

它并不会凭空赋予模型品味，而是帮助团队把原本存在于设计师经验、评审会议和 Figma 页面中的品味，外化为 AI 可以反复读取的上下文。

小黑把零散的设计经验缝进 DESIGN.md，让设计上下文可以反复读取和版本管理。

---

二、从“设计说明”到“开放格式”

DESIGN.md 的发展过程本身很有启发性。

2026 年 4 月 12 日发布的中文介绍文章，重点强调自然语言和 Markdown 的价值，并将其描述为一份几乎不依赖工具链的设计说明。九天后的 4 月 21 日，Google 正式宣布开放 DESIGN.md 草案规范，希望它能够跨工具、跨平台使用，并支持 Agent 理解颜色的语义用途以及检查 WCAG 对比度。

当前官方规范已经形成了更完整的双层结构：

┌─────────────────────────────────────┐
│ YAML Front Matter                   │
│ 机器可读：颜色、字体、间距、圆角、组件 │
├─────────────────────────────────────┤
│ Markdown Body                       │
│ 人与 AI 可读：氛围、理由、原则、边界   │
└─────────────────────────────────────┘

YAML Front Matter 是可选的，用于提供机器可解析的 Design Tokens；Markdown 正文用于解释视觉身份、设计理由和使用方式。规范层面，Token 是文件中的精确值；生成质量层面，Prose——也就是自然语言描述——承担着设计决策上下文的核心作用。

这也修正了一个容易产生的误解：

DESIGN.md 并不是“用自然语言代替所有 Design Tokens”，而是把 Token 的精确性和自然语言的表达能力放进同一份文件。

---

三、DESIGN.md 的三层设计模型

1. Token 层：告诉 AI“具体是什么”

Token 层适合承载不可含糊的值：

colors:
  primary: "#17202A"
  accent: "#A4432B"

typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6

rounded:
  sm: 4px

spacing:
  md: 16px

这一层回答的是：

• 品牌主色具体是什么；
• 正文使用哪种字体；
• 标准间距是多少；
• 卡片圆角究竟是 4px、8px 还是 16px。

它减少了 Agent 自由发挥时产生的数值漂移。

2. Prose 层：告诉 AI“为什么这样设计”

只有 Token，AI 仍然只能机械复用。

例如：

accent: "#A4432B"

这只能告诉 AI 一个色值，却没有告诉它使用边界。补充自然语言后，决策才完整：

Accent 是整个界面唯一具有明显温度的颜色。

它只用于当前页面最重要的操作和关键状态，
不能用于大面积背景、装饰图形或普通链接。
它的稀缺性比它的饱和度更重要。

当 Agent 创建一个规范中从未出现过的“批量确认面板”时，它可以根据这段理由判断：如果确认按钮代表页面最关键的动作，可以使用 Accent；面板背景本身则不应该使用 Accent。

这就是“设计语义”的价值——不仅能复刻已知组件，还能处理未知组件。

3. Guardrail 层：告诉 AI“什么不能做”

生成式模型倾向于补充细节。有时它会“好心”加入渐变、玻璃效果、装饰图标或者夸张动效。

因此，DESIGN.md 需要明确的负向约束：

## Do's and Don'ts

- Do 保持高信息密度，但通过对齐和留白维持可读性。
- Do 只在关键操作上使用强调色。
- Don't 使用渐变、玻璃拟态和发光边框。
- Don't 同时混用胶囊圆角与直角卡片。
- Don't 为了填满页面而添加无功能的装饰元素。

官方设计哲学特别强调：与“现代、简洁、高级、可信”这类宽泛形容词相比，一个具体的设计参照能够更准确地限定模型的输出空间。例如，“面向研究工程师的传统大学课程讲义”天然携带字体、留白、信息密度和装饰克制等一整套隐含约束。

---

小黑用参数、理由和边界共同控制绘图工具，为未知组件延续同一套设计语言。

四、一份标准 DESIGN.md 包含什么

官方规范定义了若干基础 Token 类别：

类别	主要内容
colors	品牌色、背景色、文本色、状态色
typography	字体、字号、字重、行高、字距
spacing	间距尺度、栅格间距、边距
rounded	圆角尺度
components	按钮、卡片、输入框等组件属性映射
omitted	明确记录有意省略的 Token 类别及原因

Markdown 正文使用二级标题组织。规范建议按照以下顺序排列：

1. Overview
2. Colors
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

不适用于项目的章节可以省略，但已经出现的标准章节应维持规定顺序。规范也允许增加 Motion、Iconography 等自定义章节；未知章节应被保留，而重复的标准章节会被视为错误。

这种设计体现了一个重要取舍：

对颜色、字体、间距等通用概念进行标准化；对动效、图标、声音反馈和行业组件等差异较大的概念保持开放。

---

五、一个完整的 DESIGN.md 示例

下面是一份面向运营控制台的简化示例。YAML 负责精确值，Markdown 负责表达设计世界观。

---
version: alpha
name: Atlas Console
description: A calm, high-density operations dashboard.

colors:
  primary: "#17202A"
  muted: "#66717D"
  accent: "#A4432B"
  accent-hover: "#8F3823"
  surface: "#F6F7F9"
  surface-raised: "#FFFFFF"
  on-primary: "#FFFFFF"
  on-accent: "#FFFFFF"

typography:
  headline-lg:
    fontFamily: Inter
    fontSize: 40px
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: -0.02em

  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6

  label-md:
    fontFamily: "IBM Plex Mono"
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1.2
    letterSpacing: 0.06em

rounded:
  sm: 4px
  md: 8px
  full: 9999px

spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 40px

components:
  app-shell:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.primary}"
    typography: "{typography.body-md}"
    padding: "{spacing.lg}"

  top-nav:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    height: 56px

  card:
    backgroundColor: "{colors.surface-raised}"
    textColor: "{colors.primary}"
    rounded: "{rounded.md}"
    padding: "{spacing.lg}"

  button-primary:
    backgroundColor: "{colors.accent}"
    textColor: "{colors.on-accent}"
    typography: "{typography.label-md}"
    rounded: "{rounded.sm}"
    padding: 12px

  button-primary-hover:
    backgroundColor: "{colors.accent-hover}"

  metadata:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.muted}"
    typography: "{typography.label-md}"
---

# Atlas Console Design System

## Overview

Atlas Console 面向需要长时间查看告警、任务和运行指标的运营人员。

整体体验介于机场运行控制台与严肃财经报纸之间：
信息密集、结构清晰、语气冷静，不通过装饰制造“科技感”。

界面首先要让人快速判断状态，其次才是视觉吸引力。
任何视觉元素都必须承担导航、分组、状态表达或操作反馈中的至少一种功能。

## Colors

界面以冷静的深墨色和浅灰表面为基础，仅保留一种温暖的陶土色作为强调。

- **Primary** {colors.primary} 用于标题、核心文字和顶部导航。
- **Muted** {colors.muted} 用于元数据、辅助说明和次要状态。
- **Accent** {colors.accent} 只用于每个页面最重要的操作。
- **Surface** {colors.surface} 是应用背景，不使用纯白作为整页底色。
- **Surface Raised** {colors.surface-raised} 用于需要从背景中分离的内容区域。

Accent 的稀缺性是设计的一部分。一个视图中不应同时出现多个相互竞争的强调按钮。

## Typography

Inter 承担标题和正文，保持稳定、中性和高可读性。

IBM Plex Mono 只用于时间戳、编号、指标标签和系统元数据。
它代表机器输出，不应用于普通段落或营销文案。

标题依靠字重和间距建立层级，不使用夸张字号。

## Layout

桌面内容区域采用固定最大宽度与流式列布局。

页面使用 8px 节奏组织主要间距，4px 仅用于图标与文字之间的微调。
相关信息应通过对齐和邻近关系分组，而不是为每一组内容增加独立卡片。

信息密度可以较高，但主要任务之间必须保留明显的结构间隔。

## Elevation & Depth

层级主要通过背景色差、边界和间距表达。

卡片只允许使用极轻的阴影；普通内容区域优先使用色调差异。
模态框和浮层可以提高阴影强度，但不能产生漂浮、发光或玻璃质感。

## Shapes

4px 是标准交互圆角，8px 仅用于较大的容器。

胶囊形状只用于标签、筛选条件和状态标记，
不能用于主要按钮、输入框或卡片。

同一视图中不得随意混用直角、轻圆角和大圆角。

## Components

主要按钮应显得明确、稳定，而不是活泼。

Hover 状态通过颜色加深表达反馈，不做弹跳、旋转或大幅位移。
卡片应服务于信息分组，不应把每一段内容都包装成卡片。

系统元数据使用等宽字体，但用户生成的内容继续使用正文字体。

## Do's and Don'ts

- Do 保持关键数字和状态在视觉扫描路径上。
- Do 使用对齐、字重和间距建立信息层级。
- Do 为错误、空状态和加载状态保留同一套视觉语言。
- Don't 使用渐变、玻璃拟态、发光边框或装饰性网格背景。
- Don't 在单个视图中安排多个同等强度的主操作。
- Don't 为了增加“设计感”而牺牲信息密度。
- Don't 把等宽字体用于长段正文。

这份文件的关键不在于写了多少 Token，而在于它建立了一个可推理的设计逻辑：

• 视觉吸引力不能压过信息判断；
• 强调色必须保持稀缺；
• 层级优先通过色调、排版和间距表达；
• 新组件也必须遵守同样的限制。

---

六、把 DESIGN.md 接入 AI 编码工作流

仅仅把文件放进项目根目录，并不能保证所有 Agent 都会自动读取。更稳妥的方式，是在 AGENTS.md、CLAUDE.md 或项目级系统提示中显式引用。

项目结构可以是：

atlas-console/
├── README.md
├── AGENTS.md
├── DESIGN.md
├── package.json
└── src/

在 AGENTS.md 中增加：

## UI Design Contract

Before creating or modifying any UI:

1. Read DESIGN.md completely.
2. Treat YAML tokens as the approved design values.
3. Use the Markdown rationale to resolve unspecified decisions.
4. Do not introduce new colors, fonts, radii, shadows, or motion styles
   unless the task explicitly requires updating DESIGN.md.
5. Preserve the Do's and Don'ts across desktop and mobile layouts.
6. Run the DESIGN.md linter before completing the task.

早期实践文章同样建议在 Agent 的项目说明文件中明确要求其首先读取 DESIGN.md，以减少不同工具之间的自动发现差异。

使用官方 CLI 检查文件

官方项目提供了 lint、diff、export 和 spec 等命令，可用于验证结构、检查 Token 引用、比较版本变化，以及导出 Tailwind 或 DTCG 格式。

npm install -D @google/design.md

检查 DESIGN.md：

npx @google/design.md lint DESIGN.md

比较两个版本：

npx @google/design.md diff DESIGN.md DESIGN.next.md

导出为 Tailwind v4 CSS Theme：

npx @google/design.md export \
  --format css-tailwind \
  DESIGN.md > src/styles/theme.css

导出为 DTCG Tokens：

npx @google/design.md export \
  --format dtcg \
  DESIGN.md > tokens.json

当前 Linter 可以发现断裂的 Token 引用、缺失的主色和字体、对比度问题、未使用的颜色、章节顺序异常以及疑似拼写错误的字段。规范中的颜色值也可被转换到 sRGB，用于执行 WCAG 对比度检查。

在 CI 中，可以把它作为普通质量门禁：

{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md",
    "design:export": "designmd export --format css-tailwind DESIGN.md > src/styles/theme.css"
  }
}

- name: Validate design contract
  run: npm run design:lint

这意味着设计规范不再只是一个“请大家自觉遵守”的文档，而可以像代码规范一样参与 Pull Request。

---

七、DESIGN.md 与 Figma、Tokens、Tailwind 是什么关系

DESIGN.md 不应该被视为 Figma、Storybook 或 Design Tokens 的替代品。

更准确的理解是，它们分别回答不同问题：

资产	主要回答的问题
Figma	当前界面具体长什么样
Storybook	已实现组件有哪些状态和行为
DTCG / Tokens JSON	代码应该使用哪些精确值
Tailwind Theme	这些值如何进入样式工具链
DESIGN.md	Agent 面对新页面和未知组件时，应该如何做设计决策

传统 Token 擅长表达：

{
  "accent": "#A4432B",
  "radius": "4px"
}

DESIGN.md 则补上：

为什么使用这两个值？
它们分别适用于什么场景？
什么场景不能使用？
当出现规范中没有的新组件时，应该如何延续这种语言？

官方规范也支持将 DESIGN.md 中的 Token 转换为 Tailwind 配置和 DTCG 格式。因此，它更像是位于设计意图与实现工具之间的语义桥梁，而不是要重新发明一套样式语言。

---

八、怎样写出真正有用的 DESIGN.md

使用具体参照，而不是形容词堆砌

低质量写法：

产品应该现代、简洁、高级、专业、可信。

这些词覆盖的设计空间过大。不同 Agent、不同会话可能得到完全不同的解释。

更有效的写法是：

界面像一份供基础设施工程师使用的事故调查报告：
克制、精确、信息密集，依靠编号、表格、对齐和留白建立秩序。
它不是营销网站，不需要巨型标题、渐变背景或装饰插画。

具体参照相当于为模型提供一个坐标，而泛化形容词只提供一片模糊区域。

小黑把具体的事故调查报告钉成设计坐标，现代、高级、简洁等模糊形容词则飘在空中。

每条规则同时写清“角色、理由和边界”

不要只写：

主色是 #A4432B。

应当写成：

主色 #A4432B 用于当前页面唯一的主操作。

它为冷静的中性色界面提供少量温度。
不要将它用于普通链接、大面积背景或装饰图形，
否则会破坏操作优先级。

一个成熟的颜色定义至少回答四个问题：

它是什么？
它用在哪里？
为什么这样用？
它不能用在哪里？

描述关系，而不只是描述元素

“标题为 40px”是参数。

“标题不应超过正文的 2.5 倍，以避免工具界面产生营销页般的视觉重心”才是规则。

设计品味往往存在于元素之间的关系里：

• 强调色与普通颜色的数量关系；
• 标题与正文的比例关系；
• 卡片与页面背景的层级关系；
• 信息密度与留白的平衡；
• 动效反馈与任务节奏的关系。

这些关系正是自然语言比孤立 Token 更擅长表达的部分。

---

九、DESIGN.md 不能解决什么

DESIGN.md 不是设计自动化的终点。

它不能替代信息架构、用户研究、内容设计和人工 Design Review。AI 生成的页面在视觉上符合品牌，并不代表任务流程合理、错误提示清晰或键盘操作完整。早期实践文章也特别指出，DESIGN.md 无法单独保证可用性、无障碍和像素级精度，并且不同 Agent 对同一文件的理解仍可能存在差异。

它也不能替代真实环境中的无障碍测试。Linter 可以检查已经声明的前景色与背景色，但无法完整判断 DOM 语义、焦点顺序、屏幕阅读器体验、动态内容以及所有交互状态。

此外，当前官方格式仍处于 alpha 阶段，组件结构和工具链仍在持续演进。团队在采用时应固定依赖版本，并避免将尚未稳定的字段直接扩散到大量项目中。

另一个风险是同质化。

直接复制某个知名品牌的 DESIGN.md，确实能快速得到“好看”的页面，却可能让产品成为 Linear、Vercel 或其他品牌的模仿品。更合理的做法是提取自己真正需要的设计原则，再结合产品用户、任务密度和品牌性格建立独立的视觉参照。

---

十、让设计规范成为持续维护的工程资产

一份可靠的 DESIGN.md 应该与代码共同演进。

当主色、字体、间距或者组件风格发生变化时，团队应在同一个 Pull Request 中同步更新：

DESIGN.md
Design Tokens
Tailwind Theme
组件代码
Storybook
视觉回归基线

推荐的治理流程是：

设计变更
   ↓
更新 DESIGN.md 的 Token 与设计理由
   ↓
运行 lint 与 diff
   ↓
导出实现层 Tokens
   ↓
生成或修改组件
   ↓
视觉回归测试
   ↓
人工 Design Review

其中，lint 检查文档是否合法，diff 检查设计契约发生了什么变化，视觉回归测试检查实现结果，而人工评审负责判断设计是否真正解决了用户问题。

这四个环节缺一不可。

小黑把设计契约、Tokens、组件和测试装订进同一个 PR，并交由人工评审。

---

结语：品味不是一个提示词，而是一套决策系统

DESIGN.md 最重要的创新，并不是选择了 Markdown。

它真正改变的是设计系统的读者和作用方式。

过去，设计规范主要供设计师和前端工程师查阅；当 AI Agent 开始大规模参与界面生产，设计规范还必须成为一种机器能够持续读取、解释和执行的上下文接口。鬼哥的文章将这种趋势概括为“文档即接口”，而 Google 的开放规范则进一步为它补上结构、校验、差异比较和格式导出能力。

AI 并不会因为项目中多了一个文件，就突然拥有真正的审美意识。

真正发生的是：

团队把隐性的设计经验，转化成了显性的设计语言；
把一次性的提示词，转化成了持续存在的工程契约；
把“看起来不对”，转化成了可以讨论、审查、验证和版本管理的规则。

当设计理由、精确参数和负向约束被放进同一份文件，AI 生成 UI 才有可能从“每次重新猜测”，走向“在同一个设计世界里持续工作”。

这才是 DESIGN.md 对 AI-First 软件开发真正重要的意义。

---

参考资料

• 《DESIGN.md：让 AI 拥有“设计品味”的新标准》
• Google Stitch DESIGN.md 开放规范与官方项目说明。
• Google 关于开放 DESIGN.md 草案规范的公告。