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: - **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. ## 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. ## File anatomy ```md --- 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 | 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. ## Canonical section order Sections are optional, but present ones MUST appear in this order. Duplicate headings reject the file. 1. Overview (alias: Brand & Style) 2. Colors 3. Typography 4. Layout (alias: Layout & Spacing) 5. Elevation & Depth (alias: Elevation) 6. Shapes 7. Components 8. 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. ## Workflow: authoring a new DESIGN.md 1. **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. 2. **Write `DESIGN.md`** in their project root using `write_file`. Always include `name:` and `colors:`; other sections optional but encouraged. 3. **Use token references** (`{colors.primary}`) in the `components:` section instead of re-typing hex values. Keeps the palette single-source. 4. **Lint it** (see below). Fix any broken references or WCAG failures before returning. 5. **If the user has an existing project**, also write Tailwind or DTCG exports next to the file (`tailwind.theme.json`, `tokens.json`). ## Workflow: lint / diff / export The CLI is `@google/design.md` (Node). Use `npx` — no global install needed. ```bash # 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) - `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. ## Workflow: refactoring existing HTML to a design system When the user asks to refactor an existing HTML page to match a design system (e.g., "refactor to Apple style", "make it look like Stripe"): 1. **Fetch the reference DESIGN.md** from GitHub's awesome-design-md repo: ```bash curl -s https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/<brand>/DESIGN.md ``` Available brands: apple, stripe, linear, vercel, airbnb, bmw, etc. 2. **Extract the design tokens** — identify: colors, typography, spacing, components, and the "Do's and Don'ts" section. 3. **For large HTML files (>1000 lines)**, extract the JavaScript/data section first: ```bash # Find where <script> starts grep -n '<script>' file.html | tail -1 # Extract from that line to end sed -n 'N,99999p' file.html > /tmp/script_section.js ``` This avoids memory issues when rewriting. 4. **Write the new HTML** with the design system applied: - CSS variables for all design tokens - Google Fonts link for the system's font family (e.g., Inter for Apple) - Component classes matching the DESIGN.md components - Preserve all `<script>` content verbatim 5. **Deploy** — the project-specific deployment flow (see world-cup skills for the actual commands). ### Pitfalls for refactoring - **Don't try to read the entire large file at once.** `read_file` on a 3000-line HTML file returns a truncated result. Use `terminal` with `sed -n 'start,endp'` to extract sections. - **Preserve JavaScript data verbatim.** The script section contains model data, team data, and round predictions — never modify these during a UI refactor. - **Test deployment immediately.** After writing the file, deploy and verify with `curl -s -I http://localhost:port/` before committing. - **The reference DESIGN.md is a spec, not a template.** Don't copy it verbatim into the project — create a project-specific DESIGN.md that adapts the tokens to the actual content. ## 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. ## 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. - **Apple Design System reference**: `references/apple-design-system.md` — quick reference for the most commonly requested brand style (colors, typography, components, responsive breakpoints). the spec itself is Apache-2.0.