Support PRODUCT.md + DESIGN.md as canonical context files

Pioneers a two-file convention for project context:
- PRODUCT.md (strategic): users, brand, principles — answers who/what/why
- DESIGN.md (visual): follows Google's Stitch DESIGN.md spec — answers how-it-looks

Both files live at the repo root. Filename matching is case-insensitive.
DESIGN.md wins on visual conflicts, PRODUCT.md wins on strategic/voice.

Legacy .impeccable.md is auto-migrated to PRODUCT.md on first read by the
new shared loader. This is silent and one-shot — the rename is permanent.

What changed:
- New scripts/load-context.mjs: shared context loader used by every command
  that needs project context. Reads both files, handles legacy migration.
- New reference/document.md: /impeccable document command that generates
  DESIGN.md by auto-extracting tokens (colors, typography, spacing, radii,
  shadows, components) from CSS/Tailwind/theme files, then asking the user
  to confirm descriptive language for atmosphere and color character.
  Follows Google's Stitch DESIGN.md format for tool compatibility.
- SKILL.md Context Gathering Protocol updated to load both files and
  nudge the user to run /impeccable document when DESIGN.md is missing.
- reference/teach.md rewritten to split discovery cleanly: strategic
  questions go to PRODUCT.md, visual/design-system work is delegated to
  /impeccable document (skipped on empty projects).
- reference/live.md consumes {product, design, productPath, designPath,
  migrated} from the loader instead of a single context blob.
- scripts/live.mjs uses the shared loader instead of inline file reading.
- Command count updated 22 → 23 (new: document). Metadata, router table,
  command menu, periodic table viz, and homepage data all updated.
- .gitignore adds PRODUCT.md + DESIGN.md (repo-local, not shared).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.agents/skills/impeccable/SKILL.md

@@ -25,10 +25,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -36,8 +43,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run $impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .agents/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `$impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run $impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -297,7 +304,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `$impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `$impeccable shape [feature]` - Plan UX/UI before writing code
-> `$impeccable teach` - Set up design context for this project (one-time)
+> `$impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `$impeccable document` - Generate DESIGN.md from existing project code
 > `$impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -343,6 +351,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.agents/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset)
