qualia-framework 4.4.0 → 4.5.0

package/rules/design-rubric.md

@@ -0,0 +1,153 @@
+# Design Rubric
+
+Anchored 1-5 scoring across 8 dimensions. Used by the verifier agent to score frontend phases. Used by `/qualia-polish --critique` for read-only audits.
+
+## How to score
+
+Every dimension is scored 1-5 with EVIDENCE on the next line. Score without evidence is rejected.
+
+Anchored definitions:
+- **1** — Fails. Hard violation. WCAG fails, broken layout, absolute-ban hit.
+- **2** — Below acceptable. Functions but signals "AI generated this."
+- **3** — Acceptable. Ships. Not memorable, not embarrassing.
+- **4** — Good. Specific choices visible. A designer would approve.
+- **5** — Excellent. Distinctive. Worth screenshotting and sharing.
+
+**Default to 3.** Only score above 3 if you can cite a specific design principle the work excels at. Only score below 3 if you can quote evidence of a violation.
+
+If a vision model is critiquing screenshots, it must score against this rubric. Without anchoring, vision models say "looks great!" to everything.
+
+## Scope guard
+
+Score only what is scope-relevant. A `/qualia-polish src/components/Button.tsx` review scores Typography, Color, States, Motion, Microcopy. Skip Layout Originality and Container Depth — they're component-internal concerns at most.
+
+A whole-app `/qualia-polish` scores all 8 dimensions across multiple representative routes.
+
+## The 8 dimensions
+
+### 1. Typography
+
+| Score | Criteria |
+|---|---|
+| 1 | Inter / Roboto / Arial / system-ui / Space Grotesk as primary. Or single weight throughout. |
+| 2 | Project font loaded but only one weight, no scale, no letter-spacing variation. |
+| 3 | Project font with 2-3 weights, basic scale (h1/h2/body), readable. |
+| 4 | Distinctive display + refined body pair. Letter-spacing varied semantically (tight headlines, open labels). Tabular numerals on numeric data. |
+| 5 | Variable font with axis-driven weight/optical-size. Hierarchy through weight + scale + letter-spacing combined. Line lengths capped at 65-75ch. |
+
+Evidence format: `font-family: "<name>" used at line N, scale 14/16/24/40 visible, weights 400/500/700`
+
+### 2. Color cohesion
+
+| Score | Criteria |
+|---|---|
+| 1 | Hex values scattered in JSX. No CSS variables. Pure `#000` or `#fff`. |
+| 2 | CSS variables defined but unused (raw hex still appears). RGB used. |
+| 3 | All colors as CSS variables. Tinted neutrals (no pure black/white). One color strategy implied. |
+| 4 | OKLCH throughout. Strategy explicit (Restrained / Committed / Full / Drenched). WCAG AA verified. |
+| 5 | OKLCH with documented strategy. Chroma reduced at extremes. Brand-tinted shadows. APCA contrast verified for dense text. |
+
+Evidence: count of CSS custom properties for color, presence of OKLCH, evidence of strategy commitment
+
+### 3. Spatial rhythm
+
+| Score | Criteria |
+|---|---|
+| 1 | Arbitrary px values everywhere. No system. |
+| 2 | 8px grid roughly followed. Same padding everywhere. |
+| 3 | 8px grid consistently. Tight within groups, generous between sections. |
+| 4 | Fluid `clamp()` padding. Spacing varies by content type. Vertical rhythm identifiable. |
+| 5 | Spatial system reads as composed — different spacing for different relationships. Generous negative space. Asymmetry where intentional. |
+
+Evidence: presence of spacing tokens, padding values divisible by 4, `clamp()` usage
+
+### 4. Layout originality
+
+| Score | Criteria |
+|---|---|
+| 1 | Three-column feature grid in section 2. Card grid of 3 identical items. Centered hero with gradient. |
+| 2 | Standard hero + sections + footer. Symmetric throughout. |
+| 3 | Some layout variation across sections. No card monotony. |
+| 4 | Asymmetry, full-bleed, varied component sizes within a section. Negative space used. |
+| 5 | Layout reads as composed by a designer. Diagonal flow, overlap, scale contrast. Each section a different shape. |
+
+Evidence: file:line references showing layout choices
+
+### 5. Shadow & depth hierarchy
+
+| Score | Criteria |
+|---|---|
+| 1 | Single shadow value applied to everything (or no shadows). Nested cards. |
+| 2 | 2 shadow levels but applied inconsistently. |
+| 3 | 3 elevation levels (subtle / medium / pronounced). Brand-tinted, not pure gray. |
+| 4 | Shadows match elevation semantically. Different shadow for hover than rest. |
+| 5 | Multi-layer shadows (offset + ambient + directional). Brand-hue tinted at chroma 0.02-0.04. Spatial logic clear. |
+
+Evidence: count of distinct `box-shadow` values, OKLCH chroma in shadow color
+
+### 6. Motion intent
+
+| Score | Criteria |
+|---|---|
+| 1 | No transitions. Or: bounce/elastic everywhere. Animates layout properties. |
+| 2 | Default browser transitions on hover. No stagger. |
+| 3 | Considered transitions on interactive elements. Respects `prefers-reduced-motion`. |
+| 4 | One signature motion identified and executed. Stagger on entrance. Easing curves chosen (ease-out-quart or expo). |
+| 5 | Orchestrated motion that communicates structure. Scroll-driven if appropriate. Restraint elsewhere. |
+
+Evidence: easing curves used, presence of `prefers-reduced-motion`, file:line of signature motion
+
+### 7. Microcopy specificity
+
+| Score | Criteria |
+|---|---|
+| 1 | "Get Started" / "Learn More" / "Welcome to <product>" / "Click here". Lorem ipsum. |
+| 2 | Generic but functional ("Save", "Cancel", "Submit"). Empty states say "No results." |
+| 3 | Action-named CTAs ("Download invoice"). Empty states with one-sentence context. |
+| 4 | Voice consistent with brand. Errors specific and actionable ("This file is 12MB; max is 10MB. Compress and retry."). |
+| 5 | Microcopy you'd quote. Voice unmistakable. Every word earned. |
+
+Evidence: grep for banned phrases, sample of empty/error states
+
+### 8. Container depth & nesting
+
+| Score | Criteria |
+|---|---|
+| 1 | Card → panel → pill → content (depth ≥ 4). Side-stripe borders. Gradient text. |
+| 2 | Card-on-card pattern (depth 3). Most things wrapped in containers. |
+| 3 | Container depth ≤ 2. No decorative side-stripes. |
+| 4 | Containers used semantically only. Things that don't need a container don't have one. |
+| 5 | Layout reads as elements arranged on a surface, not boxes inside boxes. |
+
+Evidence: max DOM nesting depth on cards/panels, grep for `border-left` decorative usage
+
+## Aggregate score
+
+```
+total       = sum of dimension scores (max 40)
+average     = total / count_of_scored_dimensions
+phase_pass  = ALL scored dimensions ≥ 3
+phase_fail  = ANY scored dimension < 3
+```
+
+A phase fails if any dimension is below 3. Same gate as functional verification.
+
+## Output format (verifier agent contract)
+
+```markdown
+## Design Rubric — Phase {N}
+
+| Dim | Score | Evidence |
+|---|---|---|
+| Typography | 4 | `app/page.tsx:14` Fraunces + JetBrains Mono pair, weights 400/500/700, clamp() scale visible |
+| Color cohesion | 3 | All CSS vars in `app/globals.css:8-22`. OKLCH used. Strategy: Restrained. WCAG AA verified |
+| Spatial rhythm | 5 | Fluid clamp padding throughout, varied within section, generous between |
+| Layout originality | 2 | `app/page.tsx:42-78` is a three-column feature grid in section 2 — first-order slop. Rework. |
+| ... | ... | ... |
+
+**Aggregate:** 28/40 (avg 3.5)
+**Phase verdict:** FAIL — Layout Originality at 2 blocks the phase.
+**Fix priority:** Rework section 2. Replace three-column grid with varied-height layout per `design-brand.md` §Layout.
+```
+
+If the score < 3, the verifier writes the diagnosis. The fix is the next builder's task.

