Loading commands...
-` placeholders.
+- **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel".
+- **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one.
+- **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish".
+
+Tech / dev-tool brands are the exception where zero imagery can be correct — a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on.
+
+## Motion
+
+- One well-orchestrated page-load with staggered reveals beats scattered micro-interactions — when the brand invites it. Tech-minimal brands often skip entrance motion entirely; the restraint is the voice.
+- For collapsing/expanding sections, transition `grid-template-rows` rather than `height`.
+
+## Brand bans (on top of the shared absolute bans)
+
+- Monospace as lazy shorthand for "technical / developer." If the brand isn't technical, mono reads as costume.
+- Large rounded-corner icons above every heading. Screams template.
+- Single-family pages that picked the family by reflex, not voice. (A single family chosen deliberately is fine.)
+- All-caps body copy. Reserve caps for short labels and headings.
+- Timid palettes and average layouts. Safe = invisible.
+- Zero imagery on a brief that implies imagery (restaurant, hotel, food, travel, fashion, photography, hobbyist). Colored blocks where a hero photo belongs.
+- Defaulting to editorial-magazine aesthetics (display serif + italic + drop caps + broadsheet grid) on briefs that aren't magazine-shaped. Editorial is ONE aesthetic lane, not the default brand aesthetic.
+
+## Brand permissions
+
+Brand can afford things product can't. Take them.
+
+- Ambitious first-load motion. Reveals, scroll-triggered transitions, typographic choreography.
+- Single-purpose viewports. One dominant idea per fold, long scroll, deliberate pacing.
+- Typographic risk. Enormous display type, unexpected italic cuts, mixed cases, hand-drawn headlines, a single oversize word as a hero.
+- Unexpected color strategies. Palette IS voice — a calm brand and a restless brand should not share palette mechanics.
+- Art direction per section. Different sections can have different visual worlds if the narrative demands it. Consistency of voice beats consistency of treatment.
diff --git a/.pi/skills/clarify/SKILL.md b/.agents/skills/impeccable/reference/clarify.md
similarity index 89%
rename from .pi/skills/clarify/SKILL.md
rename to .agents/skills/impeccable/reference/clarify.md
index 468541090..dc116e745 100644
--- a/.pi/skills/clarify/SKILL.md
+++ b/.agents/skills/impeccable/reference/clarify.md
@@ -1,14 +1,7 @@
----
-name: clarify
-description: Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing.
-version: 2.1.1
----
+> **Additional context needed**: audience technical level and users' mental state in context.
Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
-## MANDATORY PREPARATION
-
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: audience technical level and users' mental state in context.
---
@@ -178,4 +171,4 @@ Test that copy improvements work:
- **Consistency**: Does it match terminology elsewhere?
- **Tone**: Is it appropriate for the situation?
-Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.
\ No newline at end of file
+Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.
diff --git a/.agents/skills/critique/reference/cognitive-load.md b/.agents/skills/impeccable/reference/cognitive-load.md
similarity index 100%
rename from .agents/skills/critique/reference/cognitive-load.md
rename to .agents/skills/impeccable/reference/cognitive-load.md
diff --git a/.agents/skills/colorize/SKILL.md b/.agents/skills/impeccable/reference/colorize.md
similarity index 75%
rename from .agents/skills/colorize/SKILL.md
rename to .agents/skills/impeccable/reference/colorize.md
index 76075804f..176185e69 100644
--- a/.agents/skills/colorize/SKILL.md
+++ b/.agents/skills/impeccable/reference/colorize.md
@@ -1,16 +1,14 @@
----
-name: colorize
-description: Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette.
-version: 2.1.1
-user-invocable: true
-argument-hint: "[target]"
----
+> **Additional context needed**: existing brand colors.
Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality.
-## MANDATORY PREPARATION
+---
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: existing brand colors.
+## Register
+
+Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule — that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it.
+
+Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators — not decoration. Every color has a consistent meaning across every screen.
---
@@ -83,10 +81,13 @@ Add color systematically across these dimensions:
- **Comparison**: Color coding for different datasets or timeframes
### Borders & Accents
-- **Accent borders**: Add colored left/top borders to cards or sections
+- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`)
- **Underlines**: Color underlines for emphasis or active states
- **Dividers**: Subtle colored dividers instead of gray lines
- **Focus rings**: Colored focus indicators matching brand
+- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe
+
+**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe.
### Typography Color
- **Colored headings**: Use brand colors for section headings (maintain contrast)
@@ -140,4 +141,14 @@ Test that colorization improves the experience:
- **Still accessible**: Do all color combinations meet WCAG standards?
- **Not overwhelming**: Is color balanced and purposeful?
-Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional.
\ No newline at end of file
+Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional.
+
+## Live-mode signature params
+
+When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)` — typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage.
+
+```json
+{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"}
+```
+
+Layer 1-2 variant-specific params on top: palette selection (`steps` with named options), temperature warmth, or tint vs. true color. See `reference/live.md` for the full params contract.
diff --git a/.agents/skills/impeccable/reference/craft.md b/.agents/skills/impeccable/reference/craft.md
index 8cddbc9db..45249f46c 100644
--- a/.agents/skills/impeccable/reference/craft.md
+++ b/.agents/skills/impeccable/reference/craft.md
@@ -4,11 +4,11 @@ Build a feature with impeccable UX and UI quality through a structured process:
## Step 1: Shape the Design
-Run /shape, passing along whatever feature description the user provided.
+Run $impeccable shape, passing along whatever feature description the user provided.
Wait for the design brief to be fully confirmed before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.
-If the user has already run /shape and has a confirmed design brief, skip this step and use the existing brief.
+If the user has already run $impeccable shape and has a confirmed design brief, skip this step and use the existing brief.
## Step 2: Load References
@@ -24,7 +24,61 @@ Then add references based on the brief's needs:
- Responsive requirements? Consult [responsive-design.md](responsive-design.md)
- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md)
-## Step 3: Build
+## Step 3: North Star Mock (Capability-Gated)
+
+Before implementation, generate a small set of high-fidelity visual comps when all of these are true:
+
+- The work is **net-new** or visually open-ended enough that composition exploration will improve the build.
+- The brief's scope is **mid-fi, high-fi, or production-ready**.
+- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this.
+
+When those conditions are met, this step is the default for **both brand and product work**.
+
+### Purpose
+
+Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone.
+
+### What to generate
+
+Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief.
+
+- For brand work, push visual identity, composition, and mood aggressively.
+- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states.
+
+The comps must be genuinely different in primary visual direction, not just color variants.
+
+### After generation
+
+Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why.
+
+Before moving to implementation, summarize:
+
+- What to carry into code
+- What **not** to literalize from the mock
+
+Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief.
+
+## Step 4: Asset Extraction (Optional)
+
+If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building.
+
+Good candidates:
+
+- stickers
+- badges
+- seals
+- tickets
+- graphic labels
+- textures
+- abstract objects
+- decorative marks
+- non-semantic scene elements
+
+Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code.
+
+Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets.
+
+## Step 5: Build
Implement the feature following the design brief. Work in this order:
@@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order:
- Test with real (or realistic) data at every step, not placeholder text
- Check each state as you build it, not all at the end
- If you discover a design question, stop and ask rather than guessing
-- Every visual choice should trace back to something in the design brief
+- Every visual choice should trace back to something in the design brief or the chosen north-star direction
+- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI
+- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure
-## Step 4: Visual Iteration
+## Step 6: Visual Iteration
**This step is critical.** Do not stop after the first implementation pass.
@@ -59,12 +115,12 @@ Iterate through these checks visually:
After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights."
-## Step 5: Present
+## Step 7: Present
Present the result to the user:
- Show the feature in its primary state
- Walk through the key states (empty, error, responsive)
-- Explain design decisions that connect back to the design brief
+- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock
- Ask: "What's working? What isn't?"
Iterate based on feedback. Good design is rarely right on the first pass.
diff --git a/.codex/skills/critique/SKILL.md b/.agents/skills/impeccable/reference/critique.md
similarity index 78%
rename from .codex/skills/critique/SKILL.md
rename to .agents/skills/impeccable/reference/critique.md
index 185049999..78fa241ce 100644
--- a/.codex/skills/critique/SKILL.md
+++ b/.agents/skills/impeccable/reference/critique.md
@@ -1,23 +1,12 @@
----
-name: critique
-description: Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, automated anti-pattern detection, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component.
-version: 2.1.1
-argument-hint: "[area (feature, page, component...)]"
----
+> **Additional context needed**: what the interface is trying to accomplish.
-## STEPS
+### Gather Assessments
-### Step 1: Preparation
+Launch two independent assessments. **Neither may see the other's output** — this isolation is what makes the combined score honest. Running both in one head silently anchors them to each other; do not shortcut it for cost, speed, or context-size reasons.
-Invoke $impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run $impeccable teach first. Additionally gather: what the interface is trying to accomplish.
+Delegate each assessment to a separate sub-agent (Claude Code's `Agent` tool, Codex's subagent spawning, etc.). Each returns structured findings as text. Do NOT output findings to the user yet.
-### Step 2: Gather Assessments
-
-Launch two independent assessments. **Neither must see the other's output** to avoid bias.
-
-You SHOULD delegate each assessment to a separate sub-agent for independence. Use your environment's agent spawning mechanism (e.g., Claude Code's `Agent` tool, or Codex's subagent spawning). Sub-agents should return their findings as structured text. Do NOT output findings to the user yet.
-
-If sub-agents are not available in the current environment, complete each assessment sequentially, writing findings to internal notes before proceeding.
+Fall back to sequential in-head work only if the environment genuinely cannot spawn sub-agents.
**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state.
@@ -29,11 +18,11 @@ document.title = '[LLM] ' + document.title;
```
Think like a design director. Evaluate:
-**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately?
+**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines from the parent impeccable skill (already loaded in this context). Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately?
**Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness).
-**Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)):
+**Cognitive Load** (consult [cognitive-load](cognitive-load.md)):
- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical.
- Count visible options at each decision point. If >4, flag it.
- Check for progressive disclosure: is complexity revealed only when needed?
@@ -43,7 +32,7 @@ Think like a design director. Evaluate:
- **Peak-end rule**: Is the most intense moment positive? Does the experience end well?
- **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)?
-**Nielsen's Heuristics** (consult [heuristics-scoring](reference/heuristics-scoring.md)):
+**Nielsen's Heuristics** (consult [heuristics-scoring](heuristics-scoring.md)):
Score each of the 10 heuristics 0-4. This scoring will be presented in the report.
Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions.
@@ -63,7 +52,7 @@ npx impeccable --json [--fast] [target]
- For 500+ files, narrow scope or ask the user
- Exit code 0 = clean, 2 = findings
-**Browser visualization** (when browser automation tools are available AND the target is a viewable page):
+**Browser visualization** — **required** when browser automation tools are available AND the target is a viewable page. The `[Human]` overlay tab is the user-facing deliverable; the critique is incomplete without it. Skip only if the target is not a viewable page (CSS-only file, non-browser target).
The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically.
@@ -93,14 +82,14 @@ For multi-view targets, inject on 3-5 representative pages. If injection fails,
Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted.
-### Step 3: Generate Combined Critique Report
+### Generate Combined Critique Report
Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives.
Structure your feedback as a design director would:
#### Design Health Score
-> *Consult [heuristics-scoring](reference/heuristics-scoring.md)*
+> *Consult [heuristics-scoring](heuristics-scoring.md)*
Present the Nielsen's 10 heuristics scores as a table:
@@ -139,14 +128,14 @@ Highlight 2-3 things done well. Be specific about why they work.
#### Priority Issues
The 3-5 most impactful design problems, ordered by importance.
-For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions):
+For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuristics-scoring.md) for severity definitions):
- **[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: $animate, $quieter, $shape, $optimize, $adapt, $clarify, $layout, $distill, $delight, $audit, $harden, $polish, $bolder, $typeset, $critique, $colorize, $overdrive)
+- **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](reference/personas.md)*
+> *Consult [personas](personas.md)*
Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `AGENTS.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info.
@@ -175,7 +164,7 @@ Provocative questions that might unlock better solutions:
- Prioritize ruthlessly. If everything is important, nothing is.
- Don't soften criticism. Developers need honest feedback to ship great design.
-### Step 4: Ask the User
+### Ask the User
**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan.
@@ -183,7 +172,7 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene
1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options.
-2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer$bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found.
+2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found.
3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only".
@@ -193,11 +182,11 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene
- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions.
- Keep it to 2-4 questions maximum. Respect the user's time.
- Offer concrete options, not open-ended prompts.
-- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Step 5.
+- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Recommended Actions.
-### Step 5: Recommended Actions
+### Recommended Actions
-**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Step 4.
+**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Ask the User.
#### Action Summary
@@ -208,17 +197,17 @@ List recommended commands in priority order, based on the user's answers:
...
**Rules for recommendations**:
-- Only recommend commands from: $animate, $quieter, $shape, $optimize, $adapt, $clarify, $layout, $distill, $delight, $audit, $harden, $polish, $bolder, $typeset, $critique, $colorize, $overdrive
+- 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
- Skip commands that would address zero issues
- If the user chose a limited scope, only include items within that scope
- If the user marked areas as off-limits, exclude commands that would touch those areas
-- End with `$polish` as the final step if any fixes were recommended
+- End with `$impeccable polish` as the final step if any fixes were recommended
After presenting the summary, tell the user:
> You can ask me to run these one at a time, all at once, or in any order you prefer.
>
-> Re-run `$critique` after fixes to see your score improve.
\ No newline at end of file
+> Re-run `$impeccable critique` after fixes to see your score improve.
diff --git a/.kiro/skills/delight/SKILL.md b/.agents/skills/impeccable/reference/delight.md
similarity index 92%
rename from .kiro/skills/delight/SKILL.md
rename to .agents/skills/impeccable/reference/delight.md
index f323738dd..5112bef3c 100644
--- a/.kiro/skills/delight/SKILL.md
+++ b/.agents/skills/impeccable/reference/delight.md
@@ -1,14 +1,14 @@
----
-name: delight
-description: Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.
-version: 2.1.1
----
+> **Additional context needed**: what's appropriate for the domain (playful vs professional vs quirky vs elegant).
Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences.
-## MANDATORY PREPARATION
+---
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant).
+## Register
+
+Brand: delight can be distributed — copy voice, section transitions, discovery rewards, seasonal touches, personality across the whole surface.
+
+Product: delight at specific moments, not pages. Completion, first-time actions, error recovery, milestone crossings. Reliability and consistency carry the rest of the experience; delight pushed everywhere reads as noise.
---
@@ -299,4 +299,4 @@ Test that delight actually delights:
- **Appropriate**: Matches brand and context
- **Accessible**: Works with reduced motion, screen readers
-Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct.
\ No newline at end of file
+Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct.
diff --git a/.gemini/skills/distill/SKILL.md b/.agents/skills/impeccable/reference/distill.md
similarity index 91%
rename from .gemini/skills/distill/SKILL.md
rename to .agents/skills/impeccable/reference/distill.md
index e462d1c27..4f47dc0b4 100644
--- a/.gemini/skills/distill/SKILL.md
+++ b/.agents/skills/impeccable/reference/distill.md
@@ -1,14 +1,5 @@
----
-name: distill
-description: Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when the user asks to simplify, declutter, reduce noise, remove elements, or make a UI cleaner and more focused.
-version: 2.1.1
----
-
Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification.
-## MANDATORY PREPARATION
-
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first.
---
@@ -117,4 +108,4 @@ If you removed features or options:
- Consider if they need alternative access points
- Note any user feedback to monitor
-Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."
\ No newline at end of file
+Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."
diff --git a/.agents/skills/impeccable/reference/document.md b/.agents/skills/impeccable/reference/document.md
new file mode 100644
index 000000000..572b7d879
--- /dev/null
+++ b/.agents/skills/impeccable/reference/document.md
@@ -0,0 +1,427 @@
+Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): YAML frontmatter carrying machine-readable design tokens, followed by a markdown body with exactly six sections in a fixed order. **Tokens are normative; prose provides context for how to apply them.** Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
+
+## The frontmatter: token schema
+
+The YAML frontmatter is the machine-readable layer. It's what Stitch's linter validates and what the live panel renders tiles from. Keep it tight; every entry should correspond to a token the project actually uses.
+
+```yaml
+---
+name:
+description:
+colors:
+ primary: "#b8422e"
+ neutral-bg: "#faf7f2"
+ # ...one entry per extracted color; key = descriptive slug
+typography:
+ display:
+ fontFamily: "Cormorant Garamond, Georgia, serif"
+ fontSize: "clamp(2.5rem, 7vw, 4.5rem)"
+ fontWeight: 300
+ lineHeight: 1
+ letterSpacing: "normal"
+ body:
+ # ...
+rounded:
+ sm: "4px"
+ md: "8px"
+spacing:
+ sm: "8px"
+ md: "16px"
+components:
+ button-primary:
+ backgroundColor: "{colors.primary}"
+ textColor: "{colors.neutral-bg}"
+ rounded: "{rounded.sm}"
+ padding: "16px 48px"
+ button-primary-hover:
+ backgroundColor: "{colors.primary-deep}"
+---
+```
+
+Rules that matter:
+
+- **Token refs** use `{path.to.token}` (e.g. `{colors.primary}`, `{rounded.md}`). Components may reference primitives; primitives may not reference each other.
+- **Stitch validates colors as hex sRGB only** (`#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`); OKLCH/HSL/P3 trigger a linter warning, not a hard error. YAML accepts the string either way and our own parser is format-agnostic. Choose based on project posture: (a) if the project has an "OKLCH-only" doctrine or uses Display-P3 values that don't round-trip through sRGB, put OKLCH directly in the frontmatter and accept the Stitch linter warning; (b) if the project wants strict Stitch compliance or plans to use their Tailwind/DTCG export pipeline, put hex in the frontmatter and keep OKLCH in prose as the canonical reference. Never split the source of truth without explicit reason.
+- **Component sub-tokens** are limited to 8 props: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Shadows, motion, focus rings, backdrop-filter — none of those fit. Carry them in the sidecar (Step 4b).
+- **Scale keys are open-ended.** Use whatever names the project already uses (`warm-ash-cream`, `surface-container-low`). Don't rename to Material defaults.
+- **Variants are naming convention, not schema.** `button-primary` / `button-primary-hover` / `button-primary-active` as sibling keys.
+
+## The markdown body: six sections (exact order)
+
+1. `## Overview`
+2. `## Colors`
+3. `## Typography`
+4. `## Elevation`
+5. `## Components`
+6. `## Do's and Don'ts`
+
+Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
+
+## 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, overwrite, or merge.
+
+## Two paths
+
+- **Scan mode** (default): the project has design tokens, components, or rendered output. Extract, then confirm descriptive language. Use when there's code to analyze.
+- **Seed mode**: the project is pre-implementation (fresh teach, nothing built yet). Interview for five high-level answers, write a minimal DESIGN.md marked ``. Re-run in scan mode once there's code.
+
+Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no component files, and no rendered site, offer seed mode — don't silently switch. `$impeccable document --seed` forces seed mode regardless of code presence.
+
+## Scan mode (approach C: auto-extract, then confirm descriptive language)
+
+### Step 1: Find the design assets
+
+Search the codebase in priority order:
+
+1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
+2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
+3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
+4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
+5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
+6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
+7. **Visible rendered output** — if browser automation tools are available, load the live site and sample computed styles from key elements (body, h1, a, button, .card). This catches values that tokens miss.
+
+### Step 2: Auto-extract what can be auto-extracted
+
+Build a structured draft from the discovered tokens. For each token class:
+
+- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
+- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
+- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
+- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
+
+### Step 2b: Stage the frontmatter
+
+From the auto-extracted tokens, draft the YAML frontmatter now (you'll write it at the top of DESIGN.md in Step 4). This is the machine-readable layer — what the live panel and Stitch's linter consume.
+
+- **Colors**: one entry per extracted color. Key = descriptive slug (`warm-ash-cream`, `editorial-magenta`, not `blue-800`). Value = whichever format the project treats as canonical (OKLCH or hex — see the frontmatter rules above). Don't split the source of truth: one format in the frontmatter, don't redefine the same token in prose with a different value.
+- **Typography**: one entry per role (`display`, `headline`, `title`, `body`, `label`). Typography is an object; include only the props that are real for the project (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`).
+- **Rounded / Spacing**: whatever scale steps the project actually uses, keyed by whatever scale name the project uses (`sm` / `md` / `lg`, or `surface-sm`, or numeric steps).
+- **Components**: one entry per variant (`button-primary`, `button-primary-hover`, `button-ghost`). Reference primitives via `{colors.X}`, `{rounded.Y}`. If a variant needs a property Stitch's 8-prop set doesn't cover (shadow, focus ring, backdrop-filter), carry the full snippet in the sidecar instead.
+
+Skip anything the project doesn't have. Empty scale keys or fabricated tokens pollute the spec.
+
+### Step 3: Ask the user for qualitative language
+
+The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
+
+- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
+- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
+- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
+- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
+
+Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
+
+### Step 4: Write DESIGN.md
+
+The file opens with the YAML frontmatter staged in Step 2b (schema documented at the top of this reference), then the markdown body using the structure below. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
+
+```markdown
+---
+name: [Project Title]
+description: [one-line tagline]
+colors:
+ # ... staged frontmatter from Step 2b
+---
+
+# Design System: [Project Title]
+
+## 1. Overview
+
+**Creative North Star: "[Named metaphor in quotes]"**
+
+[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
+
+## 2. Colors
+
+[Describe the palette character in one sentence.]
+
+### Primary
+- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
+
+### Secondary (optional — omit if the project has only one accent)
+- **[Descriptive Name]** (#HEX): [Role.]
+
+### Tertiary (optional)
+- **[Descriptive Name]** (#HEX): [Role.]
+
+### Neutral
+- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
+- [...]
+
+### Named Rules (optional, powerful)
+**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
+
+## 3. Typography
+
+**Display Font:** [Family] (with [fallback])
+**Body Font:** [Family] (with [fallback])
+**Label/Mono Font:** [Family, if distinct]
+
+**Character:** [1-2 sentence personality description of the pairing.]
+
+### Hierarchy
+- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
+- **Headline** ([weight], [size], [line-height]): [Purpose.]
+- **Title** ([weight], [size], [line-height]): [Purpose.]
+- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
+- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
+
+### Named Rules (optional)
+**The [Rule Name] Rule.** [Short doctrine about type use.]
+
+## 4. Elevation
+
+[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
+
+### Shadow Vocabulary (if applicable)
+- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
+- [...]
+
+### Named Rules (optional)
+**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
+
+## 5. Components
+
+For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
+
+### Buttons
+- **Shape:** [radius described, exact value in parens]
+- **Primary:** [color assignment + padding, in semantic + exact terms]
+- **Hover / Focus:** [transitions, treatments]
+- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
+
+### Chips (if used)
+- **Style:** [background, text color, border treatment]
+- **State:** [selected / unselected, filter / action variants]
+
+### Cards / Containers
+- **Corner Style:** [radius]
+- **Background:** [colors used]
+- **Shadow Strategy:** [reference Elevation section]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+
+### Inputs / Fields
+- **Style:** [stroke, background, radius]
+- **Focus:** [treatment — glow, border shift, etc.]
+- **Error / Disabled:** [if applicable]
+
+### Navigation
+- **Style, typography, default/hover/active states, mobile treatment.**
+
+### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
+[Description.]
+
+## 6. Do's and Don'ts
+
+Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md. **Every anti-reference in PRODUCT.md should show up here as a "Don't" with the same language**, so the visual spec carries the strategic line through. Quote PRODUCT.md directly where possible: if PRODUCT.md says *"avoid dark mode with purple gradients, neon accents, glassmorphism"*, the Don'ts here should repeat that by name.
+
+### Do:
+- **Do** [specific prescription with exact values / named rule].
+- **Do** [...]
+
+### Don't:
+- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
+- **Don't** [...]
+- **Don't** [...]
+```
+
+### Step 4b: Write DESIGN.json sidecar (extensions only)
+
+The frontmatter owns token primitives (colors, typography, rounded, spacing, components). The sidecar at `DESIGN.json` carries **what Stitch's schema can't hold**: tonal ramps per color, shadow/elevation tokens, motion tokens, breakpoints, full component HTML/CSS snippets (the panel renders these into a shadow DOM), and narrative (north star, rules, do's/don'ts). It extends the frontmatter, it doesn't duplicate it.
+
+Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks to refresh the sidecar (e.g., from the live panel's stale-hint), preserve DESIGN.md and write only DESIGN.json.
+
+#### Schema
+
+```json
+{
+ "schemaVersion": 2,
+ "generatedAt": "ISO-8601 string",
+ "title": "Design System: [Project Title]",
+ "extensions": {
+ "colorMeta": {
+ "primary": { "role": "primary", "displayName": "Editorial Magenta", "canonical": "oklch(60% 0.25 350)", "tonalRamp": ["...", "...", "..."] },
+ "warm-ash-cream": { "role": "neutral", "displayName": "Warm Ash Cream", "canonical": "oklch(96% 0.005 350)", "tonalRamp": ["...", "...", "..."] }
+ },
+ "typographyMeta": {
+ "display": { "displayName": "Display", "purpose": "Hero headlines only." }
+ },
+ "shadows": [
+ { "name": "ambient-low", "value": "0 4px 24px rgba(0,0,0,0.12)", "purpose": "Diffuse hover glow under accent elements." }
+ ],
+ "motion": [
+ { "name": "ease-standard", "value": "cubic-bezier(0.4, 0, 0.2, 1)", "purpose": "Default easing for state transitions." }
+ ],
+ "breakpoints": [
+ { "name": "sm", "value": "640px" }
+ ]
+ },
+ "components": [
+ {
+ "name": "Primary Button",
+ "kind": "button | input | nav | chip | card | custom",
+ "refersTo": "button-primary",
+ "description": "One-line what and when.",
+ "html": "",
+ "css": ".ds-btn-primary { background: #191c1d; color: #fff; padding: 16px 48px; letter-spacing: 0.05em; text-transform: uppercase; font-weight: 500; border: none; border-radius: 0; transition: background 0.2s, transform 0.2s; } .ds-btn-primary:hover { background: oklch(60% 0.25 350); transform: translateY(-2px); }"
+ }
+ ],
+ "narrative": {
+ "northStar": "The Editorial Sanctuary",
+ "overview": "2-3 paragraphs of the philosophy — pulled from DESIGN.md Overview section.",
+ "keyCharacteristics": ["...", "..."],
+ "rules": [{ "name": "The One Voice Rule", "body": "...", "section": "colors|typography|elevation" }],
+ "dos": ["Do use ..."],
+ "donts": ["Don't use ..."]
+ }
+}
+```
+
+**What changed from schemaVersion 1.** The old sidecar carried token primitive arrays (`tokens.colors[]`, `tokens.typography[]`, etc.). Those values now live in the frontmatter. The sidecar only carries metadata that can't live in the frontmatter — tonal ramps, canonical OKLCH when the hex is an approximation, display names, role hints — keyed by the frontmatter token name (`colorMeta.`, `typographyMeta.`). Components still carry full HTML/CSS because Stitch's 8-prop set can't hold them.
+
+#### Component translation rules
+
+The `html` and `css` fields must be **self-contained, drop-in snippets** that render correctly when injected into a shadow DOM. The panel applies them directly — no post-processing, no framework runtime.
+
+1. **Tailwind expansion.** If the source uses Tailwind (className="bg-primary text-white rounded-lg px-6 py-3"), expand every utility to literal CSS properties in the `css` string. Do **not** reference Tailwind classes; do **not** assume a Tailwind CSS bundle is loaded. Each component is self-contained.
+2. **Token resolution.** If the project exposes tokens as CSS custom properties on `:root` (e.g. `--color-primary`, `--radius-md`), reference them via `var(--color-primary)` — they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time.
+3. **Icons.** Inline as SVG. Do not reference Lucide/Heroicons packages, icon fonts, or `
`. A typical icon is 16-24px; copy the SVG path data directly.
+4. **States.** Include `:hover`, `:focus-visible`, and (if meaningful) `:active` rules inline. A static default-only snapshot makes the panel feel dead. Hover + focus rules in the CSS make it feel alive.
+5. **Reset bloat.** Extract only the component's *distinctive* CSS (background, color, padding, border-radius, typography, transition). Skip universal resets (`box-sizing: border-box`, `line-height: inherit`, `-webkit-font-smoothing`). The panel already has a neutral canvas; don't re-ship resets.
+6. **Scoped class names.** Prefix every class with `ds-` (e.g. `ds-btn-primary`, `ds-input-search`) so component CSS doesn't collide with other components' CSS in the same shadow DOM.
+
+#### What to include
+
+Aim for a tight set of **5-10 components** that best represent the visual system:
+
+- **Canonical primitives (always include if the project has them):** button (each variant as a separate component entry), input/text field, navigation, chip/tag, card.
+- **Signature components (include if distinctive):** hero CTA, featured card, filter pill, any custom pattern the user mentioned as important in PRODUCT.md.
+- **Skip the rest.** Utility components, form building blocks, wrapper layouts — not worth documenting unless visually distinctive.
+
+If the project has **no component library yet** (bare landing page, new project), synthesize canonical primitives from the tokens using best-practice defaults consistent with the DESIGN.md's rules. Every DESIGN.json has *something* to render, even on day zero.
+
+#### Tonal ramps
+
+For each color token, generate an 8-step `tonalRamp` array — dark to light, same hue and chroma, stepped lightness from ~15% to ~95%. The panel renders this as a strip under the swatch. If the project already defines a tonal scale (Material `surface-container-low` family, Tailwind-style `blue-50..blue-900`), use those values. Otherwise synthesize in OKLCH.
+
+#### Narrative mapping
+
+Pull directly from the DESIGN.md you just wrote:
+
+- `narrative.northStar` → the `**Creative North Star: "..."**` line from Overview
+- `narrative.overview` → the philosophy paragraphs from Overview
+- `narrative.keyCharacteristics` → the bulleted `**Key Characteristics:**` list
+- `narrative.rules` → every `**The [Name] Rule.** [body]` across all sections, tagged with `section`
+- `narrative.dos` / `narrative.donts` → the bullet lists from Do's and Don'ts verbatim
+
+Do not reword. The panel shows these as secondary collapsible context; the same voice that's in the Markdown carries through.
+
+### Step 5: Confirm, refine, and refresh session cache
+
+1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules).
+2. Mention that `DESIGN.json` was also written alongside — the live panel will now render this project's actual button/input/nav primitives instead of generic approximations.
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+4. **Refresh the session cache.** Run `node .agents/skills/impeccable/scripts/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading.
+
+## Seed mode
+
+For projects with no visual system to extract yet. Produces a minimal scaffold, not a full spec.
+
+### Step 1: Confirm seed mode
+
+Before interviewing: "There's no existing visual system to scan. I'll ask five quick questions to seed a starter DESIGN.md. You can re-run `$impeccable document` once there's code, to capture the real tokens and components. OK?"
+
+If the user prefers to skip, stop. No file.
+
+### Step 2: Five questions
+
+Group into one `AskUserQuestion` interaction. Options must be concrete.
+
+1. **Color strategy.** Pick one:
+ - Restrained — tinted neutrals + one accent ≤10%
+ - Committed — one saturated color carries 30–60% of the surface
+ - Full palette — 3–4 named color roles, each deliberate
+ - Drenched — the surface IS the color
+
+ Then: one hue family or anchor reference ("deep teal", "mustard", "Klim #ff4500 orange").
+
+2. **Typography direction.** Pick one (specific fonts come later):
+ - Serif display + sans body
+ - Single sans (warm / technical / geometric / humanist — pick a feel)
+ - Display + mono
+ - Mono-forward
+ - Editorial script + sans
+
+3. **Motion energy.** Pick one:
+ - Restrained — state changes only
+ - Responsive — feedback + transitions, no choreography
+ - Choreographed — orchestrated entrances, scroll-driven sequences
+
+4. **Three named references.** Brands, products, printed objects. Not adjectives.
+
+5. **One anti-reference.** What it should NOT feel like. Also named.
+
+### Step 3: Write seed DESIGN.md
+
+Use the six-section spec from Scan mode. Populate what the interview answers; leave the rest as honest placeholders. The seed is a scaffold, not a fabricated spec.
+
+Lead the file with:
+
+```markdown
+
+```
+
+Per-section guidance in seed mode:
+
+- **Overview**: Creative North Star and philosophy phrased from the answers (color strategy + motion energy + references). Reference the user's anti-reference directly.
+- **Colors**: Color strategy as a Named Rule (e.g. *"The Drenched Rule. The surface IS the color."*). Hue family or anchor reference. No hex values — mark as `[to be resolved during implementation]`.
+- **Typography**: the direction the user picked (e.g. "Serif display + sans body"). No font names yet — `[font pairing to be chosen at implementation]`.
+- **Elevation**: inferred from motion energy. Restrained/Responsive → flat by default; Choreographed → layered. One sentence.
+- **Components**: omit entirely — no components exist yet.
+- **Do's and Don'ts**: carry PRODUCT.md's anti-references directly plus the anti-reference named in Q5.
+
+Seed mode writes a minimal frontmatter with `name` and `description` only — no colors, typography, rounded, spacing, or components yet. Real tokens land on the next Scan-mode run. Skip the `DESIGN.json` sidecar in seed mode for the same reason: nothing to render.
+
+### Step 4: Confirm and refresh session cache
+
+1. Show the seed DESIGN.md. Call out that it is a seed (the marker is the literal commitment).
+2. Tell the user: "Re-run `$impeccable document` once you have some code. That pass will extract real tokens and generate the sidecar."
+3. Run `node .agents/skills/impeccable/scripts/load-context.mjs` once so the seed lands in conversation for the rest of the session.
+
+## Style guidelines
+
+- **Frontmatter first, prose second.** Tokens go in the YAML frontmatter; prose contextualizes them. Don't redefine a token value in two places — the frontmatter is normative.
+- **Cite PRODUCT.md anti-references by name** in the Do's and Don'ts section. If PRODUCT.md lists "SaaS landing-page clichés" or "generic AI tool marketing" as anti-references, the DESIGN.md Don'ts should repeat those phrases verbatim so the visual spec enforces the strategic line.
+- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
+- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
+- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
+- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
+- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
+- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
+- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
+- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
+- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
+
+## Pitfalls
+
+- Don't paste raw CSS class names. Translate to descriptive language.
+- Don't extract every token. Stop at what's actually reused — one-offs pollute the system.
+- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
+- Don't overwrite an existing DESIGN.md without asking.
+- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
+- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
+- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
+- Don't duplicate token values between frontmatter and prose. If a color is in `colors.primary` as hex, the prose can name it and describe its role but should not reassert a different hex. The frontmatter is normative.
+- Don't invent frontmatter token groups outside Stitch's schema (no `motion:`, `breakpoints:`, `shadows:` at the top level). Stitch's Zod schema only accepts `colors`, `typography`, `rounded`, `spacing`, `components`. Anything else belongs in the sidecar's `extensions`.
diff --git a/.pi/skills/harden/SKILL.md b/.agents/skills/impeccable/reference/harden.md
similarity index 81%
rename from .pi/skills/harden/SKILL.md
rename to .agents/skills/impeccable/reference/harden.md
index 78eaa9881..a27c669a0 100644
--- a/.pi/skills/harden/SKILL.md
+++ b/.agents/skills/impeccable/reference/harden.md
@@ -1,9 +1,3 @@
----
-name: harden
-description: Make interfaces production-ready: error handling, empty states, onboarding flows, i18n, text overflow, and edge case management. Use when the user asks to harden, make production-ready, handle edge cases, add error states, design empty states, improve onboarding, or fix overflow and i18n issues.
-version: 2.1.1
----
-
Strengthen interfaces against edge cases, errors, internationalization issues, and real-world usage scenarios that break idealized designs.
## Assess Hardening Needs
@@ -223,40 +217,6 @@ t('items', { count }) // Handles complex plural rules
- Feature detection (not browser detection)
- Test in target browsers
-### Onboarding & First-Run Experience
-
-Production-ready features work for first-time users, not just power users. Design the paths that get new users to value:
-
-**Empty states**: Every zero-data screen needs:
-- What will appear here (description or illustration)
-- Why it matters to the user
-- Clear CTA to create the first item or start from a template
-- Visual interest (not just blank space with "No items yet")
-
-Empty state types to handle:
-- **First use**: emphasize value, provide templates
-- **User cleared**: light touch, easy to recreate
-- **No results**: suggest a different query, offer to clear filters
-- **No permissions**: explain why, how to get access
-
-**First-run experience**: Get users to their "aha moment" as quickly as possible.
-- Show, don't tell -- working examples over descriptions
-- Progressive disclosure -- teach one thing at a time, not everything upfront
-- Make onboarding optional -- let experienced users skip
-- Provide smart defaults so required setup is minimal
-
-**Feature discovery**: Teach features when users need them, not upfront.
-- Contextual tooltips at point of use (brief, dismissable, one-time)
-- Badges or indicators on new or unused features
-- Celebrate activation events quietly (a toast, not a modal)
-
-**NEVER**:
-- Force long onboarding before users can touch the product
-- Show the same tooltip repeatedly (track and respect dismissals)
-- Block the entire UI during a guided tour
-- Create separate tutorial modes disconnected from the real product
-- Design empty states that just say "No items" with no next action
-
### Input Validation & Sanitization
**Client-side validation**:
@@ -384,4 +344,4 @@ Test thoroughly with edge cases:
- **Errors**: Force API errors, test all error states
- **Empty**: Remove all data, test empty states
-Remember: You're hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component.
\ No newline at end of file
+Remember: You're hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component.
diff --git a/.agents/skills/critique/reference/heuristics-scoring.md b/.agents/skills/impeccable/reference/heuristics-scoring.md
similarity index 100%
rename from .agents/skills/critique/reference/heuristics-scoring.md
rename to .agents/skills/impeccable/reference/heuristics-scoring.md
diff --git a/source/skills/layout/SKILL.md b/.agents/skills/impeccable/reference/layout.md
similarity index 82%
rename from source/skills/layout/SKILL.md
rename to .agents/skills/impeccable/reference/layout.md
index 747fb66be..5e8022081 100644
--- a/source/skills/layout/SKILL.md
+++ b/.agents/skills/impeccable/reference/layout.md
@@ -1,15 +1,12 @@
----
-name: layout
-description: "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition."
-argument-hint: "[target]"
-user-invocable: true
----
-
Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions.
-## MANDATORY PREPARATION
+---
-Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first.
+## Register
+
+Brand: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-breaking for emphasis. Rhythm through contrast — tight groupings paired with generous separations.
+
+Product: predictable grids, consistent densities, familiar navigation patterns. Responsive behavior is structural (collapse sidebar, responsive table), not fluid typography. Consistency IS an affordance.
---
@@ -46,7 +43,7 @@ Analyze what's weak about the current spatial design:
## Plan Layout Improvements
-Consult the [spatial design reference](reference/spatial-design.md) from the impeccable skill for detailed guidance on grids, rhythm, and container queries.
+Consult the [spatial design reference](spatial-design.md) for detailed guidance on grids, rhythm, and container queries.
Create a systematic plan:
@@ -122,3 +119,23 @@ Create a systematic plan:
- **Responsiveness**: Does the layout adapt gracefully across screen sizes?
Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.
+
+## Live-mode signature params
+
+Each variant MUST declare a `density` param. Drive all spacing tokens in the variant's scoped CSS through `calc(var(--p-density, 1) * .md` before planning. Each sub-command encodes a specific discipline; skipping its reference produces generic output. Those files may require specific params; layer them on top of the §7 budget, not instead of it.
+
+### 4. Plan three genuinely distinct directions
+
+Before writing a single line of code, name each variant.
+
+**For freeform (`action` is `impeccable`, or the user supplied a free prompt):** each variant must anchor to a different **archetype** — a real-world design analogue specific enough to be recognizable at a glance. Not "modern landing page." Not "minimal product hero." Examples:
+
+- *Broadsheet masthead with rule-divided columns* (think NYT print edition)
+- *Klim Type Foundry specimen page* (dense, technical, catalog-driven)
+- *Japanese print-poster minimalism with a single oversize glyph*
+- *Bloomberg Terminal status bar*
+- *Condé Nast Traveler feature layout*
+
+Then commit each variant to a different **primary axis** of difference:
+
+1. **Hierarchy** — which element commands the eye?
+2. **Layout topology** — stacked / side-by-side / grid / asymmetric / overlay
+3. **Typographic system** — pairing, scale ratio, case/weight strategy
+4. **Color strategy** — Restrained / Committed / Full palette / Drenched
+5. **Density** — minimal / comfortable / dense
+6. **Structural decomposition** — merge, split, progressive disclosure
+
+Three variants → three DIFFERENT primary axes, not three riffs on color.
+
+**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for one dark-neutral-accent, one light-drenched, one full-palette-saturated — three color worlds, not three shades of the same.
+
+**The squint test (before writing code).** Write the three one-sentence descriptions side by side:
+
+> V1: Broadsheet masthead, ruled columns, 24px ink on cream.
+> V2: Enormous italic title, catalog spec rows, heavy monospace data.
+> V3: Card-framed poster with one oversize glyph, magenta veil.
+
+If two of them rhyme ("both use big type" / "both are stacks of sections" / "both feature the CTA prominently"), rework the offender. Freeform variants failing the squint test is the primary failure mode of this flow — three-of-the-same with minor styling tweaks.
+
+**For action-specific invocations**, each variant must vary along the dimension the action names:
+
+- `bolder` — amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
+- `quieter` — pull back a different dimension (color / ornament / spacing).
+- `distill` — remove a different class of excess (visual noise / redundant content / nested structure).
+- `polish` — target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
+- `typeset` — different type pairing AND different scale ratio each. Not three riffs on one pairing.
+- `colorize` — different hue family each (not shades of one hue). Vary chroma and contrast strategy.
+- `layout` — different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
+- `adapt` — different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
+- `animate` — different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
+- `delight` — different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
+- `overdrive` — different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step — live mode is non-interactive.
+
+### 5. Apply the freeform prompt (if present)
+
+`event.freeformPrompt` is the user's ceiling on direction — all variants must honor it — but still explore meaningfully different *interpretations*. "Make it feel like a newspaper front page" → variant 1 = broadsheet masthead + rule-divided columns, variant 2 = tabloid headline + single dominant image, variant 3 = minimalist editorial with oversized drop cap. Not three newspapers in the same voice.
+
+### 6. Write all variants in a single edit
+
+Complete HTML replacement of the original element for each variant, not a CSS-only patch. Consider the element's context (computed styles, parent structure, CSS variables from `event.element`).
+
+Write CSS + all variants in ONE edit at the `insertLine` reported by `wrap`. Colocate scoped CSS as a `
+` if the user picked a ``). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
+
+The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no scoped CSS, omit the `');
+ if (paramValues && Object.keys(paramValues).length > 0) {
+ // Preserve the user's knob positions for the carbonize-cleanup agent
+ // to bake into the final CSS when it collapses scoped rules.
+ replacement.push(indent + commentSyntax.open + ' impeccable-param-values ' + id + ': ' + JSON.stringify(paramValues) + ' ' + commentSyntax.close);
+ }
+ replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-end ' + id + ' ' + commentSyntax.close);
+ }
+
+ // Keep the `@scope ([data-impeccable-variant="N"])` selectors in the
+ // carbonize CSS block working visually by re-wrapping the accepted content
+ // in a data-impeccable-variant="N" div with `display: contents` (so layout
+ // isn't affected). The carbonize agent strips this attribute + wrapper when
+ // it moves the CSS to a proper stylesheet.
+ if (cssContent) {
+ replacement.push(indent + '… ` inside `text`,
+ * handling nested same-tag elements via depth counting. `attrMatch` is a
+ * regex source fragment that must appear inside the opener tag.
+ * Returns the inner string (may be empty), or null if not found.
+ */
+function extractInnerByAttr(text, attrMatch) {
+ const openerRe = new RegExp('<([A-Za-z][A-Za-z0-9]*)\\b[^>]*' + attrMatch + '[^>]*>');
+ const openMatch = text.match(openerRe);
+ if (!openMatch) return null;
+
+ const tagName = openMatch[1];
+ const innerStart = openMatch.index + openMatch[0].length;
+
+ // Match any opener or closer of this tag name after innerStart.
+ // (Does not match self-closing ]*\/\s*>/.test(line)) return null;
+ // Same-line open + close: extract inner text.
+ const sameLine = line.match(/]*>([\s\S]*?)<\/style\s*>/);
+ if (sameLine) {
+ const inner = sameLine[1];
+ return inner.length > 0 ? inner.split('\n') : null;
+ }
+ inStyle = true;
+ continue; // skip the ')) break;
+ content.push(line);
+ }
+ }
+
+ return content.length > 0 ? content : null;
+}
+
+/**
+ * De-indent content that was indented by live-wrap.mjs.
+ * The wrap script adds `indent + ' '` (4 extra spaces) to each line.
+ * We restore to just `indent` level.
+ */
+function deindentContent(contentLines, baseIndent) {
+ // Find the minimum indentation in the content to determine how much was added
+ let minIndent = Infinity;
+ for (const line of contentLines) {
+ if (line.trim() === '') continue;
+ const leadingSpaces = line.match(/^(\s*)/)[1].length;
+ minIndent = Math.min(minIndent, leadingSpaces);
+ }
+ if (minIndent === Infinity) minIndent = 0;
+
+ // Strip the extra indentation and re-add base indent
+ return contentLines.map(line => {
+ if (line.trim() === '') return '';
+ return baseIndent + line.slice(minIndent);
+ });
+}
+
+function detectCommentSyntax(filePath) {
+ const ext = path.extname(filePath).toLowerCase();
+ if (ext === '.jsx' || ext === '.tsx') {
+ return { open: '{/*', close: '*/}' };
+ }
+ return { open: '' };
+}
+
+// ---------------------------------------------------------------------------
+// File search (find the file containing session markers)
+// ---------------------------------------------------------------------------
+
+function findSessionFile(id, cwd) {
+ const marker = 'impeccable-variants-start ' + id;
+ const searchDirs = ['src', 'app', 'pages', 'components', 'public', 'views', 'templates', '.'];
+ const seen = new Set();
+
+ for (const dir of searchDirs) {
+ const absDir = path.join(cwd, dir);
+ if (!fs.existsSync(absDir)) continue;
+ const result = searchDir(absDir, marker, seen, 0);
+ if (result) {
+ const content = fs.readFileSync(result, 'utf-8');
+ return { file: result, content, lines: content.split('\n') };
+ }
+ }
+ return null;
+}
+
+function searchDir(dir, query, seen, depth) {
+ if (depth > 5) return null;
+ let realDir;
+ try { realDir = fs.realpathSync(dir); } catch { return null; }
+ if (seen.has(realDir)) return null;
+ seen.add(realDir);
+
+ let entries;
+ try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+ catch { return null; }
+
+ for (const entry of entries) {
+ if (!entry.isFile()) continue;
+ if (!EXTENSIONS.includes(path.extname(entry.name).toLowerCase())) continue;
+ const filePath = path.join(dir, entry.name);
+ try {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ if (content.includes(query)) return filePath;
+ } catch { /* skip */ }
+ }
+
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ if (['node_modules', '.git', 'dist', 'build'].includes(entry.name)) continue;
+ const result = searchDir(path.join(dir, entry.name), query, seen, depth + 1);
+ if (result) return result;
+ }
+
+ return null;
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function argVal(args, flag) {
+ const idx = args.indexOf(flag);
+ return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+// Auto-execute when run directly
+const _running = process.argv[1];
+if (_running?.endsWith('live-accept.mjs') || _running?.endsWith('live-accept.mjs/')) {
+ acceptCli();
+}
+
+export { findMarkerBlock, extractOriginal, extractVariant, extractCss, deindentContent, detectCommentSyntax };
diff --git a/.agents/skills/impeccable/scripts/live-browser.js b/.agents/skills/impeccable/scripts/live-browser.js
new file mode 100644
index 000000000..65e779628
--- /dev/null
+++ b/.agents/skills/impeccable/scripts/live-browser.js
@@ -0,0 +1,4590 @@
+/**
+ * Impeccable Live Variant Mode — Browser Script
+ *
+ * Injected into the user's page via \n' +
+ open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
+ );
+}
+
+function insertTag(content, config, port) {
+ const block = buildTagBlock(config.commentSyntax, port);
+ // insertBefore: match the LAST occurrence. Anchors like `
+
+
+
+
+```
+
+**Each variant div contains exactly one top-level element — the full replacement for the original.** Use the same tag as the original (e.g. `');
+ replacement.push(...restored);
+ replacement.push(indent + '
');
+ } else {
+ replacement.push(...restored);
+ }
+
+ const newLines = [
+ ...lines.slice(0, block.start),
+ ...replacement,
+ ...lines.slice(block.end + 1),
+ ];
+ fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+
+ return { carbonize: needsCarbonize };
+}
+
+// ---------------------------------------------------------------------------
+// Parsing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the start/end marker lines for a session.
+ * Returns { start, end } (0-indexed line numbers) or null.
+ */
+function findMarkerBlock(id, lines) {
+ let start = -1;
+ let end = -1;
+ const startPattern = 'impeccable-variants-start ' + id;
+ const endPattern = 'impeccable-variants-end ' + id;
+
+ for (let i = 0; i < lines.length; i++) {
+ if (start === -1 && lines[i].includes(startPattern)) start = i;
+ if (lines[i].includes(endPattern)) { end = i; break; }
+ }
+
+ return (start !== -1 && end !== -1) ? { start, end } : null;
+}
+
+/**
+ * Join wrapper lines into a single string with `` to close on)
+ * - Same-line `` blocks
+ * - Multi-line `` blocks
+ */
+function stripStyleAndJoin(lines, block) {
+ const out = [];
+ let inStyle = false;
+ for (let i = block.start; i <= block.end; i++) {
+ let line = lines[i];
+
+ if (!inStyle) {
+ // Strip any complete .
+ const closeIdx = line.search(/<\/style\s*>/);
+ if (closeIdx !== -1) {
+ inStyle = false;
+ out.push(line.slice(closeIdx).replace(/<\/style\s*>/, ''));
+ }
+ // else: skip line entirely
+ }
+ }
+ return out.join('\n');
+}
+
+/**
+ * Find the inner content of `