4.6 KiB
Frontend UX Specification
Design principles
- Confidence-first — show health, spam rate, and on-track status prominently
- Progressive disclosure — simple defaults; expert options collapsed
- Safe defaults — Grow, 30 days, 30% reply, max 40/day pre-selected
- 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.
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.