design-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DESIGN.md Skill

DESIGN.md 技能

DESIGN.md is Google's open spec (Apache-2.0,

google-labs-code/design.md

) for describing a visual identity to coding agents. One file combines:

YAML front matter — machine-readable design tokens (normative values)
Markdown body — human-readable rationale, organized into canonical sections

Tokens give exact values. Prose tells agents why those values exist and how to apply them. The CLI (

npx @google/design.md

) lints structure + WCAG contrast, diffs versions for regressions, and exports to Tailwind or W3C DTCG JSON.

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格式。

When to use this skill

何时使用此技能

User asks for a DESIGN.md file, design tokens, or a design system spec
User wants consistent UI/brand across multiple projects or tools
User pastes an existing DESIGN.md and asks to lint, diff, export, or extend it
User asks to port a style guide into a format agents can consume
User wants contrast / WCAG accessibility validation on their color palette

For purely visual inspiration or layout examples, use

popular-web-designs

instead. For process and taste when designing a one-off HTML artifact from scratch (prototype, deck, landing page, component lab), use

claude-design

. This skill is for the formal spec file itself.

用户请求DESIGN.md文件、设计令牌或设计系统规范
用户希望在多个项目或工具中保持UI/品牌一致性
用户粘贴现有DESIGN.md文件，要求进行检查、对比差异、导出或扩展
用户请求将样式指南转换为Agent可识别的格式
用户希望对其调色板进行对比度/WCAG可访问性验证

如果仅需要视觉灵感或布局示例，请改用

popular-web-designs

技能。如果是从零开始设计一次性HTML制品（原型、演示文稿、着陆页、组件实验室）时需要流程和风格建议，请使用

claude-design

技能。本技能专门用于处理正式规范文件本身。

File anatomy

文件结构

---
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}"
---

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

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

undefined

button-primary

is the only high-emphasis action on a page...

undefined

Token types

令牌类型

Type	Format	Example
Color	`#` + hex (sRGB)	`"#1A1C1E"`
Dimension	number + unit ( `px` , `em` , `rem` )	`48px` , `-0.02em`
Token reference	`{path.to.token}`	`{colors.primary}`
Typography	object with `fontFamily` , `fontSize` , `fontWeight` , `lineHeight` , `letterSpacing` , `fontFeature` , `fontVariation`	see above

Component property whitelist:

backgroundColor

textColor

typography

rounded

padding

size

height

width

. Variants (hover, active, pressed) are separate component entries with related key names (

button-primary-hover

), not nested.

类型	格式	示例
颜色	`#` + 十六进制（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

），而非嵌套结构。

Canonical section order

规范章节顺序

Sections are optional, but present ones MUST appear in this order. Duplicate headings reject the file.

Overview (alias: Brand & Style)
Colors
Typography
Layout (alias: Layout & Spacing)
Elevation & Depth (alias: Elevation)
Shapes
Components
Do's and Don'ts

Unknown sections are preserved, not errored. Unknown token names are accepted if the value type is valid. Unknown component properties produce a warning.

章节为可选，但如果存在必须按照以下顺序排列。重复的标题会导致文件被拒绝。

Overview（别名：Brand & Style）
Colors
Typography
Layout（别名：Layout & Spacing）
Elevation & Depth（别名：Elevation）
Shapes
Components
Do's and Don'ts

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

Workflow: authoring a new DESIGN.md

工作流：编写新的DESIGN.md

Ask the user (or infer) the brand tone, accent color, and typography direction. If they provided a site, image, or vibe, translate it to the token shape above.
Write
DESIGN.md
in their project root using
```
write_file
```
. Always include
```
name:
```
and
```
colors:
```
; other sections optional but encouraged.
Use token references (
```
{colors.primary}
```
) in the
```
components:
```
section instead of re-typing hex values. Keeps the palette single-source.
Lint it (see below). Fix any broken references or WCAG failures before returning.
If the user has an existing project, also write Tailwind or DTCG exports next to the file (
```
tailwind.theme.json
```
,
```
tokens.json
```
).

询问用户（或推断）品牌基调、强调色和排版方向。如果用户提供了网站、图片或风格参考，将其转换为上述令牌结构。
**编写
```
DESIGN.md
```
**文件到项目根目录，使用
```
write_file
```
工具。务必包含
```
name:
```
和
```
colors:
```
字段；其他章节为可选，但建议添加。
使用令牌引用（如
```
{colors.primary}
```
）替代重复输入十六进制值，保持调色板单一数据源。
检查文件（见下文）。在返回结果前修复所有无效引用或WCAG失败问题。
如果用户已有项目，同时将文件导出为Tailwind或DTCG格式，保存到文件旁（
```
tailwind.theme.json
```
、
```
tokens.json
```
）。

