用途
DESIGN.md 是 Google 的开放规范（Apache-2.0，仓库 google-labs-code/design.md），用于向编码智能体描述一套视觉识别系统。一个文件同时包含两类内容：YAML front matter 中的机器可读设计令牌（规范性数值），以及 Markdown 正文中的人类可读理由，并按规范章节组织。令牌给出精确值，正文则告诉智能体这些值为何存在、应如何应用。
何时使用
- 用户要求生成 DESIGN.md 文件、设计令牌或设计系统规范
- 用户希望在多个项目或工具之间保持一致的 UI/品牌
- 用户粘贴了已有的 DESIGN.md，要求 lint、diff、导出或扩展
- 用户希望把样式指南移植为智能体可消费的格式
- 用户希望对配色进行对比度 / WCAG 无障碍验证
如果只是需要纯视觉灵感或布局示例，应改用 popular-web-designs；如果是从零设计一次性 HTML 产物（原型、幻灯片、落地页、组件实验室）所需的流程与品味，应改用 claude-design。本技能针对的是正式的规范文件本身。
文件结构
文件由 YAML front matter 与 Markdown 正文组成。front matter 示例包含 version、name、description、colors、typography、rounded、spacing、components 等字段；正文按 Overview、Colors、Typography、Components 等章节展开说明。
令牌类型包括：
- 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 的对象
组件属性白名单：backgroundColor、textColor、typography、rounded、padding、size、height、width。变体（hover、active、pressed）应作为独立组件条目，使用相关键名（如 button-primary-hover），而不是嵌套。
规范章节顺序
章节均为可选，但存在的章节应按以下顺序出现。linter 会对乱序章节报 section-order 警告，并标记重复标题——按规范，消费者会拒绝重复标题，因此返回文件前应同时修复这两类问题。
- Overview（别名：Brand & Style）
- Colors
- Typography
- Layout（别名：Layout & Spacing）
- Elevation & Depth（别名：Elevation）
- Shapes
- Components
- Do's and Don'ts
未知章节会被保留而非报错。未知令牌名只要值类型有效即可接受。未知组件属性会产生警告。
工作流：编写新的 DESIGN.md
- 询问用户（或推断）品牌调性、强调色与排版方向。如果用户提供了网站、图片或氛围描述，将其转换为上述令牌形态。
- 使用 write_file 在项目根目录写入 DESIGN.md。始终包含 name: 与 colors:；其他章节可选但建议包含。
- 在 components: 章节中使用令牌引用（{colors.primary}），而不是重复书写 hex 值，以保持调色板单一来源。
- 执行 lint（见下）。返回前修复所有断开的引用或 WCAG 失败项。
- 如果用户已有项目，同时在文件旁写入 Tailwind 或 DTCG 导出（tailwind.theme.json、tokens.json）。
工作流：lint / diff / export
CLI 为 @google/design.md（Node）。使用 npx，无需全局安装。
# 校验结构 + 令牌引用 + WCAG 对比度
npx -y @google/design.md lint DESIGN.md
# 比较两个版本，出现回归则失败（exit 1 = 回归）
npx -y @google/design.md diff DESIGN.md DESIGN-v2.md
# 导出为 Tailwind v3 主题 JSON（`tailwind` 为向后兼容别名）
npx -y @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
# 导出为 Tailwind v4 CSS @theme 块（--color-*、--text-*、--radius-* 等）
npx -y @google/design.md export --format css-tailwind DESIGN.md > theme.css
# 导出为 W3C DTCG（Design Tokens Format Module）JSON
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
# 打印规范本身——在注入智能体提示时有用
npx -y @google/design.md spec --rules-only --format json
所有命令都接受 - 作为 stdin。lint 在出现错误时返回 exit 1（仅有警告时 exit 0）。export 只要导出成功就返回 exit 0，无论源文件是否有 lint 发现——如需据此把关，请单独运行 lint。输出默认是 JSON；如需结构化报告发现项，可解析它。
在 Windows 上，design.md 这个 bin 名称可能与 .md 文件关联冲突（静默无操作或文件在编辑器中打开）。请使用无点别名：npx -y -p @google/design.md designmd lint DESIGN.md。
Lint 规则参考（CLI 0.3.0 的 9 条规则）
- broken-ref（error）——{colors.missing} 指向不存在的令牌
- contrast-ratio（warning）——组件 textColor 与 backgroundColor 低于 WCAG AA（4.5:1）
- missing-primary（warning）——定义了颜色但没有 primary 令牌
- missing-typography（warning）——定义了颜色但没有排版令牌
- orphaned-tokens（warning）——颜色令牌从未被任何组件引用
- section-order（warning）——章节顺序不符合规范
- unknown-key（warning）——顶层 YAML 键疑似 schema 键的拼写错误（colours: → colors:）；自定义扩展键保持静默
- token-summary、missing-sections（info）——计数与缺失的可选章节
当用户关注无障碍时，请在总结中明确说明——WCAG 发现项是使用该 CLI 最有力的理由。
常见陷阱
- 不要嵌套组件变体。button-primary.hover 是错的；button-primary-hover 作为同级键才是对的。
- Hex 颜色必须是带引号的字符串。否则 YAML 会因 # 出错，或对 #1A1C1E 这类值产生异常截断。
- 负尺寸也需要引号。letterSpacing: -0.02em 会被解析为 YAML flow——应写成 letterSpacing: "-0.02em"。
- 章节顺序很重要，即使 linter 只给警告。如果用户给的正文顺序混乱，保存前请按规范列表重排——符合规范的消费者会期望该顺序。
- 排版子属性拼写错误会被静默丢弃。在 CLI 0.3.0 中，像 fontwight: 这样的拼写错误不会产生任何发现，且该值会从导出中消失——请对照 schema 仔细检查子属性名（fontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation）。
- version: alpha 是当前规范版本（截至 2026 年 7 月，CLI 0.3.0）。该规范标记为 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。