Design Md

DESIGN.md Skill

DESIGN.md is a format spec from Google Labs (github.com/google-labs-code/design.md) that combines YAML frontmatter (machine-readable design tokens) with markdown prose (human-readable rationale). Coding agents that read a project's DESIGN.md produce UI that matches the defined visual identity.

This skill handles the full lifecycle: generating a DESIGN.md from a user brief, validating it, keeping it in sync when tokens change, and exporting to downstream formats (Tailwind, DTCG).

When to use this skill

• User asks to create a design system, design tokens file, or DESIGN.md for a project.
• User describes a visual aesthetic and wants Claude to codify it before building UI ("I want a brutalist dark dev-tool look with lime accents").
• User asks to lint, diff, or export an existing DESIGN.md.
• User is about to build frontend UI in a project that already has a DESIGN.md — read it first and honor the tokens.

If the user just wants one-off CSS styling with no reusable system, skip this skill.

CLI

Canonical tool is the @google/design.md npm package. Prefer npx so you always get the latest spec version:

npx @google/design.md lint DESIGN.md               # validate structure + WCAG contrast
npx @google/design.md diff DESIGN.md DESIGN-v2.md  # token-level + prose regression diff
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format dtcg DESIGN.md > tokens.json
npx @google/design.md spec                         # authoritative spec text
npx @google/design.md spec --rules                 # spec + linting rules

All commands accept a file path or - for stdin. Default output is JSON. lint exits 1 on errors; diff exits 1 on regressions.

Workflow: creating a new DESIGN.md

1. Detect project state. Before drafting, check whether the project already has UI:

• Look for component dirs (src/components/, app/, pages/, components/), CSS/SCSS files, Tailwind config, or a global stylesheet.
• If found, this is an existing-UI project — apply the review gate in step 6 before propagating tokens to code.
• If no UI yet (greenfield), you can chain straight into UI generation after lint passes.

1. Gather the brief. Ask the user (or infer) — missing info is fine, propose values:

• Name of the design system (e.g., "Heritage", "Nightshade").
• Aesthetic / vibe / references (magazines, brands, sites they like).
• Primary, secondary, tertiary, and neutral colors — or propose from the vibe.
• Type pairing (display + body font). Propose Google Fonts pairings if unsure.
• Density preference (tight / comfortable / spacious) to inform spacing scale.

1. Draft frontmatter with the required token groups. Minimum: name, colors, typography, spacing. Add rounded, components if the system needs them.
2. Write prose sections in this exact order (omit any you don't need, but do not reorder):
3. Overview (alias: "Brand & Style")
4. Colors
5. Typography
6. Layout (alias: "Layout & Spacing")
7. Elevation & Depth (alias: "Elevation")
8. Shapes
9. Components
10. Do's and Don'ts
11. Save as DESIGN.md at the project root and lint it: npx @google/design.md lint DESIGN.md. Fix errors and warnings (bad token refs, WCAG contrast fails), re-lint until clean.
12. Review gate (mandatory for existing-UI projects). Even if the user's prompt chained "then apply the tokens to the UI," stop here and surface the linted DESIGN.md to the user before editing any UI files. Output something like:

> Drafted DESIGN.md (linted clean). Before I apply these tokens across [N] component files, please confirm: (1) palette looks right, (2) type pairing is what you wanted, (3) scope of UI changes — global styles only, or component-by-component?

Wait for confirmation. Reason: tokens are upstream of every UI file — a wrong accent color silently fans out into dozens of edits that are expensive to revert. For greenfield projects with no existing UI, skip the gate and proceed.

1. Wire Claude Code to it. Ask the user first, then append to the project's CLAUDE.md:

`` ## Design system All UI work must honor the tokens and guidance in ./DESIGN.md. Before adding new tokens, run npx @google/design.md lint DESIGN.md. ``

Workflow: using an existing DESIGN.md

When building UI in a project that has a DESIGN.md:

1. Read DESIGN.md first. Treat its tokens as authoritative — never substitute hardcoded colors, fonts, or spacing values.
2. Reference tokens by name where the downstream stack supports it (CSS variables, Tailwind theme, DTCG). Export with npx @google/design.md export --format tailwind if the project uses Tailwind and has no existing theme file.
3. When adding a new component, follow the existing component-naming convention (button-primary, button-primary-hover). Variants (hover, active, pressed) are separate component entries, not nested.
4. Valid component properties: backgroundColor, textColor, typography, rounded, padding, size, height, width. Anything else warns.
5. Before committing UI changes, run npx @google/design.md diff and report any regressions to the user.

Workflow: editing / evolving

• If a UI change introduces a new token, update DESIGN.md in the same commit.
• If the user asks for a new variant, extend components: with a new entry — don't mutate existing ones silently.
• After edits, lint. If the file's structure is in doubt, fetch the live spec: npx @google/design.md spec.

Spec quick reference

Frontmatter fields

version: alpha              # optional
name:               # required
description:        # optional
colors:                     # hex sRGB values
  primary: "#1A1C1E"
typography:                 # object with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:                    # dimensions
  sm: 4px
spacing:                    # dimensions or numbers
  sm: 8px
components:                 # name → sub-token map
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"

Token value types

| Type | Format | Example | |:-----|:-------|:--------| | Color | # + hex (sRGB) | "#1A1C1E" | | Dimension | number + 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 |

Consumer behavior

| Scenario | Behavior | |:---------|:---------| | Unknown section heading | Preserve, do not error | | Unknown color / typography name | Accept if value is valid | | Unknown component property | Accept with warning | | Duplicate section heading | Error — reject file |

Example brief → DESIGN.md

User brief: "Heritage — architectural, minimal, like a high-end broadsheet. Deep ink, warm limestone, one clay accent. Public Sans + Space Grotesk for labels."

Output:

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.neutral}"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview
Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors
The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.

Notes

• The description field in the frontmatter above (for this SKILL.md) is what Claude Code matches against to decide whether to load the skill. Keep it keyword-rich.
• Never embed emoji in DESIGN.md content (user's global rule: always SVG icons over emoji).
• If npx @google/design.md can't be reached (offline), fall back to the spec in this file, but warn the user that live linting is skipped.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ericxyz86
• Source: ericxyz86/claude-skill-design-md
• License: MIT

Install and usage instructions live in the source repository linked above.