Document

The YAML frontmatter is the machine-readable layer. It’s what Stitch’s linter validates and what the live panel renders tiles from. Keep it tight; every entry should correspond to a token the project actually uses.

Rules that matter:

• Token refs use {path.to.token} (e.g. {colors.primary}, {rounded.md}). Components may reference primitives; primitives may not reference each other.
• Colors accept any valid CSS color string. Hex is the recommended default for portability, but preserve an incumbent rgb(), hsl(), oklch(), wide-gamut, or mixed-color value when it is the project’s normative source. Never split the source of truth without explicit reason.
• Component sub-tokens are limited to 8 props: backgroundColor, textColor, typography, rounded, padding, size, height, width. Shadows, motion, focus rings, backdrop-filter: none of those fit. Carry them in the sidecar (Step 4b).
• Scale keys are open-ended. Use whatever names the project already uses (oxblood-deep, surface-container-low). Don’t rename to Material defaults.
• Variants are naming convention, not schema. button-primary / button-primary-hover / button-primary-active as sibling keys.

The markdown body: eight sections (canonical order)

1. ## Overview
2. ## Colors
3. ## Typography
4. ## Layout
5. ## Elevation & Depth
6. ## Shapes
7. ## Components
8. ## Do's and Don'ts

Omit irrelevant sections rather than filling them with invented rules. Put responsive layout in Layout, depth in Elevation & Depth, radius and form language in Shapes, and per-component behavior in Components. Unknown sections are preserved by the format, but new visual guidance should use the canonical structure whenever it fits.

When to run

• New-work found a coherent incumbent visual system but no DESIGN.md.
• The first implementation of a new world is complete and its provisional decisions need to be carbonized.
• An existing DESIGN.md is stale (the design has drifted).
• Before a large redesign, to capture the current state as a reference.

If a DESIGN.md already exists, do not silently overwrite it. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge.

Two paths

• Scan mode (default): the project has design tokens, components, or rendered output. Extract, then confirm descriptive language. Use when there’s code to analyze.
• Seed mode: the project is pre-implementation. Ensure PRODUCT.md exists, then reuse new-work’s visual-world workshop and write its directional DESIGN.md seed. Re-run in scan mode once there’s code.

Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no component files, and no rendered site, offer seed mode; don’t silently switch. /impeccable document --seed requests new-work’s world workshop, but it does not authorize replacing coherent code: when an incumbent system exists, offer scan mode or route an explicit identity-replacement request through new-work.

Scan mode (approach C: auto-extract, then confirm descriptive language)

Step 1: Find the design assets

Search the codebase in priority order:

1. CSS custom properties: grep for --color-, --font-, --spacing-, --radius-, --shadow-, --ease-, --duration- declarations in CSS files (usually src/styles/, public/css/, app/globals.css, etc.). Record name, value, and the file it’s defined in.
2. Tailwind config: if tailwind.config.{js,ts,mjs} exists, read the theme.extend block for colors, fontFamily, spacing, borderRadius, boxShadow.
3. CSS-in-JS theme files: styled-components, emotion, vanilla-extract, stitches; look for theme.ts, tokens.ts, or equivalent.
4. Design token files: tokens.json, design-tokens.json, Style Dictionary output, W3C token community group format.
5. Component library: scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
6. Global stylesheet: the root CSS file usually has the base typography and color assignments.
7. Visible rendered output: if browser automation tools are available, load the live site and sample computed styles from key elements (body, h1, a, button, .card). This catches values that tokens miss.

Step 2: Auto-extract what can be auto-extracted

Build a structured draft from the discovered tokens. For each token class:

• Colors: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral; omit Secondary and Tertiary rather than inventing them.
• Typography: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
• Elevation: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that’s a valid answer; state it explicitly.
• Components: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
• Layout + spacing: Extract grid, container, breakpoint, rhythm, and density behavior into Layout.
• Shapes: Extract radius, corner, border, clipping, and recurring form behavior into Shapes.

