# Design Phase Transition: AI Images → HTML Components

**Status:** Prototype  
**Author:** ARIA  
**Requested by:** Jeff  
**Date:** 2025-02-19  

---

## Executive Summary

Transition the Design phase from generating AI images (Leonardo, DALL-E) to generating live HTML/CSS components. This eliminates the interpretation gap between design mockups and implementation, enabling faster iteration and direct code handoff to the Build phase.

---

## Current State vs Future State

| Aspect | Current (AI Images) | Future (HTML Components) |
|--------|---------------------|--------------------------|
| Output | PNG/JPG mockups | Live HTML + Tailwind CSS |
| Iteration | Regenerate entire image | Edit code or prompt for changes |
| Handoff | Developer interprets mockup | Code is the deliverable |
| Consistency | Manual brand application | Programmatic design tokens |
| Preview | Static image | Interactive live preview |
| Version control | Binary files | Text diffs |

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                        Symphony UI                               │
├─────────────────────────────────────────────────────────────────┤
│  Design Phase                                                    │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │ Prompt Input │───▶│ AI Generator │───▶│ Live Preview Panel │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
│         │                  │                      │              │
│         ▼                  ▼                      ▼              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │ Brand Context│    │ Component   │    │ Iteration History  │ │
│  │ (tokens)     │    │ Storage     │    │                     │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

---

## Phase 1: Component Generation (MVP)

### 1.1 Scope

- Prompt-based HTML/CSS generation
- Live preview rendering
- Component library (starting set)
- Basic composition into layouts
- Storage as design artifacts

### 1.2 Component Library (Starting Set)

| Category | Components |
|----------|------------|
| **Navigation** | Header, Navbar, Sidebar, Breadcrumbs, Footer |
| **Hero** | Hero Section, CTA Banner, Announcement Bar |
| **Content** | Card, Feature Grid, Testimonial, Stats, Timeline |
| **Forms** | Input, Button, Select, Checkbox, Form Group, Search |
| **Layout** | Container, Grid, Section, Divider |
| **Feedback** | Alert, Toast, Modal, Badge, Progress |
| **Data Display** | Table, List, Avatar, Tooltip |

### 1.3 Tech Stack

| Layer | Technology | Rationale |
|-------|------------|-----------|
| Generation | Claude API (claude-sonnet-4-20250514) | Best code generation quality |
| Styling | Tailwind CSS | Utility-first, consistent, readable |
| Components | shadcn/ui patterns | Matches our Build phase stack |
| Preview | iframe sandbox | Isolation, security, live reload |
| Storage | File system (product artifacts) | Git-trackable, simple |

### 1.4 Generation Pipeline

```
User Prompt
     │
     ▼
┌─────────────────────────────────────┐
│ Prompt Enhancement                   │
│ - Add brand context (colors, fonts)  │
│ - Add component constraints          │
│ - Add Tailwind/shadcn instructions   │
└─────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────┐
│ AI Generation (Claude)               │
│ - System prompt with design rules    │
│ - User prompt with context           │
│ - Output: HTML + Tailwind classes    │
└─────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────┐
│ Post-processing                      │
│ - Validate HTML structure            │
│ - Inject Tailwind CDN                │
│ - Wrap in preview container          │
└─────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────┐
│ Preview Rendering                    │
│ - Render in sandboxed iframe         │
│ - Display to user                    │
└─────────────────────────────────────┘
```

### 1.5 System Prompt for Generation

```
You are a UI component generator. Generate clean, semantic HTML with Tailwind CSS classes.

Rules:
1. Use Tailwind CSS utility classes only (no custom CSS)
2. Follow shadcn/ui patterns and conventions
3. Make components responsive (mobile-first)
4. Use semantic HTML elements
5. Include hover/focus states where appropriate
6. Use the provided brand colors and fonts
7. Output ONLY the HTML - no explanations, no markdown

Brand Context:
{brand_tokens}

Component Type: {component_type}
User Request: {user_prompt}
```

