Skip to content

Study Management — Approved Design Decision

The product owner approved the Iteration 2 design and authorised implementation on 2026-09-01. This record closes design gates D2 and D4 from the design handoff and is the binding input to Waves 3–5 of the implementation plan.

Selected direction

Iteration 1 direction A (compact contextual summaries + operational Processing table) as the spine, recombined with direction C's Active + Needs attention default filter (result count and reset) and direction B's one shared status component — realised by generalising the shipped Bulk PDF StatusView contract (status-presentation.ts: kinds ok | stopped | warn | muted | info, honest bar modes, ariaValueText) across all four job families.

The full specification is the Iteration 2 handoff pack: locked decisions D1–D17 in design-decision-log.md, status vocabularies and DTO truth in design-source-truth.md, and colour/type mapping in design-token-mapping.md. Interactive/static prototypes and the Iteration 1 canvas stay outside the repository (inventory below).

Product-owner UX mandate (acceptance emphasis for every UI wave)

"Deliver an easy to use, intuitive UX — easy to navigate, with things intuitively placed." Concretely, and testable in Waves 3–5 acceptance:

  • primary actions live in visible page action areas: Bulk study update leaves the table overflow menu and joins "Add systematic search" as a page-level action on Library;
  • the three destinations keep short, recognisable navigation labels (Library / Searches / Processing) inside one Study management group;
  • one status/progress/error language everywhere, so a state learned on one page reads the same on every page;
  • "View in Processing" sits in the same position in every contextual summary, and a deep link always reveals its target (even completed), never an empty filtered list; and
  • commands sit beside the object they affect, never on the read-only history.

Binding corrections to the handoff pack (verified against source 2026-09-01)

  1. Routes. The handoff's /project/:id/library|searches|processing is overridden by the settled IA: Library keeps /projects/:projectId/studies; new children are /projects/:projectId/searches and /projects/:projectId/processing; legacy admin/systematic-searches redirects.
  2. Token naming. The handoff's DS tokens --syrf-accent (#4b5e84) and --syrf-brand-ink (#1c3053) collide with existing repo tokens holding different values (#3666ff, #203457). Mapping: the design's accent role = --mat-sys-primary (M3 primary tone 40); the design's brand-ink role = existing --syrf-brand-ink. Wave 3 must not redefine existing --syrf-* names. The three new status-container roles ship via the Material 3 programme's serial theme-contract change (PR #3059) as --syrf-warning-container (#fdecd3), --syrf-warning-accent (#8a5000, 5.61:1 on its container) and --syrf-info-container (#dfe8f7) — the handoff's provisional --syrf-color-* spellings were dropped because no existing --syrf-* token uses a color- segment. UI waves consume these names and never define them locally.
  3. Compact navigation. Below the wide breakpoint the design consumes merged PR #2994's adaptive primitive (persistent rail ↔ sticky route-aware selector, content-driven breakpoint), not a bespoke segmented-tabs variant.
  4. Minor factual slips in the pack (Angular "21", a claimed styles.scss on-surface-variant override, dark-mode activation) are noted; dark mode remains a later M3 milestone and the permission enum is ProjectActivity, values verified (8/13/14/15/16/23).

Open-question dispositions (O1–O5, product-owner approved; reversible before each wave merges)

  • O1 Expired Bulk PDF jobs group under Needs attention (not terminal, cleanup pending).
  • O2 No RoB retry affordance; note copy points to launching a new calculation. A retry API is Wave 4+ backend follow-up, not UI-invented.
  • O3 Missing initiator renders "Not available" (column kept for consistency).
  • O4 RoB's per-table "hide completed" toggle is subsumed by the default filter.
  • O5 Unknown status values render "Unknown status (n)" everywhere; Wave 4 reconciles Bulk PDF's "Status unavailable" fallback to this rule with that surface's owner (the fallback lives under project-admin/bulk-pdf-upload/**, which is Wave 4's exclusive ledger).

Verification summary

Every file/line claim in the pack was checked against the worktree (base f68f234fa, and the pack's own grounding commit cc271f478d03 exists on main): the four status enums (api-client.generated.ts:8056/8132/8179/8252), deployed display labels (Search Import statusText, RoB statusMap, Bulk PDF status-presentation.ts), the StatusChipKind contract, and permission values are all exact. Main has advanced (fb77f40e9 at approval time); each implementation wave refreshes file ownership against current main before its first commit.

Artefact inventory (outside the repository, deliberately)

  • Iteration 2 pack (prototypes StudyManagement.dc.html, Artboards.dc.html, A11y Spec Board.dc.html, original companions): ~/workspace/syrf/scratch/study-management-design-evidence/iteration-2-handoff/
  • Iteration 1 canvas (three directions + comparison): https://claude.ai/code/artifact/71632614-6f02-40a5-878a-7953014aa045
  • Gate D1 current-state captures + metadata: ~/workspace/syrf/scratch/study-management-design-evidence/current-state/

Prototype HTML references a design-system bundle that is not shipped; treat prototypes as source-of-truth markup to read, and the committed companions as the normative spec.