From 6878f19adcecf8574d8309f5c10fee22e6d2c99b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 24 Jul 2026 18:17:20 +0000 Subject: [PATCH] Add design-review subagent and sitewide UX review ledger. Records the production-page design/UX interactive review on main 01c20957 and adds a reusable Cursor design-review agent. Co-authored-by: BigSimmo --- .cursor/agents/design-review.md | 75 +++++++++++++++++++++++++++++++++ docs/branch-review-ledger.md | 1 + 2 files changed, 76 insertions(+) create mode 100644 .cursor/agents/design-review.md diff --git a/.cursor/agents/design-review.md b/.cursor/agents/design-review.md new file mode 100644 index 000000000..496905e9f --- /dev/null +++ b/.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` diff --git a/docs/branch-review-ledger.md b/docs/branch-review-ledger.md index a694ec191..81fe86dbb 100644 --- a/docs/branch-review-ledger.md +++ b/docs/branch-review-ledger.md @@ -760,3 +760,4 @@ This file is append-only. Never rewrite or delete an existing review record; app | 2026-07-25 | cursor/pr-babysit-bugbot-agents-6c52 (PR #1167) | ee44812aae9dad1973d8302eba5bfca5000dffb6 | Open-PR maintenance: review-thread fixes | Before: 8 unresolved Codex/CodeRabbit threads; branch current with main. After: target-head pinning, fresh-main verification, exact `cursor[bot]` identity checks, explicit mutation/provider authorization, direct reply-then-resolve semantics, and no-op ledger bookkeeping are documented. | Prettier check on both agent files pass; `git diff --check` pass; GitHub author probe confirmed `cursor[bot]` account type `Bot`; no provider-backed checks run. | | 2026-07-25 | codex/fix-merge-conflicts-and-ci-on-open-prs (PR #1170) | e979fc892f11a17b1a8f2ef1ab058ef40d629182 | Open-PR maintenance: CI fix + threads + drift | Before: Static PR checks failed because route-group moves made nine valid legacy `src/app/*` documentation references appear missing; 0 unresolved threads; branch already contained current main. After: docs-link resolution checks known App Router route groups and the focused failure is fixed. | `node scripts/check-docs-links.mjs` pass (1162 references); Prettier check pass; `git diff --check` 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`. |