package/skills/qualia-new/SKILL.md

@@ -107,6 +107,25 @@ git add .planning/PROJECT.md
 git commit -m "docs: initialize project"
 ```
 
+### Step 5b. Write PRODUCT.md (v4.5.0 — REQUIRED)
+
+`PRODUCT.md` is the "who and why" every road agent reads before designing or building. It is **required** — the planner, builder, and verifier all load it as substrate.
+
+Ask the user 5 short questions (one at a time, each with a sensible default they can `[Enter]` past):
+
+1. **Register** — "Is this design IS the product (marketing/landing/portfolio → `brand`) or design SERVES the product (app/admin/dashboard → `product`)?" Default: infer from project type.
+2. **Three users** — "Name 3 specific humans who will use this. Not personas — real names + their workflow scenario." Default: project type defaults.
+3. **Brand voice** — "Three adjectives, then one paragraph showing the voice in motion (an error message, a confirmation, an empty state)." Default: derive from PROJECT.md.
+4. **Anti-references** — "Three sites this should NOT look like, with why." Required, no defaults — anti-references are more useful than positive references.
+5. **One-sentence differentiation** — "What does someone remember 24 hours after first using this?" Required.
+
+Write `.planning/PRODUCT.md` from `templates/PRODUCT.md`, filling the user's answers.
+
+```bash
+git add .planning/PRODUCT.md
+git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
+```
+
 ### Step 6. Create config.json
 
 ```json
