docs(redesign): define Phase 3 UX architecture

2026-09-10 18:15:05 +02:00
parent d6d3dd977d
commit f696f23fc5
22 changed files with 1186 additions and 1 deletions
@@ -0,0 +1,51 @@
+# Application shell
+
+ARC-03; PRES-E01–PRES-E09, PRES-S02–PRES-S04, PRES-A01–PRES-A03. Reuse [AppShell](../../../job-tracker-ui/src/layout/AppShell.tsx) and [App](../../../job-tracker-ui/src/App.tsx). They already support grouped items, longest-path active matching, collapse persistence, mobile drawer, breadcrumbs, account actions and notification access.
+
+## Structure
+
+```text
+Desktop
+┌ Sidebar (expanded / rail) ┬ Search/commands     Notifications   Account ┐
+│ Dashboard                │ Breadcrumb if useful                       │
+│ JOB SEARCH               │ Page title / context        Primary action │
+│ CAREER                   │ Secondary workspace navigation             │
+│ INSIGHTS                 │ Main content                  [AI panel]   │
+│ ACCOUNT / ADMIN          │                                            │
+└──────────────────────────┴────────────────────────────────────────────┘
+Mobile: compact top bar → contextual title/actions → content
+Menu opens a modal navigation drawer; search, bell and account stay reachable.
+```
+
+Global bar owns navigation utilities, not a repeated second job/CV header. Contextual page header owns title, description, scope and one primary action plus explicit secondary/overflow actions. Detail WorkspaceHeader owns role/company/status/deadline or CV name/save/publication state.
+
+## Reuse and responsibility
+
+Retain the current collapse preference (device-local, non-private), 254/84 px starting widths and <768 px drawer breakpoint until content testing demonstrates a change. Do not reset collapse just because group labels change. Collapsed links have persistent accessible names and tooltips; the active child determines one primary owner through explicit metadata for /discover, /companies and other non-nested paths.
+
+Keep navigation metadata near existing App route/title ownership; extend it with logical parent/title information only as needed. Do not create a router framework, move to Next routing or recreate the router on theme/density changes. Route identity churn is a source-backed risk requiring a regression test before touching that owner.
+
+## Global controls
+
+- Search opens the existing command dialog. Keyboard and visible button share one action.
+- Notification bell has count and accessible unread summary; no CV/mail body in its collapsed label.
+- Account menu: Account & security, Settings, Connections, theme, language, sign out. Existing provider-link/security controls remain on their pages; appearance actions do not create another settings store.
+- A contextual “AI help” entry appears only where supported actions/context exist. It opens a narrow action panel, not automatic chat or generation. Without an eligible context, omit this entry rather than showing a global disabled assistant.
+- Build metadata remains admin-only. No operational configuration in a personal header.
+- Keep current light/dark/system and EN/Bokmål hydration; UI language and document language remain distinct.
+
+## Identity and navigation lifetimes
+
+Preserve the B02 authenticated-tree unmount, pending-request abort and stale response/mutation rejection on identity/session transition. A new panel, command result, notification list or preview may not outlive that tree. No second Axios client, persisted private command history or unscoped draft store.
+
+Navigation goes through existing dirty protection. Cancel keeps the document and focus; Discard is deliberate. An account boundary clears private content even if unsaved: do not ask B to retain A's draft. Logout retains existing server invalidation/local cleanup. Role-hidden navigation supplements, never replaces, server authorization. Denied admin/API pages show safe unavailable/permission states without fetching hidden individual data.
+
+## Interaction requirements
+
+Skip-to-main link, labelled navigation landmark, one main region, logical h1 and route-change focus on the new page title. Closing mobile drawer/command/bell returns focus to its trigger; selecting a route closes the surface and focuses the new heading. Avoid multiple active modal focus traps. A persistent desktop sidebar is not a modal dialog.
+
+Sticky headers must not obscure focused controls at zoom or with wrapped Bokmål text. Reserve no permanent AI column when it is closed. On phone use full-height dialogs for long tasks and preserve scroll/draft state through viewport changes.
+
+## Gate before shell migration
+
+Extend existing sidebar-active-nav, app-shell-notifications, quick-command-preservation, account-isolation and redesign-preservation tests with collapse persistence, mobile focus return, all logical parent routes, theme/language changes during dirty editing and two-account command/notification disposal. Loaded EN/NB × light/dark × phone/desktop evidence is required. Implement this only after Phase 4 foundations; no shell rewrite is part of Phase 3.