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.
• Validated checkpoint bdd1de0dd3259e4e9e9f46c81948f865317c6054 committed, pushed to origin/codex/a3-ui-01 and independently confirmed by git ls-remote. No infrastructure repair. Subsequent documentation receipts do not change this immutable application/evidence identity.
• 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.

Continuation and review gate

Actual selected validation: 30 theme/state/dialog tests in five suites plus five disjoint navigation/CV-thumbnail tests in two suites; baseline28 and review16 are overlapping and excluded from that35. Full typecheck/lint/build passed. Final actual React browser lane:32 screen conditions,16 keyboard dialog journeys,48 scoped axe sweeps with zero returned violations,32 screenshots, zero page exceptions or attempted backend writes. All32 existing Google font requests aborted. No physical document or native/human acceptance reopened.

Gate F is OPEN. Source: the approved design handoff docs/product-modernisation/08-a3-handoff/IMPLEMENTATION_PROPOSAL.md at design checkpoint237c79b8, A3-IM01 row: "Owner milestone review before next increment." Present this implementation and its declared qualification limits for owner review before A3-IM02 navigation. This is not a repeated final A3 approval request. User's ordinary-implementation authorisation persists; do not ask about individual reversible changes after the relevant milestone entry is authorised.

Next UI task after that review: retain all34 routes and57 groups while implementing the approved labelled grouped/collapsible desktop sidebar and hybrid mobile navigation through existing AppShell/router owners. Do not merge this branch into main or activate deployment. The original codex/direct-roadmap-integration ref remains at d3d33837; its existing isolated worktree is currently checked out on codex/a3-ui-01. Generated graph is untracked (18,714 nodes/46,204 edges). Design approval record b7051a3e is local-only on the prototype branch; do not publish that restricted branch.