Eve library

V1-AWEB-093 — Admin Shell Redesign Spec

Spec

Revision 1

On this page

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#

text
┌────────────────────────────────────────────────────────────────┐
│ 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.

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.