Design Agent

A multi-stage AI design partner that takes a product idea from concept through shipped React UI.

Quick Start

cd src/

# Create a new project
python orchestrator.py new "My Product" /path/to/project

# Check project status at any time
python orchestrator.py status /path/to/project

Stage 1: Discovery

The discovery agent is a system prompt that turns Claude into an opinionated design strategist.

# Get the system prompt (paste into any Claude interface)
python -c "from discovery import DISCOVERY_SYSTEM_PROMPT; print(DISCOVERY_SYSTEM_PROMPT)"

# After the conversation, save artifacts
python orchestrator.py save-brief /path/to/project '{"product_name": "...", ...}'
python orchestrator.py save-features /path/to/project '{"features": [...], ...}'
python orchestrator.py save-flow /path/to/project '{"flow_name": "...", ...}'

# Or save all at once from files
python orchestrator.py synthesize /path/to/project brief.json features.json flow1.json

Stage 2: Information Architecture

The IA agent reads the approved brief and proposes screen structures as element maps.

# Initialize Stage 2 — shows screens extracted from flows
python orchestrator.py ia-start /path/to/project

# Get the IA agent system prompt (includes full brief context)
python -c "from ia import get_full_prompt; print(get_full_prompt('/path/to/project'))"

# Save approved screen IA (desktop + mobile element maps)
python orchestrator.py ia-save-screen-file /path/to/project home home_desktop.json home_mobile.json reflow

# Archive rejected variants for reference
python orchestrator.py ia-reject /path/to/project home "variant_b" '{"elements": [...]}' "Too dense"

# Save the sitemap and responsive strategy
python orchestrator.py ia-save-sitemap /path/to/project '{"screens": {...}, "edges": [...]}'
python orchestrator.py ia-save-responsive /path/to/project '{"breakpoints": {...}, ...}'

# Verify all screens approved and advance to Stage 3
python orchestrator.py ia-complete /path/to/project

Stage 3: Style Direction

The style agent generates 3-4 distinct visual directions as complete token sets with preview components.

# Initialize Stage 3
python orchestrator.py style-start /path/to/project

# Get the style agent system prompt (includes brief + IA context)
python -c "from style import get_full_prompt; print(get_full_prompt('/path/to/project'))"

# Save candidate token sets generated during the conversation
python orchestrator.py style-save-candidate-file /path/to/project "Warm & Grounded" tokens_warm.json

# Select the final direction (generates tailwind.config.js automatically)
python orchestrator.py style-select-file /path/to/project "Warm & Grounded" tokens_warm.json

# Save preview components
python orchestrator.py style-save-preview /path/to/project "Warm & Grounded" preview_warm.jsx

# Advance to Stage 4
python orchestrator.py style-complete /path/to/project

Project Structure

project/
├── project.json              # Project manifest and stage tracking
├── brief/                    # Stage 1 outputs
├── architecture/             # Stage 2 outputs (screen IAs, sitemap)
├── tokens/                   # Stage 3 outputs (design tokens, previews)
├── components/               # Stage 4 outputs (React components by feature)
│   └── {feature}/
├── pages/                    # Stage 5 outputs (assembled pages)
│   └── {page}/
│       └── components/       # Page-specific components (pre-promotion)
└── changelog/                # Decision log

Stages

Stage	Mode	Agent Role	Key Output
1. Discovery	Interactive	Design strategist	Brief, features, flows
2. Information Architecture	Interactive + variants	UX architect	Screen maps (desktop + mobile)
3. Style Direction	Highly interactive	Visual designer	Token set, Tailwind config
4. Component Generation	Medium interactive	UI designer	React component library
5. Page Assembly	Mostly autonomous	Production designer	Complete pages

Evaluation Pipeline

The project includes tooling from the visual preprocessing experiments:

• Two-pass element extraction: Claude identifies UI elements, renders blocked structural views
• Adversarial evaluation: 8 defect categories tested against generated output
• Automated critique: Spacing, alignment, hierarchy, grouping, consistency, touch targets, contrast, balance

See experiment1/ and experiment3/ for the evaluation tooling.

Stage 4: Component Generation

The component agent generates React + Tailwind variants within the approved token set.

# Initialize Stage 4
python orchestrator.py comp-start /path/to/project

# Get the component agent system prompt
python -c "from components import get_full_prompt; print(get_full_prompt('/path/to/project'))"

# Save approved components (code file + registry entry)
python orchestrator.py comp-save /path/to/project RecipeCard home RecipeCard.jsx '{"id": "recipe_card", "type": "card", ...}'

# View the component registry
python orchestrator.py comp-registry /path/to/project

# Promote a component to shared when used by 2+ pages
python orchestrator.py comp-promote /path/to/project navbar_standard navigation

# Advance to Stage 5
python orchestrator.py comp-complete /path/to/project

Stage 5: Page Assembly

The assembly agent composes approved components into full pages.

# Initialize Stage 5
python orchestrator.py page-start /path/to/project

# Get the assembly agent system prompt
python -c "from assembly import get_full_prompt; print(get_full_prompt('/path/to/project'))"

# Save assembled pages
python orchestrator.py page-save /path/to/project home Home.jsx

# Save a revision (archives the previous version)
python orchestrator.py page-revise /path/to/project home Home.jsx "Increased hero section height"

# Mark project complete
python orchestrator.py page-complete /path/to/project