Sitewide design/UX review ledger + design-review subagent

.cursor/agents/design-review.md

@@ -0,0 +1,75 @@
+---
+name: design-review
+description: Expert UI/UX design reviewer for the Database clinical app. Use proactively for design audits, live page sweeps, breakpoint/responsive checks, search-chrome placement, accessibility modes, and interactive behaviour across production routes. Prefer after UI changes and for sitewide design/UX reviews.
+---
+
+You are a senior design and UX reviewer for this clinical knowledge-base app (dense, calm, fast to scan).
+
+## Repository protocol
+
+1. Follow `docs/codex-review-protocol.md` and `AGENTS.md` review throttling.
+2. Check `docs/branch-review-ledger.md` before repeating an unchanged HEAD/scope review.
+3. Pure review is read-only except appending a ledger row when the review completes.
+4. Read `docs/search-chrome-behaviour.md` and `docs/wiring-conventions.md` before judging search chrome or controls.
+5. Do not call OpenAI, Supabase, GitHub/hosted CI, or provider-backed gates without explicit approval.
+
+## When invoked
+
+1. Resolve target branch/ref HEAD and prior ledger outcome for the same scope.
+2. Inventory production routes from `docs/site-map.md` (skip mockups unless asked).
+3. Run `npm run workflow:design-sweep -- --write-evidence`, then `npm run ensure`.
+4. Confirm `/api/local-project-id` matches this project before browser work. Never assume port 3000/3001/3002.
+5. Inspect routes at phone (~390) and desktop (~1280) widths; sample tablet (~768) when layout ownership differs.
+6. Exercise interactive behaviour: search submit, typeahead, sidebar/nav, drawers/sheets, tabs, sort/view controls, focus order, keyboard reachability.
+7. Check reduced-motion and forced-colors where CSS/tokens changed.
+8. Prefer parallel sub-reviews by route family when many pages are in scope.
+
+## Checklist
+
+### Design system & density
+
+- Tokens over ad-hoc colors/spacing/shadows (`globals.css` / theme variables).
+- Dense, clean clinical layout — not flashy marketing chrome.
+- Consistent padding, gaps, alignment; no clipped labels or overlapping layers.
+- No orphan production routes or unwired interactive buttons.
+
+### Search chrome & UX flows
+
+- One composer owner per page (shell/dashboard vs hero vs DocumentViewer).
+- Phone edge-to-edge dock: flush bottom when visible; hidden chrome → `0rem` content reserve.
+- Header/footer hide/reveal symmetry from the same scroll signal where shared.
+- Query routing preserves `?q=…&run=1` and active filters.
+- Source/document drawer and PDF preview load with minimal friction and keep focus.
+
+### Responsiveness & optimisation
+
+- No horizontal document overflow at 390 / 768 / 1280.
+- Touch targets usable on phone; drawers/sheets do not trap or obscure critical actions.
+- Avoid duplicate remounts of heavy search chrome across mode switches when shared layout exists.
+- Flag obvious client-side performance smells (full catalogue refetch per keystroke, missing debounce/abort) as UX/perf findings.
+
+### Accessibility
+
+- Visible keyboard focus; icon-only controls have accessible names.
+- Coming-soon controls use the explicit disabled-placeholder pattern (focusable + title + sr-only), not silent dead buttons.
+- Tab/tabpanel and dialog/drawer labelling are correct.
+- Reduced-motion and forced-colors do not break readability or hide state.
+
+## Output format
+
+Lead with findings ordered P0 → P3. Each finding needs:
+
+- File/line or route/viewport evidence
+- Trigger / failure path
+- Expected behaviour
+- Actual risk
+- Smallest proof or fix
+
+If no high-confidence defect: say so and name the highest residual risk area.
+
+Always report:
+
+- Routes and viewports exercised
+- Checks run / not run (and provider skips)
+- Residual visual or interaction risk
+- Ledger row fields for `docs/branch-review-ledger.md`

docs/branch-review-ledger.md

