Skip to content

Specification: UX, devices and work discovery

Planning specification, written from the owner session of 4–5 October 2026. The owner decisions recorded here are planning approval only. Brief approval and implementation authorisation are separate steps, given per freeze gate (D1-04), and both remain on hold: Chris placed feature implementation on hold on 5 October 2026. Nothing in this document authorises implementation, production activation, telemetry collection, a PWA build, offline writes or messaging the design session. No work has started under it and no gate has passed. Storage choices are PROPOSALs and every numeric threshold is proposed, not approved.

Sources. The consolidation §6 (UX bullets) and §7; the session register entries Q-12 and D3-01 to D3-08 and its appended sections (collaborative question-management drafts, the eligibility-explanation goal, the U1 amendment and wording flexibility, U2 PWA exploration and its scope clarification); the condensed packages U1 to U3 and the U2 final clarification; the repository decisions on D3-14 and D3-15 recorded in the register's "Decisions already fixed for this review". Package context: UX strategy, acceptance criteria §2.3, §3 and §5, and contracts C17. PWA evidence: a read-only inspection of src/services/web/src/site.webmanifest, src/services/web/src/index.html, src/services/web/angular.json and src/services/web/package.json at worktree commit 2afbf6bf5 (5 October 2026); nothing was built or run.

Identifiers. Rules are UX-R01 onwards and acceptance evidence UX-AE01 onwards. They are distinct from the round-2 UX review finding IDs UX-01 to UX-22 cited in the UX strategy. Amendments outside the register count are cited by short name; the integration document assigns their OS-A IDs. Related specifications in this folder: review domain and versioning (RD), duplicate merge (DM), stage pools, steps and history (SP), reconciliation and screening (RS), baseline conversion (BC), training and inference (TI), reporting, imports and AI screening (RI) and access, communications and deletion (AC).

1. Summary in plain English

The reviewer page keeps one workspace. A step selector across the top lists the stage's steps, and one form area below shows the chosen step, as the prototype already shows. Reviewers can do the whole job on a phone, a tablet or a desktop from launch: screening and full annotation, including very large forms. Layouts can differ by device, but no control or feature disappears just because the screen is small. The largest real project (about 2,023 questions) is an acceptance case, not something to exclude.

The save status must never blur three different things. Draft auto-saved means recent edits are safely held as a recoverable draft. Version checkpoint saved means the reviewer pressed Save progress and an immutable version now exists. Complete means the review passed validation and counts. These words are illustrative and may change after testing; the three meanings may not.

Existing projects that have not been converted yet get the refreshed look and as many compatible new features as possible. Their review workflow (progression, screening, annotation, eligibility) behaves exactly as today until a confirmed conversion or redesign changes it.

Everyone can find their work without relying on email. Each project has a My work page listing what the user can act on, by role. The project index has a cross-project My work tab. A badge in the top bar counts actionable work across projects, even when notifications are muted. Administrators see pending changes that need them. A full global landing page waits for later.

User testing uses the tester panel already agreed. Pilots may collect timing events (for example, how long from opening a form to completing it) only with consent and never with answer content.

Three admin-facing patterns come from other specifications and are specified here as screens: the eligibility explanation (why a Study was or was not reviewed, using the history recorded at the time), presence on question-design pages (who is viewing and editing, with live updates that never overwrite local edits) and the active-work impact preview (what an admin action will do to people working now, rechecked at commit, with a narrow Apply anyway).

Making SyRF a Progressive Web App is an exploration beyond the MVP. Today's manifest and mobile tags are not a working PWA. Any caching of allocated studies or offline work needs its own design and approval; no offline writes are authorised.

Finally, the plan keeps Material 3 roles and visual baselines (D3-01), a design review per release plus previews for risky screens (D3-02), missing staging seeds added without touching production (D3-14), and Firefox, WebKit and touch coverage (D3-15).

2. Decisions covered

ID Decision in one line Status Section
Q-12 A step selector with one form area in the existing annotation workspace, as in the prototype Decided (4 Oct) §3.1, UX-R01–R03
D3-03 Labels Save progress, Complete, Needs updating, Outdated answers, Fix, Accepted answers (gold standard in help text) and Screening result; draft and checkpoint status distinguished, shown for now as "Draft auto-saved" and "Version checkpoint saved" Decided-amended (U1 amendment and wording flexibility) §3.2, UX-R11–R15
D3-04 Material 3 sentence case across reviewer screens; re-audit older all-caps specifications Decided (U1) UX-R14
D3-05 Full annotation and screening on phones, tablets and desktops at launch; no feature removed solely on phones Decided-amended (U2 device scope) §3.3, UX-R04–R10
D3-06 Refresh existing and legacy screens and add as many compatible new features as possible, without changing review-workflow semantics before a confirmed conversion or redesign Decided-amended (U2 final clarification) §3.4, UX-R16–R17
U2 PWA exploration (amendment outside the register count) Explore a PWA beyond the MVP, including possible caching of allocated studies; feasibility only; no offline writes Deferred (exploration beyond MVP) §3.11, UX-R38–R40
D3-07 Project My work, cross-project tab and global badge even when notifications are muted; pending admin changes shown; full global landing page deferred Decided (U3) §3.5, UX-R18–R23
D3-08 Current tester panel with no extra external recruitment now; consent-based timing telemetry without answer content Decided (U3) §3.6, UX-R24–R26
D3-01 Material 3 visual roles and themes, dark-mode and staging checks, visual baselines Brief item §3.12, §12, UX-R41
D3-02 Integrated release design reviews, previews of risky screens, routine checks Brief item §3.12, §12, UX-R42
D3-14 Add missing staging seeds; prefer preserving staging data; allow justified staging changes; never production Decided (owner session, outside the register) §3.12, UX-R43
D3-15 Firefox, WebKit and touch coverage Decided (owner session, outside the register) §3.12, UX-R44
Eligibility explanation (owner goal, outside the register count) Admin-facing explanation of review and inactivity over time; this specification owns the screens Decided (model in the SP spec) §3.7, UX-R27–R29
Collaborative question drafts (amendment outside the register count) Presence, live updates, safe conflicts and audit stamps on design pages; this specification owns the screens Decided (model in the RD spec) §3.8, UX-R30–R33
Active-work impact previews (consolidation §6) Previews for admin actions affecting reviewers, recheck at commit, narrow Apply anyway; this specification owns the shared screen pattern Decided (rule in the ACD spec) §3.9, UX-R34–R37
Q-13 "Library" stays with Study Management; the question area is "Design"; reusable questions are "question templates" Decided (3 Oct) §3.13, UX-R50
DQ-01 One refreshed question editor for Classic and converted projects, with each mode's own saving and assignment behaviour; it adds no versioned publication, draft or assignment behaviour to unconverted projects. QMI-04 is answered in part; the retirement timing (T-RD-17) is not decided Decided (6 Oct, design-handoff answers) §3.13, UX-R46, UX-R47
DQ-02 A compact question list or tree with the editor beside it on wide screens, and a drill-in editor page on narrow screens; no numeric breakpoint is approved Decided (6 Oct) §3.13
DQ-03 Accepted field changes save automatically into the unpublished design draft, with clear save status, safe conflict handling and per-question discard; saving a draft never publishes Decided (6 Oct) §3.8, §3.13
DQ-04 Reconciliation, question-design and admin screens get usable responsive phone layouts with no feature removed, without a formal phone acceptance gate; screening and annotation device acceptance is unchanged Decided (6 Oct) §3.3, §3.13, UX-R49, §12 A2
DQ-46 Answer terms: Answer status; Reason no value is provided; No value to enter (illustrative); Other, please specify as a value-bearing answer Decided-amended (6 Oct, revised terminology) §3.13

Referenced, owned elsewhere. D2-16 (the largest project is an acceptance case; RD spec), D3-20 (active counts and Monitor names; SP spec), D3-23 (resolved notices; ACD spec), D3-22 and D3-24 (email content and mute; ACD spec), Q-20 and Q-27 (alerts and incomplete Save after Complete; RD spec), D4-19 and reviewer-pool browsing (SP spec), D1-06 (the tester panel named on 3 October; UX strategy §9).

Scope of the counts. Of the 25 alignment, brief and validation entries in the repository universe of 89, this specification owns two (D3-01, D3-02). Of the 11 decisions outside the session register that the owner session decided or replaced, it carries two (D3-14, D3-15).

3. Concepts, entities and storage

Most of this specification is presentation over records other specifications own. Where it proposes storage, the line is a PROPOSAL.

3.1 Reviewer workspace: step selector and one form area

  • What it is. The reviewer page for one Study in one stage. A step selector lists the steps the reviewer can see, each with a state shown by shape and text: available, locked by a dependency, done, skipped, held, not applicable. Selecting a step shows that step's work in the single form area: the screening card, the annotation form, or both stacked when the step combines them. A system adjudication step appears only to eligible adjudicators, and training steps only where a project configures them (SP §3.4 step kinds; RS-R59).
  • What it reads. Step availability for this reviewer from the admission service (SP spec); the reviewer's one shared session per Study and form across stages and steps (RD spec); the screening profile renderer (RS spec); reconciled-answer hints where the form and step allow them (RS spec).
  • Narrow screens. Below the lt_sm edge the selector collapses to a labelled menu showing the current step and its state; the form area stays full width.
  • Storage. None new. The selected step is part of the URL so links and the back button work (PROPOSAL). Panel layout preferences stay in the existing ReviewerWorkspaceSettings.
  • What it is not. Several competing cards on one page; a separate session per step; a stage-owned copy of the review.

