@vadimcomanescu/nadicode-design-system 4.0.1 → 4.0.2

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

@@ -1,787 +0,0 @@
-# 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 { seedComponents } from '@vadimcomanescu/nadicode-design-system/catalog/components'
-const { NavUser } = seedComponents
-import { AppBreadcrumb } from '@/components/blocks/AppBreadcrumb'
-import { AppSearch } from '@/components/blocks/AppSearch'
-import { WorkspaceSwitcher } from '@/components/blocks/WorkspaceSwitcher'
-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 { LayoutDashboardIcon } from '@vadimcomanescu/nadicode-design-system/icons/layout-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: LayoutDashboardIcon },
-      { 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/catalog/components` via `seedComponents` | 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
-```