+- **Suggested command**: Which command to use (prefer: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `$command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `$command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset. Map findings to the most appropriate command. End with `$impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset. Map findings to the most appropriate command. End with `$impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.agents/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset)
+- **Suggested command**: Which command could address this (from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset
+- Only recommend commands from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.agents/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `$impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.agents/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `$impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.agents/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `$impeccable document` for DESIGN.md.
+- **Both exist**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ ask the user directly to clarify what you cannot infer. Focus only on what you c
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `$impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `$impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `$impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.agents/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {

.agents/skills/impeccable/scripts/live.mjs

@@ -21,10 +21,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-const CONTEXT_FILE = path.join(process.cwd(), '.impeccable.md');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -79,9 +79,8 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load design context if available
-  let context = null;
-  try { context = fs.readFileSync(CONTEXT_FILE, 'utf-8'); } catch { /* optional */ }
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
 
   // 5. Emit everything the agent needs
   console.log(JSON.stringify({
@@ -89,8 +88,13 @@ The agent should then:
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFile: checkResult.config.file,
-    hasContext: !!context,
-    context,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
   }, null, 2));
 }
 

.agents/skills/impeccable/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+
+  // 1. Look for PRODUCT.md (case-insensitive)
+  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists, rename in place
+  if (!productPath) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(cwd, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+  };
+}
+
+function firstExisting(cwd, names) {
+  for (const name of names) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

.agents/skills/impeccable/scripts/pin.mjs

@@ -27,7 +27,7 @@ const HARNESS_DIRS = [
 
 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'shape',
+  'craft', 'teach', 'extract', 'document', 'shape',
   'critique', 'audit',
   'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
   'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',

.claude-plugin/marketplace.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "impeccable",
   "metadata": {
-    "description": "Design fluency for AI harnesses. 1 skill, 22 commands, and curated anti-patterns for impeccable frontend design."
+    "description": "Design fluency for AI harnesses. 1 skill, 23 commands, and curated anti-patterns for impeccable frontend design."
   },
   "owner": {
     "name": "Paul Bakaus",
@@ -11,7 +11,7 @@
   "plugins": [
     {
       "name": "impeccable",
-      "description": "Design fluency for frontend development. 1 skill with 22 commands (/impeccable polish, /impeccable audit, /impeccable critique, etc.) and curated anti-pattern detection.",
+      "description": "Design fluency for frontend development. 1 skill with 23 commands (/impeccable polish, /impeccable audit, /impeccable critique, etc.) and curated anti-pattern detection.",
       "version": "3.0.0",
       "author": {
         "name": "Paul Bakaus",

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "impeccable",
-  "description": "Design fluency for frontend development. 1 skill with 22 commands (/impeccable polish, /impeccable audit, /impeccable critique, etc.) and curated anti-pattern detection.",
+  "description": "Design fluency for frontend development. 1 skill with 23 commands (/impeccable polish, /impeccable audit, /impeccable critique, etc.) and curated anti-pattern detection.",
   "version": "3.0.0",
   "author": {
     "name": "Paul Bakaus",

.claude/skills/impeccable/SKILL.md

@@ -3,7 +3,7 @@ name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
 version: 3.0.0
 user-invocable: true
-argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|extract|live] [target]"
+argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]"
 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
 allowed-tools:
   - Bash(npx impeccable *)
@@ -31,10 +31,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -42,8 +49,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .claude/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `/impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -303,7 +310,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `/impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `/impeccable shape [feature]` - Plan UX/UI before writing code
-> `/impeccable teach` - Set up design context for this project (one-time)
+> `/impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `/impeccable document` - Generate DESIGN.md from existing project code
 > `/impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -349,6 +357,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.claude/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `/command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.claude/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.claude/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `/impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and STOP and call the AskUserQuestion tool to clarify. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. STOP and call the AskUserQuestion tool to clarify. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.claude/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `/impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.claude/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **Both exist**: STOP and call the AskUserQuestion tool to clarify. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 STOP and call the AskUserQuestion tool to clarify. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ STOP and call the AskUserQuestion tool to clarify. Focus only on what you couldn
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then STOP and call the AskUserQuestion tool to clarify. whether they'd also like the Design Context appended to CLAUDE.md. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `/impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `/impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally STOP and call the AskUserQuestion tool to clarify. whether they'd like a brief summary of PRODUCT.md appended to CLAUDE.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.claude/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {

.claude/skills/impeccable/scripts/live.mjs

@@ -21,10 +21,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-const CONTEXT_FILE = path.join(process.cwd(), '.impeccable.md');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -79,9 +79,8 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load design context if available
-  let context = null;
-  try { context = fs.readFileSync(CONTEXT_FILE, 'utf-8'); } catch { /* optional */ }
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
 
   // 5. Emit everything the agent needs
   console.log(JSON.stringify({
@@ -89,8 +88,13 @@ The agent should then:
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFile: checkResult.config.file,
-    hasContext: !!context,
-    context,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
   }, null, 2));
 }
 

.claude/skills/impeccable/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+
+  // 1. Look for PRODUCT.md (case-insensitive)
+  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists, rename in place
+  if (!productPath) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(cwd, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+  };
+}
+
+function firstExisting(cwd, names) {
+  for (const name of names) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

.claude/skills/impeccable/scripts/pin.mjs

@@ -27,7 +27,7 @@ const HARNESS_DIRS = [
 
 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'shape',
+  'craft', 'teach', 'extract', 'document', 'shape',
   'critique', 'audit',
   'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
   'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',

.cursor/skills/impeccable/SKILL.md

@@ -27,10 +27,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -38,8 +45,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .cursor/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `/impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -299,7 +306,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `/impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `/impeccable shape [feature]` - Plan UX/UI before writing code
-> `/impeccable teach` - Set up design context for this project (one-time)
+> `/impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `/impeccable document` - Generate DESIGN.md from existing project code
 > `/impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -345,6 +353,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.cursor/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `/command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.cursor/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.cursor/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `/impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.cursor/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `/impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.cursor/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **Both exist**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ ask the user directly to clarify what you cannot infer. Focus only on what you c
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .cursorrules. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `/impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `/impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to .cursorrules for easier agent reference. If yes, append a short **Design Context** pointer section there.

.cursor/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {

.cursor/skills/impeccable/scripts/live.mjs

@@ -21,10 +21,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-const CONTEXT_FILE = path.join(process.cwd(), '.impeccable.md');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -79,9 +79,8 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load design context if available
-  let context = null;
-  try { context = fs.readFileSync(CONTEXT_FILE, 'utf-8'); } catch { /* optional */ }
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
 
   // 5. Emit everything the agent needs
   console.log(JSON.stringify({
@@ -89,8 +88,13 @@ The agent should then:
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFile: checkResult.config.file,
-    hasContext: !!context,
-    context,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
   }, null, 2));
 }
 

.cursor/skills/impeccable/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+
+  // 1. Look for PRODUCT.md (case-insensitive)
+  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists, rename in place
+  if (!productPath) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(cwd, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+  };
+}
+
+function firstExisting(cwd, names) {
+  for (const name of names) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

.cursor/skills/impeccable/scripts/pin.mjs

@@ -27,7 +27,7 @@ const HARNESS_DIRS = [
 
 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'shape',
+  'craft', 'teach', 'extract', 'document', 'shape',
   'critique', 'audit',
   'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
   'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',

.gemini/skills/impeccable/SKILL.md

@@ -26,10 +26,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -37,8 +44,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .gemini/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `/impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -298,7 +305,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `/impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `/impeccable shape [feature]` - Plan UX/UI before writing code
-> `/impeccable teach` - Set up design context for this project (one-time)
+> `/impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `/impeccable document` - Generate DESIGN.md from existing project code
 > `/impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -344,6 +352,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.gemini/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `/command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.gemini/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.gemini/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `/impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.gemini/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `/impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.gemini/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **Both exist**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ ask the user directly to clarify what you cannot infer. Focus only on what you c
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to GEMINI.md. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `/impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `/impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to GEMINI.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.gemini/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {

.gemini/skills/impeccable/scripts/live.mjs

@@ -21,10 +21,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-const CONTEXT_FILE = path.join(process.cwd(), '.impeccable.md');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -79,9 +79,8 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load design context if available
-  let context = null;
-  try { context = fs.readFileSync(CONTEXT_FILE, 'utf-8'); } catch { /* optional */ }
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
 
   // 5. Emit everything the agent needs
   console.log(JSON.stringify({
@@ -89,8 +88,13 @@ The agent should then:
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFile: checkResult.config.file,
-    hasContext: !!context,
-    context,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
   }, null, 2));
 }
 

.gemini/skills/impeccable/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+
+  // 1. Look for PRODUCT.md (case-insensitive)
+  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists, rename in place
+  if (!productPath) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(cwd, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+  };
+}
+
+function firstExisting(cwd, names) {
+  for (const name of names) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

.gemini/skills/impeccable/scripts/pin.mjs

@@ -27,7 +27,7 @@ const HARNESS_DIRS = [
 
 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'shape',
+  'craft', 'teach', 'extract', 'document', 'shape',
   'critique', 'audit',
   'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
   'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',

.github/skills/impeccable/SKILL.md

@@ -3,7 +3,7 @@ name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
 version: 3.0.0
 user-invocable: true
-argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|extract|live] [target]"
+argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]"
 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
 ---
 
@@ -29,10 +29,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -40,8 +47,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .github/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `/impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -301,7 +308,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `/impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `/impeccable shape [feature]` - Plan UX/UI before writing code
-> `/impeccable teach` - Set up design context for this project (one-time)
+> `/impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `/impeccable document` - Generate DESIGN.md from existing project code
 > `/impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -347,6 +355,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.github/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `/command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.github/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.github/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `/impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.github/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `/impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.github/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **Both exist**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ ask the user directly to clarify what you cannot infer. Focus only on what you c
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .github/copilot-instructions.md. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `/impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `/impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to .github/copilot-instructions.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.github/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {

.github/skills/impeccable/scripts/live.mjs

@@ -21,10 +21,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-const CONTEXT_FILE = path.join(process.cwd(), '.impeccable.md');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -79,9 +79,8 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load design context if available
-  let context = null;
-  try { context = fs.readFileSync(CONTEXT_FILE, 'utf-8'); } catch { /* optional */ }
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
 
   // 5. Emit everything the agent needs
   console.log(JSON.stringify({
@@ -89,8 +88,13 @@ The agent should then:
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFile: checkResult.config.file,
-    hasContext: !!context,
-    context,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
   }, null, 2));
 }
 

.github/skills/impeccable/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+
+  // 1. Look for PRODUCT.md (case-insensitive)
+  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists, rename in place
+  if (!productPath) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(cwd, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+  };
+}
+
+function firstExisting(cwd, names) {
+  for (const name of names) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

.github/skills/impeccable/scripts/pin.mjs

@@ -27,7 +27,7 @@ const HARNESS_DIRS = [
 
 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'shape',
+  'craft', 'teach', 'extract', 'document', 'shape',
   'critique', 'audit',
   'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
   'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',

.gitignore

@@ -42,8 +42,11 @@ Thumbs.db
 # Extension build artifacts
 extension/detector/
 
-# User design context
+# User design context (this repo's private project briefs — users can choose
+# whether to commit these in their own projects)
 .impeccable.md
+PRODUCT.md
+DESIGN.md
 
 # Evals (private, commercial)
 evals/

.kiro/skills/impeccable/SKILL.md

@@ -27,10 +27,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -38,8 +45,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .kiro/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `/impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -299,7 +306,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `/impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `/impeccable shape [feature]` - Plan UX/UI before writing code
-> `/impeccable teach` - Set up design context for this project (one-time)
+> `/impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `/impeccable document` - Generate DESIGN.md from existing project code
 > `/impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -345,6 +353,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.kiro/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `/command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.kiro/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.kiro/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `/impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.kiro/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `/impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.kiro/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **Both exist**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ ask the user directly to clarify what you cannot infer. Focus only on what you c
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .kiro/settings.json. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `/impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `/impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to .kiro/settings.json for easier agent reference. If yes, append a short **Design Context** pointer section there.

.kiro/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {

.kiro/skills/impeccable/scripts/live.mjs

@@ -21,10 +21,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-const CONTEXT_FILE = path.join(process.cwd(), '.impeccable.md');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -79,9 +79,8 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load design context if available
-  let context = null;
-  try { context = fs.readFileSync(CONTEXT_FILE, 'utf-8'); } catch { /* optional */ }
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
 
   // 5. Emit everything the agent needs
   console.log(JSON.stringify({
@@ -89,8 +88,13 @@ The agent should then:
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFile: checkResult.config.file,
-    hasContext: !!context,
-    context,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
   }, null, 2));
 }
 

.kiro/skills/impeccable/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+
+  // 1. Look for PRODUCT.md (case-insensitive)
+  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists, rename in place
+  if (!productPath) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(cwd, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+  };
+}
+
+function firstExisting(cwd, names) {
+  for (const name of names) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

.kiro/skills/impeccable/scripts/pin.mjs

@@ -27,7 +27,7 @@ const HARNESS_DIRS = [
 
 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'shape',
+  'craft', 'teach', 'extract', 'document', 'shape',
   'critique', 'audit',
   'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
   'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',

.opencode/skills/impeccable/SKILL.md

@@ -3,7 +3,7 @@ name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
 version: 3.0.0
 user-invocable: true
-argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|extract|live] [target]"
+argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]"
 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
 allowed-tools:
   - Bash(npx impeccable *)