@@ -124,13 +143,31 @@ git commit -m "docs: initialize project"
 
 **Note:** `workflow.research` is ALWAYS `true` for v4. It exists for telemetry but is no longer read as a gate.
 
-### Step 7. Create DESIGN.md (frontend projects)
+### Step 7. Create DESIGN.md (frontend projects — v4.5.0 OKLCH-first)
+
+If frontend work is involved, generate `.planning/DESIGN.md` from `templates/DESIGN.md`. The generation MUST commit to four things upfront (these go in §1 of DESIGN.md):
+
+1. **Aesthetic direction** — pick ONE: `editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · sci-fi · pastoral · industrial · ...`. Don't hedge ("modern minimal" is hedging — pick one extreme).
+2. **Color strategy** — pick ONE: `Restrained · Committed · Full palette · Drenched`. See `rules/design-laws.md` §2.
+3. **Scene sentence** — one concrete sentence: who uses this, where, ambient light, mood. NOT "observability dashboard" — "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room." Run the sentence, not the category.
+4. **Differentiation** — one sentence: what someone remembers 24 hours later.
+
+Then fill the rest of DESIGN.md:
+- §2 Color: OKLCH only, no `#000`/`#fff`, neutrals tinted toward brand hue (chroma 0.005-0.015), accent within the chosen strategy
+- §3 Typography: distinctive display + refined body pair. **NEVER** Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk
+- §4 Spacing: 8px grid + fluid `clamp()` for page padding
+- §5 Components: token-driven button/input/card/table specs
+- §6 Depth: 3-level shadow elevation, OKLCH-tinted (not gray)
+- §7 Motion: easing tokens (ease-out-quart/expo), no bounce, `prefers-reduced-motion` respected
+- §8 Iconography: ONE family
+- §9 Responsive: mobile-first
+- §10 Anti-pattern checklist (the auto-runnable one)
 
-If frontend work is involved, generate `.planning/DESIGN.md` from the template with concrete palette, distinctive typography (NEVER Inter/Roboto/system-ui), 8px spacing grid, motion approach, component patterns.
+Cross-check the result against `rules/design-laws.md` §8 absolute bans BEFORE writing — the design must not propose any banned pattern.
 
 ```bash
 git add .planning/DESIGN.md .planning/config.json
-git commit -m "docs: design direction + config"
+git commit -m "docs: DESIGN.md — direction commit + OKLCH palette + tokens"
 ```
 
 ### Step 8. Run Research (ALWAYS, no permission ask)

package/skills/qualia-polish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-polish
-description: "Design and UX pass — anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified."
+description: "Scope-adaptive design pass — works on a single component, a route, the whole app, or a ground-up redesign. Trigger on 'polish', 'design pass', 'fix the design', 'redesign', 'critique', 'audit design', 'looks ugly', 'make it look better'. Replaces both /qualia-polish and /qualia-design from earlier versions."
 allowed-tools:
   - Bash
   - Read
@@ -9,207 +9,251 @@ allowed-tools:
   - Grep
   - Glob
   - Agent
+argument-hint: "[file|route|--redesign|--critique|--quick] [--register=brand|product]"
 ---
 
-# /qualia-polish — Design Pass
+# /qualia-polish — Scope-Adaptive Design Pass
 
-Makes it look like a human designer built it. Kills AI slop. Run after all feature phases are verified.
+One command. Six scopes. Use it whenever you need design work — from a 30-second component touch-up to a 30-minute ground-up redesign.
 
-## The Standard
+## Scopes
 
