design-md

DESIGN.md 技能

DESIGN.md 是 Google 的开放规范（Apache-2.0，google-labs-code/design.md），用于 向编码 Agent 描述视觉标识。一个文件结合了：

• YAML 前置元数据 — 机器可读的设计令牌（规范值）
• Markdown 正文 — 人类可读的设计依据，按规范章节组织

令牌提供精确值。说明文本告诉 Agent 为什么这些值存在，以及如何 应用它们。CLI（npx @google/design.md）会检查结构和 WCAG 对比度， 比较版本以发现回归问题，并导出为 Tailwind 或 W3C DTCG JSON。

何时使用此技能

• 用户要求提供 DESIGN.md 文件、设计令牌或设计系统规范
• 用户希望在多个项目或工具中保持一致的 UI / 品牌
• 用户粘贴现有的 DESIGN.md，并要求检查、比较差异、导出或扩展
• 用户希望将风格指南移植为 Agent 可使用的格式
• 用户希望对其颜色调色板进行对比度 / WCAG 无障碍验证

对于纯视觉灵感或布局示例，请改用 popular-web-designs。从头设计一次性 HTML 成品时，若注重流程与审美 （原型、演示文稿、落地页、组件实验室），请使用 claude-design。此技能用于正式规范文件本身。

文件结构

---
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...

令牌类型

类型	格式	示例
颜色	任意 CSS 颜色（十六进制、rgb()、oklch()、命名颜色）	"#1A1C1E"、"oklch(62% 0.18 250)"
尺寸	数字 + 单位（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。变体（悬停、激活、 按下）是独立的组件条目，并使用相关键名 （button-primary-hover），而不是嵌套形式。

规范章节顺序

各章节均为可选，但已存在的章节应按此顺序出现。该 检查器会标记顺序错误的章节（section-order，警告）和重复 标题——根据规范，读取方会拒绝重复项，因此返回文件前应 将两类问题都修复。

1. 概述（别名：品牌与风格）
2. 颜色
3. 排版
4. 布局（别名：布局与间距）
5. 高度与深度（别名：高度）
6. 形状
7. 组件
8. 应该做与不应该做

未知章节会被保留，而不会报错。只要值类型有效，未知令牌名称 也会被接受。未知组件属性会产生警告。

工作流：编写新的 DESIGN.md

1. 询问用户（或推断）品牌基调、强调色和排版 方向。如果用户提供了网站、图片或风格感觉，请将其转化 为上述令牌结构。
2. 编写 DESIGN.md，使用 write_file 将其放在用户项目根目录中。始终 包含 name: 和 colors:；其他章节为可选项，但建议加入。
3. 使用令牌引用（{colors.primary}），而不是在 components: 章节中重新输入十六进制值。这样可以让调色板保持单一来源。
4. 检查它（见下文）。返回前修复所有无效引用或 WCAG 问题。
5. 如果用户已有项目，还应在文件旁写入 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 v3 theme JSON (`tailwind` is a back-compat alias)
npx -y @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json

# Export to a Tailwind v4 CSS @theme block (--color-*, --text-*, --radius-*, ...)
npx -y @google/design.md export --format css-tailwind DESIGN.md > theme.css

# 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

所有命令都接受 - 作为标准输入。出现错误时，lint 返回退出码 1（仅有警告时返回 0）。无论源文件中的 lint 发现结果如何，成功导出后 export 都会退出 0——请单独运行 lint， 以决定是否放行。默认输出为 JSON；如果需要以结构化方式 报告发现的问题，请解析输出。

在 Windows 上，design.md 的可执行文件名称可能与 .md 文件 关联发生冲突（静默无操作或文件会在编辑器中打开）。请使用不含点号的 别名：npx -y -p @google/design.md designmd lint DESIGN.md。

Lint 规则参考（截至 CLI 0.3.0，共 9 条规则）

• broken-ref（错误）——{colors.missing} 指向不存在的令牌
• contrast-ratio（警告）——组件 textColor 与 backgroundColor 的对比度低于 WCAG AA（4.5:1）
• missing-primary（警告）——已定义颜色，但没有 primary 令牌
• missing-typography（警告）——已定义颜色，但没有排版令牌
• orphaned-tokens（警告）——从未被组件引用的颜色令牌
• section-order（警告）——章节顺序与规范顺序不符
• unknown-key（警告）——看起来像是某个模式键拼写错误的顶层 YAML 键 （colours: → colors:）；自定义扩展键不会触发报告
• token-summary、missing-sections（信息）——计数和缺失的可选 章节

当用户关注无障碍功能时，请在摘要中明确指出这一点 ——WCAG 检查结果是使用 CLI 的最主要依据。

常见陷阱

• 不要嵌套组件变体。 button-primary.hover 是错误的； 将 button-primary-hover 作为同级键才是正确的。
• 十六进制颜色值必须使用带引号的字符串。 否则 YAML 会因 # 而报错，或 以异常方式截断 #1A1C1E 之类的值。
• 负数尺寸也需要引号。 letterSpacing: -0.02em 会被解析为 YAML 流——请写成 letterSpacing: "-0.02em"。
• 即使检查器只发出警告，章节顺序仍然很重要。 如果用户 以随机顺序提供文本，请按规范列表重新排序， 然后再保存——符合规范的消费者要求采用此顺序。
• 排版子属性的拼写错误会被静默丢弃。 截至 CLI 0.3.0， fontwight: 之类的拼写错误不会产生检查结果，且该值会从 导出结果中消失——请对照模式核对子属性名称 （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。