@@ -31,10 +31,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -42,8 +49,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .opencode/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `/impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -303,7 +310,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `/impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `/impeccable shape [feature]` - Plan UX/UI before writing code
-> `/impeccable teach` - Set up design context for this project (one-time)
+> `/impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `/impeccable document` - Generate DESIGN.md from existing project code
 > `/impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -349,6 +357,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.opencode/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `/command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.opencode/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.opencode/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `/impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and STOP and call the `question` tool to clarify. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. STOP and call the `question` tool to clarify. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.opencode/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `/impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.opencode/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **Both exist**: STOP and call the `question` tool to clarify. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 STOP and call the `question` tool to clarify. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ STOP and call the `question` tool to clarify. Focus only on what you couldn't in
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then STOP and call the `question` tool to clarify. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `/impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `/impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally STOP and call the `question` tool to clarify. whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.opencode/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {

.opencode/skills/impeccable/scripts/live.mjs

@@ -21,10 +21,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-const CONTEXT_FILE = path.join(process.cwd(), '.impeccable.md');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -79,9 +79,8 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load design context if available
-  let context = null;
-  try { context = fs.readFileSync(CONTEXT_FILE, 'utf-8'); } catch { /* optional */ }
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
 
   // 5. Emit everything the agent needs
   console.log(JSON.stringify({
@@ -89,8 +88,13 @@ The agent should then:
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFile: checkResult.config.file,
-    hasContext: !!context,
-    context,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
   }, null, 2));
 }
 

.opencode/skills/impeccable/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+
+  // 1. Look for PRODUCT.md (case-insensitive)
+  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists, rename in place
+  if (!productPath) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(cwd, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+  };
+}
+
+function firstExisting(cwd, names) {
+  for (const name of names) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

.opencode/skills/impeccable/scripts/pin.mjs

@@ -27,7 +27,7 @@ const HARNESS_DIRS = [
 
 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'shape',
+  'craft', 'teach', 'extract', 'document', 'shape',
   'critique', 'audit',
   'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
   'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',

.pi/skills/impeccable/SKILL.md

@@ -29,10 +29,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -40,8 +47,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .pi/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `/impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -301,7 +308,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `/impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `/impeccable shape [feature]` - Plan UX/UI before writing code
-> `/impeccable teach` - Set up design context for this project (one-time)
+> `/impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `/impeccable document` - Generate DESIGN.md from existing project code
 > `/impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -347,6 +355,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.pi/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `/command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.pi/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.pi/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `/impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.pi/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `/impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.pi/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **Both exist**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ ask the user directly to clarify what you cannot infer. Focus only on what you c
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `/impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `/impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.pi/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {

.pi/skills/impeccable/scripts/live.mjs

@@ -21,10 +21,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-const CONTEXT_FILE = path.join(process.cwd(), '.impeccable.md');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -79,9 +79,8 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load design context if available
-  let context = null;
-  try { context = fs.readFileSync(CONTEXT_FILE, 'utf-8'); } catch { /* optional */ }
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
 
   // 5. Emit everything the agent needs
   console.log(JSON.stringify({
@@ -89,8 +88,13 @@ The agent should then:
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFile: checkResult.config.file,
-    hasContext: !!context,
-    context,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
   }, null, 2));
 }
 