Step 2b: Stage the frontmatter

From the auto-extracted tokens, draft the YAML frontmatter now (you’ll write it at the top of DESIGN.md in Step 4). This is the machine-readable layer: what the live panel and Stitch’s linter consume.

• Colors: one entry per extracted color. Key = descriptive slug (oxblood-deep, editorial-magenta, not blue-800). Value = whichever format the project treats as canonical (OKLCH or hex; see the frontmatter rules above). Don’t split the source of truth: one format in the frontmatter, don’t redefine the same token in prose with a different value.
• Typography: one entry per role (display, headline, title, body, label). Typography is an object; include only the props that are real for the project (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation).
• Rounded / Spacing: whatever scale steps the project actually uses, keyed by whatever scale name the project uses (sm / md / lg, or surface-sm, or numeric steps).
• Components: one entry per variant (button-primary, button-primary-hover, button-ghost). Reference primitives via {colors.X}, {rounded.Y}. If a variant needs a property Stitch’s 8-prop set doesn’t cover (shadow, focus ring, backdrop-filter), carry the full snippet in the sidecar instead.

Skip anything the project doesn’t have. Empty scale keys or fabricated tokens pollute the spec.

Step 3: Ask the user for qualitative language

The following require creative input that cannot be auto-extracted. Ask them in two structured rounds of no more than three questions each (or the harness’s lower limit), waiting between rounds:

• Creative North Star: a single named metaphor for the whole system (“The Editorial Sanctuary”, “The Golden State Curator”, “The Lab Notebook”). Offer 2-3 options that honor PRODUCT.md’s brand personality.
• Overview voice: mood adjectives, aesthetic philosophy in 2-3 sentences, and any confirmed visual anti-reference.
• Color character (for auto-extracted colors): descriptive names (“Deep Muted Teal-Navy”, not “blue-800”). Suggest 2-3 options per key color based on hue/saturation.
• Elevation philosophy: flat/layered/lifted. If shadows exist, is their role ambient or structural?
• Component philosophy: the feel of buttons, cards, inputs in one phrase (“tactile and confident” vs. “refined and restrained”).

Carry a line from PRODUCT.md only when it is a durable brand commitment that actually constrains the visual system. Page strategy and surface concepts do not belong here.

Step 4: Write DESIGN.md

The file opens with the YAML frontmatter staged in Step 2b (schema documented at the top of this reference), then the markdown body using the canonical structure below.

Step 4b: Write .impeccable/design.json sidecar (extensions only)

The frontmatter owns token primitives (colors, typography, rounded, spacing, components). The sidecar at .impeccable/design.json carries what Stitch’s schema can’t hold: tonal ramps per color, shadow/elevation tokens, motion tokens, breakpoints, full component HTML/CSS snippets (the panel renders these into a shadow DOM), and narrative (north star, rules, do’s/don’ts). It extends the frontmatter, it doesn’t duplicate it.

Regenerate the sidecar whenever you regenerate root DESIGN.md. If the user only asks to refresh the sidecar (e.g., from the live panel’s stale-hint), preserve DESIGN.md and write only .impeccable/design.json.

Schema

What changed from schemaVersion 1. The old sidecar carried token primitive arrays (tokens.colors[], tokens.typography[], etc.). Those values now live in the frontmatter. The sidecar only carries metadata that can’t live in the frontmatter (tonal ramps, canonical OKLCH when the hex is an approximation, display names, role hints), keyed by the frontmatter token name (colorMeta.<token-name>, typographyMeta.<token-name>). Components still carry full HTML/CSS because Stitch’s 8-prop set can’t hold them.

Component translation rules

The html and css fields must be self-contained, drop-in snippets that render correctly when injected into a shadow DOM. The panel applies them directly: no post-processing, no framework runtime.

