jobtrackingapp/docs/ui-modernisation/UI-01.md

UI-01 — approved A3 foundation implementation

Status: A3-IM01 implementation and scoped validation prepared for Gate F owner review; UI-01 navigation (A3-IM02) remains pending. Implementation branch codex/a3-ui-01, isolated integration worktree. Base d3d338376444b8abdcaf7200f682faa3daf1ad10; design source 237c79b8cb3e280d7e4d1ef95cdbb2c77bb81c69; roadmap receipt 286535bef046417a09a156685c937e8be9155147.

Owner's 3 November 2026 attachment explicitly approves the final A3 foundation and staged real-application implementation. Verbatim authorisation is retained in A3_APPROVAL.md. Gates C/D/E are approved for that scope; deployment, Phase 10, security/provider/native/device/release gates are not waived.

Task ledger and verification plan

• Verify branch/commits and use accepted integration baseline; preserve existing worktrees. Created implementation branch in the already isolated integration worktree, keeping its original branch ref unchanged. No wholesale merge of the older design tree.
• Baseline: four existing theme/dialog suites, 28 tests PASSED before production edits.
• A3-IM01: approved D1 palette, typography, quiet surfaces and shared controls implemented through existing theme.ts. Added visual-contract regression checks; retained semantic contrast, theme/system persistence, focus, reduced-motion, density and dialog checks.
• Targeted tests, types, lint, production build and actual application browser checks in EN/NB, both themes and mobile/desktop. See VALIDATION.md for exact source scopes and pending human/zoom checks.
• Commit validated checkpoint, attempt ordinary development-branch publication and independently read back the remote ref. Preserve local work if unreachable; no infrastructure repair.
• Gate F review for A3-IM01 before next source-defined implementation increment. UI-01 navigation is A3-IM02, not silently treated as complete by palette changes.

Scope reaches the existing ThemeProvider and every MUI theme consumer, including navigation semantic colours and shared fields/buttons/cards/dialogs. Preserve component APIs, routes, application state, server data ownership, RD21 and physical CV/PDF renderers. No dependency, API or database changes. Existing semantic status colours must retain readable contrast on all new surfaces; dividers are decorative and do not replace stronger essential field boundaries.

Ruling: use targeted shared-theme/dialog/state checks and relevant browser workflows rather than thousands of unrelated tests, following the owner's explicit evidence/testing instructions. Backend tests are unnecessary unless backend behaviour is changed. Prototype tests are not application qualification.

Ruling: approved global MUI roles will also be inherited by existing public React consumers; this is shared theme plumbing, not selection or implementation of a new homepage layout/claims/SEO. Keep the existing gradient API and physical document rendering untouched. Later launch-site decisions remain separate.

Rollback: revert this UI increment on its development branch; no persisted data/schema change. Re-run affected theme/layout checks. Never reset unrelated work or alter the autonomous orchestrator.

Implemented behaviour

Shared MUI theme now uses approved violet canvas/text/accent/navigation roles in both schemes; existing state synchronisation/storage remains unchanged. App chrome uses the approved system font stack, more readable body rhythm and responsive page-title hierarchy. Shared cards use restrained borders without floating section shadows. Buttons use sentence case and 44px base height; outlined fields retain their notched focus indicator and now have a 44px base height. Existing density hit-region rules remain in force. Actual navigation structure and feature layouts are not represented as implemented yet.

Contrast verification exposed the old dark error role at 4.275:1 on the new elevated surface. Corrected dark error main/darker fills to #FF8A80/#FF7067 with explicit dark contrast text; thresholds were not lowered. Final semantic contrast tests pass, and code review checked standard alert text against composited surfaces. CV/template/letter previews use isolated document HTML; physical renderer source, fonts, metrics, fixtures and historical document acceptance were not changed.

Independent code review: no important/critical findings. Accepted minor recommendation to assert every collected scoped axe violation array, rather than only colour contrast. Reviewer's 16 theme tests overlap the final 30 and must not be added to them. Initial two-width browser artifact was superseded by the final four-width run, not added as extra coverage.