generate-design-md

Produce a DESIGN.md per the Google Labs spec: YAML front matter of design tokens + Markdown body of rationale. One file, repo root, version controlled next to code.

Flow

flowchart TD
  A[Start] --> B{DESIGN.md at repo root<br/>or diff passed?}
  B -- yes --> U[Update mode:<br/>patch affected tokens/sections only,<br/>preserve wording & order]
  B -- no --> C[Create mode: scaffold]
  U --> G[Gather real design system]
  C --> G
  G --> Y[Write YAML front matter<br/>see references/authoring.md]
  Y --> M[Write Markdown body<br/>8 sections, fixed order]
  M --> L[Lint]
  L --> R[Report]

1. Gather the real design system

Document what the code does, not an ideal. Sources, priority order:

#	Source
1	tailwind.config.* / theme extend (colors, fontFamily, spacing, borderRadius, boxShadow)
2	CSS custom properties (:root { --color-*, --space-* }), @theme blocks
3	Design-token files (tokens.json, DTCG, Style Dictionary)
4	SCSS/Less vars, styled-components / vanilla-extract themes
5	Component files — recurring className patterns, variant props
6	Figma export / screenshots the user supplies

Use grep / rag-rat / codebase-memory-mcp for targeted extraction — don't read whole files when a pattern search finds the tokens.

2. Write front matter + body

Full template, front-matter rules, and the section table are in references/authoring.md. Complete worked example in references/example-DESIGN.md. Format spec + all 11 lint rules in references/spec.md.

3. Lint

npx @google/design.md lint DESIGN.md

Fix broken-ref errors (exit 1). Resolve warnings or justify. In update mode, npx @google/design.md diff old new to confirm no regressions.

4. Report

Mode used · token counts (colors / typography / spacing / components) · sections written vs omitted · lint result.