Design Shell

# Design Shell

You are helping the user design the application shell — the persistent navigation and layout that wraps all sections. This is a screen design, not implementation code.

**IMPORTANT: This project uses SolidJS, NOT React.** Key differences:
- Use `class` instead of `className` for CSS classes
- Use SolidJS primitives: `createSignal`, `Show`, `For`, `createMemo`, etc.
- Import from `solid-js` not `react`
- Use `lucide-solid` for icons, not `lucide-react`
- **CRITICAL: Always use optional chaining when accessing props** (e.g., `props?.children`, `props?.navigationItems ?? []`) because props may be undefined when components are dynamically loaded by Design OS

## Step 1: Check Prerequisites

First, verify prerequisites exist:

1. Read `/product/product-overview.md` — Product name and description
2. Read `/product/product-roadmap.md` — Sections for navigation
3. Check if `/product/design-system/colors.json` and `/product/design-system/typography.json` exist

If overview or roadmap are missing:

"Before designing the shell, you need to define your product and sections. Please run:
1. `/product-vision` — Define your product
2. `/product-roadmap` — Define your sections"

Stop here if overview or roadmap are missing.

If design tokens are missing, show a warning but continue:

"Note: Design tokens haven't been defined yet. I'll proceed with default styling, but you may want to run `/design-tokens` first for consistent colors and typography."

## Step 2: Analyze Product Structure

Review the roadmap sections and present navigation options:

"I'm designing the shell for **[Product Name]**. Based on your roadmap, you have [N] sections:

1. **[Section 1]** — [Description]
2. **[Section 2]** — [Description]
3. **[Section 3]** — [Description]

Let's decide on the shell layout. Common patterns:

**A. Sidebar Navigation** — Vertical nav on the left, content on the right
   Best for: Apps with many sections, dashboard-style tools, admin panels

**B. Top Navigation** — Horizontal nav at top, content below
   Best for: Simpler apps, marketing-style products, fewer sections

**C. Minimal Header** — Just logo + user menu, sections accessed differently
   Best for: Single-purpose tools, wizard-style flows

Which pattern fits **[Product Name]** best?"

Wait for their response.

## Step 3: Gather Design Details

Use AskUserQuestion to clarify:

- "Where should the user menu (avatar, logout) appear?"
- "Do you want the sidebar collapsible on mobile, or should it become a hamburger menu?"
- "Any additional items in the navigation? (Settings, Help, etc.)"
- "What should the 'home' or default view be when the app loads?"

## Step 4: Present Shell Specification

Once you understand their preferences:

"Here's the shell design for **[Product Name]**:

**Layout Pattern:** [Sidebar/Top Nav/Minimal]

**Navigation Structure:**
- [Nav Item 1] → [Section]
- [Nav Item 2] → [Section]
- [Nav Item 3] → [Section]
- [Additional items like Settings, Help]

**User Menu:**
- Location: [Top right / Bottom of sidebar]
- Contents: Avatar, user name, logout

**Responsive Behavior:**
- Desktop: [How it looks]
- Mobile: [How it adapts]

Does this match what you had in mind?"

Iterate until approved.

## Step 5: Create the Shell Specification

Create `/product/shell/spec.md`:

```markdown
# Application Shell Specification

## Overview
[Description of the shell design and its purpose]

## Navigation Structure
- [Nav Item 1] → [Section 1]
- [Nav Item 2] → [Section 2]
- [Nav Item 3] → [Section 3]
- [Any additional nav items]

## User Menu
[Description of user menu location and contents]

## Layout Pattern
[Description of the layout — sidebar, top nav, etc.]

## Responsive Behavior
- **Desktop:** [Behavior]
- **Tablet:** [Behavior]
- **Mobile:** [Behavior]

## Design Notes
[Any additional design decisions or notes]

Step 6: Create Shell Components

Create the shell components at src/shell/components/:

AppShell.tsx

The main wrapper component that accepts children and provides the layout structure. MUST be a default export.

import { Show, type JSX } from 'solid-js'

export interface AppShellProps {
  children?: JSX.Element
  navigationItems: Array<{ label: string; href: string; isActive?: boolean }>
  user?: { name: string; avatarUrl?: string }
  onNavigate?: (href: string) => void
  onLogout?: () => void
}

export default function AppShell(props: AppShellProps) {
  // CRITICAL: Use optional chaining on all props accesses
  return (
    <div class="min-h-screen">
      <MainNav items={props?.navigationItems ?? []} onNavigate={props?.onNavigate} />
      <Show when={props?.user}>
        <UserMenu user={props?.user!} onLogout={props?.onLogout} />
      </Show>
      <main>{props?.children}</main>
    </div>
  )
}

ShellWrapper.tsx (REQUIRED)

This component is required for Design OS to wrap screen designs inside the shell. It provides default navigation and user data so screen designs can be previewed in context.

import { type JSX } from 'solid-js'
import AppShell from './AppShell'

export interface ShellWrapperProps {
  children?: JSX.Element
}

const defaultNavigationItems = [
  { label: 'Dashboard', href: '/dashboard' },
  { label: 'Section 1', href: '/section-1', isActive: true },
  // ... add all navigation items from spec
]

const defaultUser = {
  name: 'Demo User',
  email: 'demo@example.com',
}

export default function ShellWrapper(props: ShellWrapperProps) {
  return (
    <AppShell
      navigationItems={defaultNavigationItems}
      user={defaultUser}
      onNavigate={(href) => console.log('Navigate to:', href)}
      onLogout={() => console.log('Logout clicked')}
    >
      {props?.children}
    </AppShell>
  )
}

MainNav.tsx

The navigation component (sidebar or top nav based on the chosen pattern).

UserMenu.tsx

The user menu with avatar and dropdown.

index.ts

Export all components:

export { default as AppShell, type AppShellProps } from './AppShe