feat(ui): establish semantic colors and focus foundation

docs/redesign/phase-4/README.md

@@ -0,0 +1,8 @@
+# Phase 4 checkpoints
+
+Phase 4 starts from `f696f23` on `codex/ui-redesign-phase4`. The 57 preservation contracts in [Phase 2](../phase-2/PRESERVATION_MATRIX.md) and the [Phase 3 impact matrix](../phase-3/PRESERVATION_IMPACT_MATRIX.md) remain authoritative.
+
+- [P4-01 semantic colors, focus and loaded fixtures](p4-01/README.md)
+- [P4-01 preservation and visual evidence](p4-01/TRACEABILITY.md)
+
+Only P4-01 is authorized in this checkpoint. No route/layout redesign, P4-02, B07, backend/schema work or production deployment is included. F04 remains open pending actual production ingress evidence.

docs/redesign/phase-4/p4-01/README.md

@@ -0,0 +1,125 @@
+# P4-01 — semantic colors, focus and loaded-state protection
+
+Source checkpoint: `f696f23`; dedicated branch: `codex/ui-redesign-phase4`. Requirement: [P4-01 handoff](../../phase-3/PHASE4_IMPLEMENTATION_PLAN.md), [design architecture](../../phase-3/DESIGN_SYSTEM_ARCHITECTURE.md), [accessibility plan](../../phase-3/ACCESSIBILITY_PLAN.md), [responsive strategy](../../phase-3/RESPONSIVE_STRATEGY.md). Implementation SHA is the commit containing this record (`git log -- docs/redesign/phase-4`), avoiding a self-referential SHA.
+
+## Reproduced causes
+
+The new palette-pair tests were run against the unchanged theme before editing it: **6 failed, 6 passed**. MUI's contrast calculation measured light success text on the canvas at 3.04:1; light warning/error at 4.13:1 and info at 4.15:1; dark primary text at 3.70:1. The default 3:1 contrast-text selection also allowed the dark error filled-action pair at 3.07:1. These fail the project's ordinary-text target of 4.5:1. These are palette measurements, not an assertion that every old page used each pair.
+
+The original theme supplied a translucent focus shadow but no consistent shared keyboard outline, and used the decorative divider as the outlined input boundary. Selected list items used the same layer as hover.
+
+A real loaded CV scan independently found editable names in omitted sections at **4.22:1** (`#7b7b7d` on white). The responsible local style applied 58% opacity to the entire section; omitted entries used 50%. Omission from the PDF does not disable editing. This local contrast cause cannot be repaired by changing a global text token without distorting other consumers.
+
+## Implementation and changed owners
+
+| File | Change and scope |
+|---|---|
+| `job-tracker-ui/src/theme.ts` | Existing MUI CSS-variable theme owns semantic surfaces, borders, focus, navigation and action layers; mode-specific semantic tones, readable filled-action foregrounds and shared focus overrides |
+| `job-tracker-ui/src/theme.d.ts` | Small MUI palette/background augmentation for the added roles; no separate token runtime |
+| `job-tracker-ui/src/layout/AppShell.tsx` | Replace existing inverse-sidebar color literals with MUI variable references; scope inverse focus color to drawer content. Same colors, groups, widths, routes and collapse behavior |
+| `job-tracker-ui/src/views/CvBuilderEditor.tsx` | Remove whole-container opacity for omitted sections/entries only. Visibility icon/action names, inclusion settings and render/save logic retained; transient drag opacity unchanged |
+| `job-tracker-ui/src/theme-contrast.test.ts` | 14 pair/essential-boundary contrast cases across light/dark |
+| `job-tracker-ui/src/loaded-theme-states.test.tsx` | Six actual CompaniesTable loading/populated/empty/error-retry cases, both themes; no-write and dialog semantics checks |
+| `job-tracker-ui/e2e/semantic-foundations.spec.ts` | 12 real-browser cases, synthetic isolated accounts, loaded fixtures, actual focus contrast, state scans and screenshots |
+
+No dependencies, build scripts, CI, backend contracts, data model, route tree, providers, typography, layout, logo or final brand decision changed.
+
+## Token architecture
+
+The existing `#5B5BD6` hue remains **provisional continuity**, not final brand approval. Light primary retains that exact value. Dark primary uses the same hue lightened by 45%, with a dark filled-action foreground. Light success/warning/error/info use darker tones of their existing hues. Their hover tones are darker again; text on filled controls is selected at a 4.5:1 threshold. Browser scans also check the actual hovered primary action.
+
+| MUI role | Contract |
+|---|---|
+| `background.default`, `background.paper`, `background.elevated` | Existing canvas/paper retained; elevated overlay surface added and used by dialogs/popovers (menus inherit). Dark elevated surface is `#1C1C24`; light is white |
+| `text.primary/secondary/disabled` | Existing text hierarchy retained; no new feature-level text palette |
+| `divider`, `border.subtle/default/strong` | Decorative divider stays subtle. Essential input outlines use the stronger `border.default`, measured at ≥3:1 on the three application surfaces |
+| `primary`, `secondary`, `success`, `warning`, `error`, `info` | Standard MUI semantic colors and foregrounds; no duplicate `status` token family |
+| `action.hover/selected/focus/disabled/disabledBackground` | Explicit mode-specific hover/selection/focus layers; disabled controls remain disabled; focus is additionally outlined |
+| `focus.main/inverse` | 3px visible keyboard indicator against application or inverse-navigation surface |
+| `navigation.*` | Existing fixed inverse sidebar background, foreground, selection and hover moved intact into the MUI palette |
+
+`background.paper` serves the proposed surface role; there is no redundant `background.surface` alias. Generated `--palette-*` variables come from MUI. `--app-focus-color` is a scoped alias of `palette.focus.inverse`, not a second source of colors.
+
+## Focus and states
+
+Shared ButtonBase covers buttons, icon buttons, tabs, menu items and interactive cards. Links/native focusable controls use `:focus-visible`; MUI controls also use `.Mui-focusVisible`. The outline is solid, 3px with 2px offset. Tabs, menu/list items and CardActionArea use an inset outline to avoid clipping inside scroll/overflow containers. InputBase outlines standard controls, including the underline-free command input. Outlined fields/selects use a **3px notched fieldset border**, preserving MUI's floating-label cutout: visual inspection found that the initial outer outline crossed the label. Focus does not add tab stops to ordinary cards.
+
+The ring adds a visible boundary rather than relying on a selected color change. Browser tests measure ≥3:1 against the actual adjacent/composited surface, check focus return after dialogs/drawers, and verify a pointer-activated settings button does not acquire keyboard-only focus styling. Outline remains a native CSS outline; no new animation system is added. Existing reduced-motion behavior is preserved.
+
+Loading and errors already had appropriate primitives: polite named loading status/progress and MUI alert with Retry. These implementations are unchanged. New fixtures deliberately hold a read pending, expose an error, retry into empty data, then load actual owner data; editing never repeats the loading status or writes automatically. They preserve error-versus-empty distinctions. A general completion-announcement strategy and manual announcement/repetition review remain P4-02 work; this slice does not claim screen-reader certification.
+
+## Status and legacy-color handling
+
+`pipeline.ts` is unchanged: Saved/Interested/Preparing → neutral; Applied → primary; Waiting/Ghosted → warning; Interview → info; Offer → success; Rejected/Withdrawn → error. Existing labels and visibility/status icons remain, so meaning is not communicated by red/green alone. Unknown/custom statuses keep their raw label and neutral tone. No status schema, color picker or arbitrary custom-color API is added.
+
+Intentional remaining literals include printed CV page white, template/document accent controls, marketing gradients, illustration/logo artwork and specialized chart palettes. Printed paper is independent of application dark mode. These are not silently claimed as migrated. Only the demonstrated CV omission-opacity cause is changed locally; preview/layout/editor architecture is untouched.
+
+## Validation results
+
+The final full frontend/browser runs include the notched-focus adjustment. Raw local logs live in ignored `.artifacts/p4-01-*`; screenshots and a compact scan index are preserved with this package. Browser trace archives contain session details and are not committed.
+
+| Gate | Phase 3 inherited | P4-01 result |
+|---|---:|---:|
+| Backend Release tests | 916 passing | 916 passing, 0 failed/skipped |
+| Frontend Jest | 313 passing | 333 passing in 70 suites (+20), 0 failed |
+| Default browser suite | 23 actual passes + 1 expected failure | 35 actual passes + 1 unchanged expected failure (+12 actual passes) |
+| Focused loaded/focus browser | No P4-specific fixture | 12 passing |
+| Standalone TypeScript + E2E file type check | Passing | Passing |
+| ESLint | Passing | Passing |
+| API Release build, warnings as errors | Passing | Passing, 0 warnings/errors |
+| Next production export | Passing | Passing |
+| Compose validator | 3 passing | 3 passing |
+| B04 rate limits / production HTTP / PDF admission probes | 9 / 6 / 1 passing | 9 / 6 / 1 passing |
+
+The final browser report contains **38 loaded scans and zero color-contrast violations**. It also retains eight `aria-input-field-name` node occurrences: four existing unnamed Customize controls in each theme. Those are P4-02 naming debt. Axe marked checks incomplete in 20 scan states for color contrast, ten for `aria-hidden-focus` and ten for `aria-prohibited-attr`; incomplete checks are not passes. The [scan index](SCAN_RESULTS.json) records these limits. Representative screenshots and keyboard checks supplement the scans; they do not establish whole-product WCAG compliance. The browser runner's total of 36 expected outcomes includes the unchanged P2-D01 failure; it is not 36 successful workflows.
+
+Exact commands (PowerShell; repository root unless `Set-Location` changes it):
+
+```powershell
+git switch -c codex/ui-redesign-phase4 f696f23
+$env:DOTNET_ROOT='C:/Users/Connor/.dotnet'
+& C:/Users/Connor/.dotnet/dotnet.exe test JobTrackerApi.Tests/JobTrackerApi.Tests.csproj --configuration Release --no-restore --logger 'trx;LogFileName=p4-01.trx' --results-directory .artifacts/redesign-p4-01 -- xUnit.parallelizeTestCollections=false xUnit.maxParallelThreads=1
+& C:/Users/Connor/.dotnet/dotnet.exe build JobTrackerApi/JobTrackerApi.csproj --configuration Release --no-restore -warnaserror
+python scripts/test-ingress.py
+Set-Location job-tracker-ui
+npm test -- --watchAll=false --runInBand src/theme-contrast.test.ts
+npm test -- --watchAll=false --runInBand
+npm run typecheck
+npm run lint
+node node_modules/typescript/bin/tsc --project ../.artifacts/p4-01-e2e-tsconfig.json
+$env:NEXT_PUBLIC_API_BASE_URL='http://localhost:5302/api'
+$env:NEXT_TELEMETRY_DISABLED='1'
+npm run build
+$env:DOTNET_HOST_PATH='C:/Users/Connor/.dotnet/dotnet.exe'
+$env:PLAYWRIGHT_STATIC_EXPORT='true'
+$env:PLAYWRIGHT_PREBUILT_EXPORT='true'
+node node_modules/@playwright/test/cli.js test e2e/semantic-foundations.spec.ts --reporter=list,json
+$env:PLAYWRIGHT_JSON_OUTPUT_FILE='../.artifacts/p4-01-browser-results.json'
+$env:P4_CAPTURE='true'
+node node_modules/@playwright/test/cli.js test --reporter=list,json
+node node_modules/@playwright/test/cli.js test --config=playwright.rate-limits.config.ts
+node node_modules/@playwright/test/cli.js test --config=playwright.ingress.config.ts
+node node_modules/@playwright/test/cli.js test --config=playwright.pdf.config.ts
+Set-Location ..
+python scripts/supply-chain.py scan-secrets
+git diff --check
+git diff --cached --check
+```
+
+The ignored E2E type config extends the frontend tsconfig, includes only `e2e/semantic-foundations.spec.ts`, sets `incremental:false`, and resolves Node types from the frontend's node_modules. No permanent CI change is needed: standalone frontend checking already exists from Phase 2. TS2571 does not recur.
+
+Fixture corrections during validation: use the existing translated `jobTableEdit` action; honor server-persisted UI language as well as browser preference; use the sidebar's current button role; follow MUI roving-tab/option keyboard semantics; locate the three actual document-AI review actions. These were test-assumption errors, not product fixes. The real CV opacity finding above was fixed and reverified.
+
+Screenshot investigation: some immediate post-axe PNGs omitted sidebar labels/icons. A temporary two-theme browser probe captured the same page before axe, after axe, after keyboard activity and after two animation frames. Text, geometry, opacity `1`, visibility `visible` and computed white selected text stayed unchanged; the post-paint capture restored the labels without changing the DOM, styles or application. The permanent screenshot helper now allows that paint cycle before capture. Some company PNGs still partially omit sidebar glyphs, so their visual claim is limited to the main loaded state; dedicated Jobs navigation captures and keyboard assertions supply navigation evidence. This does not establish the underlying Chromium/scan capture cause or certify every captured sidebar. The two diagnostic cases passed (`node node_modules/@playwright/test/cli.js test --config=../.artifacts/p4-01-nav-probe.config.ts`; local log/paired PNGs in `.artifacts`). The probe's initial server start failed because its temporary config resolved the export directory from `.artifacts`; setting its server working directory to the actual frontend resolved that harness error. No application workaround was introduced.
+
+## Remaining boundaries / next slice
+
+**P4-01 is complete within its scoped acceptance criteria:** shared semantic/focus foundations, both themes, loaded-state fixtures, preserved regression baseline and representative visual evidence. Remaining manual accessibility proof and later structural repairs are explicitly excluded below. No claim of full accessibility or production verification is made.
+
+- P4-02 remains unstarted: shared labels, named Customize controls/command input, modal/async announcement audit. Full axe findings are retained in the scan index; the new loaded tests explicitly gate **contrast**, not all WCAG rules. Existing broad axe tests are unchanged.
+- P4-03 remains unstarted: loaded CV preview keyboard-scroll/viewport behavior. The fixture's existing horizontal-overflow warning is retained; this ticket does not hide it or claim printable-layout repair. Drag alternatives/transient drag opacity require their own interaction review.
+- All 57 preservation contracts remain; the full product cross-product of routes/data/themes/locales/providers is not claimed covered by these representative fixtures. See [traceability](TRACEABILITY.md).
+- Narrator/NVDA, real touch/virtual keyboard, mobile screen reader, zoom/text-spacing and forced-colors manual validation remain explicit gaps. Screenshots and Chromium keyboard tests do not substitute for these.
+- P2-D01 remains the narrowly documented browser expected failure. Package/tailoring restructuring remains blocked on native success evidence.
+- **F04 remains open**. No deployed Traefik/nginx/firewall evidence was obtained. Feature-branch local tests do not prove remote CI or production release health.
+- No P4-02, route/layout migration, dashboard/CV redesign, B07 or production deployment. Recommended next ticket only: P4-02 after review of this checkpoint.

