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

Phase A shell, language, metadata and mobile readability.
Phase B Start and Task library.
Phase C Projects, project detail and Tasks.
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.

5.8 KiB Raw Blame History