.pi/skills/impeccable/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+
+  // 1. Look for PRODUCT.md (case-insensitive)
+  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists, rename in place
+  if (!productPath) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(cwd, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+  };
+}
+
+function firstExisting(cwd, names) {
+  for (const name of names) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

.pi/skills/impeccable/scripts/pin.mjs

@@ -27,7 +27,7 @@ const HARNESS_DIRS = [
 
 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'shape',
+  'craft', 'teach', 'extract', 'document', 'shape',
   'critique', 'audit',
   'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
   'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',

.rovodev/skills/impeccable/SKILL.md

@@ -3,7 +3,7 @@ name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
 version: 3.0.0
 user-invocable: true
-argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|extract|live] [target]"
+argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]"
 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
 allowed-tools:
   - Bash(npx impeccable *)
@@ -31,10 +31,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -42,8 +49,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .rovodev/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `/impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -303,7 +310,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `/impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `/impeccable shape [feature]` - Plan UX/UI before writing code
-> `/impeccable teach` - Set up design context for this project (one-time)
+> `/impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `/impeccable document` - Generate DESIGN.md from existing project code
 > `/impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -349,6 +357,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.rovodev/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `/command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.rovodev/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.rovodev/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `/impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.rovodev/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `/impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.rovodev/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **Both exist**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ ask the user directly to clarify what you cannot infer. Focus only on what you c
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to AGENTS.md. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `/impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `/impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.rovodev/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {

.rovodev/skills/impeccable/scripts/live.mjs

@@ -21,10 +21,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadContext } from './load-context.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PID_FILE = path.join(process.cwd(), '.impeccable-live.json');
-const CONTEXT_FILE = path.join(process.cwd(), '.impeccable.md');
 
 async function liveCli() {
   const args = process.argv.slice(2);
@@ -79,9 +79,8 @@ The agent should then:
     process.exit(1);
   }
 
-  // 4. Load design context if available
-  let context = null;
-  try { context = fs.readFileSync(CONTEXT_FILE, 'utf-8'); } catch { /* optional */ }
+  // 4. Load PRODUCT.md + DESIGN.md context (auto-migrates legacy .impeccable.md)
+  const ctx = loadContext(process.cwd());
 
   // 5. Emit everything the agent needs
   console.log(JSON.stringify({
@@ -89,8 +88,13 @@ The agent should then:
     serverPort: serverInfo.port,
     serverToken: serverInfo.token,
     pageFile: checkResult.config.file,
-    hasContext: !!context,
-    context,
+    hasProduct: ctx.hasProduct,
+    product: ctx.product,
+    productPath: ctx.productPath,
+    hasDesign: ctx.hasDesign,
+    design: ctx.design,
+    designPath: ctx.designPath,
+    migrated: ctx.migrated,
   }, null, 2));
 }
 

.rovodev/skills/impeccable/scripts/load-context.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared context loader for every impeccable command that needs to know
+ * "who is this for" and "what does this look like".
+ *
+ * Input: project root (process.cwd()).
+ *
+ * Output (JSON to stdout):
+ *   {
+ *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
+ *     product: string | null,     // PRODUCT.md contents
+ *     productPath: string | null, // relative path
+ *     hasDesign: boolean,         // DESIGN.md found
+ *     design: string | null,      // DESIGN.md contents
+ *     designPath: string | null,
+ *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
+ *   }
+ *
+ * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
+ * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
+ * lowercase variants are also matched so users don't get punished for case.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
+const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
+const LEGACY_NAMES = ['.impeccable.md'];
+
+export function loadContext(cwd = process.cwd()) {
+  let migrated = false;
+
+  // 1. Look for PRODUCT.md (case-insensitive)
+  let productPath = firstExisting(cwd, PRODUCT_NAMES);
+
+  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists, rename in place
+  if (!productPath) {
+    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
+    if (legacyPath) {
+      const newPath = path.join(cwd, 'PRODUCT.md');
+      try {
+        fs.renameSync(legacyPath, newPath);
+        productPath = newPath;
+        migrated = true;
+      } catch {
+        // Rename failed (permissions, etc.) — fall back to reading legacy in place
+        productPath = legacyPath;
+      }
+    }
+  }
+
+  // 3. DESIGN.md (case-insensitive)
+  const designPath = firstExisting(cwd, DESIGN_NAMES);
+
+  const product = productPath ? safeRead(productPath) : null;
+  const design = designPath ? safeRead(designPath) : null;
+
+  return {
+    hasProduct: !!product,
+    product,
+    productPath: productPath ? path.relative(cwd, productPath) : null,
+    hasDesign: !!design,
+    design,
+    designPath: designPath ? path.relative(cwd, designPath) : null,
+    migrated,
+  };
+}
+
+function firstExisting(cwd, names) {
+  for (const name of names) {
+    const abs = path.join(cwd, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode — print the context as JSON
+// ---------------------------------------------------------------------------
+
+function cli() {
+  const result = loadContext(process.cwd());
+  console.log(JSON.stringify(result, null, 2));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
+  cli();
+}

.rovodev/skills/impeccable/scripts/pin.mjs

@@ -27,7 +27,7 @@ const HARNESS_DIRS = [
 
 // Valid sub-command names
 const VALID_COMMANDS = [
-  'craft', 'teach', 'extract', 'shape',
+  'craft', 'teach', 'extract', 'document', 'shape',
   'critique', 'audit',
   'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
   'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',

.trae-cn/skills/impeccable/SKILL.md

@@ -3,7 +3,7 @@ name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
 version: 3.0.0
 user-invocable: true
-argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|extract|live] [target]"
+argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target]"
 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
 ---
 
@@ -29,10 +29,17 @@ After running the script, delete this entire section (from `<post-update-cleanup
 
 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
 
