Google DESIGN.md

DESIGN.md 是 Google Labs 推出的设计系统自包含纯文本表示格式。它将机器可读的设计 token（YAML front matter）与人类可读的设计说明（Markdown 正文）结合在一起，为 AI 编程代理提供持久化、结构化的视觉身份理解。

工作原理

DESIGN.md 文件包含两层：

1. YAML front matter — 以 --- 分隔的机器可读设计 token，位于文件顶部，这些是规范性值。
2. Markdown 正文 — 按 ## 章节组织的人类可读设计说明，为如何应用 token 提供上下文。

Token Schema

---
version: alpha
name: Heritage
description: "极简建筑美学与新闻级庄重感"
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

Token 类型

类型	格式	示例
Color	任何 CSS 颜色（hex, rgb(), oklch(), 命名颜色）	"#1A1C1E", "oklch(62% 0.18 250)"
Dimension	数字 + 单位（px, em, rem）	48px, -0.02em
Token Reference	{path.to.token}	{colors.primary}
Typography	包含 fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation 的对象	—

组件 Token

组件将名称映射到一组子 token 属性，确保组件样式一致性：

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

有效的组件属性：backgroundColor, textColor, typography, rounded, padding, size, height, width。

变体（hover, active, pressed）通过相关的键名表示为单独的组件条目。

章节结构

每个 DESIGN.md 遵循以下规范顺序。章节可以省略，但出现的章节必须按此顺序排列：

1. Overview（别名："Brand & Style"）—— 产品外观和感觉的整体描述
2. Colors —— 调色板及其语义角色
3. Typography —— 字体家族、字号梯度和使用方式
4. Layout（别名："Layout & Spacing"）—— 网格系统、间距梯度和容器原则
5. Elevation & Depth（别名："Elevation"）—— 阴影、层次和视觉层级
6. Shapes —— 圆角半径和形态语言
7. Components —— 各组件样式指南
8. Do's and Don'ts —— 护栏和常见陷阱

CLI 工具

npm install @google/design.md

Lint — 验证 DESIGN.md 文件

npx @google/design.md lint DESIGN.md

如果发现错误则返回退出码 1，否则返回 0。输出结构化 JSON（包含损坏的引用、缺失 token、对比度等检查结果）。

Diff — 比较两个 DESIGN.md 文件

npx @google/design.md diff DESIGN.md DESIGN-v2.md

报告 token 级别的变更（新增、移除、修改）并检测回归。

Export — 转换 token 为其他格式

# Tailwind v3 配置（JSON）
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json

# Tailwind v4 主题（CSS）
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

# W3C Design Tokens Format Module
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

Spec — 输出格式规范

npx @google/design.md spec               # 完整规范（Markdown）
npx @google/design.md spec --rules       # 规范 + lint 规则
npx @google/design.md spec --rules-only --format json  # 规则 JSON（用于 agent prompt）

Lint 规则

规则	严重级别	检查内容
broken-ref	error	Token 引用未解析到任何已定义 token
missing-primary	warning	定义了颜色但没有 primary 颜色
contrast-ratio	warning	组件颜色对比度低于 WCAG AA（4.5:1）
orphaned-tokens	warning	颜色 token 已定义但未被任何组件引用
missing-typography	warning	定义了颜色但没有排版 token
section-order	warning	章节顺序不符合规范
unknown-key	warning	顶级 key 看起来像是已知 key 的拼写错误
missing-sections	info	存在其他 token 时缺少可选章节
token-summary	info	各章节定义的 token 数量摘要

编程 API

import { lint } from '@google/design.md/linter'

const report = lint(markdownString)
console.log(report.findings)       // Finding[]
console.log(report.summary)        // { errors, warnings, info }
console.log(report.designSystem)   // Parsed DesignSystemState

与 AI 代理集成

1. 生成 — 在 Google Stitch 中创建 DESIGN.md 或手动编写
2. Lint — npx @google/design.md lint DESIGN.md 验证
3. 导出 — 转换为 tailwind 配置、CSS 变量或 DTCG token
4. 使用 — 放入 Claude Code、Cursor 或任何读取上下文文件的代理

Token 互操作性

DESIGN.md token 灵感来自 W3C Design Token Format。支持导出：

• Tailwind v3 — theme.extend JSON 对象
• Tailwind v4 — CSS @theme 块，使用 --color-*、--font-*、--text-*、--radius-*、--spacing-* 命名空间
• DTCG — W3C Design Tokens Format Module JSON

状态

DESIGN.md 格式当前处于 alpha 版本。规范、token schema 和 CLI 正在积极开发中。

链接

• 规范文档
• GitHub 仓库
• Google Stitch