-Every site Qualia ships must feel **designed, not generated.** AI-generated sites have tells:
-- Identical card grids with rounded corners and soft shadows
-- Blue-purple gradients on everything
-- Inter/system-ui font with no hierarchy
-- Generic hero with centered text and a stock gradient background
-- Fixed-width containers leaving dead space on wide screens
-- No motion, no personality, no opinion
-- Perfect symmetry everywhere (real design has tension)
+The first argument selects the scope. Stage selection follows from scope.
 
-**Kill all of these.** A Qualia site should make someone ask "who designed this?" — not "which template is this?"
+| Invocation | Scope | Runtime | Stages |
+|---|---|---|---|
+| `/qualia-polish src/components/Button.tsx` | **Component** | ~30s | 0, 2, 3, 7 |
+| `/qualia-polish app/dashboard` | **Section** | ~3m | 0, 1 (light), 2, 3, 4, 7 |
+| `/qualia-polish` | **App** | ~12m | all 7 (fan-out batches of 5) |
+| `/qualia-polish --redesign` | **Redesign** | ~30m | all + Stage 1 mandatory + 2 vision iterations |
+| `/qualia-polish --critique` | **Critique** | read-only | 0, 4, 5 (no edits) |
+| `/qualia-polish --quick` | **Quick** | ~1m | 0, 2, 7 (gates only, no vision loop) |
 
-## Process
+Other flags: `--register=brand|product` to override register inference.
 
-```bash
-node ~/.claude/bin/qualia-ui.js banner polish
+## Setup gates (non-optional, every scope)
+
+Before any work — design or otherwise — pass these gates. Skipping them produces generic output that ignores the project.
+
+| Gate | Required check | If fail |
+|---|---|---|
+| Substrate | `rules/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md` exist and have been read | Read them. |
+| PRODUCT | `PRODUCT.md` exists at project root, has `register:` field, and is not placeholder (`[TODO]` markers, < 200 chars) | Run setup: ask 5 questions and generate it. Never synthesize from prompt alone. |
+| DESIGN | `DESIGN.md` exists. If missing on App / Redesign scope, BLOCK and run setup. If missing on Component / Section / Critique / Quick scope, NUDGE and proceed. | Generate from PRODUCT.md + 3 questions. |
+| Slop-detect | `bin/slop-detect.mjs` is callable | Install or pull from framework. |
+| Mutation | All gates above pass | Do not edit project files yet. |
+
+State this preflight explicitly before editing:
+
+```
+POLISH_PREFLIGHT: substrate=pass product=pass design=pass|nudged slop_detect=pass mutation=open
 ```
 
-### 0. Load Design Context
+## Process
 
 ```bash
-cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
+node ~/.claude/bin/qualia-ui.js banner polish
 ```
 
-If DESIGN.md exists → it's the standard. Read ALL 12 sections. Key sections for polish:
-- §1 Visual Theme — the feel and signature details
-- §2 Color Palette — exact hex values, CSS variables, contrast ratios
-- §3 Typography — hierarchy table with exact sizes/weights/spacing
-- §4 Components — exact button/card/input/badge specs
-- §5 Layout — spacing scale, grid strategy
-- §6 Depth & Elevation — shadow levels with exact rgba values
-- §7 Do's/Don'ts — brand-specific guardrails
-- §9 Agent Prompt Guide — quick reference for common patterns
-- §10 Accessibility — WCAG checklist
-- §11 Hardening — stress-test criteria
-- §12 Anti-Slop Detection — grep patterns for automated checks
+### Stage 0 — Direction commit (mandatory; light on small scopes)
 
-If no DESIGN.md → use `rules/frontend.md` defaults.
+Read PRODUCT.md and DESIGN.md. Identify the **register** — Brand (marketing/landing/portfolio) or Product (app/admin/dashboard). Priority for register inference:
 
-Read EVERY frontend file before modifying. No blind edits.
+1. The path of the target file/route (e.g., `/marketing/*` → brand; `/app/*` → product)
+2. `register:` field in PRODUCT.md
+3. `--register` flag override
 
-### 1. AI Slop Detector
+For App / Redesign scope, write the brief BEFORE any code (use `ultrathink`):
 
-Run these checks first. Any hits = mandatory fixes.
+```
+Aesthetic direction:  {editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · ...}
+Color strategy:       {Restrained · Committed · Full palette · Drenched}
+Scene sentence:       {who uses this, where, ambient light, mood — concrete}
+Differentiation:      {what someone remembers 24 hours later}
+```
 
-```bash
-# Generic fonts (the #1 AI tell)
-grep -rn "Inter\|Roboto\|Arial\|Helvetica\|system-ui\|Space.Grotesk" --include="*.tsx" --include="*.css" --include="*.scss" --include="tailwind*" app/ components/ src/ 2>/dev/null | grep -v node_modules
+For Component / Section / Quick scope, the brief is implicit (loaded from DESIGN.md). Skip the ultrathink step but cite the relevant DESIGN.md tokens you'll touch.
 
-# Hardcoded max-width containers (screams template)
-grep -rn "max-w-7xl\|max-w-\[1200\|max-w-\[1280\|max-width.*1200\|max-width.*1280" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
+For Critique scope, no commit needed — you're scoring, not editing.
 
-# Blue-purple gradients
-grep -rn "from-blue.*to-purple\|from-purple.*to-blue\|linear-gradient.*blue.*purple\|linear-gradient.*purple.*blue\|from-indigo.*to-violet" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
+### Stage 1 — Static gates (no browser, deterministic)
 
-# Card grid monotony (same card component repeated in a grid)
-grep -rn "grid-cols-3\|grid-cols-4" --include="*.tsx" app/ components/ src/ 2>/dev/null | head -5
+```bash
+# Anti-pattern scan (the slop-detect script)
+node bin/slop-detect.mjs {target_paths}
 
-# Generic hero patterns
-grep -rn "text-center.*mx-auto\|Hero\|hero" --include="*.tsx" app/ components/ src/ 2>/dev/null | head -5
+# TypeScript still compiles?
+npx tsc --noEmit 2>&1 | head -20
 
-# Scattered hardcoded colors (no design system)
-grep -rn "text-\[#\|bg-\[#\|border-\[#\|color:.*#\|background:.*#" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l
+# Token enforcement (if Stylelint configured)
+npx stylelint "src/**/*.css" 2>&1 | head -20  # optional, skip silently if not configured
 ```
 
-**Every hit gets fixed.** Not flagged — fixed.
+ANY critical-severity slop hit = mandatory fix before proceeding. Don't stage anything until critical findings are zero.
 
-### 2. Typography Pass
+### Stage 2 — Generation (forked subagents, batches of 5 files)
 
-**Goal:** A reader should feel the type was chosen, not defaulted.
+For App / Redesign / Section scope on multi-file work:
 
-- Pick a distinctive display font. Not Inter, not Roboto, not system. Something with character: Clash Display, Cabinet Grotesk, General Sans, Satoshi, Plus Jakarta Sans, Outfit, Sora, Manrope. Pair with a clean body font.
-- Establish clear hierarchy: display (hero text) → h1 → h2 → h3 → body → caption
-- Body: 16px minimum, line-height 1.5-1.7
-- Headings: tighter line-height (1.1-1.3), negative letter-spacing (-0.02em) for display sizes
-- Weight hierarchy: Regular (400) for body, Medium (500) for labels, Semibold (600) for headings, Bold (700) for display
-- Prose content: `max-width: 65ch`. Everything else: fluid full-width.
-- Use `clamp()` for fluid sizing: `clamp(2rem, 1rem + 3vw, 3.75rem)` for h1
+- Count target files. If ≤ 5, process in main context.
+- If > 5, fan out: spawn one Agent per batch of 5 files IN THE SAME RESPONSE TURN (parallel execution).
+- If the conversation already contains design-taste discussion (font/color/motion preferences threaded across multiple turns), prefer **forked subagents** (`--fork-session`) so they inherit the taste context. Otherwise, blank-context fan-out is fine for mechanical fixes.
 
-### 3. Color & Surfaces
+Each agent receives:
+- `rules/design-laws.md` + the matching register file
+- `PRODUCT.md` + `DESIGN.md` (inlined)
+- Its 5 files (paths + contents)
+- Instruction: apply the Design Quality Rubric per file. Fix every dimension scoring < 3. Make literal edits. Do NOT change logic — only styling.
 
-**Goal:** A palette that looks intentional, not random.
+For Component scope: do the work in main context. Read, fix, verify.
 
-- Define all colors as CSS variables or Tailwind config — zero scattered hex values
-- One dominant brand color. One sharp accent for CTAs that pops against the page.
-- Surfaces: layer them. Background → card → elevated card. Use subtle shade differences, not just white-on-white.
-- Dark mode (if present): rethink surfaces, don't just invert. Slightly reduce contrast. Use darker brand colors, not just white→black swap.
-- Semantic colors with non-color indicators: success (green + checkmark), error (red + icon), warning (amber + triangle)
-- Verify WCAG AA: 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+)
+**Apply fixes scoped by what's missing:**
 
-### 4. Layout & Spacing
+| If the file scores low on… | Apply fix from… |
+|---|---|
+| Typography | DESIGN.md §3 — font tokens, scale, weight hierarchy, tabular numerals |
+| Color cohesion | DESIGN.md §2 — OKLCH tokens, replace hex, verify contrast |
+| Spatial rhythm | DESIGN.md §4 — fluid spacing scale, vary by content |
+| Layout originality | register file (brand or product) — kill three-column grids, vary layout |
+| Shadow hierarchy | DESIGN.md §6 — elevation tokens, brand-tinted shadows |
+| Motion intent | DESIGN.md §7 — easing, stagger, signature motion |
+| Microcopy | rename "Get Started" / "Learn More" to action-named CTAs |
+| Container depth | flatten card-on-card; remove side-stripe borders |
 
-**Goal:** Full-width, fluid, generous. No dead space gutters.
+### Stage 3 — Runtime gates (App / Section / Redesign only — needs dev server)
 
-- Full-width layouts with fluid padding: `clamp(1rem, 5vw, 4rem)` horizontal
-- 8px spacing grid: 4, 8, 12, 16, 24, 32, 48, 64, 96
-- Tight spacing within groups (related items). Generous spacing between sections.
-- Break symmetry where it serves the design — offset grids, overlapping elements, diagonal flow
-- Varied layouts: not every section should be a centered-text-with-cards-below. Use side-by-side, staggered, asymmetric, full-bleed.
-- Section spacing: `clamp(2rem, 8vw, 6rem)` vertical padding
+If a dev server is up at `http://localhost:3000` (or detected via `lsof` on common ports):
 
