document
Generate a spec-compliant DESIGN.md that captures your visual system so every AI agent stays on-brand.
Creative North Star: "The Editorial Sanctuary." Quiet type, generous air, one committed accent.
Flat by default. Shadows appear only as a response to state.
The six sections are fixed, in a fixed order, with fixed names. Alongside, .impeccable/design.json ships as a machine-readable sidecar for tools that need structured design metadata.
When to use it
Run /impeccable document once you have enough of a visual system to document: colors, typography, at least a button and a card. The command scans your codebase, extracts the tokens and component patterns it finds, and writes a DESIGN.md at the project root that follows the Google Stitch DESIGN.md format, six sections in a fixed order, interoperable with every other DESIGN.md-aware tool.
Reach for it when:
- You just ran
/impeccable initandPRODUCT.mdnow exists. Document is the matching visual-side file. - A command nudged you toward it. Live, polish, and the new-work flow all read DESIGN.md. If it is missing, the skill suggests running document first.
- The design has drifted from an older DESIGN.md and the file no longer describes the live system.
- Before a large redesign, to capture current state as a reference for the next direction.
How it works
It reads your code, extracts everything it can on its own, and then asks one grouped question about the parts a scan cannot infer: what the system is for. That includes a named metaphor for the whole thing (something like “The Editorial Sanctuary”), descriptive color names, and the character your components are meant to have.
You get a DESIGN.md you can read and edit, plus a generated .impeccable/design.json sidecar that lets Live Mode and the design-aware detector rules check work against your real palette, type, and radii.
Every other command reads DESIGN.md on invocation, so variants, polishes, audits, and new surfaces inherit the visual system without being told. See Design Context for how the files relate.
Where it looks, and the exact file shape
The scan checks sources in priority order: CSS custom properties, Tailwind config, CSS-in-JS themes, design token files, component source, the global stylesheet, and finally computed styles from the rendered page if a browser is available.
The output has exactly six sections: Overview, Colors, Typography, Elevation, Components, and Do's and Don'ts. The headers are fixed character-for-character so other tools can parse the file.
No code yet? Use seed mode
On a fresh init with nothing built, /impeccable document --seed asks five quick strategic questions (color strategy, type direction, motion style, references, anti-references) and writes a scaffold. Re-run it in normal scan mode once there is code to read.
Try it
/impeccable documentOn a project with tokens already defined, this takes about two minutes: the scan finds your palette and type stack, you pick a North Star from 2 or 3 options, confirm descriptive color names (“Deep Muted Teal-Navy”, not “blue-800”), and the file lands at the project root.
On a fresh project:
/impeccable document --seedFive questions, about five minutes. The file is a scaffold, marked with a <!-- SEED --> comment so it is honest about what it is. Re-run without the flag once you have implemented tokens.
Pitfalls
- Running it too early. On a project with no implemented tokens, seed mode is right. Do not fabricate a full spec the code cannot back up. A fake DESIGN.md is worse than no DESIGN.md.
- Treating DESIGN.md as documentation for humans only. It is primarily for the AI. Every other command reads it. The format’s forcefulness (“never”, “always”, Named Rules) is intentional.
- Adding a Layout / Motion / Responsive top-level section. The spec has six sections, in a fixed order, with fixed names. Fold layout or motion content into Overview (philosophy-level rules) or Components (per-component behavior).
- Overwriting an existing DESIGN.md silently. Document always confirms first. If you want to start fresh, rename the existing file out of the way or explicitly tell the skill to overwrite.