FRD: Admin Shell Recipe

Document Summary

Field	Details
Feature Name	Admin Shell Seed Recipe
Status	Draft
Owner	David Holmes
Contributors	Engineering, Design
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #79, ADR-027 (Default Tech Stack)
Last Updated	2026-05-26

Introduction

Overview

The Admin Shell recipe provides a copy-pasteable scaffold for building admin dashboards and back-office applications. It composes existing design system components — saas-sidebar-layout.tsx, screen-shell.tsx, global-search-bar.tsx — into a complete application shell with resource navigation, authentication guard, notification integration, and global search. The recipe ships as a runnable example with stories and tests that developers clone and customize for their domain.

Goals

Provide a complete, copy-pasteable admin shell scaffold using existing design system components.
Demonstrate resource navigation with sidebar sections, nested items, and active-state highlighting.
Show an authentication guard pattern that redirects unauthenticated users.
Integrate notification display (toast + notification center).
Include global search wired to the application shell.
Ship as a runnable example folder with stories and tests.

Non-Goals

Building new layout primitives (uses existing saas-sidebar-layout.tsx and screen-shell.tsx).
Implementing a real authentication backend or identity provider.
Building a real notification service or WebSocket integration.
Providing a complete CRUD scaffold (this is the shell, not the page content).
Role-based access control (RBAC) implementation.

Scope

In Scope

Area	Description
App shell composition	`SaasSidebarLayout` + `ScreenShell` + header + sidebar
Resource navigation	Sidebar with grouped sections, icons, nested items, badges, and active state
Auth guard	Route-level component that checks auth state and redirects if unauthenticated
Notification integration	Toast notifications for actions; notification center in the header
Global search	`GlobalSearchBar` integrated into the header
User menu	Avatar dropdown with profile, settings, and logout
Responsive behavior	Sidebar collapse on mobile; hamburger toggle
Breadcrumbs	Route-aware breadcrumb trail below the header
Stories	Storybook stories demonstrating shell states
Tests	Unit tests for auth guard, navigation, and shell composition
Recipe MDX	Documentation page with usage guide

Out of Scope

Area	Reason
New layout primitives	Uses existing components
Real auth backend	Consumer responsibility; recipe uses mock auth
Real notification service	Consumer responsibility; recipe uses mock notifications
CRUD page patterns	Separate recipe; this covers the shell only
RBAC / permissions	Consumer responsibility; recipe shows auth-or-not guard
Data tables / forms	Separate components; shell provides the frame

Users and Pain Points

User Groups

User	Description	Needs
Application developers	Engineers building admin dashboards	A complete starting point they can copy and extend
Designers	Team members reviewing admin UX consistency	A documented pattern for consistent admin shells
New team members	Engineers onboarding to admin projects	A working example showing how to compose layout components

Pain Points

User	Pain Point	Impact
Application developers	Building an admin shell from scratch each time, composing sidebar, header, auth, and navigation	Wasted time; inconsistent admin UX across products
Application developers	No documented pattern for auth guards in the design system context	Auth integration is done differently in each admin app
Application developers	Unclear how to integrate global search, notifications, and breadcrumbs with the layout	Features are added ad hoc with inconsistent placement

Definitions

Term	Definition
Admin shell	The outer application frame: sidebar, header, content area, and supporting features (search, notifications, auth)
Resource navigation	Sidebar menu items organized by domain (e.g., Users, Products, Settings) with nesting and active states
Auth guard	A route wrapper that checks authentication state and redirects unauthenticated users to a login page
Notification center	A header element showing unread notification count with a dropdown listing recent notifications
Scaffold	A copy-pasteable starting point that developers customize for their specific application

Current State

Existing Behavior

saas-sidebar-layout.tsx provides a sidebar + content layout frame. screen-shell.tsx provides a content-area shell with header and body sections. global-search-bar.tsx provides a search input with keyboard shortcut. These exist as standalone components without a documented composition pattern for admin applications.

Current Limitations

No recipe showing how to compose these components into a complete admin shell.
No auth guard pattern documented.
No notification integration pattern.
No resource navigation example with grouped sections and active states.
No breadcrumb integration pattern.

Existing Workarounds

Developers study existing admin applications or build from scratch.
Each admin app composes the layout components differently.
Auth guards and notification integration are implemented ad hoc.

Proposed Solution

Summary

Create a recipe folder (src/recipes/admin-shell/) containing a composed admin shell, mock auth and notification services, navigation configuration, and documentation. Ship with Storybook stories demonstrating authenticated, unauthenticated, and various navigation states.

Key Capabilities

AdminShell component composing SaasSidebarLayout, ScreenShell, header bar, and sidebar navigation.
AdminNav configuration type for defining sidebar sections with icons, labels, paths, and nested items.
AuthGuard component that wraps routes and redirects unauthenticated users.
NotificationCenter header element with unread count badge and dropdown.
UserMenu avatar dropdown with profile, settings, and logout actions.
AdminBreadcrumbs route-aware breadcrumb trail.
Mock auth service (useAuth) and mock notification service (useNotifications).
Global search integrated into the header via GlobalSearchBar.

