wizz-method 1.4.1 → 1.5.0

package/src/skills-lib/impeccable/SKILL.md

@@ -10,7 +10,7 @@ license: Apache 2.0
 
 Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
 
-## Setup
+## Setup (first step, always run before anything else)
 
 You MUST do these steps before proceeding:
 
@@ -24,163 +24,47 @@ You MUST do these steps before proceeding:
 
 Produce ready-to-ship, production-grade code, not prototypes or starting points. Take no shortcuts unless the user asks for them (when in doubt, ask). Don't stop until arriving at a complete implementation (beautiful, responsive, fast, precise, bug-free, on brand). You take attention to detail seriously: every page, section or component crafted is battle tested using the tools available to you (browser screenshotting, computer use, etc). {{model}} is capable of extraordinary work. Don't hold back.
 
-### General rules
-
-#### Color
-
-- **Verify contrast.** Body text must hit ≥4.5:1 against its background; large text (≥18px or bold ≥14px) needs ≥3:1. Placeholder text needs the same 4.5:1, not the muted-gray default. The most common failure: muted gray body text on a tinted near-white. If the contrast is even close, bump the body color toward the ink end of the ramp; light gray "for elegance" is the single biggest reason AI designs feel hard to read. <!-- rule:skill-color-verify-contrast -->
-- Gray text on a colored background looks washed out. Use a darker shade of the background's own hue, or a transparency of the text color. <!-- rule:skill-color-gray-on-color -->
-
-#### Typography
-
-- Cap body line length at 65–75ch. <!-- rule:skill-typo-line-length -->
-- Don't pair fonts that are similar but not identical (two geometric sans-serifs, two humanist sans-serifs). Pair on a contrast axis (serif + sans, geometric + humanist) or use one family in multiple weights. <!-- rule:skill-typo-font-pairing-contrast -->
-- Hero / display heading ceiling: clamp() max ≤ 6rem (~96px). Above that the page is shouting, not designing. <!-- rule:skill-typo-hero-ceiling -->
-- Display heading letter-spacing floor: ≥ -0.04em. Anything tighter and letters touch; cramped, not "designed". <!-- rule:skill-typo-tracking-floor -->
-- Use `text-wrap: balance` on h1–h3 for even line lengths; `text-wrap: pretty` on long prose to reduce orphans. <!-- rule:skill-typo-text-wrap-balance -->
-
-<codex>
-One hard typographic ceiling you currently miss:
-- Display letter-spacing ≥ -0.04em. Your default of -0.05 to -0.085em on display H1s makes the letters touch and reads as cramped. -0.02 to -0.03em is plenty for tight grotesque display; -0.04em is the floor. <!-- rule:skill-typo-codex-tracking-repeat -->
-</codex>
-
-#### Layout
-
-- Vary spacing for rhythm. <!-- rule:skill-layout-vary-spacing -->
-- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong. <!-- rule:skill-layout-cards-lazy -->
-- Flexbox for 1D, Grid for 2D. Don't default to Grid when `flex-wrap` would be simpler. <!-- rule:skill-layout-flex-vs-grid -->
-- For responsive grids without breakpoints: `repeat(auto-fit, minmax(280px, 1fr))`. <!-- rule:skill-layout-auto-fit-grid -->
-- Build a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip). Never arbitrary values like 999 or 9999. <!-- rule:skill-layout-z-index-scale -->
-
-#### Motion
-- Motion should be intentional, and not be an afterthought. consider it as part of the build. <!-- rule:skill-motion-intentional -->
-- Don't animate CSS layout properties unless truly needed. <!-- rule:skill-motion-no-layout-animate -->
-- Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic. <!-- rule:skill-motion-ease-out-exp -->
-- Use libraries for more advanced motion needs (e.g. motion, gsap, anime.js, lenis etc) <!-- rule:skill-motion-use-libraries -->
-- Reduced motion is not optional. Every animation needs a `@media (prefers-reduced-motion: reduce)` alternative: typically a crossfade or instant transition. <!-- rule:skill-motion-reduced-motion -->
-- Staggering the items within one list is legitimate. The tell is the uniform reflex (one identical entrance applied to every section), not motion itself; each reveal should fit what it reveals. Suppressing the reflex is never a reason to ship a page with no motion at all. <!-- rule:skill-motion-no-section-fade -->
-- Reveal animations must enhance an already-visible default. Don't gate content visibility on a class-triggered transition; transitions pause on hidden tabs and headless renderers, so the reveal never fires and the section ships blank. <!-- rule:skill-motion-reveal-safety -->
-- Premium motion materials are not just transform/opacity. Blur, backdrop-filter, clip-path, mask, and shadow/glow are part of the palette when they materially improve the effect and stay smooth. <!-- rule:skill-motion-materials-palette -->
-
-#### Interaction
-
-- Dropdowns rendered with `position: absolute` inside an `overflow: hidden` or `overflow: auto` container will be clipped. Use the native `<dialog>` / popover API, `position: fixed`, or a portal to escape the stacking context. <!-- rule:skill-interaction-dropdown-clipping -->
-
-<gemini>
-**Gemini-specific defect: hard ban.** Never animate `<img>` elements on hover. This includes any `transform` on `:hover` of an image, AND `.group:hover .group-hover\:scale` / `.group:hover .group-hover\:rotate` / `.group:hover .group-hover\:translate` patterns from Tailwind that animate a child image via a parent hover. This is your single most common motion tell; it adds no information (the image isn't an action target) and reads as "AI animated this because it could". If a card needs hover feedback, animate the card's background, border, or shadow. Never the image, never via the image's parent. <!-- rule:skill-interaction-gemini-no-image-hover -->
-</gemini>
-
-### New projects only (when no prior work exists)
-
-#### Color & Theme
-
-- Use OKLCH. <!-- rule:skill-color-use-oklch -->
-- **The cream / sand / beige body bg is the saturated AI default of 2026.** The whole warm-neutral band (OKLCH L 0.84-0.97, C < 0.06, hue 40-100) reads as cream/sand/paper/parchment regardless of what you call it. Token names like `--paper`, `--cream`, `--sand`, `--bone`, `--flour`, `--linen`, `--parchment`, `--wheat`, `--biscuit`, `--ivory` are tells in themselves. If the brief is "warm, traditional, family-coastal-Italian" or "magazine-warm" or "editorial-restraint", DO NOT translate that into a near-white warm-tinted bg; that's the AI move. Pick: (a) a saturated brand color as the body (terracotta, oxblood, deep ochre, near-black), (b) a true off-white at chroma 0 (or chroma toward the brand's own hue, not toward warmth-by-default), or (c) a darker mid-tone tinted neutral that's clearly the brand's own. "Warmth" in the brand is carried by accent + typography + imagery, not by body bg. <!-- rule:skill-color-anti-cream -->
-- Tinted neutrals: add 0.005–0.015 chroma toward the brand's hue. Don't default-tint toward warm or cool "because the brand feels that way"; that's the cross-project monoculture move. <!-- rule:skill-color-tinted-neutrals-chroma -->
-- When picking a theme: Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe.".Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. <!-- rule:skill-color-theme-physical-scene -->
-- Pick a **color strategy** before picking colors. Four steps on the commitment axis: <!-- rule:skill-color-strategy-commitment -->
-  - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism.
-  - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
-  - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
-  - **Drenched**: the surface IS the color. Brand heroes, campaign pages.
-
-### Absolute bans
-
-Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
-
-- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing. <!-- rule:skill-ban-side-stripe-borders -->
-- **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size. <!-- rule:skill-ban-gradient-text -->
-- **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing. <!-- rule:skill-ban-glassmorphism-default -->
-- **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché. <!-- rule:skill-ban-hero-metric -->
-- **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly. <!-- rule:skill-ban-identical-card-grids -->
-- **Tiny uppercase tracked eyebrow above every section.** The 2023-era kicker (small all-caps text with wide tracking, "ABOUT" "PROCESS" "PRICING" above each heading) is now the saturated AI scaffold; it appears on 55-95% of generations regardless of brief, which is the definition of a tell. One named kicker as a deliberate brand system is voice; an eyebrow on every section is AI grammar. Choose a different cadence. <!-- rule:skill-ban-eyebrow-on-every-section -->
-- **Numbered section markers as default scaffolding (01 / 02 / 03).** Putting `01 · About / 02 · Process / 03 · Pricing` above every section is the eyebrow trope one tier deeper: reach for it because "landing pages do this" and you're scaffolding by reflex. Numbers earn their place when the section actually IS a sequence (a real 3-step process, an ordered flow, a typed timeline) and the order carries information the reader needs. One deliberate numbered sequence on one page is voice; numbered eyebrows on every section across the site is AI grammar. <!-- rule:skill-ban-numbered-section-markers -->
-- **Text that overflows its container.** Long heading words plus large clamp scales plus narrow grids cause headline overflow on tablet/mobile. Test the heading copy at every breakpoint; if it overflows, reduce the clamp max or rewrite the copy. The viewport is part of the design. <!-- rule:skill-ban-text-overflow -->
-
-<codex>
-**Codex-specific defects** (your most-frequent giveaways; refuse-and-rewrite):
-
-- **`border: 1px solid X` + `box-shadow: 0 Npx Mpx ...` with M ≥ 16px** on the same element. The "ghost-card" pattern: 1px border plus soft wide drop shadow on buttons and cards. Don't pair them. Pick one (a single solid border at the brand color, OR a defined shadow at no more than 8px blur), never both as decoration. <!-- rule:skill-ban-codex-ghost-card -->
-- **`border-radius: 32px+` on cards / sections / inputs.** You over-round. Cards top out at 12–16px; full-pill is fine for tags/buttons. Picking 24/28/32/40px on a card is the codex tell; no brand wants "insanely rounded". <!-- rule:skill-ban-codex-over-round -->
-- **Hand-drawn / sketchy SVG illustrations.** Class names like `loose-sketch`, `*-sketch`, `doodle`, `wavy`; `feTurbulence` / `feDisplacementMap` "paper grain" filters; 5-to-30 path crude scenes meant to depict a tangible subject (an otter, a table-and-fork, an album cover). All of these read as amateurish, not whimsical. If you can't render the scene with real assets, ship no illustration. Don't attempt sketchy SVG as a fallback. <!-- rule:skill-ban-codex-sketchy-svg -->
-- **`repeating-linear-gradient(...)` stripe backgrounds.** Diagonal stripes in `body:before` or section backgrounds are pure codex decoration. Don't. <!-- rule:skill-ban-codex-stripes -->
-- **Meta-criticism copy.** Naming a concept then layering an ironic modifier, or staging a strawman to "correct" it. Make the specific claim instead. <!-- rule:skill-ban-codex-x-theater -->
-</codex>
-
-### The AI slop test
-
-If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
-
-**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses.
-
-- **First-order:** if someone could guess the theme + palette from the category alone, it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. <!-- rule:skill-slop-first-order-check -->
-- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. <!-- rule:skill-slop-second-order-check -->
+**Before writing or reviewing any UI code, load `references/design-rules.md`** — the ruleset every craft/polish/audit/critique pass is checked against. Skipping it is the most common way this skill produces generic or AI-tell-heavy output.
 
 ## Commands
 
-| Command | Category | Description | Reference |
-|---|---|---|---|
-| `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) |
-| `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) |
-| `init` | Build | Set up project context: PRODUCT.md, DESIGN.md, live config, next steps | [reference/init.md](reference/init.md) |
-| `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
-| `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
-| `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
-| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) |
-| `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
-| `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
-| `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
-| `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) |
-| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) |
-| `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) |
-| `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) |
-| `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) |
-| `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) |
-| `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) |
-| `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
-| `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
-| `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
-| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) |
-| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
-| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
-
-Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>`, detailed below.
-
-### Routing rules
-
-1. **No argument**: the user is asking "what should I do?" Make the menu context-aware instead of static. Setup has already run `context.mjs`; if that reported `NO_PRODUCT_MD` you are already in init (setup), so finish that and skip this. Otherwise run `node {{scripts_path}}/context-signals.mjs` once and read its JSON, then lead with the **2-3 highest-value next commands**, each with a one-line reason pulled from the signals, followed by the full menu (the table above, grouped by category). **Never auto-run a command; the recommendation is a suggestion the user confirms.**
-
-   Reason over the signals; there is no score to obey:
-   - `setup.hasDesign` false while `setup.hasCode` true → `document` (capture the visual system).
-   - `critique.latest` is `null` → the project has never been critiqued; for a set-up project with a real surface, offering `/impeccable critique <surface>` is a strong default.
-   - `critique.latest` with a low `score` or non-zero `p0` / `p1` → `polish` (it reads that snapshot as its backlog), or re-run `critique` if the snapshot looks stale.
-   - `git.changedFiles` pointing at one surface → scope `audit` or `polish` to those files specifically, naming them.
-   - `devServer.running` true → `live` is available for in-browser iteration; if false, don't lead with `live`.
-   - Otherwise group by intent exactly as init's "Recommend starting points" step does (build new / improve what's there / iterate visually), tailored to `setup.register`.
-
-   **If `scan.targets` is non-empty, run `node {{scripts_path}}/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
-
-   Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
-2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
-3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
-4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
-
-Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `{{command_prefix}}impeccable`.
-
-If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `init` as a blocker, finish init, refresh context, then resume the original command and target.
+| Command | Category | Description |
+|---|---|---|
+| `craft [feature]` | Build | Shape, then build a feature end-to-end |
+| `shape [feature]` | Build | Plan UX/UI before writing code |
+| `init` | Build | Set up project context: PRODUCT.md, DESIGN.md, live config, next steps |
+| `document` | Build | Generate DESIGN.md from existing project code |
+| `extract [target]` | Build | Pull reusable tokens and components into design system |
+| `critique [target]` | Evaluate | UX design review with heuristic scoring |
+| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) |
+| `polish [target]` | Refine | Final quality pass before shipping |
+| `bolder [target]` | Refine | Amplify safe or bland designs |
+| `quieter [target]` | Refine | Tone down aggressive or overstimulating designs |
+| `distill [target]` | Refine | Strip to essence, remove complexity |
+| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases |
+| `onboard [target]` | Refine | Design first-run flows, empty states, activation |
+| `animate [target]` | Enhance | Add purposeful animations and motion |
+| `colorize [target]` | Enhance | Add strategic color to monochromatic UIs |
+| `typeset [target]` | Enhance | Improve typography hierarchy and fonts |
+| `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy |
+| `delight [target]` | Enhance | Add personality and memorable touches |
+| `overdrive [target]` | Enhance | Push past conventional limits |
+| `clarify [target]` | Fix | Improve UX copy, labels, and error messages |
+| `adapt [target]` | Fix | Adapt for different devices and screen sizes |
+| `optimize [target]` | Fix | Diagnose and fix UI performance |
+| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives |
+
+Each command's flow lives at `reference/<command>.md` (e.g. `reference/craft.md`, `reference/live.md` — vendored, per Setup step 2). Plus three management commands: `pin <command>`, `unpin <command>`, and `hooks <on|off|status|...>` — see `references/pin-unpin-and-hooks.md`.
+
+**If the first word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target. **If no argument was given, or the intent doesn't obviously name a command**, load `references/routing-rules.md` for the full routing logic (context-aware menu, signal-based recommendations, intent mapping, fallback general invocation).
 
 `teach` is a deprecated alias for `init`: if the user types it, load [reference/init.md](reference/init.md) and proceed as if they ran `init`.
 