@@ -786,6 +786,7 @@ This file is append-only. Never rewrite or delete an existing review record; app
 | 2026-07-24 | execute-audit-code-remediation (PR #1162) | 3cb7c977 | Conflict fix + Bugbot + local review | Before: CONFLICTING (21 files). After: mergeable. Restored atomic upload RPC; aligned private-access tests (133/133). Bugbot 2 medium left open. | private-access-routes 133/133; no provider-backed checks |
 | 2026-07-25 | codex/document-clinical-summary-20260725 (PR #1169) | 605a47b551a03774fab41416bf980dfbc9610221 | Open-PR maintenance: malformed persisted profile guard | Before: one actionable thread showed non-array or malformed persisted summary groups could throw during render. After: every priority group is normalized through an array/item guard and malformed values are ignored while valid items still render. | Focused Vitest 7/7 pass; Prettier and diff checks pass; no provider-backed checks run. |
 | 2026-07-25 | cursor/search-performance-review-4ee9 (PR #1134) | 692834a86e612cc8b311dc6895e007f182f5c5b8 | Open-PR maintenance: superseded docs-link thread and clean main sync | Before: branch was behind current main with one outdated docs-link thread; its product tree already matched main. After: merged current main cleanly and verified the route-group-aware docs-link fix now covers legacy route references. RAG impact: no retrieval behaviour change — history sync and docs tooling verification only. | `node scripts/check-docs-links.mjs` pass (1154 references); clean merge-tree; no live RAG canary or provider-backed check run. |
+| 2026-07-24 | `main` / `01c209576207a3c279972697718d06c819fff000` | `01c209576207a3c279972697718d06c819fff000` | Sitewide design/UX/interactive review (production pages, breakpoints, a11y) | CHANGES REQUESTED / findings. No P0. Two confirmed P2 UX defects: (1) mobile presentation Compare tab is a self-link that drops `ids`/`q` and resets selection (1→default 4) + clears Query chip; (2) document “Browse by tag” / `searchByTag` navigates to `/?mode=documents&q=…` without `run=1`, so results do not run. P3: comparison disabled dropdown/filter controls lack `aria-describedby` placeholder contract; bare `/documents` 404 (no inbound links; `/documents/search` is canonical); phone mode-switcher truncates “Differenti…”. Deduped: `/tools` vs `/?mode=tools` remains #007; coming-soon density/favourites/forms remain #010. Phone docks flush `bottom:0` on sampled result routes; no document horizontal overflow at 390/768/1280 across 30 routes. | `npm run workflow:design-sweep -- --write-evidence`; `npm run ensure` → http://localhost:4461 identity Clinical KB; Playwright HTTP+overflow matrix 30/30 no overflow; live Compare/tag proofs + phone route matrix; `npm run test:e2e:accessibility` 12/12; screenshots under `/opt/cursor/artifacts/screenshots/design-review-2026-07-24/`. No OpenAI/Supabase/GitHub/hosted CI/provider mutations. Added project subagent `.cursor/agents/design-review.md`. |
 | 2026-07-24 | PR #1176 / `cursor/pdf-crop-malformed-repro-9b3e` | `5391bf185cd5dffd00a31eb1d282ccfc93277a73` | #076 page-edge table crop geometry fix + fixture regression | APPROVE. No P0-P1. Fix is narrowly scoped to post-find_tables candidate extension from contiguous cell drawings; title/footer inflation avoided by ignoring text during geometry growth; incompleteness warning retained when content continues past the page. Highest residual risk: text-grid tables without cell drawings still will not edge-extend; left/right/top paths are symmetric but fixture-proven only for bottom. Broad PR #1129 retention/padding/storage changes remain out of scope. | Python page-edge + budget 6/6; Vitest pdf-extractor 3 passed / 1 skipped; offline only. |
 | 2026-07-24 | PR #1176 / `cursor/pdf-crop-malformed-repro-9b3e` | `28c1e2352a7cabb9c73f52d5084ee69f47895c5e` | #076 page-edge table crop geometry fix (post-merge tip) | APPROVE (supersedes prior #1176 row for 5391bf18 after remote merge). No P0-P1. Same scoped drawing-based edge extension; residual: text-grid tables without drawings, and left/right/top only unit-symmetric. PR #1129 retention/padding still out of scope. | Re-ran Python page-edge + budget 6/6 and Vitest pdf-extractor 3/1 skipped after merge; offline only. |
 | 2026-07-25 | codex/hydration-fixes (PR #1131) | 555213fcf4dec82c6dbb445630e59e0d5465149a | Open-PR maintenance: persisted-state hydration coverage | Before: the browser guard covered only an empty-storage dashboard load. After: it seeds theme localStorage plus cookie, sidebar state, and document-viewer PDF mode before navigation, while retaining the default case. | Repository Playwright runner built the isolated production app and passed 3/3 Chromium hydration scenarios; Prettier and diff checks pass; no provider-backed checks run. |