144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
# 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.
|