### 1.6 Data Model

```typescript
interface DesignComponent {
  id: string;
  productSlug: string;
  name: string;
  type: ComponentType;
  prompt: string;
  html: string;
  version: number;
  createdAt: Date;
  updatedAt: Date;
  iterations: DesignIteration[];
}

interface DesignIteration {
  id: string;
  prompt: string;
  html: string;
  timestamp: Date;
}

interface DesignLayout {
  id: string;
  productSlug: string;
  name: string;
  components: LayoutComponent[];
  createdAt: Date;
}

interface LayoutComponent {
  componentId: string;
  order: number;
  customizations?: Record<string, string>;
}

type ComponentType = 
  | 'navigation'
  | 'hero'
  | 'content'
  | 'form'
  | 'layout'
  | 'feedback'
  | 'data-display';
```

### 1.7 Storage Structure

```
/home/aria/products/{slug}/
├── design/
│   ├── components/
│   │   ├── header-v1.html
│   │   ├── hero-v1.html
│   │   ├── pricing-cards-v1.html
│   │   └── ...
│   ├── layouts/
│   │   ├── landing-page.json    # Component composition
│   │   └── dashboard.json
│   ├── tokens/
│   │   └── brand.json           # Colors, fonts, spacing
│   └── manifest.json            # Index of all design artifacts
```

### 1.8 API Endpoints

```typescript
// Generate a new component
POST /api/design/generate
Body: { productSlug, componentType, prompt, brandTokens? }
Response: { componentId, html, preview_url }

// Iterate on existing component
POST /api/design/iterate
Body: { componentId, prompt }
Response: { html, version, preview_url }

// Get component
GET /api/design/components/{id}
Response: { component, iterations }

// List components for product
GET /api/design/components?product={slug}
Response: { components[] }

// Create layout from components
POST /api/design/layouts
Body: { productSlug, name, componentIds[] }
Response: { layoutId, preview_url }

// Export layout as full HTML
GET /api/design/layouts/{id}/export
Response: { html }
```

---

## Phase 2: Figma Integration (Future)

### 2.1 Scope

- Export HTML components to Figma
- Import Figma designs as HTML
- Sync design tokens between systems
- Collaborative design workflow

### 2.2 Integration Points

```
Symphony HTML Components ◄──────► Figma
         │                           │
         ├── Export to Figma ────────┤
         │   (html-to-figma plugin)  │
         │                           │
         ├── Import from Figma ──────┤
         │   (figma-to-html API)     │
         │                           │
         └── Token Sync ─────────────┘
             (design tokens JSON)
```

### 2.3 Why Phase 2?

- Phase 1 validates the core concept
- Figma integration adds complexity
- Need to establish component patterns first
- Token sync requires stable design system

---

## User Flow

### Creating a Component

```
1. User navigates to Design phase for a product
2. Selects "New Component" 
3. Chooses component type (optional - can be inferred)
4. Enters natural language prompt:
   "A hero section with a gradient background, 
    large headline, subtext, and two CTA buttons"
5. System generates HTML with brand tokens applied
6. Live preview renders in panel
7. User can:
   - Approve → Component saved
   - Iterate → "Make the gradient more subtle"
   - Discard → Start over
```

### Composing a Layout

```
1. User selects "New Layout"
2. Sees component library for this product
3. Drags/arranges components:
   - Header
   - Hero
   - Features Grid
   - Testimonials
   - CTA Section
   - Footer
4. Preview shows full page
5. Can adjust spacing/order
6. Save layout → Ready for Build phase handoff
```

---

## Symphony UI Integration

### New UI Elements Required

1. **Component Type Selector** - Dropdown/chips for component categories
2. **Prompt Input** - Textarea with brand context indicator
3. **Preview Panel** - Sandboxed iframe with refresh/zoom controls
4. **Iteration History** - Sidebar showing prompt→result pairs
5. **Component Library** - Grid view of saved components
6. **Layout Composer** - Drag-and-drop canvas for page composition

