v4.4.0 build order: UX Overhaul in six phases, with two review checkpoints

claude-bot commented

2026-09-06 19:30:20 +00:00

Collaborator

Tracking issue for the v4.4.0 milestone (12 issues: the seven-step design process #361–#367, plus #182, #422, #424, #437, #464 folded in). The order, the reasoning, and where the milestone stops for a human decision. The v4.3.0 tracking issue (#514) is the model.

Principles

Design is decided by looking, not by argument. The milestone's own process is brief → divergent wireframes → convergent mockups → build. Two of those steps end with a choice only the owner can make, so the plan has two explicit checkpoints and nothing visual is built before the second.
Mechanism before appearance. Two issues change how the frontend is wired rather than how it looks (#464 data router, #182 React Compiler rules). They go first, in parallel with the brief, so the rebuild inherits them instead of redoing them.
Backend work that the design needs but does not depend on goes early. #424 needs beats persisted (a migration and a router) before any screen can show them; #437 needs an admin campaigns endpoint. Both can be built and tested against the API while the design is still being chosen; only their screens wait.
The product stays usable throughout. #366 is built surface by surface on the component library, each lane a PR that leaves main deployable. Accessibility (#367) is a rule applied in every lane plus a final pass, not a retrofit.
Same orchestration as v4.3.0. One delegate per file cluster, one PR per lane with Closes …, auto-merge on green CI, completion notes on every issue, dev deploy after each phase for a look, prod once at the end.

Phase 0 — Mechanism (parallel, starts now)

issue	what	lane
#464	`createBrowserRouter` + `RouterProvider`; `useBlocker` in the unsaved-changes hook for the summary and transcript editors	App.jsx, hooks, SessionDetail
#182	fix the `set-state-in-effect` sites, then adopt the plugin's `recommended` preset	the seven pages the probe names

Different files; both are prerequisites for everything that follows.

Phase 1 — The brief (#361) → checkpoint A

A fresh surface inventory (the audit's route table predates v4.3.0's nav bar and is in a gitignored folder that no longer exists on any machine), the six journeys as the acceptance bar, the vocabulary mapping (mostly settled by #379; the leftovers are named), the constraints, and the list of what must survive. Presented together with phase 2 so there is one review rather than two.

Phase 2 — Wireframes (#362) → checkpoint A

Seven low-fidelity concepts, each taking a distinct position on the five questions the audit posed (where attention lives, what the spine is, whether the session or the campaign is the primary object, how GM and player views relate, what the at-the-table surface is). Each concept shows the six structural surfaces at desktop and phone width and is walked through the six journeys; the secondary surfaces are placed in a table per concept. Delivered as a single comparison page. The owner picks two or three concepts, or elements of several, to carry forward.

Phase 3 — Mockups (#363) → checkpoint B

Three to five high-fidelity directions built from the choice at checkpoint A, populated with realistic sample data (a campaign mid-arc, sessions in every state, a real-length transcript and summary, a populated wiki, a queue of suggestions, a recording in progress), at desktop, tablet and phone widths, GM and player, including loading, error, empty and in-progress states. The owner picks one direction, or a recombination, and that decision is written into the brief.

Phase 4 ∥ — Backend groundwork (parallel with phases 1–3)

#424 backend half: persist beats per summarisation run (migration + model + GET router, validation results and cited transcript timestamps included), tests, no change to what a GM sees yet. The decision on per-run versus last-write-wins is made here: per run, because #423 showed two runs over the same audio genuinely differ and the comparison is the point.
#437 backend half: an admin-only campaigns list endpoint with GMs, member count, session count, guild linkage, retention overrides, created date. Metadata only. The content-access decision is taken now so the screen does not decide it by accident: admins see that a campaign exists and who runs it; they do not open it. Drill-through, if ever wanted, is a separate issue with an audit entry.

Phase 5 — The build

5a #364 the design system: tokens (type, spacing, colour with the existing dark mode, elevation), the primitives (button hierarchy, form controls, badges and counts, cards, dialogs and confirmations, empty/loading/error states, the async-progress pattern), the interaction rules written down, and a stated touch-target minimum. Ships as a library plus a documentation page; no screen changes yet.
5b #366 the rebuild, one lane per surface cluster in this order: dashboard and navigation → session (folding in #422's per-session character pin and #424's verified-events view) → prep → at-the-table and mobile (#365, on the Session Shelf, the wiki article and campaign detail ordering) → wiki and review → the remainder (profile, highlights, analytics, admin with #437's screen, join, help, login). Each lane replaces window.confirm, page-level errors and ad-hoc styles with the library as it goes.
5c #367 accessibility: the standard (WCAG 2.2 AA) is applied in every 5b lane; automated checks go into CI with the first lane; a final keyboard-only walk of the six journeys closes it. The manual screen-reader pass is the owner's, on a real device.

Phase 6 — Release

v4.4.0 at the end, deployed dev then prod. Phase 0 rides with it rather than earning a patch release of its own; if the design phases run long, phase 0 plus phase 4 can ship as v4.3.1 to keep the deploy cadence.

Out of scope, noted

No backend re-architecture, no new features beyond the four folded issues, no change to the Discord embeds or notification content (v5.4.0), no localisation. Table and safety tools are v4.5.0; they will be built on this design system.

Tracking issue for the v4.4.0 milestone (12 issues: the seven-step design process #361–#367, plus #182, #422, #424, #437, #464 folded in). The order, the reasoning, and where the milestone stops for a human decision. The v4.3.0 tracking issue (#514) is the model. ## Principles 1. **Design is decided by looking, not by argument.** The milestone's own process is brief → divergent wireframes → convergent mockups → build. Two of those steps end with a choice only the owner can make, so the plan has two explicit checkpoints and nothing visual is built before the second. 2. **Mechanism before appearance.** Two issues change how the frontend is wired rather than how it looks (#464 data router, #182 React Compiler rules). They go first, in parallel with the brief, so the rebuild inherits them instead of redoing them. 3. **Backend work that the design needs but does not depend on goes early.** #424 needs beats persisted (a migration and a router) before any screen can show them; #437 needs an admin campaigns endpoint. Both can be built and tested against the API while the design is still being chosen; only their screens wait. 4. **The product stays usable throughout.** #366 is built surface by surface on the component library, each lane a PR that leaves main deployable. Accessibility (#367) is a rule applied in every lane plus a final pass, not a retrofit. 5. **Same orchestration as v4.3.0.** One delegate per file cluster, one PR per lane with `Closes …`, auto-merge on green CI, completion notes on every issue, dev deploy after each phase for a look, prod once at the end. ## Phase 0 — Mechanism (parallel, starts now) | issue | what | lane | |---|---|---| | #464 | `createBrowserRouter` + `RouterProvider`; `useBlocker` in the unsaved-changes hook for the summary and transcript editors | App.jsx, hooks, SessionDetail | | #182 | fix the `set-state-in-effect` sites, then adopt the plugin's `recommended` preset | the seven pages the probe names | Different files; both are prerequisites for everything that follows. ## Phase 1 — The brief (#361) → **checkpoint A** A fresh surface inventory (the audit's route table predates v4.3.0's nav bar and is in a gitignored folder that no longer exists on any machine), the six journeys as the acceptance bar, the vocabulary mapping (mostly settled by #379; the leftovers are named), the constraints, and the list of what must survive. Presented together with phase 2 so there is one review rather than two. ## Phase 2 — Wireframes (#362) → **checkpoint A** Seven low-fidelity concepts, each taking a distinct position on the five questions the audit posed (where attention lives, what the spine is, whether the session or the campaign is the primary object, how GM and player views relate, what the at-the-table surface is). Each concept shows the six structural surfaces at desktop and phone width and is walked through the six journeys; the secondary surfaces are placed in a table per concept. Delivered as a single comparison page. **The owner picks two or three concepts, or elements of several, to carry forward.** ## Phase 3 — Mockups (#363) → **checkpoint B** Three to five high-fidelity directions built from the choice at checkpoint A, populated with realistic sample data (a campaign mid-arc, sessions in every state, a real-length transcript and summary, a populated wiki, a queue of suggestions, a recording in progress), at desktop, tablet and phone widths, GM and player, including loading, error, empty and in-progress states. **The owner picks one direction, or a recombination, and that decision is written into the brief.** ## Phase 4 ∥ — Backend groundwork (parallel with phases 1–3) - #424 backend half: persist beats per summarisation run (migration + model + `GET` router, validation results and cited transcript timestamps included), tests, no change to what a GM sees yet. The decision on per-run versus last-write-wins is made here: **per run**, because #423 showed two runs over the same audio genuinely differ and the comparison is the point. - #437 backend half: an admin-only campaigns list endpoint with GMs, member count, session count, guild linkage, retention overrides, created date. Metadata only. The content-access decision is taken now so the screen does not decide it by accident: **admins see that a campaign exists and who runs it; they do not open it.** Drill-through, if ever wanted, is a separate issue with an audit entry. ## Phase 5 — The build - **5a** #364 the design system: tokens (type, spacing, colour with the existing dark mode, elevation), the primitives (button hierarchy, form controls, badges and counts, cards, dialogs and confirmations, empty/loading/error states, the async-progress pattern), the interaction rules written down, and a stated touch-target minimum. Ships as a library plus a documentation page; no screen changes yet. - **5b** #366 the rebuild, one lane per surface cluster in this order: dashboard and navigation → session (folding in #422's per-session character pin and #424's verified-events view) → prep → at-the-table and mobile (#365, on the Session Shelf, the wiki article and campaign detail ordering) → wiki and review → the remainder (profile, highlights, analytics, admin with #437's screen, join, help, login). Each lane replaces `window.confirm`, page-level errors and ad-hoc styles with the library as it goes. - **5c** #367 accessibility: the standard (WCAG 2.2 AA) is applied in every 5b lane; automated checks go into CI with the first lane; a final keyboard-only walk of the six journeys closes it. The manual screen-reader pass is the owner's, on a real device. ## Phase 6 — Release v4.4.0 at the end, deployed dev then prod. Phase 0 rides with it rather than earning a patch release of its own; if the design phases run long, phase 0 plus phase 4 can ship as v4.3.1 to keep the deploy cadence. ## Out of scope, noted No backend re-architecture, no new features beyond the four folded issues, no change to the Discord embeds or notification content (v5.4.0), no localisation. Table and safety tools are v4.5.0; they will be built on this design system.

PR	issue	merged
#537 data router + in-app unsaved-edit prompt	#464, closed	`cce8601`
#538 `GET /api/admin/campaigns`, metadata only	#437, backend half; issue stays open for the screen	`9373464`
#540 React Compiler lint rules, 40 sites fixed	#182, closed	`b57fd09`

Rows
Columns

v4.4.0 build order: UX Overhaul in six phases, with two review checkpoints #535