-### 5. Interactive States
+```bash
+# Lighthouse-CI — numeric a11y/perf/best-practices
+npx lhci autorun \
+  --collect.url=http://localhost:3000{route} \
+  --collect.numberOfRuns=1 \
+  --assert.assertions='{
+    "categories:accessibility":   ["error", {"minScore": 0.9}],
+    "categories:performance":      ["warn",  {"minScore": 0.7}],
+    "categories:best-practices":   ["warn",  {"minScore": 0.8}]
+  }' 2>&1 | tail -30
+
+# axe-core direct (catches what Lighthouse misses)
+npx @axe-core/cli http://localhost:3000{route} --exit 2>&1 | tail -30
+```
+
+If Lighthouse/axe not installed, skip silently and note in the report. Don't fail the polish over missing tooling.
 
-**Goal:** Every clickable thing responds. Every async operation shows progress.
+If a11y < 90 OR axe critical/serious violations: **fix programmatically** (these are deterministic — no vision needed). Re-run to confirm.
 
-- **Hover:** color shift or underline within 150ms ease-out. `cursor: pointer` on ALL clickables.
-- **Focus:** visible ring (2px+ offset, contrasting color). Never `outline: none` without replacement.
-- **Active/pressed:** subtle scale down (`transform: scale(0.98)`) or color shift.
-- **Disabled:** opacity 0.5 + `cursor: not-allowed` + `aria-disabled="true"`
-- **Loading:** skeleton shimmer or spinner on every async operation. Never a blank void.
-- **Empty:** helpful message + CTA on empty lists/tables. Not just "No results."
-- **Error:** user-friendly message + recovery action. Not raw error text. Use `aria-live="assertive"`.
+### Stage 4 — Vision loop (Redesign scope only — max 2 iterations)
 
-### 6. Motion & Personality
+Use Anthropic's `webapp-testing` skill (Playwright). Capture screenshots at 3 viewports: 375 / 768 / 1280. Single browser (Chromium) is fine in 2026 — cross-browser CSS rendering differences are vanishingly rare.
 
-**Goal:** The site feels alive, not static. But tasteful — not a circus.
+```
+viewports: [
+  { width: 375,  height: 812,  name: 'mobile' },
+  { width: 768,  height: 1024, name: 'tablet' },
+  { width: 1280, height: 800,  name: 'desktop' }
+]
+```
 