### Design Phase Mode Toggle

```
Design Phase
├── [Image Mode] - Existing AI image generation
└── [HTML Mode]  - New component generation (default for new products)
```

---

## Implementation Checklist

### Backend

- [ ] Create `/api/design/generate` endpoint
- [ ] Create `/api/design/iterate` endpoint
- [ ] Create `/api/design/components` CRUD endpoints
- [ ] Create `/api/design/layouts` CRUD endpoints
- [ ] Implement component storage in product folders
- [ ] Add brand token loading from product config
- [ ] Set up Claude API integration for generation

### Frontend

- [ ] Add HTML Design mode to Design phase
- [ ] Build prompt input component
- [ ] Build live preview iframe component
- [ ] Build iteration history sidebar
- [ ] Build component library grid
- [ ] Build layout composer (drag-and-drop)
- [ ] Add component type selector

### System Prompts

- [ ] Create base system prompt for generation
- [ ] Create component-specific prompt templates
- [ ] Create iteration prompt template
- [ ] Test and tune prompt quality

### Testing

- [ ] Test generation quality across component types
- [ ] Test iteration coherence (changes build on previous)
- [ ] Test brand token application
- [ ] Test preview rendering edge cases
- [ ] Load test generation endpoint

---

## Success Metrics

| Metric | Target |
|--------|--------|
| Generation quality (human rating) | >4/5 average |
| Iteration coherence | Changes apply correctly >90% |
| Time to first component | <30 seconds |
| Components used in Build phase | >50% reuse rate |
| Design phase completion time | -30% vs image mode |

---

## Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| AI generates inconsistent styles | Medium | Strong system prompt + brand tokens |
| Complex components fail | High | Decompose into smaller parts |
| Preview security (XSS) | High | Sandboxed iframe, CSP headers |
| Token costs spike | Medium | Cache common patterns, rate limit |
| Users expect pixel-perfect | Medium | Set expectations, iteration flow |

---

## Open Questions

1. **Offline capability?** - Can we cache Tailwind for offline preview?
2. **Export formats?** - Besides HTML, do we need React/Vue export?
3. **Template library?** - Pre-built components users can start from?
4. **Collaboration?** - Multiple users editing same layout?

---

## Appendix: Example Generation

### Input

```
Component type: Pricing
Prompt: A pricing card with 3 tiers: Basic, Pro, Enterprise. 
        Dark theme, rounded corners, highlight the Pro tier.
Brand: { primary: "violet-500", background: "#0f0f0f" }
```

### Output

```html
<div class="grid md:grid-cols-3 gap-6">
  <!-- Basic -->
  <div class="bg-[#1a1a1a] rounded-2xl p-8 border border-gray-800">
    <h3 class="text-lg font-semibold text-gray-300">Basic</h3>
    <div class="text-4xl font-bold text-white">$9<span class="text-gray-500 text-base">/mo</span></div>
    <!-- ... -->
  </div>
  
  <!-- Pro (Highlighted) -->
  <div class="bg-[#1a1a1a] rounded-2xl p-8 border-2 border-violet-500 scale-105 shadow-lg shadow-violet-500/20">
    <span class="bg-violet-500 text-white text-xs px-3 py-1 rounded-full">POPULAR</span>
    <!-- ... -->
  </div>
  
  <!-- Enterprise -->
  <div class="bg-[#1a1a1a] rounded-2xl p-8 border border-gray-800">
    <!-- ... -->
  </div>
</div>
```

---

## Next Steps

1. **Validate** - Review this guide, confirm scope
2. **Prototype** - Build minimal generate + preview flow
3. **Test** - Generate 10-20 components, assess quality
4. **Iterate** - Tune prompts based on results
5. **Integrate** - Add to Symphony Design phase
6. **Launch** - Enable for new products first
