design-md skill

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

---
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 should appear in this order. The linter flags out-of-order sections (section-order, warning) and duplicate headings — consumers per the spec reject duplicates, so fix both before returning 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

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

1. Ask the user (or infer) the brand tone, accent color, and typography

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

1. Write DESIGN.md in their project root using write_file. Always

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

1. Use token references ({colors.primary}) in the components: section

before returning.

1. Lint it (see below). Fix any broken references or WCAG failures

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

1. If the user has an existing project, also write Tailwind or DTCG

Workflow: 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 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

All commands accept - for stdin. lint returns exit 1 on errors (warnings alone exit 0). export exits 0 on a successful export regardless of lint findings in the source — run lint separately to gate on those. Output is JSON by default; parse it if you need to report findings structurally.

On Windows, the design.md bin name can collide with the .md file association (silent no-op or the file opens in an editor). Use the dot-free alias: npx -y -p @google/design.md designmd lint DESIGN.md.

Lint rule reference (the 9 rules, as of CLI 0.3.0)

below WCAG AA (4.5:1)

• broken-ref (error) — {colors.missing} points at a non-existent token
• contrast-ratio (warning) — component textColor vs backgroundColor

schema key (colours: → colors:); custom extension keys stay silent

• missing-primary (warning) — colors defined but no primary token
• missing-typography (warning) — colors defined but no typography tokens
• orphaned-tokens (warning) — color tokens never referenced by a component
• section-order (warning) — sections out of the canonical order
• unknown-key (warning) — top-level YAML key that looks like a typo of a

sections

• token-summary, missing-sections (info) — counts and absent optional

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.

• Don't nest component variants. button-primary.hover is wrong;

truncate values like #1A1C1E oddly.

• Hex colors must be quoted strings. YAML will otherwise choke on # or

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

• Negative dimensions need quotes too. letterSpacing: -0.02em parses as

gives you prose in a random order, reorder it to match the canonical list before saving — spec-compliant consumers expect it.

• Section order matters even though the linter only warns. If the user

typo like fontwight: produces no finding and the value vanishes from exports — double-check sub-property names against the schema (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation).

• Typography sub-property typos are silently dropped. As of CLI 0.3.0 a

0.3.0). The spec is marked alpha — watch for breaking changes.

• version: alpha is the current spec version (as of Jul 2026, CLI

{primary} does not.

• Token references resolve by dotted path. {colors.primary} works;

Spec source of truth

the spec itself is Apache-2.0.

• 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;