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-Kpalette 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:
- 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.
- 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.
- Banner noise during active reading. Each panel emits a bright success /
error banner per submit; in a multi-panel page (e.g.,
/research-integritywith 5 panels) repeated submissions stack visually. - 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.
- 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. - 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#
- 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.
- 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).
- Density is an operator choice. The shell exposes a
densitytoggle (comfortable | compact) with persistence inlocalStoragekeyed per-operator. - 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.
- 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: autoon the main area, not onbody). - 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-Kon macOS /Ctrl-Kon 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-Dtoggling 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:
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 fromapps/oshun/admin/src/lib/admin-workspaces.tsresolves to a category.AdminSidebar.tsx— collapse-by-category, expand-active behaviour. Existing tests update to assert categorised render order.AdminHeader.tsx— breadcrumb segment renderer; opt-in detail segment viauseAdminBreadcrumb()context hook (new).AdminShell.tsx— density toggle + CSS custom property plumbing. Updatesglobals.csswith two density tiers under[data-admin-density="comfortable"]/[data-admin-density="compact"].AdminCommandPalette.tsx— group palette entries by category, pin recents.AdminNotificationCenter.tsx— main-area scroll isolation; category badge per row.- 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.
- 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.