3.2 Save and completion status

The status line in the action bar is derived from facts the RD spec stores: the server draft (its latest acknowledged sequence), the latest explicit version (a checkpoint or a completed version), and any local change not yet acknowledged. Labels are illustrative (U1 wording flexibility).

Situation Facts Illustrative status Notes
Not started No draft, no version "Not started" Nothing to recover yet
Draft only Draft acknowledged; no explicit version "Draft auto-saved · no checkpoint yet" Never called a version or a submission
Checkpoint, nothing newer Latest explicit version incomplete; no newer draft "Version checkpoint saved 14:02" Does not imply completion
Checkpoint plus newer draft Explicit incomplete version and a newer draft "Draft auto-saved · last checkpoint 14:02" The earlier checkpoint stays visible
Complete, nothing newer Latest explicit version completed "Complete · 14:10" Visibly distinct from a checkpoint
Complete plus newer draft Completed version and a newer draft "Draft auto-saved · your completed version (14:10) still counts" Autosave never replaces the completed version
Saving A change is in flight "Saving draft…" Quiet; no toast
Retrying Retryable failure "Trouble saving draft. Retrying…" Input continues
Offline No connection "Offline. Your latest edits are held until you reconnect." Local holding is ambiguity A1 (§12)
Failed Retries exhausted or refused "Draft not saved to the server" with Retry Focus moves here on an explicit Save or Complete

Save progress after Complete. Before an explicit incomplete Save replaces a completed version, a confirmation says what will happen: "Saving progress now replaces your completed version. This review will stop counting as complete until you complete it again." (Q-27; RD spec owns the behaviour.)

Other labels (D3-03, D3-04). Save progress, Complete, Needs updating, Outdated answers, Fix, Accepted answers (with "gold standard" in help text on first use) and Screening result, all in Material 3 sentence case. The same status machine serves the reconciler's form.

3.3 Device support profile

Device class Typical width Input Required at launch
Phone 360 to 430 CSS px (390 in the matrix) Touch, on-screen keyboard Screening and full annotation, including large forms, outcome data, comments, history, Fix and Needs updating
Tablet 768 to 1,024 CSS px Touch, optional keyboard The same, plus side panels where width allows
Desktop 1,240 CSS px and wider Pointer and keyboard The same, plus multi-panel layouts and the detached source window

Reconciliation, question-design and admin screens (owner decision DQ-04, 6 October 2026). These get usable, responsive phone layouts with no feature removed, without a formal phone acceptance gate. The launch acceptance requirement in the table above stays for screening and full annotation only (D3-05, unchanged).