User Experience

Developers browse the recipe in Storybook, see the complete admin shell with navigation, search, notifications, and breadcrumbs. They copy the recipe, replace mock services with real ones, and customize the navigation configuration for their domain.

Developer Experience

The recipe is a self-contained folder. Navigation is defined as a typed configuration object. The auth guard is a wrapper component. Services are injected via React context so mocking is straightforward. Stories show authenticated/unauthenticated states, different navigation configurations, and responsive behavior.

Requirements

ID	Requirement	Priority	Notes
FR-001	The recipe must compose `SaasSidebarLayout` and `ScreenShell`	Must	Existing components
FR-002	The recipe must show resource navigation with sections, icons, and active states	Must	Core admin UX
FR-003	The recipe must include an auth guard pattern	Must	Security baseline
FR-004	The recipe must include notification integration	Must	Common admin feature
FR-005	The recipe must include global search in the header	Must	Uses `GlobalSearchBar`
FR-006	The recipe must include a user menu	Must	Profile, settings, logout
FR-007	The recipe must show responsive sidebar collapse	Must	Mobile support
FR-008	The recipe should include breadcrumbs	Should	Navigation context
FR-009	The recipe must ship with stories	Must	Visual reference
FR-010	The recipe must ship with tests	Must	Quality gate

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	Sidebar renders navigation sections from a typed configuration array	Declarative navigation definition	Must
FUNC-002	Each nav item shows an icon, label, and optional badge (e.g., unread count)	Clear visual hierarchy	Must
FUNC-003	Nested nav items expand/collapse on parent click	Organized deep navigation	Must
FUNC-004	Active nav item is highlighted based on the current route	Wayfinding	Must
FUNC-005	`AuthGuard` checks auth state on mount and redirects to `/login` if unauthenticated	Route protection	Must
FUNC-006	`AuthGuard` shows a loading state while checking auth	Prevents flash of wrong content	Must
FUNC-007	`NotificationCenter` shows unread count badge in the header	Quick notification visibility	Must
FUNC-008	`NotificationCenter` dropdown lists recent notifications with timestamp and dismiss action	Notification management	Must
FUNC-009	`UserMenu` shows avatar, name, and dropdown with profile, settings, and logout	Account management	Must
FUNC-010	On mobile (below breakpoint), sidebar collapses to a hamburger toggle	Responsive layout	Must
FUNC-011	Breadcrumbs show the current route hierarchy below the header	Navigation context	Should
FUNC-012	`GlobalSearchBar` in the header opens with Cmd+K / Ctrl+K keyboard shortcut	Quick search access	Must

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Recipe code must be copy-pasteable and self-contained	Maintainability	Must
NFR-002	All recipe code must pass TypeScript strict mode	Correctness	Must
NFR-003	Stories must render in light and dark themes	Compatibility	Must
NFR-004	Auth guard must not flash protected content before redirect	Security	Must
NFR-005	Sidebar collapse/expand must not cause layout shift in the content area	Performance	Must
NFR-006	Navigation configuration must support at least 3 levels of nesting	Flexibility	Should

API / Interface Requirements

Public API

This is a recipe, not a published package. No new public API is exported from the design system.

Name	Type	Description	Required
Recipe folder	`source`	`src/recipes/admin-shell/` with components, config types, and services	Yes
Recipe MDX	`documentation`	Storybook MDX page documenting the scaffold	Yes
Recipe stories	`stories`	Storybook stories showing all shell states	Yes
Recipe tests	`tests`	Vitest tests for auth guard and navigation	Yes

Example Usage

import { AdminShell } from "./admin-shell";
import type { AdminNavConfig } from "./admin-shell";

const navigation: AdminNavConfig = [
  {
    label: "Dashboard",
    icon: "LayoutDashboard",
    path: "/",
  },
  {
    label: "Users",
    icon: "Users",
    path: "/users",
    children: [
      { label: "All Users", path: "/users" },
      { label: "Roles", path: "/users/roles" },
    ],
  },
  {
    label: "Settings",
    icon: "Settings",
    path: "/settings",
  },
];

function App() {
  return (
    <AuthProvider>
      <AdminShell
        navigation={navigation}
        appName="My Admin"
        logoSrc="/logo.svg"
      >
        <Routes />
      </AdminShell>
    </AuthProvider>
  );
}

API Notes

AdminShell accepts navigation, appName, logoSrc, and children.
AdminNavConfig is an array of NavSection objects with optional children for nesting.
Auth and notification services are provided via React context; the recipe ships mock implementations.
The recipe is router-agnostic; active state detection uses window.location.pathname by default with an override prop.

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Sidebar navigation must use `<nav>` with `aria-label="Main navigation"`	Landmark for screen readers
A11Y-002	Expandable nav sections must use `aria-expanded`	Screen readers announce collapse state
A11Y-003	Active nav item must use `aria-current="page"`	Screen readers announce current page
A11Y-004	Hamburger toggle must have `aria-label="Toggle navigation"` and `aria-expanded`	Mobile accessibility
A11Y-005	Notification center dropdown must be keyboard-navigable	Arrow keys, Enter, Escape
A11Y-006	User menu dropdown must be keyboard-navigable	Arrow keys, Enter, Escape
A11Y-007	Skip-to-content link must be provided	Keyboard users can skip navigation
A11Y-008	Focus must move to content area after navigation selection on mobile	Sidebar closes and focus moves to content

