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.

## 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/design-system.json` exists

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 system is missing, show a warning but continue:

"Note: Design system hasn'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 1b: Check for Brand Identity in Design System

Check if `product/design-system/design-system.json` exists and contains personality, voice, or uiStyle fields.

If these optional brand identity fields exist, use them to inform design decisions:

**Brand Personality** — Use adjectives and mood to suggest appropriate layout patterns:
- Professional/trustworthy → Clean sidebar with clear hierarchy
- Playful/energetic → Bold colors, rounded elements, animated transitions
- Minimal/refined → Subtle navigation, lots of whitespace
- Technical/precise → Dense information, structured layout

**Brand Voice** — Apply tone to navigation labels and UI copy suggestions:
- Friendly tone → "Your Dashboard", "Let's create something"
- Professional tone → "Dashboard", "New Project"
- Technical tone → "System Overview", "Initialize"

**UI Style Preferences** — Apply to component styling:
- Border radius preference for buttons and cards
- Shadow intensity for elevated elements
- Spacing/density for layout

When presenting shell options, reference the brand guide:

"Based on your brand guide, your product has a [personality adjectives] feel with [UI style preferences]. This suggests:
- [Layout pattern recommendation]
- [Navigation style recommendation]
- [Visual treatment recommendation]"

## 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

Ask clarifying questions:
- "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.

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

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.

Component Requirements:

• Use props for all data and callbacks (portable)
• Apply design tokens if they exist (colors, fonts)
• Support light and dark mode with dark: variants
• Be mobile responsive
• Use Tailwind CSS for styling
• Use lucide-react for icons

Step 7: Create Shell Preview

Create src/shell/ShellPreview.tsx — a preview wrapper for viewing the shell in Design OS:

import data from '@/../product/sections/[first-section]/data.json' // if exists
import { AppShell } from './components/AppShell'

export default function ShellPreview() {
  const navigationItems = [
    { label: '[Section 1]', href: '/section-1', isActive: true },
    { label: '[Section 2]', href: '/section-2' },
    { label: '[Section 3]', href: '/section-3' },
  ]