+Impeccable recognizes two complementary context files at the project root:
+
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme & atmosphere, color palette & roles, typography rules, component stylings, layout principles. Answers "how it looks". Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+
+Filename matching is case-insensitive for both. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
 **Required context** (every design skill needs at minimum):
-- **Target audience**: Who uses this product and in what context?
-- **Use cases**: What jobs are they trying to get done?
-- **Brand personality/tone**: How should the interface feel?
+- **Target audience**: Who uses this product and in what context? → PRODUCT.md
+- **Use cases**: What jobs are they trying to get done? → PRODUCT.md
+- **Brand personality/tone**: How should the interface feel? → PRODUCT.md (and DESIGN.md's Visual Theme & Atmosphere)
 
 Individual sub-commands may require additional context. Check the commands' preparation section for specifics.
 
@@ -40,8 +47,8 @@ Individual sub-commands may require additional context. Check the commands' prep
 
 **Gathering order:**
 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
-2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
-3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+2. **Load PRODUCT.md + DESIGN.md (fast)**: Run `node .trae-cn/skills/impeccable/scripts/load-context.mjs`. It returns both files as JSON and auto-migrates legacy `.impeccable.md` to `PRODUCT.md` if needed (reports via `migrated: true`). If `hasProduct` is true, proceed. If `hasDesign` is false, do a gentle one-time nudge: "Consider running `/impeccable document` to generate a DESIGN.md from your existing code so variants stay on-brand."
+3. **Run impeccable teach (REQUIRED)**: If `hasProduct` is false, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
 
 ---
 
@@ -301,7 +308,8 @@ This skill supports sub-commands. Parse the first word of the argument string to
 > **Build & Plan**
 > `/impeccable craft [feature]` - Shape, then build a feature end-to-end
 > `/impeccable shape [feature]` - Plan UX/UI before writing code
-> `/impeccable teach` - Set up design context for this project (one-time)
+> `/impeccable teach` - Set up PRODUCT.md and DESIGN.md context for this project
+> `/impeccable document` - Generate DESIGN.md from existing project code
 > `/impeccable extract [target]` - Pull reusable tokens and components into design system
 >
 > **Evaluate**
@@ -347,6 +355,7 @@ When a sub-command is matched, load the linked reference and follow its instruct
 | `craft` | [craft](reference/craft.md) | Full shape-then-build flow with visual iteration |
 | `teach` | [teach](reference/teach.md) | One-time setup: gather design context for the project |
 | `extract` | [extract](reference/extract.md) | Pull reusable tokens and components into design system |
+| `document` | [document](reference/document.md) | Generate DESIGN.md from existing project code (visual design system doc) |
 | `shape` | [shape](reference/shape.md) | Plan UX and UI before writing code (produces a design brief) |
 | `critique` | [critique](reference/critique.md) | UX design review with heuristic scoring and persona testing |
 | `audit` | [audit](reference/audit.md) | Technical quality checks across a11y, perf, theming, responsive, anti-patterns |

.trae-cn/skills/impeccable/reference/audit.md

@@ -95,7 +95,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +114,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`** — Brief description (specific context from audit findings)
 2. **[P?] `/command-name`** — Brief description (specific context)
 
-**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with `/impeccable polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user:
 

.trae-cn/skills/impeccable/reference/critique.md

@@ -132,7 +132,7 @@ For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuris
 - **[P?] What**: Name the problem clearly
 - **Why it matters**: How this hurts users or undermines goals
 - **Fix**: What to do about it (be concrete)
-- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
 
 #### Persona Red Flags
 > *Consult [personas](personas.md)*
@@ -197,7 +197,7 @@ List recommended commands in priority order, based on the user's answers:
 ...
 
 **Rules for recommendations**:
-- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
 - Order by the user's stated priorities first, then by impact
 - Each item's description should carry enough context that the command knows what to focus on
 - Map each Priority Issue to the appropriate command

.trae-cn/skills/impeccable/reference/document.md

@@ -0,0 +1,126 @@
+Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
+
+## When to run
+
+- The user just ran `/impeccable teach` and needs the visual side documented.
+- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
+- 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 and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
+
+## Process (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** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., 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 by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
+- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
+- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
+- **Radii & shadows**: List the values used.
+- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+
+### Step 3: Ask the user for qualitative language
+
+The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
+
+- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
+- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
+- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
+- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
+
+If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
+
+### Step 4: Write DESIGN.md
+
+Use this exact structure (section headers must match the Google spec character-for-character):
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [optional — only if a Stitch project ID exists]
+
+## 1. Visual Theme & Atmosphere
+
+[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
+
+## 2. Color Palette & Roles
+
+### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
+- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
+
+## 3. Typography Rules
+
+**Primary Font Family:** [Name]
+**Character:** [1-sentence personality description.]
+
+### Hierarchy & Weights
+- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
+
+### Spacing Principles
+[Short list of rules about leading, letter-spacing, vertical rhythm.]
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** [radius description with px value in parens]
+- **Primary CTA:** [color assignment + padding]
+- **Hover State:** [transition description]
+- **Focus State:** [accessibility treatment]
+- **Secondary CTA (if applicable):** [description]
+
+### Cards & Containers
+- **Corner Style:** [description]
+- **Background:** [colors used]
+- **Shadow Strategy:** [flat / soft / heavy]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+- **Image Treatment:** [if relevant]
+
+### Navigation
+- [Style, typography, default/hover/active states, mobile treatment]
+
+### Inputs/Forms
+- [Stroke style, background, focus treatment]
+
+## 5. Layout Principles
+
+[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
+```
+
+### Step 5: Write & confirm
+
+1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
+2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+## Style guidelines
+
+- **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.
+- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
+- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
+
+## 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.

.trae-cn/skills/impeccable/reference/live.md

@@ -21,12 +21,21 @@ Output JSON:
   "serverPort": 8400,
   "serverToken": "...",
   "pageFile": "public/index.html",
-  "hasContext": true,
-  "context": "...full .impeccable.md contents..."
+  "hasProduct": true,
+  "product": "...full PRODUCT.md contents...",
+  "productPath": "PRODUCT.md",
+  "hasDesign": true,
+  "design": "...full DESIGN.md contents...",
+  "designPath": "DESIGN.md",
+  "migrated": false
 }
 ```
 
-Keep the `context` in mind for variant generation. If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
+Keep **PRODUCT.md** (strategic: users, brand, principles) and **DESIGN.md** (visual: colors, typography, components) in mind for variant generation. **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.**
+
+If `migrated` is true, the loader auto-renamed legacy `.impeccable.md` to `PRODUCT.md` — mention this once to the user and suggest running `/impeccable document` to also generate a `DESIGN.md`.
+
+If browser automation tools are available, navigate to the page so the user can see it. Then proceed directly to the poll loop — no other setup steps needed.
 
 ### First-time setup (config missing)
 

.trae-cn/skills/impeccable/reference/teach.md

@@ -1,8 +1,31 @@
 # Teach Flow
 
-One-time setup that gathers design context for a project. Design without context produces generic output, so every other command reads this file before doing any work.
+Gathers design context for a project and writes two complementary files at the project root:
 
-## Step 1: Explore the Codebase
+- **PRODUCT.md** (strategic): target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node {{scripts_path}}/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `/impeccable document` for DESIGN.md.
+- **Both exist**: ask the user directly to clarify what you cannot infer. which to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+## Step 2: Explore the codebase
 
 Before asking questions, thoroughly scan the project to discover what you can:
 
@@ -13,9 +36,9 @@ Before asking questions, thoroughly scan the project to discover what you can:
 - **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 - **Any style guides or brand documentation**
 
-Note what you've learned and what remains unclear.
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 
-## Step 2: Ask UX-Focused Questions
+## Step 3: Ask strategic questions (for PRODUCT.md)
 
 ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
 
@@ -29,39 +52,53 @@ ask the user directly to clarify what you cannot infer. Focus only on what you c
 - Any reference sites or apps that capture the right feel? What specifically about them?
 - What should this explicitly NOT look like? Any anti-references?
 
-### Aesthetic Preferences
-- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
-- Light mode, dark mode, or both?
-- Any colors that must be used or avoided?
-
 ### Accessibility & Inclusion
 - Specific accessibility requirements? (WCAG level, known user needs)
 - Considerations for reduced motion, color blindness, or other accommodations?
 
-Skip questions where the answer is already clear from the codebase exploration.
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
 
-## Step 3: Write Design Context
+## Step 4: Write PRODUCT.md
 
-Synthesize your findings and the user's answers into a `## Design Context` section:
+Synthesize into a strategic document:
 
 ```markdown
-## Design Context
+# Product
 
-### Users
+## Users
 [Who they are, their context, the job to be done]
 
-### Brand Personality
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
 [Voice, tone, 3-word personality, emotional goals]
 
-### Aesthetic Direction
-[Visual tone, references, anti-references, theme]
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
 
-### Design Principles
-[3-5 principles derived from the conversation that should guide all design decisions]
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "editorial over marketing", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
 ```
 
-Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
 
-Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to RULES.md. If yes, append or update the section there as well.
+## Step 5: Decide on DESIGN.md
 
-Confirm completion and summarize the key design principles that will now guide all future work.
+If the project has meaningful code to analyze (CSS tokens, components, a running site), **offer to run `/impeccable document`** next: "I can also generate a DESIGN.md that captures your visual design system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+
+If the user agrees, delegate to `/impeccable document` (load its reference and follow that flow).
+
+If the project is empty (no code yet, pre-implementation), skip DESIGN.md — there's nothing visual to document yet. Mention: "Once you've built some of the interface, run `/impeccable document` to generate a DESIGN.md."
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to RULES.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

.trae-cn/skills/impeccable/scripts/command-metadata.json

@@ -4,7 +4,11 @@
     "argumentHint": "[feature description]"
   },
   "teach": {
-    "description": "One-time setup that gathers design context for a project. Runs a short discovery interview and writes the answers to .impeccable.md. Every other command reads this file before doing work. Use once per project.",
+    "description": "Gathers design context for a project. Runs a short discovery interview and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
     "argumentHint": ""
   },
   "extract": {