Review deck v2 — the approved page, answers file + submit hand-off, rig-measured boxes, rig fixes

.claude/skills/ui-review/SKILL.md

@@ -58,24 +58,22 @@ then a **review page** — never a gallery, never a chat summary:
 1. Capture the branch: `bash scripts/ui-review/run-review.sh <worktree> scratch/<phase>`
    (it starts its own server on Vite 5473 and refuses if that port serves another worktree).
    For a second variant, a second worktree + run dir.
-2. Write `docs/active/design/<audit>/<phase>-cards.json` (copy `phase-c-cards.json`), then
-   `python3 scripts/ui-review/review-cards.py crop <spec>` and `… build <spec>`. Crop regions
-   come from `scripts/ui-review/crops.json`; add new ones there. The page is a **deck — one
-   point at a time**: one screenshot with ONE ring on the target, one line of problem, one
-   line of fix, `measured`/`judgment` tag, Yes / No / Tell me more (keys Y/N/M), progress dots, summary +
-   copyable feedback at the end. Rationale and ledger corrections go under the collapsed
-   "Why / details", never in the headline. Three formats were rejected before this one
-   (gallery → prose page → board of cards): "not clear where I'm supposed to glance/select".
-   `review-page.py` is the old prose format, kept only for the Phase A/B pages.
-3. Every item on the page carries, in this order: the problem **with the measured number
-   or the broken behaviour**, exactly what was edited, 1:1 crops of the element per theme
-   (before / after, a column per variant), what he'll notice + the risks *against* the
-   change, alternatives considered, and a decision control. **Tag each item `measured`,
-   `judgment` or `mixed`** and say which parts are which — on 2026-08-25 a taste argument
-   (P-12) went in as if it were a defect and was rightly rejected on sight.
-4. Hand Destin the page path; he pastes the generated feedback block. Act on it exactly;
-   record the decisions in the findings ledger (the row, not a new section), the guide,
-   the ROADMAP entry, and a `banner` on the page. Merge, archive, clean up.
+2. Write `docs/active/design/<audit>/<phase>-review.json` (copy `phase-c-review-v2.json`): one
+   step per point with `surface`, `path`, `crop`, `highlight` (`"auto"` for before/after, else
+   `{"selector": …}` measured by the rig), and the four texts — **headline** (≤ 25 words, what a
+   user sees), **changed** (what was edited, plain words, with `measured` when there is a number),
+   **notice** (what changes for users — intended and side effects), **risk** (what could look
+   wrong, or is not shown faithfully). The builder refuses jargon (token, primitive, selector,
+   IPC, prop, reducer, handler, component…), a missing picture, or an unresolved box.
+3. `python3 scripts/ui-review/review-cards.py serve <spec>` **in the background** (it builds
+   first; fix every `missing:` line it prints — a measurement that is missing means the plan
+   needed a `measure` line before the Before run). The browser opens itself; Destin answers
+   Yes / No / Other per step with an optional note and presses Submit; the background command
+   exits with the summary (exit 0 = submitted, summary on stdout; 2 = nobody submitted before the
+   timeout; 3 = another process already serves this spec — neither 2 nor 3 carries answers, do not
+   invent a result) (`wait <spec>` if you lost the process). Never ask him to paste anything.
+4. Act on the summary exactly (`Other` + note = change it as described); record decisions in the
+   findings ledger row, the guide, the ROADMAP entry. Merge, archive, clean up.
 
 ## Red flags
 

.gitignore

