文档
什么是 DESIGN.md?
DESIGN.md 是一个为 AI 智能体描述设计系统的纯文本文件。顶部的 YAML front matter 存放精确的设计令牌:颜色、字体排版、间距、圆角和组件。下方的 Markdown 正文说明如何以及为什么应用它们。人和智能体都能阅读、编辑并遵循它。
README.md 说明项目是什么。AGENTS.md 告诉编程智能体如何构建它。DESIGN.md 告诉它们项目应该呈现怎样的外观和感觉,让智能体生成的页面共用同一套配色、字号层级和组件语言,而不是各自走样。
DESIGN.md 的由来
Google 随其 AI 设计工具 Google Stitch 推出了 DESIGN.md,作为 AGENTS.md 在设计方面的对应物。Google Labs 在 google-labs-code/design.md 仓库中以 Apache 2.0 许可证将该格式作为开放规范发布。DESIGN.md 规范目前标注为 alpha,因此格式在成熟过程中可能会有变化。
同一仓库还提供一个 npm 包 @google/design.md,其中的 lint 命令可以检查结构、失效的令牌引用和 WCAG 对比度,diff 命令可以逐个令牌比较文件的两个版本。
DESIGN.md 文件的结构
每个 DESIGN.md 文件都有两层。YAML front matter 包含机器可读的设计令牌,比如精确的颜色值、字体属性、间距尺度和组件令牌引用。Markdown 正文提供人类可读的设计理由。
规范把令牌视为规范性的数值,把文字说明视为应用这些数值的上下文。令牌给智能体提供精确的数值,文字说明则告诉它们这些数值为什么存在,以及如何在各个页面中一致地使用。
---
name: DevFocus Dark
colors:
primary: "#2665fd"
secondary: "#475569"
surface: "#0b1326"
on-surface: "#dae2fd"
error: "#ffb4ab"
typography:
body-md:
fontFamily: Inter
fontSize: 16px
fontWeight: 400
rounded:
md: 8px
---
# Design System
## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.
## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions
## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers
## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast
## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text八个标准章节
Markdown 正文使用 ## 标题。不相关的章节可以省略,但出现的章节应该按以下顺序排列。同一个标题出现两次会使文件无效;未知章节会被保留。
- Overview(也可写作 Brand & Style)。用几句话描述外观和感觉:氛围、密度、个性。
- Colors。每个颜色令牌及其承担的角色,比如主要操作或页面表面。
- Typography。字体族和字号层级,从展示标题到小号标签。
- Layout(也可写作 Layout & Spacing)。间距尺度、网格、内容宽度和栏间距。
- Elevation & Depth(也可写作 Elevation)。表面之间如何区分:阴影、边框、色调。
- Shapes。圆角和其他形状规则。
- Components。按钮、输入框、卡片和其他基础组件,包括它们的令牌和状态。
- Do's and Don'ts。智能体不应违反的规则。
一个精简的 Markdown 正文,按顺序包含每个标准章节。根据你的产品调整内容,保留标题和顺序。
## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.
## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds
## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase
## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile
## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces
## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view
## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast
## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text设计令牌与结构
DESIGN.md 把设计令牌以 YAML front matter 的形式嵌入文件开头。front matter 块以一行仅包含 --- 的内容开始,并以同样的分隔符结束。
version: <string>
name: <string>
description: <string>
colors:
<token-name>: <Color>
typography:
<token-name>: <Typography>
rounded:
<scale-level>: <Dimension>
spacing:
<scale-level>: <Dimension | number>
components:
<component-name>:
<token-name>: <string | token reference>常见的尺度名称包括 xs、sm、md、lg、xl 和 full,但任何描述性的键名都有效。间距令牌位于 YAML 的 spacing: 下,并在 Markdown 正文的 Layout 章节中说明。
令牌类型
- 颜色
- 任何有效的 CSS 颜色字符串。推荐默认使用
#RRGGBB形式的 hex 值,例如"#1A1C1E"。 - 尺寸
- 数字加上 px、em 或 rem 单位。示例:
48px、-0.02em。 - 令牌引用
- 用花括号包裹,指向 YAML 树中的某个值。示例:
{colors.primary}。 - 字体排版
- 一个组合对象,包含字体族、字号、字重、行高和字间距等字体属性。参见字体排版属性。
字体排版属性
- fontFamily
- 字体族名称。
- fontSize
- 以尺寸表示的字号。
- fontWeight
- 数字字重,比如 400 或 700。
- lineHeight
- 尺寸或无单位倍数。推荐使用无单位的值。
- letterSpacing
- 以尺寸表示的字间距调整。
- fontFeature
- 配置 font-feature-settings。
- fontVariation
- 配置 font-variation-settings。
令牌引用
令牌引用用花括号包裹,包含指向 YAML 树中另一个值的对象路径。对于大多数令牌组,引用应指向一个基本值,而不是一个组。在 components 章节中,允许引用字体排版层级等组合值。
components:
button-primary:
backgroundColor: "{colors.primary-60}"
textColor: "{colors.primary-20}"
rounded: "{rounded.md}"
button-primary-hover:
backgroundColor: "{colors.primary-70}"组件
components 章节记录基础组件的样式指导,比如按钮、标签、列表、输入框、复选框、单选按钮和工具提示。设计系统可以定义对其产品领域重要的其他组件。
悬停、激活或按下状态的变体,以单独的组件条目定义,并使用相关的键名,比如 button-primary-hover。
- backgroundColor
- 颜色
- textColor
- 颜色
- typography
- 字体排版
- rounded
- 尺寸
- padding
- 尺寸
- size
- 尺寸
- height
- 尺寸
- width
- 尺寸
推荐的令牌名称
这些名称只是建议,不是要求。它们提供了实用的默认值,便于在不同系统之间保持一致。
颜色:primary, secondary, tertiary, neutral, surface, on-surface, error
字体排版:headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm
圆角:none, sm, md, lg, xl, full
AI 智能体如何使用 DESIGN.md
把 DESIGN.md 放在仓库根目录,与 README.md 和 AGENTS.md 并列。任何能访问文件的智能体都能读取它,但大多数智能体不会主动加载它。请在智能体已经会读取的指令中指向它,或者在请求界面相关的工作时在提示词中提到它。简短的一句指引就够了:
## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.- Claude Code
- 会读取你仓库中的文件,并在启动时加载 CLAUDE.md。在 CLAUDE.md 中加一行指向 DESIGN.md,或者在提示词中提到这个文件。
- Cursor
- 把 DESIGN.md 添加到聊天上下文,或在项目规则中引用它,让它适用于每个界面请求。
- GitHub Copilot
- 在仓库的 Copilot 指令文件中指向 DESIGN.md,或者在请求界面相关的工作时在聊天中附上它。
- Google Stitch
- 这个格式的发源地。Stitch 使用 DESIGN.md,让生成的页面共用同一套配色、字号层级和组件语言。
然后,智能体会从令牌中取用精确数值(主按钮的 hex 值、body-md 标签的字号),并根据文字说明决定它们该用在哪里。
DESIGN.md、AGENTS.md 与 README.md 的区别
这三个文件并列存在,回答不同的问题。DESIGN.md 并不取代 AGENTS.md,两者相互配合。
| 文件 | 面向 | 回答的问题 |
|---|---|---|
README.md | 使用项目或为项目做贡献的人 | 这是什么?如何运行它? |
AGENTS.md | 编程智能体 | 如何构建、测试和修改这些代码? |
DESIGN.md | 编程和设计智能体 | 界面应该呈现怎样的外观和感觉? |
真实的 DESIGN.md 示例
理解这个格式最快的方法,是读几份真实的文件。下面每个示例库页面都展示了从品牌公开网站提取的 DESIGN.md,以及它的配色和字体样张。它们不是官方品牌规范。
如何获取 DESIGN.md
- 手动编写。从规范和上面的示例入手,然后用免费的 DESIGN.md 校验器或 Google 的
lint命令检查文件。 - 从示例开始。从示例库中复制一个文件,修改令牌和文字说明,使其符合你的产品。
- 从实时网站生成。把公开网址粘贴到 Design Extractor。它会在浏览器中渲染网站,并返回一份遵循上述规范、包含网站颜色、字体排版、间距和组件的 DESIGN.md。DESIGN.md 生成器页面介绍了你会得到什么。同样的提取也可以通过 Chrome 扩展程序运行,或由你的智能体通过 MCP 服务器运行。
常见问题
DESIGN.md 常见问题
关于 DESIGN.md 格式、它的由来以及如何与 AI 智能体配合使用的简短解答。
DESIGN.md 是一个为 AI 智能体描述设计系统的纯文本文件。顶部的 YAML front matter 存放精确的令牌(颜色、字体排版、间距、圆角和组件),下方的 Markdown 正文说明如何以及为什么应用它们。智能体从令牌中读取数值,从文字说明中理解意图。
Google 随其 AI 设计工具 Stitch 推出了 DESIGN.md。Google Labs 在 GitHub(google-labs-code/design.md)上以 Apache 2.0 许可证发布了该规范。这个格式目前标注为 alpha,因此在成熟过程中可能会有变化。
AGENTS.md 告诉编程智能体如何构建和维护项目:命令、约定、测试。DESIGN.md 告诉它们产品应该呈现怎样的外观和感觉:颜色、字体、间距、形状和组件。README.md 则面向使用项目或为项目做贡献的人。很多仓库会把这三个文件并列放在一起。
放在仓库根目录,与 README.md 和 AGENTS.md 并列,这样能访问文件的智能体就能找到它。然后在智能体已经会加载的指令中指向它,比如 AGENTS.md、CLAUDE.md、Cursor 规则或 Copilot 指令;或者在请求界面相关的工作时在提示词中提到它。
不必。规范允许省略不适用的章节,但保留的章节应遵循标准顺序:Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts。同一个章节标题不能出现两次,未知章节会被保留而不会被拒绝。
Google 的 npm 包 @google/design.md 提供 lint 命令,可以检查结构、失效的令牌引用和 WCAG 对比度。Design Extractor 也提供免费的 DESIGN.md 校验器,在你的浏览器中检查结构和令牌并预览文件,无需上传。
你可以根据规范手动编写,从真实示例库中复制一份作为起点,或者从实时网站生成。Design Extractor 接收一个公开网址,在浏览器中渲染网站,然后返回一份包含网站颜色、字体排版、间距和组件的 DESIGN.md,可以直接放进你的仓库。
想为你喜欢的网站生成一份?
粘贴一个公开网址,获取它的 DESIGN.md。