-## Pin / Unpin
-
-**Pin** creates a standalone shortcut so `{{command_prefix}}<command>` invokes `{{command_prefix}}impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.
-
-```bash
-node {{scripts_path}}/pin.mjs <pin|unpin> <command>
-```
-
-Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
+## Reference map — load each file when needed
 
-## Hooks
+- `references/design-rules.md` — general + new-project rules, absolute bans, AI slop test. **Load before producing/reviewing UI code.**
+- `references/routing-rules.md` — full routing algorithm for no-argument or ambiguous invocations. **Load when you can't map the request to a table row.**
+- `references/pin-unpin-and-hooks.md` — the `pin`/`unpin`/`hooks` management flows. **Load when the user invokes one of those.**
+- `reference/<command>.md` (singular — e.g. `reference/craft.md`, `reference/brand.md`) — vendored per-command/per-register flows from the `impeccable` npm package, resolved by Setup steps 2 and 4. Not part of this repo.
 
-`{{command_prefix}}impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `{{command_prefix}}impeccable hooks` with any argument.
+Zero content was cut — every rule, example, and routing detail lives verbatim in its `references/` file.

package/src/skills-lib/impeccable/references/design-rules.md

@@ -0,0 +1,95 @@
+# Design rules — general, new-project, absolute bans, AI slop test
+
+Load this file before producing or reviewing any UI code — it's the ruleset every design/craft/polish/audit command is checked against. Covers: general rules (color, typography, layout, motion, interaction), new-project-only rules (color & theme strategy when no prior work exists), absolute bans (match-and-refuse patterns like side-stripe borders, gradient text, ghost-card shadows), and the two-altitude AI slop test.
+
+### General rules
+
+#### Color
+
+- **Verify contrast.** Body text must hit ≥4.5:1 against its background; large text (≥18px or bold ≥14px) needs ≥3:1. Placeholder text needs the same 4.5:1, not the muted-gray default. The most common failure: muted gray body text on a tinted near-white. If the contrast is even close, bump the body color toward the ink end of the ramp; light gray "for elegance" is the single biggest reason AI designs feel hard to read. <!-- rule:skill-color-verify-contrast -->
+- Gray text on a colored background looks washed out. Use a darker shade of the background's own hue, or a transparency of the text color. <!-- rule:skill-color-gray-on-color -->
+
+#### Typography
+
+- Cap body line length at 65–75ch. <!-- rule:skill-typo-line-length -->
+- Don't pair fonts that are similar but not identical (two geometric sans-serifs, two humanist sans-serifs). Pair on a contrast axis (serif + sans, geometric + humanist) or use one family in multiple weights. <!-- rule:skill-typo-font-pairing-contrast -->
+- Hero / display heading ceiling: clamp() max ≤ 6rem (~96px). Above that the page is shouting, not designing. <!-- rule:skill-typo-hero-ceiling -->
+- Display heading letter-spacing floor: ≥ -0.04em. Anything tighter and letters touch; cramped, not "designed". <!-- rule:skill-typo-tracking-floor -->
+- Use `text-wrap: balance` on h1–h3 for even line lengths; `text-wrap: pretty` on long prose to reduce orphans. <!-- rule:skill-typo-text-wrap-balance -->
+
+<codex>
+One hard typographic ceiling you currently miss:
+- Display letter-spacing ≥ -0.04em. Your default of -0.05 to -0.085em on display H1s makes the letters touch and reads as cramped. -0.02 to -0.03em is plenty for tight grotesque display; -0.04em is the floor. <!-- rule:skill-typo-codex-tracking-repeat -->
+</codex>
+
+#### Layout
+
+- Vary spacing for rhythm. <!-- rule:skill-layout-vary-spacing -->
+- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong. <!-- rule:skill-layout-cards-lazy -->
+- Flexbox for 1D, Grid for 2D. Don't default to Grid when `flex-wrap` would be simpler. <!-- rule:skill-layout-flex-vs-grid -->
+- For responsive grids without breakpoints: `repeat(auto-fit, minmax(280px, 1fr))`. <!-- rule:skill-layout-auto-fit-grid -->
+- Build a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip). Never arbitrary values like 999 or 9999. <!-- rule:skill-layout-z-index-scale -->
+
+#### Motion
+- Motion should be intentional, and not be an afterthought. consider it as part of the build. <!-- rule:skill-motion-intentional -->
+- Don't animate CSS layout properties unless truly needed. <!-- rule:skill-motion-no-layout-animate -->
+- Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic. <!-- rule:skill-motion-ease-out-exp -->
+- Use libraries for more advanced motion needs (e.g. motion, gsap, anime.js, lenis etc) <!-- rule:skill-motion-use-libraries -->
+- Reduced motion is not optional. Every animation needs a `@media (prefers-reduced-motion: reduce)` alternative: typically a crossfade or instant transition. <!-- rule:skill-motion-reduced-motion -->
+- Staggering the items within one list is legitimate. The tell is the uniform reflex (one identical entrance applied to every section), not motion itself; each reveal should fit what it reveals. Suppressing the reflex is never a reason to ship a page with no motion at all. <!-- rule:skill-motion-no-section-fade -->
+- Reveal animations must enhance an already-visible default. Don't gate content visibility on a class-triggered transition; transitions pause on hidden tabs and headless renderers, so the reveal never fires and the section ships blank. <!-- rule:skill-motion-reveal-safety -->
+- Premium motion materials are not just transform/opacity. Blur, backdrop-filter, clip-path, mask, and shadow/glow are part of the palette when they materially improve the effect and stay smooth. <!-- rule:skill-motion-materials-palette -->
+
+#### Interaction
+
+- Dropdowns rendered with `position: absolute` inside an `overflow: hidden` or `overflow: auto` container will be clipped. Use the native `<dialog>` / popover API, `position: fixed`, or a portal to escape the stacking context. <!-- rule:skill-interaction-dropdown-clipping -->
+
+<gemini>
+**Gemini-specific defect: hard ban.** Never animate `<img>` elements on hover. This includes any `transform` on `:hover` of an image, AND `.group:hover .group-hover\:scale` / `.group:hover .group-hover\:rotate` / `.group:hover .group-hover\:translate` patterns from Tailwind that animate a child image via a parent hover. This is your single most common motion tell; it adds no information (the image isn't an action target) and reads as "AI animated this because it could". If a card needs hover feedback, animate the card's background, border, or shadow. Never the image, never via the image's parent. <!-- rule:skill-interaction-gemini-no-image-hover -->
+</gemini>
+
+### New projects only (when no prior work exists)
+
+#### Color & Theme
+
+- Use OKLCH. <!-- rule:skill-color-use-oklch -->
+- **The cream / sand / beige body bg is the saturated AI default of 2026.** The whole warm-neutral band (OKLCH L 0.84-0.97, C < 0.06, hue 40-100) reads as cream/sand/paper/parchment regardless of what you call it. Token names like `--paper`, `--cream`, `--sand`, `--bone`, `--flour`, `--linen`, `--parchment`, `--wheat`, `--biscuit`, `--ivory` are tells in themselves. If the brief is "warm, traditional, family-coastal-Italian" or "magazine-warm" or "editorial-restraint", DO NOT translate that into a near-white warm-tinted bg; that's the AI move. Pick: (a) a saturated brand color as the body (terracotta, oxblood, deep ochre, near-black), (b) a true off-white at chroma 0 (or chroma toward the brand's own hue, not toward warmth-by-default), or (c) a darker mid-tone tinted neutral that's clearly the brand's own. "Warmth" in the brand is carried by accent + typography + imagery, not by body bg. <!-- rule:skill-color-anti-cream -->
+- Tinted neutrals: add 0.005–0.015 chroma toward the brand's hue. Don't default-tint toward warm or cool "because the brand feels that way"; that's the cross-project monoculture move. <!-- rule:skill-color-tinted-neutrals-chroma -->
+- When picking a theme: Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe.".Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. <!-- rule:skill-color-theme-physical-scene -->
+- Pick a **color strategy** before picking colors. Four steps on the commitment axis: <!-- rule:skill-color-strategy-commitment -->
+  - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism.
+  - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
+  - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
+  - **Drenched**: the surface IS the color. Brand heroes, campaign pages.
+
+### Absolute bans
+
+Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
+
+- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing. <!-- rule:skill-ban-side-stripe-borders -->
+- **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size. <!-- rule:skill-ban-gradient-text -->
+- **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing. <!-- rule:skill-ban-glassmorphism-default -->
+- **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché. <!-- rule:skill-ban-hero-metric -->
+- **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly. <!-- rule:skill-ban-identical-card-grids -->
+- **Tiny uppercase tracked eyebrow above every section.** The 2023-era kicker (small all-caps text with wide tracking, "ABOUT" "PROCESS" "PRICING" above each heading) is now the saturated AI scaffold; it appears on 55-95% of generations regardless of brief, which is the definition of a tell. One named kicker as a deliberate brand system is voice; an eyebrow on every section is AI grammar. Choose a different cadence. <!-- rule:skill-ban-eyebrow-on-every-section -->
+- **Numbered section markers as default scaffolding (01 / 02 / 03).** Putting `01 · About / 02 · Process / 03 · Pricing` above every section is the eyebrow trope one tier deeper: reach for it because "landing pages do this" and you're scaffolding by reflex. Numbers earn their place when the section actually IS a sequence (a real 3-step process, an ordered flow, a typed timeline) and the order carries information the reader needs. One deliberate numbered sequence on one page is voice; numbered eyebrows on every section across the site is AI grammar. <!-- rule:skill-ban-numbered-section-markers -->
+- **Text that overflows its container.** Long heading words plus large clamp scales plus narrow grids cause headline overflow on tablet/mobile. Test the heading copy at every breakpoint; if it overflows, reduce the clamp max or rewrite the copy. The viewport is part of the design. <!-- rule:skill-ban-text-overflow -->
+
+<codex>
+**Codex-specific defects** (your most-frequent giveaways; refuse-and-rewrite):
+
+- **`border: 1px solid X` + `box-shadow: 0 Npx Mpx ...` with M ≥ 16px** on the same element. The "ghost-card" pattern: 1px border plus soft wide drop shadow on buttons and cards. Don't pair them. Pick one (a single solid border at the brand color, OR a defined shadow at no more than 8px blur), never both as decoration. <!-- rule:skill-ban-codex-ghost-card -->
+- **`border-radius: 32px+` on cards / sections / inputs.** You over-round. Cards top out at 12–16px; full-pill is fine for tags/buttons. Picking 24/28/32/40px on a card is the codex tell; no brand wants "insanely rounded". <!-- rule:skill-ban-codex-over-round -->
+- **Hand-drawn / sketchy SVG illustrations.** Class names like `loose-sketch`, `*-sketch`, `doodle`, `wavy`; `feTurbulence` / `feDisplacementMap` "paper grain" filters; 5-to-30 path crude scenes meant to depict a tangible subject (an otter, a table-and-fork, an album cover). All of these read as amateurish, not whimsical. If you can't render the scene with real assets, ship no illustration. Don't attempt sketchy SVG as a fallback. <!-- rule:skill-ban-codex-sketchy-svg -->
+- **`repeating-linear-gradient(...)` stripe backgrounds.** Diagonal stripes in `body:before` or section backgrounds are pure codex decoration. Don't. <!-- rule:skill-ban-codex-stripes -->
+- **Meta-criticism copy.** Naming a concept then layering an ironic modifier, or staging a strawman to "correct" it. Make the specific claim instead. <!-- rule:skill-ban-codex-x-theater -->
+</codex>
+
+### The AI slop test
+
+If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
+
+**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses.
+
+- **First-order:** if someone could guess the theme + palette from the category alone, it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. <!-- rule:skill-slop-first-order-check -->
+- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. <!-- rule:skill-slop-second-order-check -->