@@ -82,3 +82,10 @@ docs/active/investigations/harness-eval-runs/**
 
 # UI-audit screenshot sheets (evidence for docs/active/design/2026-08-25-*); regenerate per the folder README
 docs/active/design/*-ui-audit/images/
+*.answers.json
+*.answers.*.json
+*.serve.json
+
+# Python bytecode from the deck tooling + its tests
+__pycache__/
+*.pyc

CLAUDE.md

@@ -116,7 +116,7 @@ bash scripts/run-dev.sh <branch-or-worktree> --label "Feature Name"
 
 ### New Features & UI/UX Changes
 
-When designing new features or making changes to user-facing app interfaces, the first step should always be to visualize and design the UI/UX of the final feature. Planning sessions should prioritize iterative UI design using the workbench and other tooling to help Destin shape the final user experience of the feature before building backend. When Destin provides final sign-off on the UI/UX design for the feature, the UI/UX should be treated as largely final and backend should be designed around the UI/UX accordingly. The standard every new surface is measured against is `docs/active/design/2026-08-25-ui-design-guide.md` (five laws, primitives, per-surface anatomies, checklist); show him the change as a **review deck** (`scripts/ui-review/review-cards.py` — one point per step: one screenshot, one ring, one problem line, one fix line, Yes / No / Tell me more, Before/After flip), built from the UI review rig below; never a gallery, a prose page or a chat description (all three were rejected).
+When designing new features or making changes to user-facing app interfaces, the first step should always be to visualize and design the UI/UX of the final feature. Planning sessions should prioritize iterative UI design using the workbench and other tooling to help Destin shape the final user experience of the feature before building backend. When Destin provides final sign-off on the UI/UX design for the feature, the UI/UX should be treated as largely final and backend should be designed around the UI/UX accordingly. The standard every new surface is measured against is `docs/active/design/2026-08-25-ui-design-guide.md` (five laws, primitives, per-surface anatomies, checklist); show him the change as a **review deck** (scripts/ui-review/review-cards.py — one point per step: Before | After with the changed region boxed by the rig, a headline and three cards — What changed / You'll notice / Risk — Yes / No / Other, answers saved to a file and handed to Claude on Submit; `serve <spec>` in the background does it all), built from the UI review rig below; never a gallery, a prose page or a chat description (all three were rejected).
 
 ### UI Workbench
 

ROADMAP.md

@@ -1141,6 +1141,9 @@ surface, not a history.
   Destin's ask: the session switcher (`SessionStrip.tsx` — NOT `SessionDrawer.tsx`, which is the artifacts/Files drawer) and panel-opening transitions feel abrupt/undertuned and deserve real motion design. Not scoped — no design pass, no target easing/duration, no list of which panels. Likely pairs with the UI-consistency work under Features once that reaches tranches touching session-switcher UI.
 - [ ] Session switcher should use the theme's rounding rules `idea` `#renderer` `#ui` `#themes` (added 2026-07-20)
   Destin's ask: the session switcher's (`SessionStrip.tsx`) corners should follow whatever rounding rule the active theme sets. **Checked 2026-07-20 and the premise may already hold, in which case this is a verify-not-build item:** `SessionStrip.tsx` already uses plain Tailwind `rounded-full`/`rounded-lg`/`rounded-sm` utilities throughout (no hardcoded `rounded-[Npx]` or inline `border-radius` found), and `globals.css`'s `@theme` block maps those straight to `--radius-*` custom properties, which `theme-engine.ts`'s `applyThemeToDom` overwrites per-theme from an optional `shape.radius*` block in `ThemeShape` (`theme-types.ts`) — `theme-builder`'s `manifest-template.jsonc` even lists corner rounding as a *required* Kit field with named presets ("Heavily rounded" vs "Minimal rounding — brutalist", `kit-presets.json`), and the community `golden-sunbreak` theme already overrides it. **The likely real gap:** all four BUILT-IN themes (light/dark/midnight/creme) currently ship identical radius values (`globals.css`), so there's nothing to visually confirm this against without installing/building a theme with a different rounding preset — if Destin observed the switcher NOT rounding correctly under some theme, that's a repro to chase (possibly a stale/cached class, a z-order surface that isn't `.session-strip` itself, or a spot missed by the grep), not a missing token. Verify against an actual differently-rounded theme before assuming code needs to change.
+- [ ] Workbench serves community theme folders (`theme-asset://`) so decks show real previews `idea` `#tooling` (added 2026-08-27)
+- [ ] Attach your own screenshot to a review-deck step (the serve endpoint can accept uploads) `idea` `#tooling` (added 2026-08-27)
+- [ ] Review-deck test hygiene: bare `open()` in `scripts/ui-review/tests/{fixture,test_spec,test_serve}.py` prints ResourceWarnings that bury real failures; `shot-measure.test.mjs` sleeps 800 ms for python's http.server instead of polling the port and never tests the `run: null` branch; no test drives `review-cards.py serve`'s build-failure short-circuit (exit 1, no server) `chore` `#tooling` `#tests` (added 2026-08-27, from the deck-v2 final review)
 
 ## Shipped