# V1-AWEB-093 — Admin Shell Redesign Spec

This is the implementation spec for the Phase 17.10 admin shell redesign. Scope:
the chrome that wraps every admin route — header, sidebar, breadcrumb, command
palette, notification center, focus indicators, density, and theming.

The goal is **stronger orientation, calmer chrome, and lower operator fatigue
across long sessions** (per the V1-AWEB-093 ticket description). It is _not_ a
re-skin: the chrome must materially reduce the number of glances an operator
makes during routine triage, and the visual noise during active reading.

## Reference: as-is shell

(See `V1_AWEB_092_REDESIGN_INVENTORY.md` for the full per-route panel list.
Files referenced below live under `apps/oshun/admin/src/components/`.)

- `AdminShell.tsx` — top-level wrapper that renders header, sidebar, and the
  route's children. Two-column layout (sidebar + main).
- `AdminHeader.tsx` — sticky top header with brand, current workspace label,
  command-palette trigger, notification center, operator menu.
- `AdminSidebar.tsx` — vertical workspace nav (one entry per admin route),
  collapsed/expanded variant.
- `AdminCommandPalette.tsx` + `AdminCommandPaletteProvider.tsx` +
  `AdminCommandPaletteTrigger.tsx` — `Cmd-K` palette for navigation and quick
  actions.
- `AdminNotificationCenter.tsx` — pull-out drawer of operator notifications.
- `KeyboardShortcutsHelp.tsx` — modal listing keyboard shortcuts.
- `WorkspaceEntryPoint.tsx` — per-route header card that summarises whether the
  workspace loaded and any access refusal reason.
- `WorkspacePage.tsx` / `WorkspaceSummaryCard.tsx` — dashboard cards on `/`.

### As-is pain points

The redesign is a response to specific, measured pain points:

1. **Orientation cost on workspace switches.** The header shows the current
   workspace label but not its position within a logical group (operations /
   governance / customer / models / research). Operators traversing 3+
   workspaces in a session re-read the sidebar to confirm context.
2. **Sidebar density.** All workspace links are at the same visual weight; the
   sidebar reads as a flat list of ~16 items even though operators tend to live
   in 2-3 workspaces per shift.
3. **Banner noise during active reading.** Each panel emits a bright success /
   error banner per submit; in a multi-panel page (e.g., `/research-integrity`
   with 5 panels) repeated submissions stack visually.
4. **Notification center as a side-effect.** The notification center pulls out
   from the right but does not retain the operator's panel scroll position;
   returning to the panel requires re-finding the row.
5. **Operator menu lacks a "where am I?" trail.** The shell does not render a
   route breadcrumb; deep detail routes (`/review/[reviewId]`) lose the
   workspace context once an operator has scrolled past the header.
6. **Density toggle missing.** The shell defaults to a comfortable 0.78–0.85rem
   text density; long-session operators asked for a "compact" mode that drops
   vertical padding by ~30%.

## Design principles

1. **Orientation first.** The shell makes the current workspace, its category,
   and the operator's context (review id, case id) visible without the operator
   scrolling to find a header.
2. **Calm by default, loud only on changes.** Background chrome stays in a
   low-contrast palette; bright surfaces only render when the operator's
   attention is needed (success / error banner, severity escalation, SLA
   breach).
3. **Density is an operator choice.** The shell exposes a `density` toggle
   (`comfortable | compact`) with persistence in `localStorage` keyed
   per-operator.
4. **Keyboard-first parity.** Every chrome surface (sidebar, palette,
   notification center, density toggle, breadcrumb) has a keyboard shortcut and
   a visible focus ring at WCAG 2.2 AA.
5. **Don't move chrome.** Once the operator opens a workspace, the shell does
   not move under them: no animated banners that shift content, no
   collapse-on-scroll behaviour for the header.

## Layout

```
┌────────────────────────────────────────────────────────────────┐
│ AdminHeader  (sticky, 48px comfortable / 36px compact)         │
│   [Oshun]   Workspace · Subworkspace › Detail   [⌘K]  [🔔]  [👤]│
├────────────────────────────────────────────────────────────────┤
│ AdminSidebar │  Main content area                              │
│ (240px /     │   ┌──────────────────────────────────────────┐  │
│  64px collapsed)│  WorkspaceEntryPoint                       │  │
│              │   └──────────────────────────────────────────┘  │
│  Operations  │   ┌──────────────────────────────────────────┐  │
│  · /inbox    │   │  Panel A                                 │  │
│  · /review   │   └──────────────────────────────────────────┘  │
│  Governance  │   ┌──────────────────────────────────────────┐  │
│  · /policy   │   │  Panel B                                 │  │
│  · /privacy  │   └──────────────────────────────────────────┘  │
│  · /rights   │                                                  │
│  Research    │                                                  │
│  · /research-│                                                  │
│    integrity │                                                  │
│  Models      │                                                  │
│  · /models   │                                                  │
│  Customer    │                                                  │
│  · /support  │                                                  │
│  Editorial   │                                                  │
│  · /editorial│                                                  │
│  Trust       │                                                  │
│  · /trust-   │                                                  │
│    safety    │                                                  │
│  Incidents   │                                                  │
│  · /incidents│                                                  │
│  Personas    │                                                  │
│  · /personas │                                                  │
└──────────────┴──────────────────────────────────────────────────┘
```

### Workspace categorisation

Per the V1-AWEB-092 inventory the 16 routes group naturally into 8 categories.
The sidebar collapses to category headers on hover and expands the active
category by default. Categories are declarative (driven by a workspace-id →
category map shipped in
`apps/oshun/admin/src/lib/admin-workspace-categories.ts`).

