DESIGN.md — Design System Library & Generator

DESIGN.md is a plain-text design system document in the Google Stitch 9-section format that AI agents read to generate consistent UI. It is the token layer between design intent (.design-context.md from /shape) and implementation (/minoan-frontend-design).

Three Workflows

Workflow A: Fetch a reference DESIGN.md

Use the getdesign CLI to fetch from a library of 68 brand design systems:

npx getdesign@latest add <brand>        # Drops DESIGN.md into project root
npx getdesign@latest add stripe --out ./docs/DESIGN.md  # Custom output path
npx getdesign@latest list               # Show all 68 available brands

Available brands include: airbnb, apple, claude, cursor, figma, framer, linear.app, nike, notion, shopify, spotify, stripe, supabase, tesla, vercel, and 53 more. Each is a ~350-line file with exact hex values, font stacks, component specs, shadow systems, and responsive breakpoints.

After fetching, /minoan-frontend-design reads the DESIGN.md during implementation (its QA normalize step aligns output with project DESIGN.md tokens).

Pre-fetched Library

All 68 brand DESIGN.md files can be pre-fetched into a local reference library:

bash ~/.claude/skills/design-md/scripts/fetch_all_design_md.sh         # Fetch all 68
bash ~/.claude/skills/design-md/scripts/fetch_all_design_md.sh --force # Re-fetch

The library lives at ~/.claude/skills/design-md/library/<brand>/DESIGN.md. Read any brand directly without running npx:

cat ~/.claude/skills/design-md/library/stripe/DESIGN.md

The library/ directory is gitignored — it's a local cache, not distributed with the skill.

Workflow B: Generate a custom DESIGN.md

Extract design tokens from an existing project's CSS and scaffold a DESIGN.md:

python3 ~/.claude/skills/design-md/scripts/generate_design_md.py <project-path>
python3 ~/.claude/skills/design-md/scripts/generate_design_md.py . --output DESIGN.md

The script scans for CSS files containing @theme blocks (Tailwind CSS 4), :root custom properties, font declarations, shadows, border radii, and breakpoints. It organizes extracted tokens into the 9-section format with TODO placeholders for prose sections (Visual Theme, Do's/Don'ts) that require human or Claude completion.

After generating the scaffold, fill in the prose sections using project context — the conceptual direction, the atmosphere, the design guardrails. The format spec is at references/design-md-format.md.

Workflow C: Validate and export with Google CLI

Use @google/design.md (the upstream CLI for the 9-section format) to lint, diff, and export:

npx @google/design.md lint DESIGN.md                       # 8 validation rules, JSON output
npx @google/design.md diff OLD.md NEW.md                   # Token-level diff, exits 1 on regressions
npx @google/design.md export --format tailwind DESIGN.md   # Tailwind theme JSON
npx @google/design.md export --format dtcg DESIGN.md       # W3C Design Token Format JSON

Lint after generate: Run lint after Workflow B to surface missing sections, broken refs, and contrast issues before prose completion.

Lint before handoff: Run lint before passing DESIGN.md to /minoan-frontend-design. Clean lint (exit 0) confirms structural completeness.

Export for implementation: export --format tailwind produces a theme JSON that downstream tooling can consume directly.

Diff for versioning: Compare a project's DESIGN.md against a library reference or audit changes between revisions. Exit 1 = regressions (removed tokens, broken contrast).

See references/google-cli.md for lint rule reference and exit code semantics.

The 9-Section Format

See references/design-md-format.md for the full annotated spec with examples for each section.

Pipeline Integration

/shape → .design-context.md (intent: audience, mood, anti-goals)
/design-md → DESIGN.md (tokens: hex values, font stacks, shadow systems)
  lint → npx @google/design.md lint DESIGN.md (validation gate)
/minoan-frontend-design → implementation (creative direction + materials)
/design-audit + /design-polish → refinement

.design-context.md and DESIGN.md are complementary:

• .design-context.md captures who and why — audience, aesthetic direction, design dials (DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY), anti-goals
• DESIGN.md captures what exactly — hex colors, font-size/weight/tracking tables, padding values, shadow stacks, breakpoints

Both live in the project root. /minoan-frontend-design consumes both — creative direction from the design context, materials from the design tokens. Tokens are materials, not recipes: creative direction still leads.

Diagrams

Component hierarchies and token relationships can be visualized as Mermaid diagrams using beautiful-mermaid ASCII mode, then included directly in DESIGN.md files:

printf 'graph TD\n  Tokens --> Components --> Patterns' | \
  node ~/.claude/skills/beautiful-mermaid/scripts/mermaid.mjs -

For SVG export (e.g., in companion HTML docs), use -f svg -t github-light.

When Not to Use This Skill

• For pattern research (how do other design systems implement tabs?), use /component-gallery
• For creative direction and UI implementation, use /minoan-frontend-design
• For pre-code design briefs, use /shape
• For visual effects (shaders, WebGL), use /grainient or /rocaille-shader