project-root/
├── product/ # Product definition (portable)
├── src/ # Screen design components
└── product-plan/ # Export package (generated)
```plaintext
## The `product/` Directory
This directory contains all your product planning files. These files are **portable**—they define your product independently of any code.
```plaintext
product/
├── product-overview.md # Product description, problems/solutions, features
├── product-roadmap.md # List of sections with titles and descriptions
│
├── data-shape/ # Product data shape
│ └── data-shape.md # Entity names, descriptions, and relationships
│
├── design-system/ # Design tokens
│ ├── colors.json # { primary, secondary, neutral }
│ └── typography.json # { heading, body, mono }
│
├── shell/ # Application shell
│ └── spec.md # Shell specification
│
└── sections/
└── [section-name]/
├── spec.md # Section specification
├── data.json # Sample data for screen designs
├── types.ts # TypeScript interfaces
└── *.png # Screenshots
```plaintext
### Key Files in `product/`
<Steps>
<Step title="Product Overview">
`product/product-overview.md`
Defines your product's core identity:
- Product name and description
- Problems you're solving
- Key features
- Target users
Generated by `/product-vision`
</Step>
<Step title="Product Roadmap">
`product/product-roadmap.md`
Lists all sections (feature areas) in your product. Each section has:
- Section ID (URL-friendly identifier)
- Title
- Description
Generated by `/product-vision`, updated with `/product-roadmap`
</Step>
<Step title="Data Shape">
`product/data-shape/data-shape.md`
Defines the core entities (nouns) in your system:
- Entity names
- Descriptions
- Conceptual relationships
This creates shared vocabulary for consistent naming across sections.
Generated by `/product-vision`, updated with `/data-shape`
</Step>
<Step title="Design Tokens">
`product/design-system/colors.json` and `typography.json`
Your design system tokens:
- **Colors:** Primary, secondary, and neutral palettes from Tailwind
- **Typography:** Heading, body, and mono fonts from Google Fonts
Generated by `/design-tokens`
</Step>
<Step title="Shell Specification">
`product/shell/spec.md`
Defines your application shell:
- Navigation structure
- User menu content
- Layout pattern
Generated by `/design-shell`
</Step>
<Step title="Section Files">
`product/sections/[section-name]/`
Each section contains:
- **spec.md** — Requirements, user flows, scope
- **data.json** — Sample data for screen designs
- **types.ts** — TypeScript interfaces
- **screenshots** — PNG files of finished designs
Generated by `/shape-section`, `/design-screen`, and `/screenshot-design`
</Step>
</Steps>
## The `src/` Directory
This directory contains all React components for your screen designs. These components use your design tokens and sample data to create realistic previews.
```plaintext
src/
├── shell/ # Shell design components
│ ├── components/
│ │ ├── AppShell.tsx
│ │ ├── MainNav.tsx
│ │ ├── UserMenu.tsx
│ │ └── index.ts
│ └── ShellPreview.tsx
│
└── sections/
└── [section-name]/
├── components/ # Exportable components
│ ├── [Component].tsx
│ └── index.ts
└── [ViewName].tsx # Preview wrapper
```plaintext
### Component Organization
<Accordion title="Shell Components">
`src/shell/components/`
Contains the persistent navigation and layout:
- **AppShell.tsx** — Main layout wrapper
- **MainNav.tsx** — Primary navigation
- **UserMenu.tsx** — User account menu
- **index.ts** — Exports all shell components
**ShellPreview.tsx** wraps these components for preview in Design OS.
</Accordion>
<Accordion title="Section Components">
`src/sections/[section-name]/components/`
Contains exportable components for each section:
- Each component is a separate `.tsx` file
- Components are props-based and accept data via props
- **index.ts** exports all components
The **[ViewName].tsx** file wraps these components with sample data for preview.
</Accordion>
<Info>
Components in `src/` are designed to be **exported and integrated** into your actual product codebase. They're production-ready and follow React best practices.
</Info>
## The `product-plan/` Directory
This directory is generated when you run `/export-product`. It contains your complete handoff package for implementation.
```plaintext
product-plan/ # Export package (generated)
├── README.md # Quick start guide
├── product-overview.md # Product summary
├── prompts/ # Ready-to-use prompts for coding agents
│ ├── one-shot-prompt.md # Prompt for full implementation
│ └── section-prompt.md # Prompt template for incremental
├── instructions/ # Implementation instructions
│ ├── one-shot-instructions.md # All milestones combined
│ └── incremental/ # Milestone-by-milestone instructions
│ ├── 01-shell.md
│ └── [NN]-[section-id].md # Section-specific instructions
├── design-system/ # Tokens, colors, fonts
├── data-shapes/ # UI data contracts (types components expect)
├── shell/ # Shell components
└── sections/ # Section components (with tests.md each)
```plaintext
### What's in the Export
<Steps>
<Step title="Ready-to-Use Prompts">
`prompts/`
Pre-written prompts to copy/paste into your coding agent:
- **one-shot-prompt.md** — Implement the entire product in one session
- **section-prompt.md** — Template for implementing one section at a time
These prompts include all context your agent needs to build correctly.
</Step>
<Step title="Implementation Instructions">
`instructions/`
Step-by-step guides for building your product:
- **one-shot-instructions.md** — All milestones in one document
- **incremental/** — Separate markdown file for each milestone (shell, then each section)
Each section includes a `tests.md` file with UI behavior specs.
</Step>
<Step title="Design System">
`design-system/`
Your design tokens, color palettes, and typography choices. Ready to integrate into your actual codebase.
</Step>
<Step title="Data Shapes">
`data-shapes/`
TypeScript interfaces defining what data your components expect. These serve as the contract between your frontend and backend.
</Step>
<Step title="Components">
`shell/` and `sections/`
All your React components, organized by shell and section. Each component is:
- Props-based and accepts data via props
- Production-ready
- Documented with inline comments
- Includes test specifications
</Step>
</Steps>
<Note>
The `product-plan/` directory is **generated**—don't edit files here directly. Make changes in `product/` or `src/` and re-run `/export-product`.
</Note>
## File Naming Conventions
### Section Names
Section directories use **kebab-case** (lowercase with hyphens):
- `user-dashboard`
- `project-list`
- `account-settings`
### Component Files
Component files use **PascalCase**:
- `ProjectCard.tsx`
- `UserProfile.tsx`
- `SettingsForm.tsx`
### Specification Files
Specification files use **lowercase with hyphens**:
- `spec.md`
- `data.json`
- `types.ts`
## Working with the Structure
### When to Edit `product/`
Edit files in `product/` when you need to:
- Update your product overview or roadmap
- Modify data shape definitions
- Change design tokens
- Adjust section specifications
- Update sample data or types
### When to Edit `src/`
Edit files in `src/` when you need to:
- Refine component designs
- Adjust component props or interfaces
- Fix styling or layout issues
- Add new components to a section
### When to Regenerate `product-plan/`
Run `/export-product` to regenerate the export package after:
- Making significant changes to components
- Adding or removing sections
- Updating design tokens
- Changing data shapes or types
- Completing all sections and preparing for handoff
<Info>
The export is designed to be regenerated multiple times as your design evolves. Don't worry about overwriting previous exports.
</Info>
## Next Steps
<CardGroup cols={2}>
<Card title="Product Planning" icon="compass" href="/planning/product-vision">
Start building your first product
</Card>
<Card title="Design System" icon="palette" href="/planning/design-system">
Learn how to set up design tokens
</Card>
</CardGroup>