Workflow: lint / diff / export

工作流：检查/对比差异/导出

The CLI is

@google/design.md

(Node). Use

npx

— no global install needed.

bash

undefined

CLI工具为

@google/design.md

（基于Node.js）。使用

npx

无需全局安装。

bash

undefined

Validate structure + token references + WCAG contrast

验证结构 + 令牌引用 + WCAG对比度

npx -y @google/design.md lint DESIGN.md

Compare two versions, fail on regression (exit 1 = regression)

对比两个版本，发现回归则失败（退出码1表示存在回归）

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

Export to Tailwind theme JSON

导出为Tailwind主题JSON

npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

Export to W3C DTCG (Design Tokens Format Module) JSON

导出为W3C DTCG（设计令牌格式模块）JSON

npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json

Print the spec itself — useful when injecting into an agent prompt

打印规范本身——注入到Agent提示词时非常有用

npx -y @google/design.md spec --rules-only --format json


All commands accept `-` for stdin. `lint` returns exit 1 on errors. Use the
`--format json` flag and parse the output if you need to report findings
structurally.

npx -y @google/design.md spec --rules-only --format json


所有命令接受`-`作为标准输入。`lint`命令在出错时返回退出码1。如果需要结构化报告结果，可使用`--format json`标志并解析输出内容。

Lint rule reference (what the 7 rules catch)

检查规则参考（7条规则的检测内容）

```
broken-ref
```
(error) —
```
{colors.missing}
```
points at a non-existent token
```
duplicate-section
```
(error) — same
```
## Heading
```
appears twice

invalid-color

invalid-dimension

invalid-typography

(error)

```
wcag-contrast
```
(warning/info) — component
```
textColor
```
vs
```
backgroundColor
```
ratio against WCAG AA (4.5:1) and AAA (7:1)
```
unknown-component-property
```
(warning) — outside the whitelist above

When the user cares about accessibility, call this out explicitly in your summary — WCAG findings are the most load-bearing reason to use the CLI.

```
broken-ref
```
（错误）——
```
{colors.missing}
```
指向不存在的令牌
```
duplicate-section
```
（错误）——同一个
```
## 标题
```
出现多次

invalid-color

、

invalid-dimension

、

invalid-typography

（错误）

```
wcag-contrast
```
（警告/信息）——组件
```
textColor
```
与
```
backgroundColor
```
的比率是否符合WCAG AA（4.5:1）和AAA（7:1）标准
```
unknown-component-property
```
（警告）——属性不在上述白名单内

当用户关注可访问性时，在总结中明确指出这一点——WCAG检测结果是使用此CLI工具最核心的原因之一。

Pitfalls

注意事项

Don't nest component variants.
```
button-primary.hover
```
is wrong;
```
button-primary-hover
```
as a sibling key is right.
Hex colors must be quoted strings. YAML will otherwise choke on
```
#
```
or truncate values like
```
#1A1C1E
```
oddly.
Negative dimensions need quotes too.
```
letterSpacing: -0.02em
```
parses as a YAML flow — write
```
letterSpacing: "-0.02em"
```
.
Section order is enforced. If the user gives you prose in a random order, reorder it to match the canonical list before saving.
version: alpha
is the current spec version (as of Apr 2026). The spec is marked alpha — watch for breaking changes.
Token references resolve by dotted path.
```
{colors.primary}
```
works;
```
{primary}
```
does not.

不要嵌套组件变体。
```
button-primary.hover
```
是错误写法；
```
button-primary-hover
```
作为同级键才是正确的。
十六进制颜色必须用引号包裹。否则YAML会解析
```
#
```
时出错，或错误截断
```
#1A1C1E
```
这类值。
负尺寸也需要引号。
```
letterSpacing: -0.02em
```
会被解析为YAML流——应写成
```
letterSpacing: "-0.02em"
```
。
章节顺序是强制要求的。如果用户提供的说明性文字顺序混乱，保存前需调整为规范列表中的顺序。
version: alpha
是当前规范版本（截至2026年4月）。该规范处于alpha阶段——注意可能存在破坏性变更。
令牌引用通过点路径解析。
```
{colors.primary}
```
有效；
```
{primary}
```
无效。

Spec source of truth

规范权威来源

Repo: https://github.com/google-labs-code/design.md (Apache-2.0)
CLI:
```
@google/design.md
```
on npm
License of generated DESIGN.md files: whatever the user's project uses; the spec itself is Apache-2.0.

仓库：https://github.com/google-labs-code/design.md（Apache-2.0协议）
CLI工具：npm上的
```
@google/design.md
```
生成的DESIGN.md文件许可：遵循用户项目的许可；规范本身采用Apache-2.0协议。