1. Tailwind expansion. If the source uses Tailwind (className=”bg-primary text-white rounded-lg px-6 py-3”), expand every utility to literal CSS properties in the css string. Do not reference Tailwind classes; do not assume a Tailwind CSS bundle is loaded. Each component is self-contained.
2. Token resolution. If the project exposes tokens as CSS custom properties on :root (e.g. --color-primary, --radius-md), reference them via var(--color-primary); they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time.
3. Icons. Inline as SVG. Do not reference Lucide/Heroicons packages, icon fonts, or <img src="...">. A typical icon is 16-24px; copy the SVG path data directly.
4. States. Include :hover, :focus-visible, and (if meaningful) :active rules inline. A static default-only snapshot makes the panel feel dead. Hover + focus rules in the CSS make it feel alive.
5. Reset bloat. Extract only the component’s distinctive CSS (background, color, padding, border-radius, typography, transition). Skip universal resets (box-sizing: border-box, line-height: inherit, -webkit-font-smoothing). The panel already has a neutral canvas; don’t re-ship resets.
6. Scoped class names. Prefix every class with ds- (e.g. ds-btn-primary, ds-input-search) so component CSS doesn’t collide with other components’ CSS in the same shadow DOM.

What to include

Aim for a tight set of 5-10 components that best represent the visual system:

• Canonical primitives (always include if the project has them): button (each variant as a separate component entry), input/text field, navigation, chip/tag, card.
• Signature components (include if distinctive): the recurring custom patterns that actually define the implemented system.
• Skip the rest. Utility components, form building blocks, wrapper layouts: not worth documenting unless visually distinctive.

If the project has no component library yet (bare landing page, new project), synthesize canonical primitives from the tokens using best-practice defaults consistent with the DESIGN.md’s rules. Every .impeccable/design.json has something to render, even on day zero.

Tonal ramps

For each color token, generate an 8-step tonalRamp array: dark to light, same hue and chroma, stepped lightness from ~15% to ~95%. The panel renders this as a strip under the swatch. If the project already defines a tonal scale (Material surface-container-low family, Tailwind-style blue-50..blue-900), use those values. Otherwise synthesize in OKLCH.

Narrative mapping

Pull directly from the DESIGN.md you just wrote:

• narrative.northStar → the **Creative North Star: "..."** line from Overview
• narrative.overview → the philosophy paragraphs from Overview
• narrative.keyCharacteristics → the bulleted **Key Characteristics:** list
• narrative.rules → every **The [Name] Rule.** [body] across all sections, tagged with section
• narrative.dos / narrative.donts → the bullet lists from Do’s and Don’ts verbatim

Do not reword. The panel shows these as secondary collapsible context; the same voice that’s in the Markdown carries through.

Step 5: Confirm and refine

1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules).
2. Mention that .impeccable/design.json was also written alongside; the live panel will now render this project’s actual button/input/nav primitives instead of generic approximations.
3. Offer to refine any section: “Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?”

Your own write is the freshest source; subsequent commands in this session don’t need a reload.

Seed mode

For projects with no visual system to extract yet. Produces a user-chosen visual-world scaffold, not a fabricated token spec.

Step 1: Route through new-work’s workshop

PRODUCT.md is the prerequisite. If it is missing, load init.md and complete its product interview first. Do not create a visual identity without durable product context.

If PRODUCT.md exists, load new-work.md and resolve visual authority. Seed mode requires a concrete first surface: use the target the user named, or ask what they want to make first. Run new-work’s Create or replace the visual world flow, then Commit the world, so the visual world and its first expression are chosen together. Stop after the directional DESIGN.md seed and surface brief; do not implement. A structured simulated user counts as the user and must get the same choice.

If new-work already completed the workshop in this session, use its chosen direction directly. Do not ask again.

Step 2: Write seed DESIGN.md

Use the canonical section order from Scan mode. Populate the selected workshop direction and leave unresolved implementation facts as honest placeholders. The seed commits a world and its invariants; it does not pretend implementation tokens already exist.

