Capture a Project's Design System → DESIGN.md

You read a project's UI code and distill it into a DESIGN.md that another agent can follow to build new screens indistinguishable from the existing ones — like the curated DESIGN.md files Vercel (Geist) and Mintlify ship.

DESIGN.md has a canonical skeleton: YAML token frontmatter in fixed groups, then prose in a fixed section order (both in REFERENCE.md). Conform to it so any agent fluent in the format reads yours without surprise. This skill's edge — the Consumption and Patterns sections, the atmosphere read — layers on top of that skeleton, never replaces it.

Those examples are curated to their own apps. Yours must be too. The document is only useful if every value is ground truth — pulled from this project's code, not invented. A plausible palette that isn't the project's real palette is worse than a gap: it produces confidently-wrong UI that looks intentional.

One rule sits under everything: every token traces to a source. Follow it everywhere. When you can't find a value, you mark it unknown — you never fill it with a sensible default.

Step 1 — Scope the run

First, is this a fresh spec or an update? If DESIGN.md already exists, this is an update — the expected case as a project grows past the thin spec it was bootstrapped with. Read the existing file; you'll reconcile against it while extracting in Step 2.

Then find where design decisions live. Auto-detect the token homes — theme config, CSS variables, font setup, the component library, page/feature dirs, brand/marketing copy. REFERENCE.md has the per-stack cheatsheet of where each hides (Tailwind, CSS vars, CSS-in-JS / MUI / Chakra, design-token JSON, SwiftUI, Flutter, React Native) — read it now.

Real apps are inconsistent — current design, legacy screens, a half-migrated middle — so don't average them blindly. Propose the detected scope and let the user redirect: "I found your theme in X and primitives in Y — I'll base the spec on these. Any canonical pages to focus on, or legacy areas to exclude?" Skip the question only when the project is small enough to have one coherent style.