1---
2tagline: "Generate a spec-compliant DESIGN.md that captures your visual system so every AI agent stays on-brand."
3---
4
5<div class="docs-viz-hero">
6 <div class="docs-viz-file">
7 <div class="docs-viz-file-header">
8 <span class="docs-viz-file-name">DESIGN.md</span>
9 <span class="docs-viz-file-status">Google Stitch format</span>
10 </div>
11 <div class="docs-viz-designmd-section">
12 <div class="docs-viz-designmd-head">
13 <span class="docs-viz-designmd-num">01</span>
14 <span class="docs-viz-designmd-title">Overview</span>
15 </div>
16 <p class="docs-viz-designmd-note">Creative North Star: <em>"The Editorial Sanctuary."</em> Quiet type, generous air, one committed accent.</p>
17 </div>
18 <div class="docs-viz-designmd-section">
19 <div class="docs-viz-designmd-head">
20 <span class="docs-viz-designmd-num">02</span>
21 <span class="docs-viz-designmd-title">Colors</span>
22 </div>
23 <div class="docs-viz-designmd-swatches" aria-hidden="true">
24 <span class="docs-viz-designmd-swatch" style="background:#1a1a1a"></span>
25 <span class="docs-viz-designmd-swatch" style="background:#f5f3ef"></span>
26 <span class="docs-viz-designmd-swatch" style="background:oklch(60% 0.22 30)"></span>
27 <span class="docs-viz-designmd-swatch" style="background:oklch(90% 0.02 30)"></span>
28 </div>
29 </div>
30 <div class="docs-viz-designmd-section">
31 <div class="docs-viz-designmd-head">
32 <span class="docs-viz-designmd-num">03</span>
33 <span class="docs-viz-designmd-title">Typography</span>
34 </div>
35 <div class="docs-viz-designmd-type">
36 <span class="docs-viz-designmd-type-display">Aa</span>
37 <span class="docs-viz-designmd-type-body">Cormorant Garamond · Instrument Sans</span>
38 </div>
39 </div>
40 <div class="docs-viz-designmd-section">
41 <div class="docs-viz-designmd-head">
42 <span class="docs-viz-designmd-num">04</span>
43 <span class="docs-viz-designmd-title">Elevation</span>
44 </div>
45 <p class="docs-viz-designmd-note">Flat by default. Shadows appear only as a response to state.</p>
46 </div>
47 <div class="docs-viz-designmd-section">
48 <div class="docs-viz-designmd-head">
49 <span class="docs-viz-designmd-num">05</span>
50 <span class="docs-viz-designmd-title">Components</span>
51 </div>
52 <div class="docs-viz-designmd-comps" aria-hidden="true">
53 <span class="docs-viz-designmd-btn">Subscribe</span>
54 <span class="docs-viz-designmd-chip">filter</span>
55 <span class="docs-viz-designmd-card">card</span>
56 </div>
57 </div>
58 <div class="docs-viz-designmd-section">
59 <div class="docs-viz-designmd-head">
60 <span class="docs-viz-designmd-num">06</span>
61 <span class="docs-viz-designmd-title">Do's and Don'ts</span>
62 </div>
63 <div class="docs-viz-designmd-rules">
64 <span class="docs-viz-designmd-do">Tint neutrals toward the accent hue.</span>
65 <span class="docs-viz-designmd-dont">Gradient text for emphasis.</span>
66 </div>
67 </div>
68 </div>
69 <p class="docs-viz-caption">The six sections are fixed, in a fixed order, with fixed names. Alongside, <code>DESIGN.json</code> ships as a machine-readable sidecar for the Live Mode design panel.</p>
70</div>
71
72## When to use it
73
74Run `/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](https://stitch.withgoogle.com/docs/design-md/format/), six sections in a fixed order, interoperable with every other DESIGN.md-aware tool.
75
76Reach for it when:
77
78- **You just ran `/impeccable teach`** and `PRODUCT.md` now exists. Document is the matching visual-side file.
79- **A command nudged you toward it.** Live, craft, and polish all read DESIGN.md. If it is missing, the skill suggests running document first.
80- **The design has drifted** from an older DESIGN.md and the file no longer describes the live system.
81- **Before a large redesign**, to capture current state as a reference for the next direction.
82
83For projects with no code yet (fresh `teach` run, nothing built), there is a seed mode: `/impeccable document --seed` asks five quick strategic questions (color strategy, type direction, motion energy, references, anti-references) and writes a scaffold. Re-run in scan mode once there is code.
84
85## How it works
86
87The 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.
88
89Output 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, `DESIGN.json` is written as a machine-readable sidecar. That sidecar is what the live-mode design panel uses to render *this project's* actual button, input, nav, and card tiles instead of a generic approximation.
90
91Every other command reads DESIGN.md on invocation. Variants, polishes, audits, and new features inherit the visual system without being told.
92
93## Try it
94
95```
96/impeccable document
97```
98
99On 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.
100
101On a fresh project:
102
103```
104/impeccable document --seed
105```
106
107Five 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.
108
109## Pitfalls
110
111- **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.
112- **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.
113- **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).
114- **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.