document

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 init and PRODUCT.md now exists. Document is the matching visual-side file.
• A command nudged you toward it. Live, craft, and polish 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.

For projects with no code yet (fresh init run, nothing built), there is a seed mode: /impeccable document --seed asks five quick strategic questions (color strategy, type direction, motion style, references, anti-references) and writes a scaffold. Re-run in scan mode once there is code.

How it works

The scan pass finds design assets 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 live rendered output if a browser is available. It auto-extracts everything it can, then asks one grouped question for the parts that need creative input: the Creative North Star (a single named metaphor for the whole system, like “The Editorial Sanctuary”), descriptive color names, the elevation philosophy, and the component character.

Output is a DESIGN.md with exactly six sections: Overview, Colors, Typography, Elevation, Components, Do’s and Don’ts. Headers are fixed character-for-character so the file is parseable by other tools. Alongside it, .impeccable/design.json is written as a machine-readable sidecar. That sidecar gives Live Mode and design-aware detector rules structured access to this project’s actual palette, type, radii, component snippets, and narrative.

Every other command reads DESIGN.md on invocation. Variants, polishes, audits, and new features inherit the visual system without being told. See Design Context for how DESIGN.md relates to PRODUCT.md and .impeccable/design.json.

Try it

/impeccable document

On 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 --seed

Five 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.