DESIGN.md 规范

编写/验证/导出 Google DESIGN.md 令牌规范

DESIGN.md Skill

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:

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.

使用场景 this skill

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.

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

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

Token types

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.

Canonical section order

Sections are optional, but present ones MUST appear in this order. Duplicate

headings reject the file.

Unknown sections are preserved, not errored. Unknown token names are accepted

if the value type is valid. Unknown component properties produce a warning.

工作流程: authoring a new DESIGN.md

direction. If they provided a site, image, or vibe, translate it to the

token shape above.

include name: and colors:; other sections optional but encouraged.

instead of re-typing hex values. Keeps the palette single-source.

before returning.

exports next to the file (tailwind.theme.json, tokens.json).

工作流程: lint / diff / export

The CLI is @google/design.md (Node). Use npx — no global install needed.

# 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

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.

Lint rule reference (what the 7 rules catch)

ratio against WCAG AA (4.5:1) and AAA (7:1)

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.

Pitfalls

button-primary-hover as a sibling key is right.

truncate values like #1A1C1E oddly.

a YAML flow — write letterSpacing: "-0.02em".

reorder it to match the canonical list before saving.

is marked alpha — watch for breaking changes.

{primary} does not.

Spec source of truth

the spec itself is Apache-2.0.