@vadimcomanescu/nadicode-design-system 2.0.0

package/.agents/skills/seed/recipes/navigation-shell.md

@@ -0,0 +1,786 @@
+# Recipe: Navigation Shell
+
+Shared app navigation frame with sidebar, top bar, Cmd+K search, breadcrumbs, and user menu.
+
+## Purpose
+
+The navigation shell wraps all app-shell pages. It is not a page itself but the persistent frame around page content. This recipe defines the complete app shell layout with working wiring for every navigation subsystem.
+
+## Shell
+
+`app-shell` (this IS the shell definition)
+
+---
+
+## Layout Blueprint (Desktop)
+
+```
++--+----------------------------------------------+
+|  |  [=]  Home > Settings    [Cmd+K] [🔔] [User] |
+|S |                                                |
+|I |  +------------------------------------------+  |
+|D |  |                                          |  |
+|E |  |  Page Content                            |  |
+|B |  |  (filled by child route)                 |  |
+|A |  |                                          |  |
+|R |  |                                          |  |
+|  |  +------------------------------------------+  |
++--+----------------------------------------------+
+
+Sidebar (expanded):
++------------------+
+| [v] Acme Inc     |    <-- Workspace switcher (DropdownMenu)
++------------------+
+| Group: Main      |
+|   Dashboard      |
+|   Analytics      |
+|   Agents         |
++------------------+
+| Group: Manage    |
+|   Team           |
+|   Settings       |
++------------------+
+| [Avatar] Jane    |    <-- NavUser (DropdownMenu)
++------------------+
+
+Mobile: Sidebar hidden, hamburger in top bar opens Sheet overlay
+```
+
+---
+
+## Section Sequence
+
+### 1. App Shell Layout (the file)
+
+This is your app route group layout (e.g. src/app/(app)/layout.tsx). It composes every subsystem.
+
+```tsx
+'use client'
+
+import { usePathname } from 'next/navigation'
+import {
+  Sidebar,
+  SidebarProvider,
+  SidebarTrigger,
+  SidebarInset,
+  SidebarHeader,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarMenuSub,
+  SidebarMenuSubItem,
+  SidebarMenuSubButton,
+} from '@vadimcomanescu/nadicode-design-system/sidebar'
+import { NavUser } from '@vadimcomanescu/nadicode-design-system/nav-user'
+import { AppBreadcrumb } from '@vadimcomanescu/nadicode-design-system/app-breadcrumb'
+import { AppSearch } from '@vadimcomanescu/nadicode-design-system/app-search'
+import { WorkspaceSwitcher } from '@vadimcomanescu/nadicode-design-system/workspace-switcher'
+import { ThemeToggle } from '@vadimcomanescu/nadicode-design-system/theme-toggle'
+import { Button } from '@vadimcomanescu/nadicode-design-system/button'
+import { BellIcon } from '@vadimcomanescu/nadicode-design-system/icons/bell'
+import { DashboardIcon } from '@vadimcomanescu/nadicode-design-system/icons/dashboard'
+import { ChartBarIcon } from '@vadimcomanescu/nadicode-design-system/icons/chart-bar'
+import { BotIcon } from '@vadimcomanescu/nadicode-design-system/icons/bot'
+import { UsersIcon } from '@vadimcomanescu/nadicode-design-system/icons/users'
+import { SettingsIcon } from '@vadimcomanescu/nadicode-design-system/icons/settings'
+
+const NAV_ITEMS = [
+  {
+    group: 'Main',
+    items: [
+      { label: 'Dashboard', href: '/dashboard', icon: DashboardIcon },
+      { label: 'Analytics', href: '/analytics', icon: ChartBarIcon },
+      {
+        label: 'Agents',
+        href: '/agents',
+        icon: BotIcon,
+        children: [
+          { label: 'Active', href: '/agents/active' },
+          { label: 'History', href: '/agents/history' },
+        ],
+      },
+    ],
+  },
+  {
+    group: 'Manage',
+    items: [
+      { label: 'Team', href: '/team', icon: UsersIcon },
+      { label: 'Settings', href: '/settings', icon: SettingsIcon },
+    ],
+  },
+]
+
+export default function AppShellLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const pathname = usePathname()
+
+  return (
+    <SidebarProvider>
+      <Sidebar>
+        <SidebarHeader>
+          <WorkspaceSwitcher />
+        </SidebarHeader>
+
+        <SidebarContent>
+          {NAV_ITEMS.map((group) => (
+            <SidebarGroup key={group.group}>
+              <SidebarGroupLabel>{group.group}</SidebarGroupLabel>
+              <SidebarMenu>
+                {group.items.map((item) => (
+                  <SidebarMenuItem key={item.href}>
+                    <SidebarMenuButton
+                      asChild
+                      isActive={pathname === item.href || pathname.startsWith(item.href + '/')}
+                      tooltip={item.label}
+                    >
+                      <a href={item.href}>
+                        <item.icon size={16} />
+                        {item.label}
+                      </a>
+                    </SidebarMenuButton>
+
+                    {item.children && (
+                      <SidebarMenuSub>
+                        {item.children.map((child) => (
+                          <SidebarMenuSubItem key={child.href}>
+                            <SidebarMenuSubButton
+                              asChild
+                              isActive={pathname === child.href}
+                            >
+                              <a href={child.href}>{child.label}</a>
+                            </SidebarMenuSubButton>
+                          </SidebarMenuSubItem>
+                        ))}
+                      </SidebarMenuSub>
+                    )}
+                  </SidebarMenuItem>
+                ))}
+              </SidebarMenu>
+            </SidebarGroup>
+          ))}
+        </SidebarContent>
+
+        <SidebarFooter>
+          <NavUser
+            user={{ name: 'Jane Smith', email: 'jane@acme.com', avatar: '/avatars/jane.jpg' }}
+            items={[
+              { label: 'Profile', href: '/settings/profile' },
+              { label: 'Billing', href: '/settings/billing' },
+              { label: 'Sign out', onClick: handleSignOut },
+            ]}
+          />
+        </SidebarFooter>
+      </Sidebar>
+
+      <SidebarInset>
+        <header className="flex items-center gap-3 px-4 py-3 border-b border-border">
+          <SidebarTrigger />
+          <AppBreadcrumb />
+          <div className="ml-auto flex items-center gap-2">
+            <AppSearch />
+            <Button variant="ghost" size="icon" className="relative">
+              <BellIcon size={16} />
+              <span className="absolute -top-0.5 -right-0.5 size-2 rounded-full bg-destructive" />
+            </Button>
+            <ThemeToggle />
+          </div>
+        </header>
+
+        <div className="flex-1 p-4 lg:p-6">
+          {children}
+        </div>
+      </SidebarInset>
+    </SidebarProvider>
+  )
+}
+```
+
+---
+
+### 2. Breadcrumb Generation
+
+The breadcrumb builds itself from the current pathname and a route config map. This is a reusable block, not inline logic.
+
+**Consumer file: src/components/blocks/AppBreadcrumb.tsx**
+
+```tsx
+'use client'
+
+import { usePathname } from 'next/navigation'
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+} from '@vadimcomanescu/nadicode-design-system/breadcrumb'
+import { Fragment } from 'react'
+
+// Map route segments to display labels.
+// Dynamic segments use a placeholder; the caller can resolve them.
+const ROUTE_LABELS: Record<string, string> = {
+  dashboard: 'Dashboard',
+  analytics: 'Analytics',
+  agents: 'Agents',
+  active: 'Active',
+  history: 'History',
+  team: 'Team',
+  settings: 'Settings',
+  profile: 'Profile',
+  billing: 'Billing',
+  security: 'Security',
+}
+
+// Max visible crumbs before collapsing middle segments.
+const MAX_VISIBLE = 4
+
+export function AppBreadcrumb() {
+  const pathname = usePathname()
+  const segments = pathname.split('/').filter(Boolean)
+
+  if (segments.length === 0) return null
+
+  // Build crumb list: [{label, href}]
+  const crumbs = segments.map((segment, i) => ({
+    label: ROUTE_LABELS[segment] ?? decodeURIComponent(segment),
+    href: '/' + segments.slice(0, i + 1).join('/'),
+  }))
+
+  // Collapse if too many crumbs
+  const shouldCollapse = crumbs.length > MAX_VISIBLE
+  const visible = shouldCollapse
+    ? [crumbs[0], ...crumbs.slice(-2)]
+    : crumbs
+
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        {visible.map((crumb, i) => (
+          <Fragment key={crumb.href}>
+            {i > 0 && <BreadcrumbSeparator />}
+            {shouldCollapse && i === 1 && (
+              <>
+                <BreadcrumbItem>
+                  <BreadcrumbEllipsis />
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+              </>
+            )}
+            <BreadcrumbItem>
+              {i === visible.length - 1 ? (
+                <BreadcrumbPage>{crumb.label}</BreadcrumbPage>
+              ) : (
+                <BreadcrumbLink href={crumb.href}>{crumb.label}</BreadcrumbLink>
+              )}
+            </BreadcrumbItem>
+          </Fragment>
+        ))}
+      </BreadcrumbList>
+    </Breadcrumb>
+  )
+}
+```
+
+**Dynamic segments** (e.g., `/agents/[id]`): extend `ROUTE_LABELS` with a resolver function, or pass a `resolveLabel` prop that fetches the entity name from a cache.
+
+---
+
+### 3. SearchCommand (Cmd+K) Wiring
+
+The search palette needs three things: route items, action items, and a router integration. Wrap it in a Dialog triggered by Cmd+K.
+
+**Consumer file: src/components/blocks/AppSearch.tsx**
+
+```tsx
+'use client'
+
+import { useCallback, useMemo, useState } from 'react'
+import { useRouter } from 'next/navigation'
+import { Dialog, DialogContent } from '@vadimcomanescu/nadicode-design-system/dialog'
+import { SearchCommand, SearchResult } from '@vadimcomanescu/nadicode-design-system/search-command'
+import { Button } from '@vadimcomanescu/nadicode-design-system/button'
+import { SearchIcon } from '@vadimcomanescu/nadicode-design-system/icons/search'
+import { useHotkey } from '@/hooks/useHotkey'
+
+// Route items: all navigable pages in the app.
+const PAGE_ITEMS: SearchResult[] = [
+  { id: 'dashboard',  title: 'Dashboard',  category: 'Pages', description: 'Overview and KPIs' },
+  { id: 'analytics',  title: 'Analytics',  category: 'Pages', description: 'Charts and trends' },
+  { id: 'agents',     title: 'Agents',     category: 'Pages', description: 'AI agent management' },
+  { id: 'team',       title: 'Team',       category: 'Pages', description: 'Team members' },
+  { id: 'settings',   title: 'Settings',   category: 'Pages', description: 'App configuration' },
+]
+
+// Action items: commands that do something (not navigation).
+const ACTION_ITEMS: SearchResult[] = [
+  { id: 'new-agent',   title: 'Create Agent',    category: 'Actions' },
+  { id: 'invite-user', title: 'Invite Team Member', category: 'Actions' },
+  { id: 'toggle-theme', title: 'Toggle Theme',   category: 'Actions' },
+]
+
+// Combine all items into a single searchable list.
+const ALL_ITEMS = [...PAGE_ITEMS, ...ACTION_ITEMS]
+
+// Map item IDs to routes (pages) or callbacks (actions).
+const ROUTE_MAP: Record<string, string> = {
+  dashboard: '/dashboard',
+  analytics: '/analytics',
+  agents: '/agents',
+  team: '/team',
+  settings: '/settings',
+}
+
+export function AppSearch() {
+  const [open, setOpen] = useState(false)
+  const [query, setQuery] = useState('')
+  const router = useRouter()
+
+  // Cmd+K to open
+  useHotkey('mod+k', (e) => {
+    e.preventDefault()
+    setOpen(true)
+  })
+
+  // Filter results by query
+  const results = useMemo(() => {
+    if (!query) return ALL_ITEMS
+    const q = query.toLowerCase()
+    return ALL_ITEMS.filter(
+      (item) =>
+        item.title.toLowerCase().includes(q) ||
+        item.description?.toLowerCase().includes(q),
+    )
+  }, [query])
+
+  const handleSelect = useCallback(
+    (result: SearchResult) => {
+      setOpen(false)
+      setQuery('')
+
+      const route = ROUTE_MAP[result.id]
+      if (route) {
+        router.push(route)
+        return
+      }
+
+      // Handle action items
+      switch (result.id) {
+        case 'toggle-theme':
+          document.documentElement.classList.toggle('dark')
+          break
+        case 'new-agent':
+          router.push('/agents/new')
+          break
+        case 'invite-user':
+          router.push('/team?invite=true')
+          break
+      }
+    },
+    [router],
+  )
+
+  return (
+    <>
+      <Button
+        variant="ghost"
+        size="sm"
+        className="gap-2 text-text-secondary"
+        onClick={() => setOpen(true)}
+      >
+        <SearchIcon size={16} />
+        <span className="hidden sm:inline">Search...</span>
+        <kbd className="hidden sm:inline text-xs bg-surface-raised px-1.5 py-0.5 rounded border border-border">
+          ⌘K
+        </kbd>
+      </Button>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent className="p-0 max-w-lg">
+          <SearchCommand
+            value={query}
+            onChange={setQuery}
+            results={results}
+            onSelect={handleSelect}
+            placeholder="Search pages and actions..."
+          />
+        </DialogContent>
+      </Dialog>
+    </>
+  )
+}
+```
+
+**Extending with recent items**: store last 5 selected IDs in `localStorage`, prepend them as a "Recent" category on mount.
+
+---
+
+### 4. NavUser Wiring
+
+NavUser sits in the sidebar footer. It needs auth data and menu items.
+
+```tsx
+// In the layout, wire NavUser to your auth context:
+
+import { useAuth } from '@/hooks/useAuth'  // your auth hook
+
+function AppShellSidebarFooter() {
+  const { user, signOut } = useAuth()
+
+  if (!user) return null
+
+  return (
+    <SidebarFooter>
+      <NavUser
+        user={{
+          name: user.name,
+          email: user.email,
+          avatar: user.avatarUrl,
+        }}
+        items={[
+          { label: 'Profile', href: '/settings/profile' },
+          { label: 'Billing', href: '/settings/billing' },
+        ]}
+        footer={
+          <button
+            onClick={signOut}
+            className="w-full text-left px-2 py-1.5 text-sm text-text-secondary hover:text-text-primary"
+          >
+            Sign out
+          </button>
+        }
+      />
+    </SidebarFooter>
+  )
+}
+```
+
+NavUser renders a `DropdownMenu` with the user's avatar and name as trigger. On mobile, the dropdown opens upward (`side="top"`). On desktop, it opens right (`side="right"`).
+
+---
+
+### 5. Mobile Sidebar (Sheet Overlay)
+
+The Sidebar component handles mobile automatically. No extra code needed, but you need to understand the behavior:
+
+```
+MOBILE BEHAVIOR
+===============
+
+Trigger:     SidebarTrigger (hamburger icon in top bar)
+Container:   Sheet overlay (slides from left, 80% viewport width)
+Backdrop:    Semi-transparent overlay, tap to close
+Close:       Tap backdrop, tap X button, or navigate to a new route
+Focus trap:  Yes (keyboard focus stays inside sheet)
+Scroll:      SidebarContent scrolls independently
+Width:       var(--sidebar-width), max 320px
+
+DESKTOP BEHAVIOR
+================
+
+< lg:        Sidebar hidden (mobile mode, Sheet overlay)
+lg:          Sidebar visible, collapsible to icon-only (var(--sidebar-width-icon) = 3rem)
+xl:          Sidebar expanded by default (var(--sidebar-width) = 16rem)
+Collapse:    SidebarTrigger or Cmd+B toggles between expanded and icon-only
+Rail:        SidebarRail provides invisible drag handle on sidebar edge
+Cookie:      Expanded/collapsed state persists via cookie
+```
+
+To close the mobile sidebar on navigation:
+
+```tsx
+// In nav item click handlers or via useEffect:
+const { setOpenMobile } = useSidebar()
+
+// Close mobile sidebar after navigating
+function handleNavClick(href: string) {
+  setOpenMobile(false)
+  router.push(href)
+}
+```
+
+---
+
+### 6. Top Bar Composition
+
+The top bar is a `<header>` inside `SidebarInset`. It contains four zones:
+
+```
++---+------------------+-----------------------------------+
+| = |  Breadcrumb      |  [Search]  [Notifications]  [Theme] |
++---+------------------+-----------------------------------+
+ ^       ^                    ^          ^             ^
+ |       |                    |          |             |
+ Trigger  AppBreadcrumb       AppSearch   NotifButton   ThemeToggle
+```
+
+**Notification button pattern** (badge + dropdown):
+
+```tsx
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@vadimcomanescu/nadicode-design-system/dropdown-menu'
+import { BellIcon } from '@vadimcomanescu/nadicode-design-system/icons/bell'
+import { Button } from '@vadimcomanescu/nadicode-design-system/button'
+import { Badge } from '@vadimcomanescu/nadicode-design-system/badge'
+import { ScrollArea } from '@vadimcomanescu/nadicode-design-system/scroll-area'
+
+function NotificationButton({ notifications }: { notifications: Notification[] }) {
+  const unreadCount = notifications.filter((n) => !n.read).length
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="ghost" size="icon" className="relative">
+          <BellIcon size={16} />
+          {unreadCount > 0 && (
+            <span className="absolute -top-0.5 -right-0.5 size-4 rounded-full bg-destructive text-destructive-foreground text-[10px] flex items-center justify-center">
+              {unreadCount}
+            </span>
+          )}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-80">
+        <div className="px-3 py-2 border-b border-border">
+          <span className="text-sm font-medium">Notifications</span>
+        </div>
+        <ScrollArea className="max-h-64">
+          {notifications.length === 0 ? (
+            <div className="px-3 py-6 text-center text-sm text-text-secondary">
+              No notifications
+            </div>
+          ) : (
+            notifications.map((n) => (
+              <DropdownMenuItem key={n.id} className="flex flex-col items-start gap-1 py-2">
+                <span className="text-sm">{n.title}</span>
+                <span className="text-xs text-text-secondary">{n.timeAgo}</span>
+              </DropdownMenuItem>
+            ))
+          )}
+        </ScrollArea>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+---
+
+### 7. Workspace Switcher
+
+Logo area in sidebar header doubles as a workspace/org switcher.
+
+**Consumer file: src/components/blocks/WorkspaceSwitcher.tsx**
+
+```tsx
+'use client'
+
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+} from '@vadimcomanescu/nadicode-design-system/dropdown-menu'
+import { SidebarMenuButton } from '@vadimcomanescu/nadicode-design-system/sidebar'
+import { ChevronsUpDownIcon } from '@vadimcomanescu/nadicode-design-system/icons/chevrons-up-down'
+import { PlusIcon } from '@vadimcomanescu/nadicode-design-system/icons/plus'
+import { Avatar, AvatarFallback, AvatarImage } from '@vadimcomanescu/nadicode-design-system/avatar'
+
+interface Workspace {
+  id: string
+  name: string
+  logo?: string
+  plan: string
+}
+
+export function WorkspaceSwitcher({
+  workspaces,
+  activeId,
+  onSwitch,
+}: {
+  workspaces: Workspace[]
+  activeId: string
+  onSwitch: (id: string) => void
+}) {
+  const active = workspaces.find((w) => w.id === activeId)
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <SidebarMenuButton size="lg" className="gap-2">
+          <Avatar className="size-6 rounded-md">
+            <AvatarImage src={active?.logo} />
+            <AvatarFallback className="rounded-md text-xs">
+              {active?.name.slice(0, 2).toUpperCase()}
+            </AvatarFallback>
+          </Avatar>
+          <div className="flex-1 text-left">
+            <span className="text-sm font-medium truncate">{active?.name}</span>
+            <span className="text-xs text-text-secondary block">{active?.plan}</span>
+          </div>
+          <ChevronsUpDownIcon size={14} className="text-text-secondary" />
+        </SidebarMenuButton>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" className="w-56">
+        {workspaces.map((ws) => (
+          <DropdownMenuItem
+            key={ws.id}
+            onClick={() => onSwitch(ws.id)}
+            className={ws.id === activeId ? 'bg-sidebar-accent' : ''}
+          >
+            <Avatar className="size-5 rounded-md mr-2">
+              <AvatarImage src={ws.logo} />
+              <AvatarFallback className="rounded-md text-[10px]">
+                {ws.name.slice(0, 2).toUpperCase()}
+              </AvatarFallback>
+            </Avatar>
+            {ws.name}
+          </DropdownMenuItem>
+        ))}
+        <DropdownMenuSeparator />
+        <DropdownMenuItem>
+          <PlusIcon size={14} className="mr-2" />
+          Create workspace
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+---
+
+## Navigation Rules
+
+1. **Max 3 levels**: Group > Item > Sub-item. No deeper nesting.
+2. **Group labels required**: Every `SidebarGroup` must have `SidebarGroupLabel` (ESLint enforced).
+3. **Active state**: Use `isActive` prop on `SidebarMenuButton`. Match with `pathname === href || pathname.startsWith(href + '/')`.
+4. **Icons required**: Every top-level nav item has an icon from `@vadimcomanescu/nadicode-design-system/icons/`.
+5. **Max 7 top-level items**: Keep primary nav focused. Use groups to organize.
+6. **Labels from config**: Nav labels come from the `NAV_ITEMS` config array, not hardcoded in JSX.
+7. **Close on navigate (mobile)**: Call `setOpenMobile(false)` before `router.push()`.
+8. **Breadcrumb on every page**: Every app-shell page must show breadcrumb context in the top bar.
+
+---
+
+## Animation Storyboard
+
+```
+ANIMATION STORYBOARD
+====================
+BUDGET: 200ms | SPRING: snappy | REDUCED: none (shell is instant)
+
+T+0ms     [sidebar]   Sidebar visible                (instant)
+T+0ms     [topbar]    Top bar visible                 (instant)
+T+0ms     [content]   Page content area visible       (instant)
+
+SIDEBAR COLLAPSE/EXPAND:
+T+0ms     [sidebar]   Width transitions               {CSS ease-in-out-cubic, 200ms}
+T+0ms     [labels]    Text fades out (collapse)        {opacity, 100ms}
+T+100ms   [icons]     Icons center-align               {CSS ease-out, 100ms}
+
+MOBILE SIDEBAR OPEN:
+T+0ms     [backdrop]  Backdrop fades in                {opacity 0->1, 150ms}
+T+0ms     [sheet]     Sidebar slides from left         {translateX(-100% -> 0), snappy spring}
+
+CMD+K OPEN:
+T+0ms     [overlay]   Backdrop fades in               {fadeIn, 150ms}
+T+0ms     [dialog]    Command palette scales in        {scaleIn 0.95->1, snappy}
+
+REDUCED MOTION: All transitions instant
+```
+
+---
+
+## Required Components
+
+| Component | Import Path | Purpose |
+|-----------|-------------|---------|
+| `Sidebar` (full system) | `@vadimcomanescu/nadicode-design-system/sidebar` | App sidebar with all subcomponents |
+| `NavUser` | `@vadimcomanescu/nadicode-design-system/nav-user` | User menu in sidebar footer |
+| `AppBreadcrumb` | Consumer block (see Section 2) | Route-aware breadcrumb |
+| `AppSearch` | Consumer block (see Section 3) | Cmd+K search palette |
+| `WorkspaceSwitcher` | Consumer block (see Section 7) | Org/workspace picker |
+| `SearchCommand` | `@vadimcomanescu/nadicode-design-system/search-command` | Search UI primitive |
+| `Breadcrumb` (full system) | `@vadimcomanescu/nadicode-design-system/breadcrumb` | Breadcrumb primitives |
+| `Dialog` | `@vadimcomanescu/nadicode-design-system/dialog` | Cmd+K dialog wrapper |
+| `DropdownMenu` | `@vadimcomanescu/nadicode-design-system/dropdown-menu` | Notifications, workspace switcher |
+| `ThemeToggle` | `@vadimcomanescu/nadicode-design-system/theme-toggle` | Light/dark switch |
+| `Button` | `@vadimcomanescu/nadicode-design-system/button` | Top bar actions |
+| `ScrollArea` | `@vadimcomanescu/nadicode-design-system/scroll-area` | Notification dropdown scroll |
+| `Avatar` | `@vadimcomanescu/nadicode-design-system/avatar` | User and workspace avatars |
+
+### Allowed (optional)
+
+`NotificationCenter`, `Badge` (notification count), `StyleToggle`, `Tooltip`, `ContextMenu`, `Menubar`
+
+### Forbidden
+
+Marketing blocks (`HeroBlock`, `FooterBlock`), chart components, form components, agentic components in the shell itself
+
+---
+
+## Responsive Contract
+
+| Breakpoint | Sidebar | Top Bar | Breadcrumb |
+|------------|---------|---------|------------|
+| Mobile | Hidden, Sheet overlay via SidebarTrigger | Always visible, hamburger left | Hidden (not enough space) |
+| `sm:` | Same as mobile | Same | Visible, max 2 crumbs |
+| `lg:` | Collapsible (icon-only or full, Cmd+B) | Visible with all actions | Full breadcrumb trail |
+| `xl:` | Full sidebar (expanded by default) | Same | Same |
+
+---
+
+## Styling Rules
+
+- Sidebar: `bg-sidebar` token (not `bg-background`)
+- Sidebar border: `border-sidebar-border`
+- Active item: `bg-sidebar-accent text-sidebar-accent-foreground`
+- Top bar: `border-b border-border`, same `bg-background` as content
+- Content area: `bg-background`
+- No raw palette colors
+- Sidebar width: `var(--sidebar-width)` (16rem) and `var(--sidebar-width-icon)` (3rem)
+- Workspace switcher: `SidebarMenuButton size="lg"` for consistent sizing
+
+---
+
+## Accessibility
+
+- Sidebar: `<nav aria-label="Main navigation">`
+- Groups: `role="group"` with `aria-labelledby` pointing to group label
+- Active item: `aria-current="page"` (handled by `isActive` prop)
+- SidebarTrigger: `aria-label="Toggle sidebar"`, `aria-expanded`
+- Cmd+K: keyboard-triggered (Cmd/Ctrl+K), focus trapped in dialog
+- Skip-nav link: `<SkipNav />` before sidebar targets `#main-content`
+- Mobile sheet: focus trap, Escape to close, backdrop click to close
+- Notification button: `aria-label="Notifications"`, badge announces count
+- Breadcrumb: `<nav aria-label="breadcrumb">` with `aria-current="page"` on last item
+
+---
+
+## Reference Implementations
+
+- `src/app/(showcase)/layout.tsx` (showcase shell, uses AnimatedTabs instead of Sidebar)
+- `src/components/ui/Sidebar.tsx` (sidebar system)
+- `src/components/blocks/NavUser.tsx` (user menu)
+- `src/components/ui/SearchCommand.tsx` (search primitive)
+- `src/components/ui/Breadcrumb.tsx` (breadcrumb primitives)
+- `src/components/ui/Command.tsx` (cmdk wrapper)
+
+---
+
+## Verification
+
+```bash
+npx tsc --noEmit
+npm run lint
+npm run test
+npx vitest run src/test/opinion-navigation.test.ts
+```