design-md

name design-md description Author/validate/export Google's DESIGN.md token spec files. version 1.1.0 author Hermes Agent license MIT platforms ["linux","macos","windows"] metadata {"hermes":{"tags":["design","design-system","tokens","ui","accessibility","wcag","tailwind","dtcg","google"],"related_skills":["popular-web-designs","claude-design","excalidraw","architecture-diagram"]}} 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 Type Format Example Color any CSS color (hex, rgb() , oklch() , named) "#1A1C1E" , "oklch(62% 0.18 250)" 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 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. 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. Workflow: authoring a new 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 ). 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) broken-ref (error) — {colors.missing} points at a non-existent token contrast-ratio (warning) — component textColor vs backgroundColor below WCAG AA (4.5:1) 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 schema key ( colours: → colors: ); custom extension keys stay silent token-summary , missing-sections (info) — counts and absent optional sections 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 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 matters even though the linter only warns. If the user gives you prose in a random order, reorder it to match the canonical list before saving — spec-compliant consumers expect it. Typography sub-property typos are silently dropped. As of CLI 0.3.0 a 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 ). version: alpha is the current spec version (as of Jul 2026, CLI 0.3.0). 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.