Large-form mechanics (consolidation §6).

  • Virtual scrolling and bounded rendering. Only a bounded slice of the form mounts at once (AF2's paged units and CDK virtualisation), on every device.
  • Diff autosave. Drafts send changed answers only, with base-version checks (RD spec).
  • Whole-form validation. Validation runs over the full logical form, not the mounted rows. "N required missing · Jump to next" opens the right step, category, unit and branch, waits for the control to mount and focuses it.
  • Acceptance case. The largest project (2,023 questions; the figure is VB-12's and UNVERIFIED here) is tested on phone, tablet and desktop. Benchmark tier RV-DS-04 (2,023 questions, 5,000 pins per session version) is its synthetic stand-in.

Known design risks on phones (to be solved, not to remove features): the outcome-data grid needs a phone presentation that keeps every function (for example a per-cell list with the same validation); drag reordering needs its menu and keyboard alternatives; the on-screen keyboard must not hide the action bar; the study source opens embedded on narrow screens (existing AF2 rule).

Storage. None.

3.4 Legacy-screen refresh and the compatibility register

  • What it is. Existing projects that have not yet been converted get the refreshed visual design and every compatible new feature. A compatibility register in the UX brief lists each new feature, whether it can run on unconverted projects, why, and the parity evidence (PROPOSAL; a document in the feature folder, not a database record).
  • The test for "compatible". The feature must leave progression, screening, annotation, eligibility, serving and other protocol or workflow semantics unchanged, and the legacy flags-off spec set must still pass (AC-ALL-02).
Feature Unconverted projects Why (PROPOSAL)
Material 3 restyle of chrome and shared pages Compatible Appearance only
Navigation rail, help links, "What changed" panel Compatible No workflow semantics
My work, cross-project tab and badge Compatible Lists legacy work it can compute from current state
Phone and tablet layouts for legacy screening and annotation Compatible Layout only; the same actions
Keyboard screening shortcuts Compatible The same decisions through another input
Dark mode and accessibility fixes Compatible Presentation only
Draft and checkpoint status labels Not compatible as worded A legacy save overwrites the session and creates no immutable version; legacy screens keep truthful legacy wording
Step selector Not compatible Unconverted stages have no steps; the opt-in wizard maps them
Unsure, discussion, tie adjudication Not compatible They change screening semantics
Reconciled-answer hints and click-to-fill Not compatible They change exposure
Reviewer-pool browsing Not compatible It changes serving
Eligibility explanation Compatible for current state only No pool history exists before tracking begins; the panel says so
Presence counts Compatible where tracking is already on Existing behaviour

Storage. None.

3.5 My work, the cross-project tab and the global badge

  • My work (one project). Every item the user can act on, grouped by role, computed when the page loads from the owning features' records. Rows deep-link to the exact task.
Role Rows (owning specification)
Reviewer To review, by stage and step, with Start or Continue (SP); Saved work you may still finish after a Study left the pool (SP); Needs your attention: Needs updating, Outdated answers with Fix, drafts whose place was released (RD); Merge conflicts delegated to you (DM); Training to complete or retry (TI); Requested reviews from additional-review requests (RD §3.12)
Reconciler or adjudicator Reconciliation assigned, available or held; adjudication assigned to you or to your group (RS)
Administrator Changes awaiting your approval, for example a change to a completed stage (SP); publications in progress or blocked (RD); merge conflicts awaiting resolution (DM); external screening runs awaiting acceptance (RI); training attempts awaiting manual assessment (TI); conversion findings needing action (BC)
  • Cross-project tab. On the project index beside "Pending Projects": the same rows grouped by project, so work in a project the user has not opened is one click away.
  • Global badge. In the app bar: the total of actionable rows across the user's projects. It is independent of notification flags, email mute and inbox state.
  • Pending admin changes. A banner on the project overview ("2 changes are waiting for your approval") with the same source as the administrator rows.
  • Resolution. An item someone else resolves leaves the counts and stays in history (D3-23, AC spec).
  • Storage. None. Counts come from indexed read-time queries over the feature records (programme integration §7.4); the badge refreshes on navigation and on a short interval (PROPOSAL 60 seconds). No stored counter (PROPOSAL).
  • What it is not. The inbox, which stays delivery and history; a full global landing page, which is deferred.

3.6 Tester panel and pilot timing telemetry

  • Tester panel. The D1-06 panel named on 3 October stays as agreed. D3-08 adds no external recruitment now; the earlier "at least two external SyRF users where possible" wording no longer sets a requirement.
  • Consent record. TelemetryConsent (PROPOSAL name): per user and project, Granted or Withdrawn with time. Events are recorded only when the project administrator has enabled pilot timing at pilot admission and the user has granted consent. Withdrawing stops new events at once.
  • Timing event. PilotTimingEvent (PROPOSAL name): event kind (study opened, decision submitted, form opened, Save progress, Complete, step switched), timestamp, a per-project hashed user key, a per-project hashed Study key, device class and form-size tier. No answer content, no free text, no titles, no reviewer names and no clear identifiers.
  • Storage. A dedicated store with time-limited retention, separate from scientific history events and from statistics (PROPOSAL: its own collection with a retention period of the pilot plus 90 days).
  • Use. Aggregated pilot reports only, with a minimum group size before any figure is shown (PROPOSAL 3 people). Never used to assess an individual's performance.
  • What it is not. Audit evidence; LogRocket or Google Analytics, which stay unused for UX metrics.

3.7 Eligibility explanation screens

  • What it is. The screens over the SP spec's history and explanation model.
  • Administrator panel ("Why?"). Opened from a Study's History tab or a stage Monitor row. It shows, in time order: pool entries and departures with the filter version, the satisfied or failed clauses and the causal change; review starts and submissions with the route and the eligibility recorded at the time; configuration changes that explain a change in availability; the current reason category (outside the pool, already sufficiently reviewed, progression ended by exclusion, awaiting earlier-step work, unavailable to this reviewer under allocation, permissions or capacity); and any continuation of started work after the Study left the pool.
  • Honesty rules on screen. Historical entries show the versions in force then, never today's settings. A Study that was eligible and not reviewed says "No review is recorded". A gap in tracking says "History before 12 March 2027 was not tracked" (example date) instead of guessing.
  • Reviewer view ("Why isn't this available to me?"). Only the reviewer's own reasons: their allocation, the step dependency, "enough reviewers", or a collective outcome where the configured disclosure rules allow it. Never another reviewer's candidate decision, identity or timing.
  • Storage. None; reads the SP spec's projections over C20 events.

3.8 Presence on question-design pages

  • What it is. On question-management and form-design pages, authorised users see who else is viewing and who is editing, with names and avatars, and a per-question "editing" marker.
  • Live updates. Changes the server has accepted appear in other open views of the same design pages. An incoming change never overwrites what the local user is typing; if both changed the same item, both versions stay visible and recoverable, and the user chooses. Owner decision DQ-03 (6 October 2026): accepted field changes save automatically into the unpublished design draft, with a clear save status, safe conflict handling and per-question discard, so a same-item conflict shows as soon as the other change lands; saving a draft never publishes to reviewers.
  • Audit stamps. Each accepted change shows its author and time in the item's history. Presence itself is not an audit record.
  • Publication. Many drafts may be open; only one publication runs per form. While it runs, the page shows "Publishing by Priya since 14:05. You can keep editing drafts." The running or stalled publication uses the Material 3 long-running-job contract and the shared status chip (§3.13, UX-R48).
  • Storage. Presence is ephemeral and never an audit record; accepted draft changes are RD's draft revisions. The carrier is owner question QMI-01. Recommended: a TTL-bounded presence record read by the realtime v2 change-feed reader and pushed on a v2 design topic, because production runs several API pods with no backplane; the alternatives are per-pod bus fan-out and a Valkey backplane (PROPOSAL; RD §3.7). The earlier "presence hub" and "presence group" wording is superseded: the realtime plan's hub contract v2 has topics, not groups.
  • Release (PROPOSAL; rollout R-AMB-04 (a), X-06). Presence and live updates ship with R2c on realtime hub v2 in the target environment, never on R1a's legacy-API editor, which has no draft to stamp. If v2 is not live, R2c ships base checks only and presence stays behind its flag, off (UX-R45).
  • Connection state. "Live updates paused" maps to the realtime client's reconnecting status; on ResyncRequired or a new connection the page reloads the draft head (X-05; UX-R51).

3.9 Active-work impact preview pattern

  • What it is. One shared screen used before any admin action that affects people working now, built on the impact-flow scaffold of the UX strategy.
  • Sections. What changes; who is affected now (counts of active reviewers and reconcilers; names only for holders of the Monitor capability, and never across reconciliation blinding); what is kept (drafts and submitted work); what will be released (temporary reservations only); dependent results whose inputs change; which notices will be sent.
  • Actions. Cancel; Confirm; and Apply anyway, shown only when the change conflicts with temporary reservations. Its text names exactly what it releases. It cannot bypass permissions, allocation constraints or an invalid configuration.
  • Recheck at commit. If the impact changed after the admin reviewed it, the screen shows "The impact changed since you reviewed it", lists the difference and asks again.
  • Producers. Publication and target changes (RD), merge and unmerge (DM), capacity, filter, continuation and stage-completion changes (SP), policy changes (RS), import acceptance and search withdrawal (RI), contribution exclusion and project deletion (AC), conversion waves (BC).
  • Storage. The preview is not stored. The owning operation records the digest of the impact that was confirmed (PROPOSAL).

3.10 Post-change alerts for reviewers

  • In-form alerts. When a reviewer's own edit makes another answer need attention, the form says so inline; no separate notice is sent (Q-20).
  • Admin-caused changes. When an admin action affects a reviewer's work, the reviewer sees a banner in the form and a deduplicated notice per cause, both saying what changed, that the draft is kept, and whether started work may continue.

3.11 PWA exploration (beyond the MVP)

Repository finding (read-only, commit 2afbf6bf5).

Item Observed
src/services/web/src/site.webmanifest Present; name and short_name empty; display: standalone; white theme and background; icons at /android-chrome-192x192.png and /android-chrome-512x512.png
Icon files Present at src/assets/img/android-chrome-192x192.png and src/assets/img/android-chrome-512x512.png, so the manifest's root paths do not match where the build copies them
src/services/web/angular.json assets src/favicon.ico and src/assets; the manifest is not listed, so it is probably not copied into the build
src/services/web/src/index.html theme-color, viewport and apple-mobile-web-app-* tags; no <link rel="manifest">
Service worker No @angular/service-worker dependency, no ngsw-config.json, no service-worker reference in the web source

The app is therefore very likely not installable as a PWA today. This was not built or tested at runtime, so it stays UNVERIFIED. Existing metadata is not evidence of PWA readiness.

What the exploration must answer. Installability and standalone behaviour per browser (including iOS Safari's limits); update and caching behaviour, including service-worker version skew against the forced-reload contract (AC-T-04); authentication, token handling and cache clearing at logout or access removal; draft persistence and connectivity handling; whether and how allocated studies could be cached (which data, protection at rest, eviction, revocation when access is removed, and blinding); and what a real offline review mode would need (version checks, publication rules, authorisation revalidation, conflicts).

Output. A feasibility report and a proposed scope for an owner decision. No implementation, no protected-data caching by default and no offline writes.

3.12 Design system, review cadence, seeds and browsers

  • Visual roles and baselines (D3-01). Material 3 roles over today's components, no component islands; every new route registered in FEAT-023's route matrix and visual baselines; the shared theme cutover coordinated before the new reviewer UI where possible; notification screens validated before testers see them; dark mode checked on staging, where themeToggle is on.
  • Design review cadence (D3-02). One integrated staging build reviewed per release; PR previews for new shared patterns and for high-risk screens (publication, reconciliation, the stage designer, Members and groups, guided setup); routine design checks on every PR. Proposed additions to the high-risk list: the merge and unmerge wizard, import acceptance, the eligibility explanation, large-form annotation on phones and the active-work impact preview (PROPOSAL).
  • Seeds (D3-14). Missing staging seeds are added; existing staging data is preserved where possible; justified staging changes are allowed; production is never touched. Seeds this specification needs (PROPOSAL): a synthetic large-form project with the RV-DS-04 shape and no real content; a cross-project My work seed with an assignment in a project the tester has not opened; an eligibility-history seed with a tracking gap, a departure and a continuation; a question-design seed with two administrators; and the existing legacy seed projects for the refresh checks.
  • Browsers and touch (D3-15). Chromium for full end-to-end, performance and accessibility runs; Firefox and WebKit smoke journeys; touch journeys at 390 px (phone) and 768 px (tablet); real device spot checks on iOS Safari and Android Chrome at staging acceptance (PROPOSAL).

3.13 Question authoring screens (question-management integration)

Added on 5 October 2026 (evening) from the question-management plan. The behaviour belongs to RD (§3.4, §3.5, §3.7, §4.7); this section fixes the screens. Nothing here is approved for implementation.

  • Name. The area is Design (Q-13). The question page is Questions and entity types, the label the agreed navigation already uses (C17; design handoff §4.1). Reusable items are question templates in the catalogue. "Library" never labels anything about questions, because it belongs to Study Management (UX-R50).
  • One editor, two modes (owner decision DQ-01, 6 October 2026; QMI-04 answered in part). main's new Design/Assign/Preview editor, refreshed, serves every project, with the saving and assignment behaviour appropriate to each project mode. Projects not yet converted use its legacy API mode: live saves, per-question Required, and no versions, drafts or presence; it never adds versioned publication, draft or assignment behaviour to them. Converted and admitted projects use its canonical draft mode. When the editor becomes the default entry, and when the legacy "Question design" page and the newQuestionManagement flag retire, was not addressed: the recommendation stays after R1a acceptance and one staging soak (T-RD-17, PROPOSAL; UX-R46).
  • Assign has two modes (follows DQ-01 and SF1; mechanics PROPOSAL). In legacy API mode, Assign keeps today's per-stage question selection until the project converts. In canonical mode the same two-tree interaction composes a form version: choosing a child adds its ancestors, and a stage binds the form identity, so per-stage selection disappears (M-10, H-WEB-09, DH-C17; UX-R47).
  • Layout (owner decision DQ-02, 6 October 2026). A compact question list or tree with the editor beside it on wide screens, and a separate drill-in editor page on narrow screens (list, then editor, then back). The editor never expands inline inside a tree node. No numeric breakpoint is approved: where the layout switches is a design detail to validate with users, so any width in a design is an example.
  • Saving design edits (owner decision DQ-03, 6 October 2026). In canonical mode accepted field changes save automatically into the unpublished design draft, with a clear save status ("Unpublished · saved 14:03", illustrative), safe conflict handling (§3.8) and "Discard changes" per question. There is no per-question Save or "Keep changes". Saving a draft never publishes to reviewers, and design pages never use the reviewer words "Draft auto-saved". Legacy API mode saves directly, as today.
  • Publication progress (PROPOSAL). Running and stalled publications use the Material 3 long-running-job visual contract and the status chip that Study Management uses, promoted to shared code through a serial theme PR. Processing may list them read-only (X-37; UX-R48).
  • Devices. Authoring is accepted on desktop and on tablet with touch (the §3.3 device classes; PROPOSAL): the question tree, the editor, form composition, drafts, history and publication. Drag is pointer-based, with "Move up", "Move down" and keyboard alternatives. On a phone the same functions appear in one column (list, then editor, then back) with no feature hidden and no formal phone acceptance gate (owner decision DQ-04, 6 October 2026, which settles ambiguity A2 as option (b); UX-R49).
  • Material 3. Sentence case; no literal colours; the "Focused question" debug text never appears; lifecycle, version, editing-by-someone-else, invalid-child and retired-option states each have an icon shape and text, in light and dark themes (UX-R41).
  • Storage. None beyond RD's draft records and the presence carrier (§3.8).
  • Requiredness, reasons no value is provided and answer metadata (added 6 October 2026). Chris decided that new questions are required by default, with explicit reasons no value is provided configured per question, and that answer metadata is configurable per answer state (RD §3.16; decision register §1.17). Later that day he decided the terms (DQ-46, approved with revised terminology; decision register §1.18): Answer status for a question's overall state (Unanswered; answered with a value, including Other, please specify with its text; or answered with a reason no value is provided); Reason no value is provided for the configured reasons, each with a stable identity (short form "no-value reason" in dense tables only); No value to enter as illustrative wording for the reviewer's action, not a fixed label; and Other, please specify as a value-bearing answer, never a reason. Unanswered, Option and "Not compared (unanswered)" are carried from the recommendation. The working term "no-value answer" is retired, as are "blank", "response mode", "response option", "missing-data code" and "answer exception". RD owns the behaviour; the screens (PROPOSAL) are:
  • Form composition: a newly added question shows Required; Optional sits under "Advanced settings" with the warning "Reviewers can skip this without saying why"; the form summary counts optional questions.
  • Question editor: a "Reasons no value is provided" block (the defaults Not reported, Not applicable and Unable to assess, "Add your own", and "Add from a catalogue template" such as SYRCLE, recording "copied from"); an "Other, please specify" option whose free text belongs to the answer's value; a metadata grid of fields (comment, unit, evidence quote with source location, reason) against answer states, each cell Hidden, Allowed or Required; a risk-of-bias "Unclear" stays an option.
  • Reviewer form: per question, an action that opens its reasons (illustrative wording "No value to enter"); the answer status shown by icon shape and text; metadata fields only for the chosen answer state, with "Needed to complete" on required ones; the whole-form validation summary names questions without an answer and missing required fields ("Add a comment for Unable to assess"); Save progress is never blocked; "Clear answer" returns a question to unanswered, with "answered, then cleared" in history.
  • Reconciliation: an unanswered candidate question reads "Not compared (unanswered)" (RS-R14); "Other, please specify" compares as a value, the option with its text. The design handoff §5.24 and DH-C119 to DH-C123 carry the layouts for the design session. Every state follows the copy deck and the Material 3 rules above.

4. What loads and writes when

W1. Tom opens the reviewer workspace on his phone.

Aspect Detail
Reads Study header, the steps he can see and their states, his shared session (latest explicit version plus any newer draft), the bounded first slice of the selected step's form, hint availability
Writes A connection record and, where capacity tracking is on, a capacity claim if he holds no place yet and capacity allows (RD §4.1; SP §4.5). No session exists until his first autosave
Transaction boundary Read-only
Derived afterwards The status line from §3.2; the step selector states refresh when admission state changes

W2. Tom switches to step 2.

Aspect Detail
Reads The step's current availability (rechecked at the server), the form or profile for that step
Writes The URL changes; a pilot timing event if consent applies (W10)
Transaction boundary None
Derived afterwards A locked step shows why it is locked and what unlocks it, without revealing other reviewers' decisions

W3. Tom changes an answer.

Aspect Detail
Reads Nothing extra
Writes A debounced draft diff with the base version (RD spec)
Transaction boundary The RD draft write
Derived afterwards Status "Saving draft…", then "Draft auto-saved"; validation counts update from the logical form

W4. Tom taps Save progress.

Aspect Detail
Reads The draft and base version
Writes An immutable incomplete version (RD spec)
Transaction boundary RD's Save transaction
Derived afterwards Status "Version checkpoint saved 14:02"; if the latest version was completed, the §3.2 confirmation appears first

W5. Tom taps Complete.

Aspect Detail
Reads The whole logical form for validation
Writes On failure, nothing; on success, an immutable completed version (RD spec)
Transaction boundary RD's Complete transaction
Derived afterwards On failure, a summary "3 required answers missing" with Jump, focused for screen readers; on success, "Complete · 14:10" and the next-study preference applies

W6. Mei opens My work; the badge refreshes.

Aspect Detail
Reads Indexed read-time queries over the feature records for the projects she can access, filtered by her permissions
Writes Nothing
Transaction boundary Read-only
Derived afterwards Counts are never shown as 0 when a query failed; that row shows "Couldn't load"

W7. Priya opens the eligibility explanation for Study S-204.

Aspect Detail
Reads The SP spec's timeline projection for the Study and stage, filtered by Priya's permissions and the blinding rules
Writes Nothing
Transaction boundary Read-only
Derived afterwards Coverage gaps and "No review is recorded" lines are computed from the absence of records, never filled in

W8. Priya edits questions while Sam has the same page open.

Aspect Detail
Reads The design draft, presence of other authorised users
Writes Priya's accepted draft changes (RD spec); presence heartbeats (ephemeral; carrier per QMI-01, PROPOSAL)
Transaction boundary RD's draft writes with base-version checks
Derived afterwards Sam's page shows Priya's accepted change; if Sam was typing in the same item, his text stays and both versions are offered

W9. Priya confirms an admin action from an impact preview.

Aspect Detail
Reads The impact computed by the owning feature; at confirm, the impact again
Writes The owning feature's operation, with the confirmed impact digest; if Apply anyway was chosen, the release of the named temporary reservations in the same commit
Transaction boundary The owning feature's transaction
Derived afterwards Affected reviewers see banners and notices (§3.10); if the impact changed, nothing commits until Priya confirms again

W10. A timing event is emitted.

Aspect Detail
Reads The consent state and the project's pilot setting, cached for the page session and rechecked at the server
Writes One PilotTimingEvent without content
Transaction boundary Its own write, outside every review transaction; a failure is dropped silently and never retried in a loop
Derived afterwards Aggregated pilot reports

W11. A legacy project page loads under the refresh.

Aspect Detail
Reads The same data as today
Writes The same writes as today
Transaction boundary Unchanged legacy paths
Derived afterwards Refreshed presentation and the compatible features of §3.4 only

5. Rules

Reviewer workspace

  • UX-R01 The reviewer page uses a step selector with one form area in the existing annotation workspace. Owner decision Q-12.
  • UX-R02 Step states are shown by shape and text, never colour alone; the selector has a keyboard model and collapses to a labelled menu on narrow screens. PROPOSAL (UX strategy pattern inventory).
  • UX-R03 The selector is checked with users before its layout freezes (U7), as Q-12's recommendation asked; the prototype presentation is the starting point. Owner decision Q-12.

Devices and large forms

  • UX-R04 Screening and full annotation work on phones, tablets and desktops at launch. No control or feature is removed solely because the device is a phone. Owner decision D3-05.
  • UX-R05 Presentation may differ by device; draft, Save progress, Complete, validation and access rules behave identically. Owner decision D3-05.
  • UX-R06 Large forms use bounded rendering with virtual scrolling, diff autosave and whole-form validation that does not depend on what is mounted. Owner decision; consolidation §6.
  • UX-R07 The largest project is an acceptance case on every device class; size alone never excludes it. Owner decision D3-05 and D2-16 (RD spec).
  • UX-R08 Touch targets are at least 44 px below 600 px wide and 24 px everywhere; drag uses pointer-based interactions with a menu or keyboard alternative; native HTML5 drag is not used in programme folders. PROPOSAL (UX strategy §8).
  • UX-R09 WCAG 2.2 AA is the working standard; the independent audit at GA is to WCAG 2.1 AA. PROPOSAL; D4-18 recorded reading.
  • UX-R10 Performance and usability evidence covers the supported device matrix, including a phone profile. Owner decision D3-05; thresholds in §12 are proposed.

Status labels and copy

  • UX-R11 Status text always distinguishes a recoverable draft, an explicit checkpoint and a completed version. The words are illustrative and may change through design review; the distinction may not. Owner decision D3-03 with the U1 amendment and wording flexibility.
  • UX-R12 An autosaved draft is never called a version or a submission, and a checkpoint never implies completion. When a checkpoint exists and newer edits are autosaved, the earlier checkpoint stays visible. Owner decision, U1 amendment.
  • UX-R13 Complete is visibly distinct from an incomplete checkpoint, and an incomplete Save over a completed version is confirmed first with its consequence. Owner decision D3-03; Q-27.
  • UX-R14 Labels use Material 3 sentence case: Save progress, Complete, Needs updating, Outdated answers, Fix, Accepted answers ("gold standard" in help text) and Screening result. Owner decision D3-03 and D3-04.
  • UX-R15 The copy-deck guard spec rejects superseded status wording ("Changes kept, not yet saved", "Autosaved—not yet submitted", "Save draft" as the explicit save label). PROPOSAL enforcement of the owner decision.

Legacy screens

  • UX-R16 Existing and legacy project screens receive the refreshed design and as many compatible new features as possible, while progression, screening, annotation, eligibility, serving and other workflow semantics stay faithful until a confirmed conversion or later configuration change. Owner decision D3-06 (U2 final clarification).
  • UX-R17 Each feature offered on unconverted projects has a compatibility entry and parity evidence; legacy screens keep wording that describes legacy behaviour truthfully. Owner decision D3-06 ("assess compatibility and behaviour parity in the brief"); register format PROPOSAL.

Work discovery

  • UX-R18 Each project has a My work page listing actionable items by role. Owner decision D3-07.
  • UX-R19 The project index has a cross-project My work tab. Owner decision D3-07.
  • UX-R20 A global badge counts actionable work at read time, independent of notification flags, email mute and inbox state. Owner decision D3-07.
  • UX-R21 Administrators see pending admin changes on My work and as an overview banner. Owner decision D3-07.
  • UX-R22 An item resolved by someone else leaves the counts and stays in history. D3-23 (ACD spec).
  • UX-R23 A full global landing page is deferred. Owner decision D3-07.

Testing and telemetry

  • UX-R24 User testing uses the agreed tester panel; no extra external recruitment is required now. Owner decision D3-08.
  • UX-R25 Pilot timing events need project enablement and user consent, carry no answer content, and are stored apart from scientific audit records. Owner decision D3-08 (consent, no content); the two-level consent and separate store are PROPOSAL.
  • UX-R26 Timing data is reported only in aggregate with a minimum group size, is never used to judge individuals and has time-limited retention. PROPOSAL.

Eligibility explanation

  • UX-R27 The explanation uses the versions in force at the time, says "No review is recorded" when nothing was recorded, and shows tracking gaps instead of guessing. Owner goal (explain review activity and inactivity over time).
  • UX-R28 The reviewer-facing view shows only the reviewer's own reasons and any collective outcome the disclosure rules allow; it never shows other reviewers' candidate decisions, identities or timing. Owner decisions on blinding (Q-28, Q-30, browsing clarification).
  • UX-R29 The administrator view is permission-aware and links each entry to its recorded evidence. Owner goal; SP spec.

Question-design presence

  • UX-R30 Design pages show which authorised users are viewing and which are editing. Owner decision, collaborative question drafts.
  • UX-R31 Accepted changes appear live in other views; incoming changes preserve local unsaved edits; conflicts stay recoverable and visible. Owner decision, collaborative question drafts.
  • UX-R32 Every accepted change shows author and time in history; presence is never treated as an audit record. Owner decision, collaborative question drafts.
  • UX-R33 The page shows when a publication is running; drafting continues; only one publication runs per form. Owner decision D2-11.

Active-work impact previews

  • UX-R34 Admin actions that affect reviewers use the shared impact preview before commit. Owner decision; consolidation §6.
  • UX-R35 The impact is rechecked at commit; a changed impact needs a fresh confirmation. Owner decision (Q-24, Q-27).
  • UX-R36 Apply anyway appears only for conflicts with temporary reservations, names what it releases, preserves drafts and never bypasses permissions or legal configuration. Owner decision (Q-24; consolidation §6).
  • UX-R37 Previews show counts to everyone and names only to Monitor-capability holders, never across reconciliation blinding. D3-20 (SP spec).

PWA

  • UX-R38 PWA work is a feasibility exploration beyond the MVP, including whether allocated studies could be cached. Owner decision, U2 PWA scope clarification.
  • UX-R39 No offline writes are authorised and protected study data is never cached as an accidental default; offline review and synchronisation need their own design and approval. Owner decision, U2 exploration and clarification.
  • UX-R40 Existing manifest and mobile metadata are not evidence of a PWA; the feasibility report records what was tested. Owner decision, U2 exploration.

Design system, cadence, seeds and browsers

  • UX-R41 New screens use Material 3 roles, register their routes for visual baselines and are checked in dark mode on staging. Brief item D3-01.
  • UX-R42 Each release has an integrated staging design review; new shared patterns and high-risk screens get PR previews; every PR runs routine design checks. Brief item D3-02.
  • UX-R43 Missing staging seeds are added; staging data is preserved where possible; justified staging changes are allowed; production is never seeded or changed. Owner decision D3-14.
  • UX-R44 Firefox and WebKit smoke journeys and touch journeys are part of acceptance. Owner decision D3-15.

Question authoring (question-management integration, 5 October 2026)

  • UX-R45 Design-page presence and live updates ship with R2c on realtime hub v2, never on R1a's legacy-API editor; without v2, R2c ships base checks only and presence stays off behind its flag. PROPOSAL (X-06; rollout R-AMB-04 (a), a brief confirmation).
  • UX-R46 The new question editor is the default entry for every project, in legacy API mode for projects not yet converted and in canonical draft mode for converted and admitted projects; the legacy designer and newQuestionManagement retire after R1a acceptance and one staging soak. One editor with each mode's own saving and assignment behaviour, adding no versioned publication, draft or assignment behaviour to unconverted projects: owner decision DQ-01 (6 October 2026), which answers QMI-04 in part. The default-entry timing and the retirement after R1a acceptance and one staging soak stay PROPOSAL (T-RD-17).
  • UX-R47 Assign keeps per-stage selection for projects not yet converted and becomes form composition, with ancestors added automatically, for canonical projects; no canonical screen offers per-stage selection. Follows DQ-01 (each mode keeps its own assignment behaviour) and SF1; the mechanics are PROPOSAL (M-10, H-WEB-09, DH-C17).
  • UX-R48 Publication progress uses the Material 3 long-running-job contract and the shared status chip. PROPOSAL (X-37).
  • UX-R49 Question authoring is accepted on desktop and tablet with touch; phones show every authoring function in one column with no phone acceptance gate; drag has menu and keyboard alternatives. The desktop and tablet acceptance is PROPOSAL (AC-R1a-12). 6 October 2026: reconciliation, question-design and other admin screens get usable, responsive phone layouts with no feature removed and no formal phone acceptance gate, while screening and annotation keep D3-05's acceptance (UX-R04): owner decision DQ-04, settling ambiguity A2 as option (b).
  • UX-R50 The question area is "Design" and its page "Questions and entity types"; reusable questions are "question templates"; "Library" never labels questions, and the copy deck rejects "question library". Owner decision Q-13; the page label follows C17.
  • UX-R51 "Live updates paused" follows the realtime client's connection status, and a design page reloads its draft head on ResyncRequired or a new connection. PROPOSAL (X-05).

6. Authorisation, blinding and provenance

  • Server authority. Every list, badge and panel is filtered at the server by the caller's permissions; hiding something in the UI is never the control (C10).
  • My work. Rows use context-local reconciliation labels under the form's or profile's blinding; they never reuse an alias across Studies. The superseded "stage-owned aliases (BL1)" wording no longer applies.
  • Presence. Design-page presence is visible only to users authorised for those pages. Reviewer presence on Studies shows counts and the user's own place; names need the Monitor capability (D3-20).
  • Eligibility explanation. Administrators see the full timeline their permissions allow; reviewers see only §3.7's reviewer view.
  • Telemetry. No event is recorded without project enablement and user consent; events carry hashed keys only; access to pilot reports is limited to the pilot's research team (PROPOSAL).
  • Provenance shown. Status lines and history panels show times and authors from the records the RD, SP and RS specs keep; the UX layer adds no provenance of its own.

7. Active-work impacts

This specification owns the screens; the owning specifications decide what each action affects.

Moment What the admin or reviewer sees
Before commit The impact preview of §3.9 with counts, kept work, released reservations, dependent results and notices
At commit A recheck; a changed impact shows the difference and asks again
After commit, affected reviewer in the form A banner naming the change, confirming the draft is kept and saying whether started work may continue
After commit, affected reviewer elsewhere A deduplicated notice per cause and a My work row where action is needed
Reviewer's own edit causes an issue An inline alert in the form only (Q-20)
Apply anyway Only for temporary-reservation conflicts; the confirmation names the reservations; drafts survive

8. Failure and recovery

Failure What the user sees Recovery
Draft write fails briefly "Trouble saving draft. Retrying…" Automatic retry with the same sequence
Draft write keeps failing "Draft not saved to the server" with Retry Retry; Save progress when the server returns
Stale base (a newer version exists) "A newer version of this review was saved, perhaps in another tab. Your changes here are kept as a copy." Open the current version or compare copies (RD spec)
Second tab or device editing the same session Both connections edit the one shared session; a change to the same answer from a stale base shows a conflict panel with both values (RD §4.2; D2-08) Keep either value; nothing is discarded silently. A read-only-with-take-over presentation is only a brief option for small screens (RD §12)
Connection lost "Offline" status Edits replay on reconnect only if the base version still matches (ambiguity A1)
Phone discards the tab in the background On return, the page reloads the server draft Nothing acknowledged is lost
Presence connection drops Avatars grey out with "Live updates paused" while the realtime client reports reconnecting Editing continues; on reconnect or ResyncRequired the page reloads the draft head and updates resume (UX-R51)
My work query fails The affected row shows "Couldn't load" Retry; counts never show a false 0
Impact changed at commit "The impact changed since you reviewed it" Review and confirm again, or cancel
Timing event fails Nothing visible Dropped; no retry loop
A feature fails legacy parity The feature is withheld from unconverted projects Fix or keep it for converted projects only

9. User flows and examples

The cast is fictional. Tom Reid and Mei Lin are reviewers. Priya Shah and Sam Ortiz administer the project. Dr Ada Okafor is a methodologist.

9.1 Tom annotates the largest form on a phone.

  1. Loading. Tom opens Study S-204 on his phone on a train. The step selector shows "Full text · Extraction"; the form area shows a skeleton, then the first page of units.
  2. Draft only. He answers twelve questions. The status reads "Draft auto-saved · no checkpoint yet".
  3. Offline. The train enters a tunnel. The status reads "Offline. Your latest edits are held until you reconnect." Two minutes later it reads "Draft auto-saved" again.
  4. Checkpoint. He taps Save progress. The status reads "Version checkpoint saved 14:02".
  5. Incomplete. He taps Complete. The summary says "3 required answers missing · Jump to next". Jump opens the Treatment unit three pages away and focuses the empty dose field.
  6. Completed. He fills the three answers and taps Complete. The status reads "Complete · 14:10".
  7. Unavailable. On another Study, step 2 shows "Locked: finish step 1 first", and nothing about other reviewers' decisions.

9.2 Mei edits after completing. Mei completed S-301 yesterday. Today she changes one answer; the status reads "Draft auto-saved · your completed version (yesterday 16:40) still counts". She taps Save progress; a confirmation explains that this replaces her completed version and the review will stop counting as complete. She cancels and taps Complete instead, which validates and creates a new completed version.

9.3 Three steps in one workspace. The full-text stage has "Screening", "Risk of bias" and "Extraction". Tom's selector shows Screening done, Risk of bias available and Extraction locked by a dependency on Risk of bias. The form area shows one step at a time. On a desktop he uses [ and ] to move between steps.

9.4 Finding work with notifications muted. Mei muted email for all projects. The app bar badge shows 4. The cross-project tab lists "Rodent stroke: 2 to review, 1 adjudication assigned to your group" and "Spinal injury: 1 merge conflict delegated to you" in a project she has not opened this month. Priya's overview shows "2 changes are waiting for your approval". After Sam resolves the adjudication, Mei's badge drops to 3 and the item stays in her history.

9.5 Two administrators editing questions. Priya and Sam open the question designer. Each sees the other's avatar, and Sam's marker sits on "Anaesthetic used". Priya renames a different question; Sam sees it appear without losing the option text he is typing. Both then edit the same option label; Sam's save reports the conflict, shows Priya's accepted text beside his own and lets him keep either. The history shows "Renamed by Priya Shah, 14:03". Priya starts a publication; Sam's page shows "Publishing by Priya since 14:05. You can keep editing drafts."

9.6 Reducing capacity with active work. Priya lowers the form's capacity cap from 3 to 2 (from the effective target plus one to the effective target, which is 2; SP §3.11). The preview shows 4 Studies with 3 active reviewers each, 4 temporary reservations that would exceed the new cap, drafts kept in every case and 4 notices to send. She chooses Apply anyway; the confirmation names the 4 reservations it will release. At commit one reviewer has just finished, so the impact is now 3 reservations; the screen shows the change and Priya confirms again.

9.7 Explaining an apparent inconsistency. Dr Okafor asks why S-204 was extracted in stage 3 when it no longer matches stage 3's filter. Priya opens the explanation panel. It shows that S-204 entered the stage 3 pool on 2 February under filter version 2 (species = rat), that Tom started extraction on 4 February with that eligibility recorded, that a reconciled species answer changed to "mouse" on 9 February and the Study left the pool, and that Tom completed his started work on 10 February under the continuation rule. No reviewer action is shown as unexplained.

9.8 A legacy project after the refresh. Sam's older project (not yet converted) shows the new navigation, dark mode, the My work badge and phone layouts. Screening still serves studies the same way, there is no step selector, and the save status uses legacy wording because a legacy save overwrites the session.

9.9 Consent for pilot timing. Priya enables pilot timing when admitting her project to the R3a pilot. Tom sees a one-time consent card ("We would like to record how long screening steps take. No answers or study details are recorded.") and declines. No events are recorded for Tom; Mei's consent produces events that appear only in aggregated reports.

9.10 The PWA exploration. The exploration finds that the manifest is not linked from index.html, is not in the build's asset list and points at icon paths that do not exist in the build; there is no service worker. It reports what installability and cached allocated studies would need, including clearing caches on logout and on loss of access, and returns a proposed scope for Chris to decide. Nothing is built.

10. Rollout and adoption

Capability Class Release or lane Flag decision Dependencies
Status machine and labels Baseline/MVP R2a (versioned sessions) Within R2a's flag; observable copy changes ship with the behaviour RD spec; copy deck at F1c
Phone, tablet and desktop annotation and screening Baseline/MVP, launch requirement R2a for annotation hosts, R3a and R3b for screening and steps, each with phone evidence Within each release's flag AF2 programme; large-form benchmarks (RV-DS-04)
Step selector and one form area Baseline/MVP R3a R3a flag SP admission; U7
My work badge and admin banner Baseline/MVP R3c Flag-independent display once R3c ships, per the existing plan Read-time queue queries
Full My work and cross-project tab Baseline/MVP R4a R4a flag RS queues
Eligibility explanation screens Baseline/MVP With the SP history release: events and query API from R3a; the timeline screen behind its UI flag until staging acceptance (SP §10.1) UI flag stageEligibilityTimeline (SP §10.1) SP spec
Question-design presence and live updates Baseline/MVP R2c, with collaborative drafts on realtime hub v2 (X-06). Superseded: "with collaborative drafts (R1a question library, R2a forms)"; R2a ships single-editor drafts with base checks only Its own flag, depending on the realtime v2 hub and client flags (PROPOSAL, X-40) RD spec; realtime hub v2 in the target environment; QMI-01
The new question editor as the default entry (legacy API mode), and retirement of the legacy designer and newQuestionManagement Baseline/MVP An R1a follow-on, at the latest R7 (T-RD-17) The default-entry switch, then the flag retirement contract (PROPOSAL; one editor for both modes is decided, DQ-01, but this timing is not) R1a acceptance; one staging soak
Assign as form composition Baseline/MVP R2a canonical mode; legacy API mode keeps per-stage selection until conversion Within R2a's flag RD §3.5
Active-work impact preview pattern Baseline/MVP First consumer R2c (publication); reused by later releases Within each consumer's flag ACD spec rule
Legacy-screen refresh and compatible features Baseline/MVP Restyle by GA (AC-GA-09); compatible features as each ships Each feature's own flag Compatibility register; AC-ALL-02
Tester panel In place All releases Not applicable D1-06
Pilot timing telemetry Opt-in pilot measure From R2a pilots New flag, default off (PROPOSAL pilotTimingTelemetry): it collects personal data and needs a kill switch Consent store; retention job
Harness: Firefox, WebKit, touch, axe Baseline/MVP S0 (S0-7), before R1a Not applicable D3-15
Staging seeds Baseline/MVP S0 (S0-4) and per release Not applicable D3-14
PWA exploration Beyond MVP Separate non-MVP exploration lane; the rollout drafter names it and sets its timing so it never delays MVP work No feature flag; no build Owner decision on the feasibility report
Full global landing page Deferred Post-GA None now D3-07

Pilots. Phone annotation is piloted on the synthetic large-form seed first, then on staging pilot projects created by testers. No pilot uses production data for UX work.

11. Acceptance evidence

Method codes follow acceptance criteria §1.4. Rows are PROPOSAL until confirmed at their freeze gate, except where they restate an owner decision as a testable assertion.

ID Evidence Method Amends
UX-AE01 The reviewer page renders one form area at a time with a step selector; switching steps keeps one shared session per Study and form E AC-R3a step rows; U7
UX-AE02 Step states are distinguishable in forced colours and by screen reader; the narrow menu shows the current step and its state A, E UI-6, UI-7
UX-AE03 At 390 px with touch, a tester completes the RV-DS-04-shaped form: answers in every category, Save progress, a failed Complete with Jump, then Complete E, X, UT UI-6 phone clause
UX-AE04 No action available on desktop is missing at 390 px for screening and annotation (a generated inventory of actions per breakpoint matches) U, E UI-6
UX-AE05 Whole-form validation reports missing answers in unmounted units, and Jump focuses the control E AC-ALL-24
UX-AE06 Keystroke-to-paint p95 under 50 ms at 200 and 1,000 questions on the desktop reference; a phone profile budget is set at the R2a freeze from measurement B AC-UX-04
UX-AE07 The status machine shows the §3.2 states for each fact combination; no state labels a draft as a version or a checkpoint as complete U, E AC-R2a status rows
UX-AE08 An incomplete Save over a completed version shows the confirmation first E AC-R2a Save rows
UX-AE09 The copy-deck guard rejects the superseded status strings and enforces sentence case for core verbs U UI-11
UX-AE10 Every feature enabled on unconverted projects has a compatibility entry, and the legacy flags-off spec set passes with it on D, E AC-ALL-02, AC-GA-09
UX-AE11 Unconverted projects never show the versioned status labels E AC-GA-09
UX-AE12 With every notification flag off and the project muted, the badge and My work show the correct counts E U30
UX-AE13 From the project index, a tester reaches an assignment in an unopened project in one step UT U30
UX-AE14 An administrator sees pending changes on the overview banner and My work without opening stage settings E U30
UX-AE15 An item resolved by someone else leaves the counts within one refresh and appears in history E D3-23 rows
UX-AE16 With consent withdrawn or the project setting off, zero timing events are recorded I AC-ALL-25
UX-AE17 The timing event schema has no field able to carry answer content, free text, titles or clear identifiers (a contract test over the schema) C AC-ALL-20
UX-AE18 The explanation panel shows historical versions, "No review is recorded" and tracking gaps on the eligibility-history seed E New (SP release)
UX-AE19 The reviewer view never contains another reviewer's decision, identity or timing (disclosure probes) C, I AC-ALL-19
UX-AE20 Two sessions on a design page see each other's presence; an accepted change appears in the other view within a budget set at the F2 freeze (PROPOSAL 2 seconds) without overwriting local edits. R2c (moved from R1a on 5 October 2026 with R-AMB-04 (a); the budget was "set at the R1a freeze") E U9, U14; AC-R2c-34
UX-AE21 A same-item conflict on a design page keeps both versions recoverable; history shows author and time E, I New (R2a for base checks; R2c with presence)
UX-AE22 The impact preview rechecks at commit and asks again when the impact changed E, I U6 (revised)
UX-AE23 Apply anyway releases only the named temporary reservations, keeps drafts and is absent when no reservation conflict exists I, E AC-R3a capacity rows
UX-AE24 Previews show names only to Monitor-capability holders I AC-T-08
UX-AE25 The PWA feasibility report exists, records the repository finding and answers every question in §3.11, and no service worker or offline write ships before an owner decision D, G New
UX-AE26 New routes are registered in FEAT-023's route matrix and baselines; dark screenshots are taken on staging per release V, G UI-4, UI-9
UX-AE27 Each release records its integrated staging design review and the previews of high-risk screens G UI-8
UX-AE28 Seeds run idempotently on staging and preview, add only missing data and never target production I, R AC-S0-06
UX-AE29 Firefox and WebKit smoke journeys and the phone and tablet touch journeys pass on the release candidate X AC-ALL-07
UX-AE30 The screen-reader matrix includes VoiceOver with iOS Safari for phone annotation, not only phone screening A AC-ALL-07
UX-AE31 After ResyncRequired or a reconnect a design page reloads its draft head, and "Live updates paused" shows only while the realtime client reports reconnecting E New (R2c)
UX-AE32 Every project opens the new editor from Design; a project not yet converted uses legacy API mode with today's save semantics and flags-off parity; after T-RD-17 no route reaches the legacy designer E, U New (DQ-01 decided the one editor; the T-RD-17 part stays PROPOSAL)
UX-AE33 Assign shows per-stage selection for a project not yet converted and form composition with automatic ancestors for a canonical project; no canonical screen offers per-stage selection E New (R2a)
UX-AE34 A running and a stalled publication render with the Material 3 job contract and the shared status chip, in light and dark themes V, E New (R2c)
UX-AE35 At 768 px with touch, a tester reorders questions by drag and by "Move down", composes a form and publishes it; at 390 px every authoring function is reachable in one column with no page-level horizontal scroll X, E AC-R1a-12; DQ-04 (no formal phone gate)
UX-AE36 The copy-deck guard rejects "question library" on every screen U UI-11

12. Brief items, specialist inputs and unapproved proposals

Entries this specification owns (treatment required).

Entry Required treatment Tracker row
D3-01 Coordinate visual roles and themes, staging dark-mode checks and visual baselines with the Material 3 programme; record the cutover sequencing for the reviewer UI T-UX-00
D3-02 Put the design review schedule in each release brief: one integrated staging review, previews for new shared patterns and high-risk screens, routine checks per PR T-UX-00

Proposed thresholds, not approved. Badge refresh interval of 60 seconds; presence update within 2 seconds; telemetry retention of pilot plus 90 days and a minimum group size of 3; the phone performance budget, to be set from measurement at the R2a freeze; touch targets and WCAG levels from the UX strategy; the AC-UX metrics of acceptance criteria §2.3.

Proposals an owner may want to see. Two-level telemetry consent (project enablement and user consent) with a separate store (UX-R25, UX-R26); the compatibility register's initial verdicts (§3.4), especially that versioned status labels stay off unconverted projects; the additions to the high-risk preview list (§3.12); real-device spot checks at staging acceptance; the selected step in the URL; the new names TelemetryConsent and PilotTimingEvent; the flag name pilotTimingTelemetry. From the question-management integration: the retirement timing of the legacy designer (UX-R46; the one editor with two modes is decided, DQ-01), Assign's mechanics (UX-R47) and the designer's desktop and tablet acceptance (UX-R49; the phone part is decided, DQ-04).

Owner questions from the question-management integration (asked in the question-management plan; tracker row T-OI-02; QMI-01 is not decided, and QMI-04 is answered in part by DQ-01 on 6 October 2026):

  • QMI-01. How design-page presence and live draft updates reach users on other API pods. Recommended: an ephemeral, TTL-bounded presence record read by the realtime v2 change-feed reader, never an audit record. Alternatives: per-pod bus fan-out; a Valkey backplane. It shapes §3.8 and UX-R45, not the screens.
  • QMI-04. Whether the new editor becomes the default entry for every project, in legacy API mode for legacy projects, with the legacy designer and newQuestionManagement retiring after R1a acceptance and one staging soak (T-RD-17); the alternative keeps the legacy designer until R7. It decides UX-R46 and UX-AE32. Answered in part, 6 October 2026 (DQ-01): the same refreshed editor serves every project, with each mode's own saving and assignment behaviour. The default-entry and retirement timing (T-RD-17) was not addressed and stays the recommendation.

Brief-level confirmation: X-06, closing rollout R-AMB-04 as option (a) with the realtime v2 join, which UX-R45 and the UX-AE20 move assume.

Ambiguities found (options and a recommendation; no owner answer is assumed).

  • A1. Holding edits on the device during a connection loss. The UX strategy (§6.4, E82) proposes a bounded local copy in IndexedDB replayed on reconnect, and AC-UX-06 tests a 60-second offline interval. The owner said no offline writes are authorised and protected data must not be cached by accident. Options: (a) keep a bounded in-session holding area for short interruptions, cleared at logout, completion and access loss, never used to fetch new work, replayed only when the server base version still matches; (b) hold edits in memory only, so closing the tab loses unacknowledged edits; © remove local holding until the PWA design decides. Recommendation: (a), described as connectivity resilience within one editing session, confirmed explicitly in the UX brief because it stores answer data on the device.
  • A2. Reconciliation and design screens on phones. D3-05 requires screening and full annotation. Options: (a) require phone acceptance for reconciliation too; (b) keep reconciliation's narrow layout usable with no feature removed, without a phone acceptance gate; © desktop only. Recommendation: (b) for reconciliation, and responsive but not phone-accepted design and admin screens at launch, recorded as PROPOSALs. Decided 6 October 2026 (DQ-04, option (b)): "usable responsive phone layouts with no feature removed, without a formal phone acceptance gate for reconciliation and design. The previously approved screening/annotation device acceptance requirements remain." This now holds for reconciliation, question-design and admin screens (§3.3, §3.13, UX-R49).
  • A3. The largest project as test data. Options: (a) a synthetic replica at the RV-DS-04 shape; (b) a structure-only replica measured from the real project; © the real project. Recommendation: (a) now; (b) only after a separately approved read-only measurement that copies no study content or answers; never ©.

Harmonisation notes (5 October 2026).

  • §8: the "second tab or device" row no longer says read-only with "Take over editing". D2-08 is decided (one shared session, concurrent edits with base checks); the take-over presentation is only a brief option (RD §12). This matches RD §4.2 and RD §14.
  • §3.5: "Requested reviews" now cites RD §3.12 (additional-review requests are RD's, not RS's).
  • §10: the eligibility explanation row follows SP §10.1 (R3a API; timeline screen behind stageEligibilityTimeline until staging acceptance), replacing "panel by R3c" and "SP flag".
  • §9.6: capacity numbers tied to SP §3.11's cap values, matching ACD E10.
  • §3.1: the step selector shows the system adjudication step only to eligible adjudicators and training steps where configured (SP §3.4).
  • RD's offline wording now points to ambiguity A1 here instead of asserting a local copy.
  • W1: opening the workspace writes a connection record and, with tracking on, a capacity claim, as RD §4.1 and SP §4.5 specify. The earlier "writes nothing; no claim until he starts work" wording contradicted both.

13. Amendments to existing package documents

  • ux-strategy.md
  • §3.1 My work contents: replace "use stage-owned aliases (BL1)" with context-local labels under form-owned or profile-owned blinding; add the rows of §3.5 (saved work after pool departure, merge conflicts, training, adjudication for groups, external runs awaiting acceptance, conversion findings); mark D3-07 decided.
  • §3.4 and §14: D3-06 decided with compatible features; add the compatibility register.
  • §4.3 pattern inventory: Save-status states renamed to the §3.2 set; add the eligibility explanation panel, the design-page presence pattern and the active-work impact preview.
  • §5.2 terms: replace "Changes kept, not yet saved" with "Draft auto-saved" (illustrative) and add "Version checkpoint saved" (illustrative); mark D3-03 decided with wording flexibility; the "Primary and secondary study (duplicates)" row follows the DM spec.
  • §6.1: D3-05 decided; the phone path covers full annotation, not only title and abstract steps.
  • §6.4: rename the states; record ambiguity A1 against the "Offline kept on this device" row.
  • §8.2 and §8.3: the screen-reader matrix covers phone annotation; D3-15 decided.
  • §9: D3-08 decided; drop the external-participant requirement; telemetry approved with consent.
  • §13.2: D3-02 is a brief item with the proposed additions.
  • §15.1: update statuses from the §2 table of this specification.
  • New section: PWA exploration beyond the MVP with the §3.11 finding.
  • acceptance-criteria.md
  • UI-6: the phone clause covers full annotation and screening; status from pending-D3-05 to confirmed.
  • UI-11: recommended verbs updated (illustrative draft and checkpoint labels); status to confirmed (D3-03).
  • UI-5: status to confirmed (D3-04).
  • UI-8: status from pending-D3-02 to brief item.
  • UI-3: status from pending-D3-01 to brief item.
  • §3.1 width matrix: the 390 row covers annotation as well as screening.
  • AC-ALL-07: add VoiceOver with iOS Safari for phone annotation; add touch journeys.
  • AC-ALL-25 and AC-UX-03: "if D3-08 approves" becomes approved with consent.
  • §5.3 and §5.4: drop the external-participant requirement (D3-08); keep the panel numbers.
  • AC-GA-09: status from pending-D3-06 to confirmed, with compatible features and UX-AE10.
  • AC-R2a-22: the "ceiling starts below the largest project's 2,023 questions" wording follows the RD spec's replacement of D2-16 (the largest project is an acceptance case).
  • Add UX-AE rows to the releases named in §10.
  • contracts.md C17: copy-deck terms updated as above; the impact preview DTO shape is shared across producers; My work counts are read-time.
  • integrated-plan.md: R2a, R3a, R3c and R4a scope bullets cite this specification; GA's legacy restyle includes compatible features; add the PWA exploration as a non-MVP lane (the rollout drafter names it).
  • open-questions-and-assumptions.md: D3-03 to D3-08 decided; D3-01 and D3-02 brief items; D3-14 and D3-15 decided; A-38 rewritten so external participants are not required.
  • decision-register.md §2: add the rows in §14 of this specification.

Question-management integration (5 October 2026, evening). This page now carries §3.8 (presence carrier pending QMI-01, R2c release, connection state), §3.13 (question authoring screens), UX-R45 to UX-R51, the moved UX-AE20 and UX-AE21, UX-AE31 to UX-AE36 and the §10 rows. The question-management plan owns the change list for the rest of the package:

  • ux-strategy.md → §3.2: "Design … canonical (legacy keeps the legacy editor)" conflicts with C17's two editor modes; follow C17 (UX-R46, owner question QMI-04). §4.3 pattern inventory: presence uses the realtime v2 carrier, not "the existing hub"; add the publication job row (UX-R48).
  • acceptance-criteria.md → move UX-AE20 and UX-AE21 to R2c; add UX-AE31 to UX-AE36; UI-11 adds "question library" to the banned strings.
  • integrated-plan.md → R1a: the presence placement note closes as R-AMB-04 (a); "Question library and import" is renamed so "library" no longer labels questions (for example "Question templates and import").
  • rollout-plan.md → §7.6 closes R-AMB-04 as (a); §9 adds the design-presence flag with its realtime v2 dependency.

Owner answers, 6 October 2026. §3.13 gains the screens for required by default, reasons no value is provided and answer metadata (applied by the integration writer). Their acceptance evidence is RD's (RD-AE39 to RD-AE45); this page adds none. Updated: DQ-46 is answered (below), so the copy deck (T-UX-02) takes the decided terms.

Design-handoff answers, 6 October 2026. Chris answered DQ-01 to DQ-04 and DQ-46 in a Codex discussion (record archived at owner-session-2026-10-05/syrf-design-decisions-2026-10-06.md.txt; decision register §1.18). This page records them in §2, §3.3 (phones for reconciliation and admin screens), §3.8 (automatic saving into the design draft), §3.13 (one editor, the layout without a numeric breakpoint, saving, devices and the answer terms), UX-R46, UX-R47, UX-R49, the §10 editor row, UX-AE32, UX-AE35, §12 (QMI-04 and A2) and §14. Changes for other package documents:

  • ux-strategy.md: §1.1 statuses for DQ-01 to DQ-04 and DQ-46; §3.2's Design row; §4.3's candidate-pill and design-presence rows; §5.2's answer terms; §7.3's A2 note; §7.13; §15.1.
  • acceptance-criteria.md: any row that waits on QMI-04 (for example AC-R1a-14) is answered only in part; any row that names the working term "no-value answer" takes the decided terms. These belong to the writer of that document.

Implementation stays on hold, and none of this sends the design pack.

14. Superseded wording

Old wording New wording Where the old wording appears today
"Changes kept, not yet saved" and "Autosaved—not yet submitted" "Draft auto-saved" for recoverable drafts and "Version checkpoint saved" after Save progress, both illustrative; Complete stays distinct ux-strategy.md §5.2 and §6.4; acceptance-criteria.md UI-11 (superseded item 15)
Phone support for title and abstract screening only; annotation on tablet and desktop first Full annotation and screening on phones, tablets and desktops at launch ux-strategy §6.1 and §8.2; acceptance criteria UI-6 and §3.1
The 2,023-question project stays on the legacy path; a size ceiling below it The largest project is an acceptance case (RD spec) open-questions-and-assumptions.md D2-16 row; versioning model D2-16 row; AC-R2a-22 (superseded item 12)
My work rows "use stage-owned aliases (BL1)" Context-local labels under form-owned or profile-owned blinding, with no alias continuity across Studies ux-strategy §3.1 (superseded item 4)
Legacy screens restyled "with no behaviour change" only Restyle plus as many compatible new features as possible, with workflow semantics unchanged ux-strategy §3.4; AC-GA-09
"At least two external SyRF users where possible" as a testing requirement The agreed tester panel; no extra external recruitment now ux-strategy §9; acceptance criteria §5.3 and §5.4; A-38
Timing telemetry "if D3-08 approves" Approved, with consent and without answer content ux-strategy §9 and §10; AC-ALL-25; AC-UX-03
"Pending D3-0x" markers for D3-03 to D3-08, D3-14 and D3-15 Decided as recorded in §2 ux-strategy §15.1 and inline markers
Question-design presence "with collaborative drafts (R1a question library, R2a forms)", budget "set at the R1a freeze", presence "on the existing hub" in a "presence group" Presence and live updates in R2c on realtime hub v2, budget at F2, carrier per QMI-01 (UX-R45) Integrated plan R1a note; ux-strategy §4.3; earlier UX §10 and UX-AE20
"Question library" for the project's questions "Design › Questions and entity types"; reusable items are "question templates" (Q-13; UX-R50) Integrated plan R1a title; v10 pack strings (handoff DH-C100)
"No-value answer" (the working term of 6 October 2026) and the code name noValueAnswerId "Reason no value is provided" (short form "no-value reason" in dense tables), with noValueReasonId (PROPOSAL) if a code name is needed; the overall state is "Answer status" (DQ-46) Package documents written on 6 October 2026 before DQ-46 was answered
"Other: specify" text as an answer metadata field Part of the "Other, please specify" option's value; metadata keeps comments, units, evidence quotes and reasons (DQ-46) RD §3.16 and the 6 October 2026 metadata wording
A phone acceptance gate for reconciliation, or desktop-only reconciliation and design screens Usable responsive phone layouts with no feature removed and no formal phone gate (DQ-04) UX §12 A2 options (a) and ©

15. Existing work reused

QM v2 PR-D (#2575) holds a stage-scoped designer, a publish wizard, a reviewer alert and design docs; #2387 holds child-question checks and an assign tree for the current new editor; #3934 adds an import dialog. Most of the UI code is avoided: it predates Material 3 on main, it is stage-scoped and it carries confirmed defects. The reviewer alert, the digest recheck and the design docs are worth keeping. The harvest map is authoritative; nothing is ported while the hold lasts.

Entries Verdict Target section
H-WEB-08 Adapt §3.9 impact preview recheck (UX-R35; T-UX-06, T-RD-05)
H-WEB-11 Adapt §3.10 post-change alerts (T-RD-05)
H-WEB-06, H-WEB-07, H-WEB-10, H-WEB-12, H-SVC-03 Reference only §3.9 impact preview (T-UX-06, T-RD-05)
H-WEB-03, H-WEB-04, H-WEB-18 Reference only §3.8 design pages; §3.12 design system; AC-R2c-27 and AC-R1a-12
H-TREE-01, H-TREE-07 Adapt R1a editor hardening (T-RD-12)
H-TREE-02 Reference only AC-R1a-06r (T-RD-12)
H-IMP-05 Adapt C17 placement; §3.12 (T-RD-11)
H-WEB-01, H-WEB-02, H-WEB-05, H-WEB-09, H-WEB-13, H-WEB-14, H-WEB-15, H-TREE-03, H-TREE-04, H-TREE-05, H-TREE-06, H-TREE-08 Avoid §3.8, §3.12; UI-1 to UI-11

Merged on main (question-management integration, 5 October 2026). The screens build on work already on main; the question-management plan has the full inventory.

Items on main Verdict Target section
M-09 (the Design/Assign/Preview editor) Keep and evolve: the default entry, in two modes §3.13; UX-R46
M-10 (Assign and stage question sets) Bridge per-stage selection for legacy projects; adapt into form composition §3.13; UX-R47
M-11, M-16 (Preview tab, AF2) Keep and evolve: the designer preview renders pinned versions through AF2 §3.13
M-13 (native drag and drop) Replace with pointer drag and keyboard alternatives §3.13; UX-R08, UX-R49
M-15, M-32 (legacy designer, newQuestionManagement) Bridge, then retire after the default-entry slice and one staging soak UX-R46 (QMI-04)
M-21 (study presence) Adapt its client patterns only; the design carrier is QMI-01 §3.8; UX-R45

What this specification requires that the earlier work lacks.

  • Material 3 roles. No var(--mat-sys-*, #fallback) and no literal colours; --syrf-* roles, app-page-shell and app-page-state, public Material components only, sentence case and the copy deck (UX-R41, D3-04). PR-D's designer has 67 fallback uses, 35 literal colours, native controls and emoji icons.
  • Presence on design pages (UX-R30 to UX-R33), on realtime hub v2 with the carrier owner question QMI-01 chooses (superseded: "as a design group on main's existing hub").
  • The shared impact preview with a recheck at commit and a narrow "Apply anyway" (UX-R34 to UX-R37); PR-D's wizard is stage-scoped, fails on open and drops the admin's choices.
  • In-form alerts with attribution for generated versions, offering a previous answer only when it is valid under the session's pinned version.
  • Version numbers on cards, and history with a diff (AC-R2c-27).
  • Pointer-based CDK drag with a keyboard alternative that works with touch and in Firefox and WebKit (AC-R1a-12, UX-R44), and a virtualised tree that handles the largest project.
  • Zoneless-safe code. main is zoneless-ready, not zoneless by default: change detection is chosen at bootstrap, the zonelessChangeDetection flag defaults to false and no environment sets it. Guard specs still enforce zoneless discipline, so any ported component must pass them; PR-D's wizard would not.