design-md-author

DESIGN.md author

Read, write, or update a DESIGN.md at the project root. DESIGN.md is the Google-Labs-published cross-tool spec for documenting a design system: tokens, typography, components, motion, do's-and-don'ts. When present, it grounds every subsequent prompt in this project — the agent reads it as project-context before generating UI.

When to use

• The user asks to "set up the design system", "create a DESIGN.md", "import this design system", "capture our look".
• A project doesn't have a DESIGN.md yet and the user wants to commit to a direction once instead of re-deciding per prompt.
• The user wants to import a DESIGN.md from elsewhere (a Stitch export, a community gallery, another project).
• The user wants to update tokens, typography rules, or component specs declared in the project's existing DESIGN.md.

Skip when:

• The user is generating a one-off design — DESIGN.md is for projects with continuity, not single artifacts.
• The change is implementation, not specification. (Component code changes go through frontend-design; the DESIGN.md only changes when the spec shifts.)

The schema (Google spec)

A valid DESIGN.md has YAML front-matter and a fixed set of markdown sections in order. Every section is required.

---
version: "0.1.0"
name: "Project name"
description: "One-sentence aesthetic direction."
colors:
  bg: "#hex"
  surface: "#hex"
  ink: "#hex"
  brand: "#hex"
  # … semantic tokens, named by purpose
typography:
  display: "Font Name, fallback"
  body: "Font Name, fallback"
  mono: "Font Name, fallback"
rounded:
  none: "0"
  sm: "4px"
  md: "8px"
  lg: "16px"
spacing:
  unit: "4px"
  scale: [0, 1, 2, 3, 4, 6, 8, 12, 16, 24]
components:
  button:
    primary:
      bg: "{colors.brand}"
      ink: "{colors.bg}"
    # … per-component variants
---

Token references use {path.to.token} so semantic relationships survive when individual values change.

Required markdown sections, in this order:

1. ## Overview — the aesthetic direction in 2–4 paragraphs. What feeling, what posture, what's the differentiation.
2. ## Colors — semantic role per color, with hex and a one-line use-case. Reference front-matter tokens.
3. ## Typography — display vs body vs mono roles, the type scale, tracking rules, letter-spacing floors.
4. ## Layout — grid system, spacing scale, breakpoints, content max-widths.
5. ## Elevation & Depth — shadow tokens, when to use which.
6. ## Shapes — radii, border weights, decorative elements.
7. ## Components — per-component spec: button, card, input, dialog, navigation, etc. Each with state variants (default, hover, active, disabled, error).
8. ## Do's and Don'ts — the project-specific anti-patterns, paired with what to do instead.