docs/redesign/phase-4/p4-01/TRACEABILITY.md

@@ -0,0 +1,51 @@
+# P4-01 preservation and visual evidence
+
+Chain: `PRES → original requirement → P4-01 owner change → executed regression → loaded visual/UX evidence`. Resolve the implementation commit with `git log -- docs/redesign/phase-4`; its parent is `f696f23`. All baseline routes, query parameters, write/ownership contracts and provider boundaries are retained. None of the 57 [original preservation rows](../../phase-2/PRESERVATION_MATRIX.md) is replaced by this shorter scope table.
+
+## Affected contracts
+
+| PRES → retained requirement | Implementation / location retained | Automated regression and result | Visual/UX evidence / explicit limit |
+|---|---|---|---|
+| PRES-E08 → existing theme/system and EN/NB state, shared notices/dialogs | `theme.ts`, `theme.d.ts`; existing ThemeProvider/preferences/I18nProvider unchanged | `theme-contrast.test.ts` 14 pairs; `loaded-theme-states.test.tsx` six transitions; existing theme-state/i18n/dialog tests; 12 new browser cases | Both themes, EN/NB, 1440/390 widths on company states; no theme remount/state change. General completion announcements and AT review remain P4-02 |
+| PRES-E07 → collapse/drawer, current destination and commands | `AppShell.tsx` only replaces color references and adds inverse focus alias. Same sidebar groups/buttons, routes, widths and storage key | Existing sidebar-active-nav/quick-command-preservation; real command navigation baseline; new nav/command input/item focus and phone drawer return | `jobs-nav-*`, company phone fixtures. No command hierarchy or navigation migration |
+| PRES-J05, PRES-J07 → row actions and existing pipeline meanings | Shared colors only; `JobTable`, `KanbanBoard`, `pipeline.ts` unchanged | Existing pipeline/grouped Kanban tests; loaded six-status Jobs native API/browser scans in both modes; inherited dark Kanban browser | `jobs-nav-*`: labelled Saved/Applied/Waiting/Interview/Offer/Rejected, primary/neutral/warning/info/success/error. Custom statuses retain neutral/raw label; no new custom-color picker |
+| PRES-J08 → company/contact edits and relationships | CompaniesTable unchanged; shared fields/dialog/action styling | Eight browser matrix cases: named loading → error/Retry → empty → actual populated table/card; keyboard edit/dialog/return; six Jest cases also prove no write on load/edit | `companies-*`: EN/NB × light/dark × desktop/phone. Contact-save/relationship behavior retained in existing tests; no new claim of every date/source edge |
+| PRES-C06, PRES-C07 → CV tabs, previews, inclusion and isolated overrides | Shared theme plus two omission-opacity branches in CvBuilderEditor; no data/save/preview change | Loaded Content with canonical source and omitted sections, named override focus/contrast; existing CV Jest coverage and native Phase 2 mobile override/sibling isolation test | `cv-content-*`: omitted sections are editable/readable, visibility indicators retained. Existing overflow warning remains. P4-03 preview keyboard and long print-layout gaps remain |
+| PRES-C08, PRES-C09 → capability-aware template/customize/document controls | Existing controls consume shared palette and notched focus | Loaded Template/hovered PDF action, Customize Page size combobox/menu/Escape/focus return; existing CV normalization/template/render tests | EN desktop in both themes; advanced document choices and printed paper colors unchanged. New naming failures are not silently repaired |
+| PRES-C11, PRES-S04 → AI review/accept/reject and entitlement locks | AI logic/actions unchanged | Three real Free document-AI Review buttons remain disabled; loaded AI panel contrast; inherited accept/reject/malformed response Jest tests and server entitlement/browser checks | Pro notice/locked controls readable; no model invoked, no claim of live provider factual quality |
+| PRES-S03 → preferences and notification settings | Settings owner unchanged, shared tab/button/field styles | Loaded Notifications tab/checkbox/save in both modes, pointer-vs-keyboard focus; existing settings failure/retry and mobile→desktop preference persistence baseline | EN desktop plus inherited responsive settings workflow; no preference schema/UI redesign |
+| PRES-E01, PRES-E02 → public plans/auth entry | Shared theme influence only; marketing literals retained | Unchanged public axe, responsive plans/keyboard and real login browser; existing entry tests | Full original browser cases retained. No final brand or external sign-in/reset-delivery approval |
+| PRES-E09 → server/session and private-state separation | No authentication, App/provider, cache or API changes | Four existing real account-isolation browser cases plus full backend/session regression baseline | Regression dependency, not a newly claimed visual/privacy mechanism |
+
+The remaining protected groups have no directly changed workflow owner. Their mapped tests remain in the complete 916 backend / 333 frontend baseline. Shared theme reach does **not** imply a newly verified loaded/visual state for every one of the 57 groups. Original provider-dependent, production, accessibility and untested capability gaps remain in the Phase 2 matrix.
+
+## New browser fixture boundary
+
+[semantic-foundations.spec.ts](../../../../job-tracker-ui/e2e/semantic-foundations.spec.ts) uses the existing Playwright app/API topology and a new non-admin synthetic owner per test. Native endpoints create profile, CV, company and status examples using B02 session/CSRF headers. Internet/provider traffic is blocked. Only the Companies GET is deliberately delayed/replaced for deterministic loading/503/empty; the populated state returns to the real API. No public fixture route or component gallery was added.
+
+The browser's keyboard helper follows Tab/Shift+Tab or menu ArrowDown/ArrowUp, checks the actual focused target, indicator width/style and ≥3:1 composited contrast. CV tabs use their real roving-tab arrow/Enter interaction. The native MUI dialog/drawer focus-return behavior is asserted. A pointer click on the settings save action remains free of a keyboard focus indicator.
+
+All loaded axe scans run the existing WCAG A/AA tag set without disabling rules. This new file asserts **color-contrast violations only**, as explicitly scoped to P4-01; the complete violation and incomplete results are attached to the local Playwright JSON report. [Scan index](SCAN_RESULTS.json) retains concise rule/node evidence rather than credentials or trace archives. Existing general axe tests remain unchanged. Non-color results are debt, not passes or a certification claim.
+
+## Visual evidence
+
+Captured in local Chromium via the actual built Next application and disposable .NET API, 2026-09-10/11. Heights are 900 CSS px. Files contain synthetic accounts/data only. The same [test source](../../../../job-tracker-ui/e2e/semantic-foundations.spec.ts) defines each exact route and keyboard state. `P4_CAPTURE=true` regenerates the committed screenshots; normal test runs write to ignored test-results.
+
+| Artifact | Route/state/viewport | Review |
+|---|---|---|
+| [Jobs light](visual/jobs-nav-light.png), [Jobs dark](visual/jobs-nav-dark.png) | `/jobs`, six populated statuses, Companies sidebar item keyboard-focused, EN, 1440×900 | Status labels and filled foregrounds readable; distinct selected page vs focus; unchanged dense table; inverse ring visible |
+| [CV light](visual/cv-content-light.png), [CV dark](visual/cv-content-dark.png) | `/career/builder/:id`, loaded Content with canonical profile, omitted sections and headline field keyboard-focused, EN, 1440×900 | Readable omitted rows, field label notch and focus, outline Saved chip, disabled undo/redo and colored alerts. Printed preview stays white. Existing overflow warning retained |
+| [Companies light EN desktop](visual/companies-light-en-1440.png), [dark EN desktop](visual/companies-dark-en-1440.png) | `/companies`, populated table, edit icon keyboard-focused, EN, 1440×900 | Essential action/ring and text visible; surfaces/table hierarchy retained |
+| [Companies light NB desktop](visual/companies-light-nb-1440.png), [dark NB desktop](visual/companies-dark-nb-1440.png) | Same state, Bokmål, 1440×900 | Norwegian labels and æ/ø/å retained |
+| [Companies light EN phone](visual/companies-light-en-390.png), [dark EN phone](visual/companies-dark-en-390.png) | Populated existing mobile card, edit focus, EN, 390×900 | Existing card workflow retained; visible action focus without page restructuring |
+| [Companies light NB phone](visual/companies-light-nb-390.png), [dark NB phone](visual/companies-dark-nb-390.png) | Same state, Bokmål, 390×900 | No truncation of fixture labels; ring visible against both surfaces; drawer keyboard/return tested after screenshot |
+
+No final visual identity or layout approval is implied. Disabled controls retain disabled semantics and existing adjacent explanations; their text is not falsely counted as satisfying active-text contrast. Subtle decorative dividers are not used to claim essential-control contrast. Placeholder-only naming, transient drag opacity, remaining local chart/marketing colors, manual assistive technology and full loaded responsive CV interactions remain separately scoped.
+
+Capture limitation: some company-page PNGs still partially omit sidebar glyphs despite unchanged visible DOM/computed styles. The paired diagnostic captures described in the completion report show those glyphs returning after painting without an application change. Company PNGs evidence the main loaded state and edit focus; use the dedicated `jobs-nav-*` captures and actual keyboard assertions for navigation evidence. This is not treated as a successful whole-sidebar screenshot comparison. No content was hidden or restyled to produce the evidence.
+
+## Review and rollback
+
+Self-review: no action, data, event handler, ownership or route change; no newly focusable ordinary cards; keyboard rings remain distinct from hover/selection; both CSS variable schemes are exercised; B01–B05 suites retained. The one CV local change addresses an independently measured contrast cause. No sensitive traces are committed.
+
+Rollback is a normal revert of this isolated P4-01 checkpoint; no schema/data migration or infrastructure rollback is needed. Do not start P4-02 or broader migration until Connor has reviewed this checkpoint. F04 and P2-D01 retain their separate closure requirements.