# Frontend UX Specification

## Design principles

1. **Confidence-first** — show health, spam rate, and on-track status prominently
2. **Progressive disclosure** — simple defaults; expert options collapsed
3. **Safe defaults** — Grow, 30 days, 30% reply, max 40/day pre-selected
4. **Mobile-readable** — dashboard works on tablet; setup flows desktop-first

## Tech recommendation

- **Vite + React + TypeScript**
- **shadcn/ui** + Tailwind
- **TanStack Query** for API state
- **Recharts** for time series

## Information architecture

```
Dashboard (overview)
├── Campaigns
│   ├── [Campaign detail]
│   │   ├── Overview tab
│   │   ├── Activity log tab
│   │   ├── Satellites tab
│   │   └── Settings tab
│   └── New campaign wizard
├── Mailboxes
│   ├── All mailboxes
│   ├── Add primary
│   └── Add satellite
├── Activity (global log)
└── Settings
    ├── AI provider
    ├── Schedule defaults
    └── API keys
```

## Key screens

### 1. Dashboard (home)

**Purpose:** At-a-glance health of all warming primaries.

| Section | Content |
|---------|---------|
| Hero stats | Active campaigns, total sends today, avg inbox rate |
| Campaign cards | One card per primary: day X/Y, sends, spam %, status badge |
| Alerts | Error mailboxes, high spam rate, paused campaigns |
| Quick actions | Add primary, Add satellite, New campaign |

### 2. New campaign wizard (4 steps)

**Step 1 — Primary**  
Select existing primary mailbox or add new.

**Step 2 — Recipe**  
Radio cards: Grow (recommended), Flat, Randomized, Custom.  
Sliders: duration 30–45, min/max sends, reply rate 30%.

**Step 3 — Satellites**  
Multi-select from satellite pool; minimum 2 warning; recommend 4+.

**Step 4 — Review**  
Preview ramp chart; confirm; Start campaign.

### 3. Campaign detail — Overview

| Widget | Data |
|--------|------|
| Progress ring | Day 12/30 |
| Sends today | 15/18 bar |
| Replies today | 5/6 bar |
| Inbox rate 7d | 94% with trend arrow |
| Ramp chart | Planned vs actual line chart |
| Placement | Inbox vs spam stacked bar |

Actions: Pause, Edit settings, Export CSV.

### 4. Campaign detail — Satellites

Table: email, provider, status, last activity, remove button.  
Add satellite dropdown.

### 5. Campaign detail — Activity

Filterable log table (reuse `/api/logs`).

### 6. Add mailbox modal

Tabs: Primary | Satellite  
Fields: email, provider preset (Gmail/Yahoo/Outlook/Custom), SMTP/IMAP auto-fill, app password, industry, test connection button.

Provider presets fill host/port from [05-primary-satellite-topology.md](./05-primary-satellite-topology.md).

### 7. Mailbox detail

Connection status, DNS check results (future), assigned campaigns, error history.

### 8. Settings

- AI: API key, model, test generation button
- Defaults: recipe, duration, reply rate
- Danger zone: reset campaign, delete mailbox

## UX patterns

| Pattern | Use |
|---------|-----|
| Status badges | active=green, paused=yellow, error=red, completed=blue |
| Empty states | Guided CTA to add first primary |
| Loading skeletons | Stats cards |
| Optimistic updates | Pause/resume |
| Toast notifications | Test connection result, save settings |

## Recipe selector UI

```
┌─────────────────────────────────────────┐
│ ● Grow (Recommended)                    │
│   Progressive ramp over 30 days         │
├─────────────────────────────────────────┤
│ ○ Flat                                  │
│   Steady volume every day               │
├─────────────────────────────────────────┤
│ ○ Randomized                            │
│   Variable volume for testing           │
├─────────────────────────────────────────┤
│ ○ Custom                                │
│   Expert day-by-day schedule            │
└─────────────────────────────────────────┘
```

## Accessibility

- WCAG 2.1 AA contrast on charts
- Keyboard navigation for wizards
- Screen reader labels on status badges

## MVP frontend scope (phase 2)

**In scope:** Dashboard, campaign wizard, campaign detail, mailbox CRUD, connection test, activity log.

**Out of scope:** Billing, team members, OAuth connect, mobile app.