jobtrackingapp/docs/redesign/phase-3/PHASE4_IMPLEMENTATION_PLAN.md

# Phase 4 implementation plan

**Planning only. Phase 4 has not started.** This package is a documentation checkpoint from d6d3dd9. The next phase establishes shared foundations; broad navigation/layout migration stays Phase 5 under the original redesign sequence. No B07 work is included.

## Entry conditions

- Phase 3 route/impact plan is the reviewed working contract; retain all 57 PRES IDs and 31 existing patterns.
- Current baseline is available: 916 backend, 313 frontend; general browser **23 pass + 1 documented expected failure**. No tests/gates removed.
- Select the exact shared consumer/state fixture before editing. Gaps in [Phase 2](../phase-2/BASELINE_DEFECTS.md) remain explicit.
- Brand, providers and cross-device layout decisions do not block the first semantic accessibility slice. Keep current identity and storage behavior.
- No schema or persistence redesign here. R03 restore/rollback proof gates schema; D01–D03 govern editor/job revision semantics. B02 identity and creation idempotency remain distinct.
- Local foundation work can proceed without production access. Production rollout still needs required CI and F04 ingress evidence; a feature-branch push is not deployment approval.

## Session-sized foundation queue

| Ticket / scope | Owned surface and dependencies | Regression/UX evidence | Risk / rollback |
|---|---|---|---|
| **P4-01 Semantic state and focus foundation** | Existing theme.ts; narrowly required theme typing/shared MUI overrides; existing browser/Jest fixtures. Coordinate with validated A01, do not duplicate it | Loaded button/chip/tab/field/alert state pairs in both modes; visible keyboard focus; preserve filled-button contrast and EN/NB labels | Broad visual reach, no schema. Revert this isolated theme/test slice if necessary; no data migration |
| **P4-02 Named controls and modal state** | RichTextField/actual unlabelled Select call sites plus confirm/prompt/ViewStateNotice as evidenced. After P4-01; inventory callers first | Labels/helper/error links, draft retained on error, dialog focus/return, loading announcements; no mass form rewrite | Small caller changes; revert per shared primitive, retain all behavior tests |
| **P4-03 Builder preview keyboard boundary** | Actual preview region in CvBuilderEditor and focused browser fixture; coordinate validated A02. Serialize with D01; no editor save refactor | Loaded one/multipage preview, keyboard entry/scroll/exit and mobile→desktop transition; edit/preview/undo state retained | Touches stateful editor; stop if change requires persistence redesign. No schema |
| **P4-04 Page layout and typography primitives** | Theme/page variables plus smallest PageHeader/PageSection composition needed by existing consumers. After P4-01/02; use current hue/mark | One h1, long NB copy, 320 px reflow, reading/data/editor width, no hidden actions | Limit to one representative existing consumer, not all pages; revert primitive/consumer together |
| **P4-05 Table/list density contract** | Theme Table styles and a bounded existing table consumer; typed Comfortable/Compact preference scoped explicitly. After P4-04 | Row selection/link/action isolation; readable values at both densities; touch hit regions; existing column/page prefs retained | No replacement table library. If preference API/schema is needed, separate that decision instead of broadening this slice |
| **P4-06 Shared validation checkpoint** | Tests/docs only plus separately ticketed defects; after combined foundations | Loaded EN/NB × light/dark × mobile/desktop, keyboard/manual preview/form, full suites/type/lint/build and PRES traces | Do not mask failures. Foundation accepted before Phase 5 shell/pages |

Do not scaffold every component in COMPONENT_ARCHITECTURE.md during Phase 4. Command expansion, aggregate dashboards, document query APIs, status settings, scheduled tasks and full AI panel are later feature slices, not required to establish tokens/names/focus. A shared AI diff frame can be extracted when the first domain migrates and its validation remains intact.

## First implementation handoff: P4-01 only

Problem: F14 identified semantic small-text contrast and focus debt across shared states. Current theme and shell/page literals can produce inconsistent pairings; replacing MUI is not required.

Objective: make the chosen existing MUI state pairs readable and keyboard focus clear in light/dark, using the current provisional brand hue. Inspect actual rendered default/hover/focus/selected states for Chips, outlined/contained Buttons, Tabs and Alerts. If a failure lives in one local hardcoded style, include only that directly responsible override with caller evidence.

Start with theme.ts and existing theme/accessibility test owners. Add a populated fixture through the existing test app/environment; no new public test route, component gallery framework or production data. Verify real foreground/background/icon/focus pairs. Preserve labels, action outcomes and enabled/disabled behavior. Do not merely test that token names exist or choose new arbitrary global colors.

**Exclude:** App route/provider changes, navigation grouping, sidebar rewrite, dashboard cards/layout, CV save/preview extraction (separate P4-03), final logo/color/font choice, API/schema, dependencies, billing, B07. Do not silently bundle all of A01–A03.