| Category   | Workspaces                       |
| ---------- | -------------------------------- |
| Operations | `/inbox`, `/review`              |
| Governance | `/policy`, `/privacy`, `/rights` |
| Research   | `/research-integrity`            |
| Models     | `/models`                        |
| Customer   | `/support`                       |
| Editorial  | `/editorial`                     |
| Trust      | `/trust-safety`                  |
| Incidents  | `/incidents`                     |
| Personas   | `/personas`                      |
| Analytics  | `/analytics`                     |

(`/handoff` and `/unauthorized` are not surfaced in the sidebar.)

### Header breadcrumb

The header renders a breadcrumb of the form `{Category} · {Workspace}` for
top-level routes, and `{Category} · {Workspace} › {Detail}` for detail routes.
The detail segment is sourced from a per-page `useAdminBreadcrumb()` hook that
detail pages call with the entity id and display name (e.g., review package
title). The hook is opt-in: top-level pages do not need to call it.

## Density

The shell exposes a `density` toggle in the operator menu with two values:

- `comfortable` (default): existing 0.78–0.85rem text, 0.45– 0.55rem vertical
  padding on form rows.
- `compact`: 0.74rem text, 0.30rem vertical padding, 0.5rem reduced section
  gaps, 36px header (down from 48px).

Toggle persists via `localStorage` under the `oshun.admin.density` key. The
shell broadcasts the active value through a CSS custom property
`--admin-density` consumed by panel `.module.css` via two density-tier rules.

## Notification center

- Pull-out remains right-aligned but **never moves the main scroll position**
  (use `overflow-y: auto` on the main area, not on `body`).
- Notification rows surface the originating workspace category badge so an
  operator can scan by category at a glance.
- "Mark all read" is a single-click action with no confirmation modal — a
  destructive-style undo toast appears for 6s.

## Command palette

- `Cmd-K` on macOS / `Ctrl-K` on Win/Linux opens the palette.
- Palette is now grouped by the same workspace categories as the sidebar; each
  entry shows its category as a leading badge.
- Recent commands (last 8) appear at the top under a "Recent" group, persisted
  per-operator in `localStorage`.

## Banner discipline

Per-panel success / error banners stay (operators expect per-action feedback)
but the shell adds a single rule: when a panel emits a success banner and the
operator has scrolled elsewhere on the page, the banner does NOT scroll back
into view. This already matches the current implementations in V1-AWEB-085 / 086
/ 087 / 088 / 089 — the spec codifies it for the redesign.

## Accessibility

- All sidebar items, header buttons, and palette entries have visible 2px focus
  rings at `outline-color: #fbbf24` (matches WCAG 2.2 AA against the slate
  background).
- The density toggle is reachable from the keyboard via the operator menu (Tab +
  Enter); it is also wired to a global shortcut `Cmd-Shift-D` toggling between
  the two values.
- The breadcrumb is rendered as `<nav aria-label="breadcrumb">` with `<ol>` +
  `<li>` per segment.
- The notification center pull-out traps focus while open and returns focus to
  the trigger on close.

## Implementation deliverables

For the engineer picking up V1-AWEB-093 implementation:

1. **`apps/oshun/admin/src/lib/admin-workspace-categories.ts`** — pure data:
   workspace-id → category map plus an ordered category list. Test coverage:
   every workspace id from `apps/oshun/admin/src/lib/admin-workspaces.ts`
   resolves to a category.
2. **`AdminSidebar.tsx`** — collapse-by-category, expand-active behaviour.
   Existing tests update to assert categorised render order.
3. **`AdminHeader.tsx`** — breadcrumb segment renderer; opt-in detail segment
   via `useAdminBreadcrumb()` context hook (new).
4. **`AdminShell.tsx`** — density toggle + CSS custom property plumbing. Updates
   `globals.css` with two density tiers under
   `[data-admin-density="comfortable"]` / `[data-admin-density="compact"]`.
5. **`AdminCommandPalette.tsx`** — group palette entries by category, pin
   recents.
6. **`AdminNotificationCenter.tsx`** — main-area scroll isolation; category
   badge per row.
7. **Component tests:**
   - `AdminSidebar.test.tsx` — categorised render order.
   - `AdminHeader.test.tsx` — breadcrumb (with + without detail).
   - `AdminShell.test.tsx` — density toggle persistence.
   - `AdminCommandPalette.test.tsx` — grouping + recents.
8. **E2E:**
   - `admin-shell-redesign.spec.ts` — density toggle round-trips in
     localStorage; sidebar category collapse/expand keyboard navigation;
     breadcrumb renders on `/review/[reviewId]`; palette grouping renders.

## Out of scope

- Multi-window / multi-tab session sync (deferred).
- Sidebar drag-to-reorder of workspaces (deferred).
- Per-workspace theming overrides (deferred to V1-AWEB-097 which redesigns
  evidence/provenance/diff surfaces).

## Acceptance criteria

- Sidebar renders workspaces grouped by category with the active category
  expanded.
- Header renders a breadcrumb of `{Category} · {Workspace}` on every top-level
  route and `{Category} · {Workspace} › {Detail}` on `/review/[reviewId]`.
- Density toggle round-trips in `localStorage`; refresh restores the operator's
  choice.
- Command palette is grouped by category; recents pinned at top.
- Notification center pull-out does not move the main scroll position.
- All chrome focus rings pass WCAG 2.2 AA contrast against the slate background.
- All existing AdminShell / AdminSidebar / AdminHeader tests remain green; the
  new tests above pass.