-- Page load: stagger children entrance (50-80ms delay between items, `fadeUp` animation, 300ms)
-- Hover transitions: 150-200ms ease-out
-- Section transitions: 300-500ms with `cubic-bezier(0.4, 0, 0.2, 1)`
-- One signature motion that gives the site personality (parallax, scroll-triggered reveal, magnetic buttons, morphing shapes)
-- **Always** `prefers-reduced-motion: reduce` — disable non-essential animation
-- CSS-only for static sites, `motion/react` (formerly Framer Motion) for React
+For each iteration:
 
-### 7. Accessibility (Non-Negotiable)
+1. Capture all 3 viewports
+2. Pass to a vision-model agent with `rules/design-rubric.md` as the prompt anchor + DESIGN.md as the spec
+3. The agent scores 8 dimensions, anchored 1-5, with evidence per dimension
+4. Apply fixes ONLY to dimensions scored 1 or 2 (don't nitpick 3s; prevents oscillation)
+5. STOP if: all dimensions ≥ 3 (success), OR any dimension regressed from previous iteration (regression-stop), OR 2 iterations reached (hard cap)
 
-- Semantic HTML: `nav`, `main`, `section`, `article`, `header`, `footer` — not div soup
-- One `h1` per page, sequential heading order (no h1 → h3 skip)
-- All images: descriptive `alt` (or `alt=""` + `aria-hidden` if decorative)
-- All form inputs: visible `<label>` with `htmlFor` — not placeholder-only
-- All interactive elements: keyboard accessible (Tab, Enter, Escape, Arrow keys)
-- Touch targets: 44x44px minimum
-- Skip link: `<a href="#main" class="sr-only focus:not-sr-only">` as first focusable element
-- `<html lang="en">` set
-- Color never the sole information carrier — icons, text, patterns as supplements
-- `aria-live="polite"` for toast notifications and dynamic content updates
+**The anchored rubric is mandatory.** Without it, vision models say "looks great!" to everything. Quote from the rubric prompt: "Score 3 = acceptable. Only 1-2 = must fix. 4-5 = exceeds. Default to 3 unless you can cite specific evidence."
 
-### 8. Responsive (Mobile-First)
+### Stage 5 — Drift audit (App / Redesign / Critique scope)
 
-- Base styles for mobile (320px), scale up with `min-width` breakpoints
-- Test at: 320px (small phone), 375px (iPhone), 768px (iPad), 1024px (laptop), 1440px (desktop)
-- No horizontal scroll at any viewport
-- Navigation: hamburger/drawer on mobile, full horizontal on desktop
-- Stack on mobile, expand on desktop
-- Fluid typography with `clamp()`
-- Images: `max-width: 100%`, responsive `srcset`, `next/image` with width/height
-- Tables: card layout or horizontal scroll on mobile
+Compare the implementation against DESIGN.md as source of truth. Flag deltas.
 
-### 9. Harden (Edge Cases)
+```bash
+# Find tokens used in code that don't exist in DESIGN.md
+grep -rE "var\(--[a-z-]+\)" src/ app/ components/ 2>/dev/null | \
+  awk -F'var\\(--' '{print $2}' | awk -F'\\)' '{print $1}' | sort -u > /tmp/used-tokens
+grep -E "^\s*--[a-z-]+:" templates/DESIGN.md | sed -E 's/.*--([a-z-]+):.*/\1/' | sort -u > /tmp/declared-tokens
+comm -23 /tmp/used-tokens /tmp/declared-tokens > /tmp/orphan-tokens
+[ -s /tmp/orphan-tokens ] && echo "── orphan tokens (used in code, missing from DESIGN.md) ──" && cat /tmp/orphan-tokens
+
+# Find raw hex still appearing
+grep -rnE "#[0-9a-fA-F]{6}\b" src/ app/ components/ --include="*.tsx" --include="*.css" 2>/dev/null | \
+  grep -v "shadow\|outline\|currentColor" | head -20
+```
 
-After all visual work, stress-test:
-- Long text: does a 200-character username break the layout?
-- Empty everywhere: all lists empty, all data missing — does it still make sense?
-- Error everywhere: every fetch fails — are error states visible and helpful?
-- 320px viewport: nothing overflows, nothing clips, nothing overlaps
-- Keyboard only: Tab through the entire app — can you reach everything? Is focus visible?
-- Slow network: are loading states visible? Does content stream in or flash?
+Drift findings get reported, not auto-fixed (drift may be intentional). For Critique scope, this IS the deliverable.
 
-### 10. Verify & Ship
+### Stage 6 — Verify (every scope)
 
 ```bash
-npx tsc --noEmit 2>&1 | head -20
+# Re-run Stage 1 — all critical findings must be zero
+node bin/slop-detect.mjs {target_paths}
+[ $? -eq 0 ] || { echo "polish failed — slop-detect still finds critical issues"; exit 1; }
+
+# TypeScript clean
+npx tsc --noEmit 2>&1 | tail -10
 ```
 
-Fix any TypeScript errors.
+### Stage 7 — Commit & state
+
+For Critique scope: write the report to `.planning/polish-critique-{timestamp}.md` and STOP. Do not edit, do not commit.
+
+For all other scopes:
 
 ```bash
-git add {changed files}
-git commit -m "polish: design pass — typography, color, states, motion, responsive, a11y"
+git add {modified files}
+git -c user.name="Qualia Solutions" -c user.email="info@qualiasolutions.net" commit -m "$(cat <<'EOF'
+polish({scope}): {brief summary}
+
+- {key change 1}
+- {key change 2}
+- rubric scores: typography {N}, color {N}, ..., aggregate {N}/40
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
 ```
 
+If this is the FINAL polish before deploy (Handoff milestone, last phase):
+
 ```bash
 node ~/.claude/bin/state.js transition --to polished
 ```
 
+Otherwise, no state transition (polish is now a normal verb, not a phase boundary).
+
+### Output
+
 ```bash
 node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "AI slop: killed"
-node ~/.claude/bin/qualia-ui.js ok "Typography: {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Color: {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Layout: {brief}"
-node ~/.claude/bin/qualia-ui.js ok "States: {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Motion: {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Accessibility: {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Responsive: {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Hardened: {brief}"
-node ~/.claude/bin/qualia-ui.js end "POLISHED" "/qualia-ship"
+node ~/.claude/bin/qualia-ui.js ok "Scope: {component|section|app|redesign|critique|quick}"
+node ~/.claude/bin/qualia-ui.js ok "Files: {N}"
+node ~/.claude/bin/qualia-ui.js ok "Slop-detect: {N critical, M high, K medium}"
+node ~/.claude/bin/qualia-ui.js ok "Rubric aggregate: {N}/40 (avg {N})"
+node ~/.claude/bin/qualia-ui.js ok "Vision iterations: {0|1|2}"
+node ~/.claude/bin/qualia-ui.js ok "Drift findings: {N}"
+node ~/.claude/bin/qualia-ui.js end "POLISHED" "{next command — depends on context}"
 ```
 
 ## Rules
 
 1. **Read before write.** Understand every file before changing it.
-2. **DESIGN.md is law.** If it exists, follow it. Don't override client decisions.
+2. **DESIGN.md is law.** If a project decision exists, follow it. Don't override.
 3. **Don't break functionality.** Only change styling, never logic.
-4. **AI slop is a bug.** Generic fonts, card grids, blue-purple gradients, centered-everything — treat these as defects, not preferences.
+4. **Slop is a bug.** Critical-severity findings block commit. No overriding the script.
 5. **TypeScript must pass** after every change.
-6. **One commit** at the end — not per category.
+6. **One commit per polish run** — not per category, not per file.
+7. **Forked subagents inherit taste.** When the conversation has design discussion, fork. Otherwise blank-context.
+8. **The rubric is anchored.** Score = 3 means ships. Default there. Justify deviations.
+
+## Failure modes (handle gracefully)
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `bin/slop-detect.mjs not found` | Framework not installed in project | Run `npx qualia install` or pull script from framework repo |
+| `PRODUCT.md missing` | Pre-v4.5.0 project | Run setup (ask 5 questions, generate). For Component scope, can proceed with nudge. |
+| `Lighthouse not installed` | Optional tool | Skip Stage 3 numeric gates, note in report. Don't fail. |
+| `webapp-testing skill not present` | Optional Anthropic skill | Skip Stage 4 vision loop on Redesign scope. Note in report. Recommend installing. |
+| Vision loop oscillates between iterations | Rubric not anchored properly | Verify rubric prompt instructs "default to 3, only 1-2 = fix". Hard cap at 2 iterations. |
+| User says "you missed X" after polish completes | Scope was too narrow | Re-run with wider scope (`/qualia-polish` whole-app). Don't argue scope. |