Checklist

Keyboard support is defined.
Focus behavior is defined.
Screen reader behavior is defined.
Color contrast requirements are met.
Reduced motion behavior is considered.
Semantic HTML expectations are documented.
ARIA usage is defined only where needed.

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Recipe MDX page with shell composition guide	Storybook MDX	Must
DOC-002	Navigation configuration guide	Storybook MDX	Must
DOC-003	Auth guard integration guide	Storybook MDX	Must
DOC-004	”How to customize” section for replacing mock services	Storybook MDX	Must
DOC-005	Responsive behavior notes	Storybook MDX	Must
DOC-006	Accessibility notes for admin navigation	Storybook MDX	Must

Documentation Should Include

Overview of the admin shell pattern
When to use this recipe
Prerequisites (which components to install)
Navigation configuration
Auth guard setup
Notification integration
Global search integration
User menu customization
Responsive behavior
Breadcrumb configuration
Accessibility notes
Common mistakes

Dependencies

Dependency	Type	Owner	Status	Notes
`saas-sidebar-layout.tsx`	Design System	David Holmes	Ready	Existing layout component
`screen-shell.tsx`	Design System	David Holmes	Ready	Existing shell component
`global-search-bar.tsx`	Design System	David Holmes	Ready	Existing search component
React 18+	Engineering	David Holmes	Ready	Peer dependency
Vitest	Engineering	David Holmes	Ready	Test runner
Icon library	Design System	David Holmes	Ready	For nav icons

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Recipe is router-agnostic but most apps use a specific router	Developers must adapt active-state detection	Default uses `pathname`; document override pattern for TanStack Router
Mock auth service may not reflect real auth complexity	Developers may underestimate auth integration effort	Document the mock as a starting point; link to auth-flows recipe (#80) for complete auth patterns
Large recipe may be overwhelming for simple admin apps	Some developers may not need all features	Document which sections are optional; structure code so features can be removed independently
No RBAC means all authenticated users see all navigation	Insufficient for multi-role applications	Document RBAC as a consumer responsibility; show where permission checks would be added

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the recipe include a dark mode toggle in the header?	David Holmes	Open	—
Q-002	Should the recipe include a settings page scaffold or just the shell?	David Holmes	Open	—
Q-003	Should navigation support external links (opening in new tab) alongside internal routes?	David Holmes	Open	—
Q-004	Should the recipe include a help/support button pattern?	David Holmes	Open	—

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Admin shell composes `SaasSidebarLayout` and `ScreenShell`	FR-001
AC-002	Sidebar renders navigation from a typed configuration array	FUNC-001
AC-003	Active nav item is highlighted based on current route	FUNC-004
AC-004	Nested nav items expand/collapse	FUNC-003
AC-005	Auth guard redirects unauthenticated users without flashing protected content	FUNC-005, NFR-004
AC-006	Notification center shows unread count and lists notifications	FUNC-007, FUNC-008
AC-007	Global search activates with Cmd+K / Ctrl+K	FUNC-012
AC-008	Sidebar collapses on mobile with hamburger toggle	FUNC-010
AC-009	Stories demonstrate authenticated, unauthenticated, and various navigation states	FR-009
AC-010	Unit tests pass covering auth guard, navigation rendering, and responsive behavior	FR-010
AC-011	All recipe code passes TypeScript strict mode	NFR-002
AC-012	Recipe MDX renders in Storybook without errors	DOC-001

LLM Handoff Instructions

Expected LLM Behavior

Follow the requirements and acceptance criteria in this document.
Do not expand scope beyond the In Scope section.
Respect the Out of Scope section.
Use existing design system components (SaasSidebarLayout, ScreenShell, GlobalSearchBar); do not rebuild them.
Navigation must be configuration-driven, not hardcoded.
Auth guard must show a loading state, not flash protected content.
Mock services must be clearly separated from shell components so consumers can replace them.
Use design system tokens for all styling.
Place the recipe in src/recipes/admin-shell/.

LLM Should Not

Invent undocumented product behavior.
Implement real authentication or notification backends.
Add new dependencies without justification.
Change existing design system components.
Hardcode navigation items.
Implement RBAC or permissions.
Use inline styles instead of design system tokens.

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Recipe, not a published component	Admin shells vary too much across products for a one-size-fits-all component	David Holmes
2026-05-26	Configuration-driven navigation	Declarative nav is easier to maintain and test than imperative JSX trees	David Holmes
2026-05-26	Router-agnostic with pathname default	Avoids coupling the recipe to a specific router; most routers can provide pathname	David Holmes
2026-05-26	Mock services via React context	Clean separation enables easy replacement in consumer applications	David Holmes

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft