DevRunbook-Public/docs/52-usability-recovery-roadmap.md

# 52 — Usability recovery roadmap

## Why this roadmap exists

The live visual audit on 2026-07-30 found that the technical release gates in
roadmap 51 were satisfied, while the production interface was still too dense,
too technical and inconsistent in Dutch. This roadmap therefore governs the
next product release. Earlier security, integrity and deterministic rendering
contracts remain mandatory.

The release is outcome-gated. A phase is complete only after its checks run on
the Unraid deployment candidate and its evidence is recorded in
`CURRENT_STATE.md`.

## Baseline findings

- The interface mixes Dutch and English in navigation, headings and actions.
- The mobile library and project list create pages over ten thousand pixels
  tall and put filters before the primary content.
- The Start action bar obscures content on a phone.
- Several mobile header controls are smaller than 44 by 44 CSS pixels.
- Task and project details expose implementation terminology before the user
  understands the outcome.
- Generic labels such as More and Management do not describe their destination.
- Empty task history does not help the user take the next useful action.

## Phase A — Readable foundation

Outcome: every primary screen has one clear purpose, consistent language and a
stable information hierarchy.

- use task, project and result as the default user vocabulary;
- localize the authenticated shell, commands, primary pages, status and errors;
- assign a unique browser title to every primary route;
- keep expert and governance terminology behind contextual disclosure;
- use one primary action per page header and demote secondary actions;
- establish a readable measure, spacing scale and minimum 44-pixel touch target.

Gate: Start, Tasks, Projects and Task library are understandable in Dutch at
390, 768 and 1440 pixels without mixed-language primary controls, overlap or
horizontal scrolling.

## Phase B — Two-step task creation and library

Outcome: a first-time user can choose a project, describe the desired result
and generate a governed task without understanding internal platform concepts.

- keep the default flow to project plus task;
- show a short, plain-language review of scope, protection and success;
- make advanced settings optional and collapsed;
- collapse library filters by default, especially on mobile;
- render results progressively rather than as an unbounded page;
- make task cards describe outcome first and technical evidence second;
- provide actionable zero-result and validation recovery.

Gate: representative beginner tasks complete with project plus task, no raw
schema keys are visible, and the primary mobile action never covers content.

## Phase C — Projects and task history

Outcome: projects and generated tasks are easy to find, compare and resume.

- add search, useful sort and compact project rows;
- show connection freshness and action required in ordinary language;
- make project overview the default, with technical profile as a secondary tab;
- rename Run Pack and run terminology in the primary UI to task and result;
- add useful empty states, filters and status summaries to task history;
- preserve immutable historical output and exact profile/version evidence.

Gate: a target project is findable in a 500-project fixture using keyboard or
touch, stale/error states have a clear recovery action, and empty task history
links directly to creating a first task.

## Phase D — Accessibility, responsive behavior and release proof

Outcome: the simplified product is independently usable and operationally safe.

- verify keyboard order, focus visibility, dialogs, drawers and error focus;
- verify 200% zoom, reflow, reduced motion and light/dark contrast;
- run Axe on all critical authenticated flows with zero serious or critical
  findings;
- measure mobile target sizes and prevent nested page scrolling;
- run end-to-end browser journeys against the Unraid release candidate;
- run format, lint, typecheck, unit, integration, security and production build;
- rehearse restart and persistence, then deploy exactly one healthy DockerMan
  container reachable on the LAN with the configured icon.

Gate: all required suites execute rather than skip, critical browser flows pass
at 390, 768 and 1440 pixels with no console errors, and production health and
persistence checks pass after restart.

## Delivery order

1. Phase A shell, language, metadata and mobile readability.
2. Phase B Start and Task library.
3. Phase C Projects, project detail and Tasks.
4. Phase D accessibility, full qualification and production deployment.

Each phase is committed separately when practical. No release tag is created
without explicit operator approval.

## Follow-up closure — 2026-08-01

The cross-role follow-up audit closes the recovery release for primary user
journeys. Shared shell controls, account/security, role labels, denials and
recovery actions are consistently localized. Account routes inherit useful
navigation commands, viewer-only sessions no longer advertise write-only
composition, and empty viewer workspaces explain the required editor/owner
action.

Evidence was produced from the exact all-in-one candidate on Unraid: 36/36
PostgreSQL integration tests, the full repository verify/security/audit gate,
17/17 focused Chromium/Axe scenarios, owner/editor/viewer browser journeys,
390-pixel mobile and 200%-equivalent reflow, with no horizontal overflow or
console errors.

The roadmap does not claim a multi-workspace switcher, localized public
onboarding or a plain-language rewrite of canonical expert authoring contracts.
The current application deliberately selects one deterministic authorized
membership; first-run setup, login and invitation acceptance remain English;
and repository-profile and integration authoring remain expert surfaces.
Implementing these requires separate product, localization and authorization
milestones rather than a cosmetic shell change.