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
| # | Section | Content |
|---|---|---|
| 1 | Visual Theme & Atmosphere | Prose: mood, philosophy, conceptual direction |
| 2 | Color Palette & Roles | Grouped: semantic name + hex + functional role |
| 3 | Typography Rules | Font families, hierarchy table (size/weight/tracking/line-height) |
| 4 | Component Stylings | Buttons, cards, inputs, nav — CSS values + states |
| 5 | Layout Principles | Spacing scale, grid, whitespace philosophy, border-radius scale |
| 6 | Depth & Elevation | Shadow system table, surface hierarchy |
| 7 | Do's and Don'ts | Design guardrails and anti-patterns |
| 8 | Responsive Behavior | Breakpoints table, touch targets, collapsing strategy |
| 9 | Agent Prompt Guide | Quick color reference for copy-paste |
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.mdcaptures who and why — audience, aesthetic direction, design dials (DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY), anti-goalsDESIGN.mdcaptures 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
/grainientor/rocaille-shader