For React web apps, design a simple shell. For quant tools using Streamlit/Dash, skip this step entirely — those frameworks handle navigation with st.sidebar or similar.

Red Flags

The Flow

1. Check Prerequisites

First, verify prerequisites exist:

1. Read [project]/product-overview.md — Product name and description
2. Read [project]/roadmap.md — Sections for navigation

If overview or roadmap are missing:

"Before designing the shell, we need to define your product and sections. Let me help you with that."

Then proceed directly to the define flow.

2. Ask About Approach

"I'm preparing to design the shell for [Product Name].

Quick question: Is this a web app (React) or a quant tool (Streamlit/Dash)?

For Streamlit/Dash, you can skip the shell design — those frameworks handle navigation with built-in patterns like st.sidebar.

For React web apps, I'll help you design the navigation structure."

3. Analyze Product Structure

If they're building a React web app:

"Based on your roadmap, you have [N] sections:

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

Common shell patterns:

A. Sidebar Navigation — Vertical nav on the left Best for: Apps with many sections, dashboards

B. Top Navigation — Horizontal nav at top Best for: Simpler apps, fewer sections

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

Which pattern fits [Product Name]?"

4. Gather Design Details

Ask clarifying questions one at a time:

• "Where should the user menu (avatar, logout) appear?"
• "Do you want the nav collapsible on mobile?"
• "Any additional items? (Settings, Help, etc.)"
• "What should the default view be when the app loads?"

5. Present Shell Specification

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

Layout Pattern: [Sidebar/Top Nav/Minimal]

Navigation:

• [Nav Item 1] → [Section]
• [Nav Item 2] → [Section]
• [Nav Item 3] → [Section]

User Menu: [Location and contents]

Mobile: [How it adapts]

Does this match what you had in mind?"

Iterate until approved.

6. Create the Shell Specification

Create [project]/design/shell.md:

# Application Shell Specification

## Overview
[Description of the shell design]

## Navigation Structure
- [Nav Item 1] → [Section 1]
- [Nav Item 2] → [Section 2]
- [Nav Item 3] → [Section 3]

## User Menu
[Location and contents]

## Layout Pattern
[Sidebar, top nav, etc.]

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

7. 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:

• Props-based (portable)
• Apply design tokens if they exist
• Support light and dark mode with dark: variants
• Mobile responsive
• Use Tailwind CSS
• Use lucide-react for icons

8. Create Shell Preview

Create src/shell/ShellPreview.tsx for viewing the shell in DRIVER.

9. Suggest Next Step

Once the shell is created, proactively suggest moving forward:

"I've designed the application shell for [Product Name]:

Created files:

• [project]/design/shell.md — Shell specification
• src/shell/components/ — Shell components

Features:

• [Layout pattern] layout
• Navigation for all [N] sections
• User menu
• Mobile responsive

Important: Restart your dev server to see the shell.

Now let's work on the sections. Which section would you like to tackle first?

[List sections from roadmap]

I can help you define what it needs to do, or jump straight into building it."

If they choose, proceed directly to that work.

Proactive Flow

As a Cognition Mate:

• Suggest skipping for quant tools — Streamlit/Dash handle navigation
• Recommend the simplest pattern that fits
• Suggest next steps after shell is created
• If they agree, continue directly — don't say "run /command"

Guiding Principles

• KISS — Simple navigation, don't over-engineer
• Skip for quant tools — Streamlit/Dash handle this
• Props-based — Components are portable
• Trust their judgment — They know their users