package/src/skills-lib/impeccable/references/pin-unpin-and-hooks.md

@@ -0,0 +1,17 @@
+# Pin/unpin and hooks management commands
+
+Load this file when the user invokes `pin`, `unpin`, or `hooks` (with any argument). Covers: creating/removing standalone command shortcuts, and managing the design detector hook that auto-runs after direct UI file edits.
+
+## Pin / Unpin
+
+**Pin** creates a standalone shortcut so `{{command_prefix}}<command>` invokes `{{command_prefix}}impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.
+
+```bash
+node {{scripts_path}}/pin.mjs <pin|unpin> <command>
+```
+
+Valid `<command>` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error.
+
+## Hooks
+
+`{{command_prefix}}impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project. The hook auto-runs the detector after direct UI file edits and surfaces findings as system reminders. Full flow is in [reference/hooks.md](reference/hooks.md); load it when the user invokes `{{command_prefix}}impeccable hooks` with any argument.

package/src/skills-lib/impeccable/references/routing-rules.md

@@ -0,0 +1,28 @@
+# Routing rules — how to pick a command
+
+Load this file whenever the skill is invoked without an explicit sub-command, or when the user's intent doesn't obviously name one of the commands in the table. Covers: the no-argument menu logic (reading context-signals.mjs and detect.mjs, picking the 2-3 highest-value next commands), first-word command matching, intent-to-command mapping, and the fallback general design invocation path.
+
+### Routing rules
+
+1. **No argument**: the user is asking "what should I do?" Make the menu context-aware instead of static. Setup has already run `context.mjs`; if that reported `NO_PRODUCT_MD` you are already in init (setup), so finish that and skip this. Otherwise run `node {{scripts_path}}/context-signals.mjs` once and read its JSON, then lead with the **2-3 highest-value next commands**, each with a one-line reason pulled from the signals, followed by the full menu (the table above, grouped by category). **Never auto-run a command; the recommendation is a suggestion the user confirms.**
+
+   Reason over the signals; there is no score to obey:
+   - `setup.hasDesign` false while `setup.hasCode` true → `document` (capture the visual system).
+   - `critique.latest` is `null` → the project has never been critiqued; for a set-up project with a real surface, offering `/impeccable critique <surface>` is a strong default.
+   - `critique.latest` with a low `score` or non-zero `p0` / `p1` → `polish` (it reads that snapshot as its backlog), or re-run `critique` if the snapshot looks stale.
+   - `git.changedFiles` pointing at one surface → scope `audit` or `polish` to those files specifically, naming them.
+   - `devServer.running` true → `live` is available for in-browser iteration; if false, don't lead with `live`.
+   - Otherwise group by intent exactly as init's "Recommend starting points" step does (build new / improve what's there / iterate visually), tailored to `setup.register`.
+
+   **If `scan.targets` is non-empty, run `node {{scripts_path}}/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
+
+   Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.
+2. **First word matches a command** (table above OR `pin` / `unpin` / `hooks`): load its reference file and follow its instructions. Everything after the command name is the target.
+3. **First word doesn't match, but the intent clearly maps to one command** (e.g. "fix the spacing" → `layout`, "rewrite this error message" → `clarify`, "the colors feel flat" → `colorize`): load that command's reference and proceed as if invoked. If two commands could fit, ask once which.
+4. **No clear command match**: general design invocation. Apply the setup steps, the General rules, and the loaded register reference, using the full argument as context.
+
+Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `{{command_prefix}}impeccable`.
+
+If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `init` as a blocker, finish init, refresh context, then resume the original command and target.
+
+`teach` is a deprecated alias for `init`: if the user types it, load [reference/init.md](reference/init.md) and proceed as if they ran `init`.