DESIGN.md 规范
编写/验证/导出 Google DESIGN.md 令牌规范
DESIGN.md Skill
DESIGN.md 是 Google 的开放规范（Apache-2.0，google-labs-code/design.md），用于
向编码代理描述视觉标识。单个文件同时包含：
YAML front matter——机器可读的设计令牌（规范化值）
Markdown 正文——人类可读的设计依据，按规范章节组织
令牌提供精确数值。文字说明则告诉代理这些值*为什么*存在以及如何
应用。CLI（npx @google/design.md）可校验结构和 WCAG 对比度、
对比版本差异以发现回归，并导出为 Tailwind 或 W3C DTCG JSON。
使用场景
用户要求生成 DESIGN.md 文件、设计令牌（design tokens）或设计系统规范
用户希望多个项目或工具之间保持一致的 UI/品牌风格
用户粘贴已有的 DESIGN.md，要求进行 lint、diff、导出或扩展
用户要求把样式指南移植为代理可消费的格式
用户希望对自己的调色板进行对比度 / WCAG 无障碍验证
如果只是想要纯粹的视觉灵感或布局示例，请改用 popular-web-designs。
若是在从零设计一次性 HTML 产物（原型、演示文稿、落地页、组件实验场）
时需要*流程与品味*方面的指导，请使用
claude-design。本 skill 面向的是*正式规范文件*本身。
文件结构
---
version: alpha
name: Heritage
description: Architectural minimalism meets journalistic gravitas.
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
fontWeight: 700
lineHeight: 1.1
letterSpacing: "-0.02em"
body-md:
fontFamily: Public Sans
fontSize: 1rem
rounded:
sm: 4px
md: 8px
lg: 16px
spacing:
sm: 8px
md: 16px
lg: 24px
components:
button-primary:
backgroundColor: "{colors.tertiary}"
textColor: "#FFFFFF"
rounded: "{rounded.sm}"
padding: 12px
button-primary-hover:
backgroundColor: "{colors.primary}"
---
## Overview
Architectural Minimalism meets Journalistic Gravitas...
## Colors
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
## Typography
Public Sans for everything except small all-caps labels...
## Components
`button-primary` is the only high-emphasis action on a page...
令牌类型
| 类型 | 格式 | 示例 |
| 颜色 | `#` + hex（sRGB） | `"#1A1C1E"` |
| 尺寸 | 数字 + 单位（`px`、`em`、`rem`） | `48px`、`-0.02em` |
| 令牌引用 | `{path.to.token}` | `{colors.primary}` |
| 排版 | 包含 `fontFamily`、`fontSize`、`fontWeight`、`lineHeight`、`letterSpacing`、`fontFeature`、`fontVariation` 的对象 | 见上文 |
组件属性白名单：backgroundColor、textColor、typography、
rounded、padding、size、height、width。变体（hover、active、
pressed）是独立的组件条目，使用相互关联的键名
（button-primary-hover），而非嵌套。
规范章节顺序
章节均为可选，但已存在的章节必须按以下顺序出现。出现重复的
标题会导致文件被拒绝。
Overview（别名：Brand & Style）
Colors
Typography
Layout（别名：Layout & Spacing）
Elevation & Depth（别名：Elevation）
Shapes
Components
Do's and Don'ts
未知章节会被保留而不是报错。只要值类型有效，未知令牌名也会被
接受。未知的组件属性会产生警告。
工作流程：编写新的 DESIGN.md
询问用户（或自行推断）品牌基调、强调色和排版
方向。如果用户提供了网站、图片或整体感觉，将其转换为上文
所示的令牌结构。
编写 DESIGN.md，使用 write_file 写入用户的项目根目录。务必包含
name: 和 colors:；其他章节可选但建议提供。
使用令牌引用（{colors.primary}）填写 components: 章节，
而不是重复输入十六进制值，以保持调色板单一来源。
进行 lint 校验（见下文）。在返回之前修复所有
失效引用或 WCAG 不达标项。
如果用户已有现成项目，还要在该文件旁边写入 Tailwind 或 DTCG
导出文件（tailwind.theme.json、tokens.json）。
工作流程：lint / diff / export
CLI 为 @google/design.md（Node 包）。使用 npx 即可，无需全局安装。
# Validate structure + token references + WCAG contrast
npx -y @google/design.md lint DESIGN.md
# Compare two versions, fail on regression (exit 1 = regression)
npx -y @google/design.md diff DESIGN.md DESIGN-v2.md
# Export to Tailwind theme JSON
npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
# Export to W3C DTCG (Design Tokens Format Module) JSON
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
# Print the spec itself — useful when injecting into an agent prompt
npx -y @google/design.md spec --rules-only --format json
所有命令都支持 - 表示 stdin。lint 在出错时返回退出码 1。如需以
结构化方式报告检查结果，可使用 --format json 标志
并解析其输出。
Lint 规则参考（7 条规则分别能捕获什么）
broken-ref（错误）——{colors.missing} 指向不存在的令牌
duplicate-section（错误）——同一个 ## Heading 出现两次
invalid-color、invalid-dimension、invalid-typography（错误）
wcag-contrast（警告/提示）——组件 textColor 与 backgroundColor
的对比率依据 WCAG AA（4.5:1）和 AAA（7:1）评估
unknown-component-property（警告）——不在上述白名单之内
当用户关注无障碍性时，请在总结中明确指出——WCAG 检查结果
是使用该 CLI 最关键的理由。
注意事项
不要嵌套组件变体。button-primary.hover 是错误的；
button-primary-hover 作为同级键才是正确的。
十六进制颜色必须是带引号的字符串。否则 YAML 会因 # 报错，
或把 #1A1C1E 这样的值奇怪地截断。
负值尺寸同样需要加引号。letterSpacing: -0.02em 会被解析为 YAML flow——
应写作 letterSpacing: "-0.02em"。
章节顺序是强制性的。如果用户提供的文字顺序混乱，
保存前请按规范列表重新排序。
version: alpha 是当前的规范版本（截至 2026 年 4 月）。该规范
仍处于 alpha 阶段——请留意破坏性变更。
令牌引用按点分路径解析。{colors.primary} 有效；
{primary} 无效。
规范权威来源
仓库：https://github.com/google-labs-code/design.md（Apache-2.0）
CLI：npm 上的 @google/design.md
生成的 DESIGN.md 文件许可证：遵循用户项目所用的许可证；
规范本身为 Apache-2.0。
