Application Shell

interface AppShellProps {
  children: React.ReactNode
  navigationItems: Array<{
    label: string
    href: string
    icon?: React.ReactNode
    isActive?: boolean
  }>
  user?: {
    name: string
    email?: string
    avatarUrl?: string
  }
  onNavigate?: (href: string) => void
  onLogout?: () => void
}
```plaintext

### MainNav.tsx

The navigation component (sidebar or top nav based on pattern):

- Renders navigation items
- Handles active states
- Responsive behavior (mobile menu)
- Icon support from lucide-react

### UserMenu.tsx

The user menu with avatar and dropdown:

- User avatar (initials fallback if no image)
- User name and email
- Logout option
- Optional profile/settings links

## Example Shell Specification

```markdown product/shell/spec.md
# Application Shell Specification

## Overview
Sidebar navigation layout with persistent left-side nav and user menu at the bottom.

## Navigation Structure
- Dashboard → Dashboard section
- Projects → Projects section
- Tasks → Tasks section
- Team → Team section
- Settings → Settings section

## User Menu
Located at the bottom of the sidebar. Displays user avatar, name, and opens a dropdown with:
- Profile
- Account Settings
- Logout

## Layout Pattern
Sidebar navigation with fixed 256px width on desktop. Collapsible to icon-only mode. Content area takes remaining space.

## Responsive Behavior
- **Desktop (1024px+):** Full sidebar visible, can toggle to collapsed icon-only mode
- **Tablet (768px-1023px):** Collapsed by default, expands on hover or click
- **Mobile (<768px):** Hidden by default, accessible via hamburger menu button

## Design Notes
- Use primary color for active nav items
- Icons from lucide-react for all nav items
- Smooth transitions for sidebar collapse/expand
- Light and dark mode support
```plaintext

## Design Token Application

The shell automatically applies your design tokens:

### Colors

- **Primary color** - Active nav items, key accents
- **Secondary color** - Hover states, subtle highlights
- **Neutral color** - Backgrounds, borders, text

### Typography

- **Heading font** - Nav item labels, section titles
- **Body font** - User name, other text

### Example Usage

```tsx
// Active nav item uses primary color
<button className="bg-blue-600 text-white dark:bg-blue-500">
  Dashboard
</button>

// Hover state uses secondary color
<button className="hover:bg-slate-100 dark:hover:bg-slate-800">
  Projects
</button>

// Background uses neutral color
<nav className="bg-slate-50 dark:bg-slate-900 border-r border-slate-200 dark:border-slate-800">
  {/* navigation items */}
</nav>
```plaintext

## Mobile Responsiveness

The shell is fully responsive:

### Sidebar Pattern on Mobile

- Sidebar hidden by default
- Hamburger menu button in top left
- Sidebar slides in as overlay when opened
- Backdrop dismisses menu

### Top Nav Pattern on Mobile

- Logo remains visible
- Nav items collapse into hamburger menu
- User menu remains in top right

## Example ShellPreview.tsx

The preview wrapper shows the shell in Design OS:

```tsx src/shell/ShellPreview.tsx
import { AppShell } from './components/AppShell'
import { Home, FolderKanban, CheckSquare, Users, Settings } from 'lucide-react'

export default function ShellPreview() {
  const navigationItems = [
    { label: 'Dashboard', href: '/dashboard', icon: <Home className="w-5 h-5" />, isActive: true },
    { label: 'Projects', href: '/projects', icon: <FolderKanban className="w-5 h-5" /> },
    { label: 'Tasks', href: '/tasks', icon: <CheckSquare className="w-5 h-5" /> },
    { label: 'Team', href: '/team', icon: <Users className="w-5 h-5" /> },
    { label: 'Settings', href: '/settings', icon: <Settings className="w-5 h-5" /> },
  ]

  const user = {
    name: 'Alex Morgan',
    email: '[email protected]',
    avatarUrl: undefined,
  }

  return (
    <AppShell
      navigationItems={navigationItems}
      user={user}
      onNavigate={(href) => console.log('Navigate to:', href)}
      onLogout={() => console.log('Logout')}
    >
      <div className="p-8">
        <h1 className="text-2xl font-bold mb-4">Content Area</h1>
        <p className="text-slate-600 dark:text-slate-400">
          Section content will render here.
        </p>
      </div>
    </AppShell>
  )
}
```plaintext

<Info>
The preview wrapper is for Design OS only. The exportable components (`AppShell`, `MainNav`, `UserMenu`) are props-based and can be integrated into any React application.
</Info>

## Dark Mode Support

All shell components support light and dark modes:

```tsx
// Backgrounds adapt to theme
<div className="bg-white dark:bg-slate-900">

// Text adjusts for contrast
<span className="text-slate-900 dark:text-slate-100">

// Borders remain subtle
<div className="border border-slate-200 dark:border-slate-800">
```plaintext

Use Tailwind's `dark:` variants throughout to ensure the shell looks great in both modes.

## What About Authentication?

The shell does NOT include authentication UI (login forms, signup flows, password reset, etc.). It assumes the user is already authenticated.

Authentication screens are separate from the shell and are typically designed as standalone sections or handled by your implementation's auth provider.

## Icons

Use [lucide-react](https://lucide.dev) for all icons:

```tsx
import { Home, Settings, User, LogOut } from 'lucide-react'

<Home className="w-5 h-5" />
<Settings className="w-5 h-5" />
```plaintext

Lucide provides a comprehensive icon set that matches modern design aesthetics and works well at different sizes.

## Important Notes

<Warning>
**Restart your dev server** after the shell is created. New components need to be picked up by the build system.
</Warning>

### Shell vs. Section Screens

- **Shell** - Global navigation and layout
- **Section screens** - Content that renders inside the shell

When you design section screens with `/design-screen`, they render as children of the shell, showing the complete application experience.

### Props-Based Architecture

All shell components accept data and callbacks via props:

- No direct data imports in exportable components
- Navigation handled via `onNavigate` callback
- User actions handled via callback props
- Easy to integrate with any routing solution

### Styling Requirements

- Use Tailwind CSS utility classes only
- Support light and dark mode with `dark:` variants
- Mobile responsive with `sm:`, `md:`, `lg:` breakpoints
- No custom CSS or styled-components

## Next Steps

With your application shell designed:

1. Run `/shape-section` to define specifications for your first section
2. Run `/design-screen` to create screen designs that render inside the shell
3. Section designs will automatically wrap in the shell to show the full app experience