Acceptance:
1. Original targeted contrast/focus failure reproduced or explicitly matched to prior evidence; fixed at the responsible shared layer.
2. Representative loaded fixtures verify both themes and active states, including no regression to filled-button foregrounds.
3. Keyboard focus visible; names/semantics/actions preserved in EN/Bokmål.
4. Related Jest/browser checks, standalone TypeScript, lint and production build pass; full frontend suite remains at least the unchanged 313 plus intentional additions.
5. Backend/B01–B05 contracts unchanged; execute relevant suite at checkpoint if shared tooling/API changes occur. Do not claim fresh full backend run without executing it.
6. Document actual PRES-E08 and affected consumer evidence, source/contrast measurement, changed files and any remaining manual gaps. Commit separately, review before P4-02/next surface.

## Foundation stop conditions

Stop the affected slice if it requires a new component library, HTTP/auth change, schema, broad state rewrite or unresolved product semantics. Do not expand a theme fix into routing or all page styling.

Do not proceed to broad representative migration with failing named/focus/contrast states. P2-D01 must be independently repaired and successful native package/archive tests obtained before package/tailoring restructuring. Do not co-edit CvBuilderEditor with D01, even if one change seems visual. A mounted save queue remains insufficient against stale browsers.

No hiding functions, test exclusions, CSS overflow clipping or broad axe suppression to create apparent parity. Unexpected known-baseline recurrence is recorded separately, with affected work paused as necessary.

## Later sequencing, without starting it

1. Review P4 foundation evidence.
2. Phase 5 shell/navigation grouping, retaining existing routes/provider tree; add drawer/account/command gap tests first.
3. Jobs Table/Board owner and /kanban alias in one scoped migration after filter/query parity. Keep discovery/companies/offers/reminders reachable.
4. Existing-data dashboard/Analytics presentation with accurate definitions. New metrics do not block relocating already available charts.
5. Job workspace sections **after** package/native and relevant integrity gates; CV editor **after** revision/focus gates. Keep mail-send owner isolated.
6. Phase 6 review, then Phase 7 remaining routes using each PRES trace.
7. Phase 8 customization/new data requirements only after relevant product decisions and backend/recovery readiness.
8. Full QA/release evidence; cleanup only with proven unreferenced code and explicit preservation sign-off.

## Safe coordination

Theme fixture planning and backend baseline defect investigation can be independent if separately authorized and owned. Source/metric definition documentation can proceed independently from UI primitives. Do not concurrently mutate theme.ts or App.tsx from several visual sessions.

Serialize route helper/App/private-tree changes; serialize table/board integration at its shared owner. Serialize D01 with preview/editor extraction. Serialize document index work with package persistence changes only after their contracts settle. Mail send/draft state is never a generic document-form refactor.

No backend security queue is automatically authorized by this planning sequence. F04 and B07 retain their existing scope/approval boundaries.

## Phase 3 checkpoint validation

Method: inspect the current application source and model/controller contracts; compare against Phase 1 full ledger/routes and Phase 2 assertion/gap mapping. Read the product specification package. Validate local Markdown/source links, complete ID/route coverage, new-requirement catalogue, representative existing test names and documentation-only Git diff. No rendered visual prototype or production visit was necessary to validate a documentation-only plan.

Commands were run from repository root using PowerShell/Python/Git. Full application suites were not rerun solely for prose changes; their unchanged Phase 2 evidence is reused with that limitation. Source-backed observations P3-O01/P3-O02 are recorded, not repaired.

| Executed command / review | Result |
|---|---|
| git switch -c codex/ui-redesign-phase3 d6d3dd9 | Dedicated branch created at the requested clean checkpoint |
| python - (inline document/PRES/route/link validator) | 19 required deliverables; 57 unique PRES rows exactly match the original ledger; 31 routes exactly match current App.tsx; 16 ARC and 16 NEW definitions; 39 widget IDs; all 73 local package links resolve |
| python - (inline Markdown table and named-test checks) | Balanced fences and consistent table columns; named existing regression references checked against Phase 2/current test files |
| rg / Get-Content current source and model review | Confirmed route/query/provider boundaries, current statuses, canonical/variant relationship, widget field availability and source-backed limitations; corrected draft references before completion |
| git diff --check and git diff --cached --check | Passed; no whitespace errors |
| git diff --cached --name-only / --stat | 22 Markdown files only: 19 package files, root index, traceability link and TODO; no app/test/build/CI/schema changes |
| python scripts/supply-chain.py scan-secrets | Passed on the staged documentation; no high-confidence credential patterns found |

This proves architecture-document completeness and consistency with inspected source. It does not prove a future migration, manual usability, AI factual quality, provider operation, remote CI or production ingress. Commit/push status is reported with the final checkpoint SHA; no deployment is performed.