Lead the file with:

Per-section guidance in seed mode:

• Overview: the chosen design thesis, layout behavior, material character, imagery stance, motion grammar, and reusable signature. Keep the selected first-surface expression in its surface brief; do not promote its composition into the global world.
• Colors: the selected palette strategy and roles. Include values only when the user, an existing asset, or new-work’s exploration established them; otherwise mark them [to be resolved during implementation].
• Typography: the selected type character and role relationship. Include font names only when established; otherwise mark the pairing [to be resolved during implementation].
• Layout: the selected spatial grammar and responsive behavior, without pretending exact measurements are settled.
• Elevation & Depth: the selected material and depth behavior, stated as an invariant rather than inferred from a generic preset.
• Shapes: the selected form and corner language.
• Components: omit entirely; no components exist yet.
• Do’s and Don’ts: record the durable guardrails confirmed during the world choice, not task-local refusals.

Seed mode writes a minimal frontmatter with name and description only; no colors, typography, rounded, spacing, or components yet. Real tokens land on the next Scan-mode run. Skip the .impeccable/design.json sidecar in seed mode for the same reason: nothing to render.

Step 3: Confirm

1. Show the seed DESIGN.md. Call out that it is a seed (the marker is the literal commitment).
2. Tell the user: “Re-run /impeccable document once you have some code. That pass will extract real tokens and generate the sidecar.”

Your own write is the freshest source; no reload needed.

Style guidelines

• Frontmatter first, prose second. Tokens go in the YAML frontmatter; prose contextualizes them. Don’t redefine a token value in two places; the frontmatter is normative.
• Carry only durable product constraints. A binding logo, identity asset, accessibility need, or brand commitment from PRODUCT.md may constrain DESIGN.md. Surface strategy stays in its surface brief.
• Match the spec. Use its eight canonical sections in order and omit any that are irrelevant. Put motion guidance with the world or component it affects rather than creating a token group the schema does not support.
• Descriptive > technical: “Gently curved edges (8px radius)” > “rounded-lg”. Include the technical value in parens, lead with the description.
• Functional > decorative: for each token, explain WHERE and WHY it’s used, not just WHAT it is.
• Exact values in parens: hex codes, px/rem values, font weights; always the number in parens alongside the description.
• Use Named Rules: **The [Name] Rule.** [short doctrine]. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch’s own outputs use them heavily (“The No-Line Rule”, “The Ghost Border Fallback”). Aim for 1-3 per section.
• Be decisive where evidence is decisive. Use hard language for actual invariants and softer language for provisional guidance.
• Use concrete audit tests only when they are grounded in the observed system or a confirmed user decision. A one-sentence test beats a paragraph of principle.
• Reference PRODUCT.md selectively. Product truth explains why the world fits; it does not supply page composition or a visual don’t-list by default.
• Group colors by role, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.

Pitfalls

• Don’t paste raw CSS class names. Translate to descriptive language.
• Don’t extract every token. Stop at what’s actually reused; one-offs pollute the system.
• Don’t invent components that don’t exist. If the project only has buttons and cards, only document those.
• Don’t overwrite an existing DESIGN.md without asking.
• Don’t duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
• Don’t replace canonical sections with near-synonyms. Put layout and responsive behavior in Layout; put motion with the affected world or component.
• Don’t rename sections even slightly. “Colors” not “Color Palette & Roles”. “Typography” not “Typography Rules”. Tooling parsing depends on exact headers.
• Don’t duplicate token values between frontmatter and prose. If a color is in colors.primary as hex, the prose can name it and describe its role but should not reassert a different hex. The frontmatter is normative.
• Don’t invent frontmatter token groups outside Stitch’s schema (no motion:, breakpoints:, shadows: at the top level). Stitch’s Zod schema only accepts colors, typography, rounded, spacing, components. Anything else belongs in the sidecar’s extensions.