Inboxintel/docs/discovery/04-ux-redesign-and-design-system.md

# 04 — UX/UI Redesign, Information Architecture & Design System (Phase 4A)

A **complete redesign**, not an iterative tweak. Nothing about the current layout is
assumed to survive. Governed by the [Design Brief](00-design-brief.md): Notion/Arc-
professional, pointer-first & discoverable, balanced density, dark-first, green
`#3ba31f`, subtle motion, fully responsive, mainstream-friendly.

---

## Part A — UX Research (per-screen evaluation)
Evaluating the *jobs*, not the current pixels. For each screen: **goal · is it intuitive
· what's unnecessary · how to simplify · click reduction · what must be obvious · sources
of cognitive overload.**

| Screen | User goal | Redesign verdict |
|--------|-----------|------------------|
| **Dashboard (current draggable widgets)** | Understand my inbox | Becomes the **Analytics** view, not the home. A draggable widget grid is *configuration overhead* most users never want. Default = a curated overview; customisation is progressive. |
| **Inbox/list** | Triage what matters | Reframe from "all mail newest-first" to **lanes** (Needs you · Awaiting reply · Everything). Obvious: who/subject/one-line intent/time. Overload source: undifferentiated noise → fix with grouping + priority. |
| **Reading a message** | Understand + act | Add a **thread summary** header, **extracted actions/dates**, and inline reply. Reduce clicks: reply/snooze/label as one-key or one-click from the pane. |
| **Search** | Find a specific thing | **Promote to the front door.** Today it's an operator box; redesign to inviting, visual, assisted (see [05](05-search-redesign.md)). |
| **Cleanup / unsubscribe** | Reduce noise safely | Strong bones (confirm+preview). Make it **suggestion-led** ("cut these 12 newsletters?") with confidence + undo. |
| **Settings** | Configure incl. AI | Add a clear **AI panel**: off / local (Ollama) / provider, model status, VRAM. AI-off must feel first-class, not degraded. |

**Cross-cutting UX principles:** search-as-home · lanes over one big list · explain every
decision · progressive disclosure of power · confidence/undo everywhere · one primary
action per screen.

---

## Part B — Information Architecture

### Navigation shell (responsive 3-pane → 1-pane)
```
┌───────────────────────────────────────────────────────────────┐
│  TopBar:  [ 🔍  Search your inbox…            ⌘K ]   ☾  ⚙  👤  │
├──────────┬──────────────────────────┬─────────────────────────┤
│ Sidebar  │  List / Results          │  Reading / Preview      │
│ (collaps)│  (virtualised)           │  (thread + AI summary)  │
│          │                          │                         │
│ Search   │  ▸ Needs you (lane)      │  Subject                │
│ Priority │  ▸ Awaiting reply        │  ⟶ AI summary (local)   │
│ Unread   │  ▸ Everything            │  ⟶ extracted actions    │
│ Saved ★  │                          │  body …                 │
│ Categories                          │  [Reply] [Snooze] […]   │
│ Cleanup  │                          │                         │
│ Analytics│                          │                         │
│ ─────────│                          │                         │
│ 👤 acct  │                          │                         │
└──────────┴──────────────────────────┴─────────────────────────┘
```
- **Search sits at the top of everything** (top bar) *and* as the first sidebar item — reinforcing search-as-home.
- **Responsive collapse:** 3-pane (wide desktop) → 2-pane (list+reading, laptop) → 1-pane with push navigation (tablet/mobile). Reading opens as an overlay sheet on mobile.
- **Progressive disclosure:** advanced filters, operators, saved-search management, and automation are revealed on demand — never in a beginner's face.
- **Command palette (⌘K / Ctrl+K):** an *accelerator* — navigate, act, and search — layered on top of the fully clickable UI (pointer-first per brief).
- **Right-click context menus** on rows/senders/threads (archive, label, unsubscribe, "find similar," "everything from this sender").
- **Multi-window / dockable panels:** deferred (web app); pop-out reading view is a v-later opportunity.

### Screen hierarchy
1. **Search-home** (front door) · 2. **List/Results** (lanes, ranked) · 3. **Reading/thread**
· 4. **Cleanup** · 5. **Analytics** · 6. **Settings (incl. AI)**.

---

## Part C — Design System

### Colour — accent ramp (from `#3ba31f`)
```
green-50  #f890? →  use tint set:
--green-50:  #f1f9ec   --green-300: #93d07d   --green-600: #2f8419
--green-100: #dcf0d0   --green-400: #63b84a   --green-700: #266a15
--green-200: #bde3ab   --green-500: #3ba31f   --green-800: #1e5312
                        (brand base)          --green-900: #163a0e
```
**Usage rules (dark-first):**
- Brand/base = `green-500`. On dark surfaces, interactive fills use `green-500`/`green-400`; **foreground on accent is contrast-checked** (near-black `#0f1a0b` on light greens, white on `green-600`+).
- Accent is used **sparingly** — primary actions, selection, active nav, positive status.
- **Never colour-only:** selection also shows a left-bar/checkbox; status pairs green with an icon/label (colour-blind-safe by construction, even though formal a11y is deferred).

### Colour — neutrals (warm-leaning)
| Token | Dark (default) | Light |
|-------|----------------|-------|
| `--bg` | `#1a1917` (warm charcoal, **not** pure black) | `#ffffff` (genuine white) |
| `--surface-1` | `#211f1d` | `#faf9f7` |
| `--surface-2` | `#2a2724` | `#f4f2ee` |
| `--surface-3` | `#34302c` | `#ebe8e2` |
| `--border` | `#3a3632` | `#e4e0d9` |
| `--text` | `#f2efe9` (warm off-white) | `#1c1a17` |
| `--text-muted` | `#a8a29a` | `#6b6459` |
| `--text-subtle` | `#7a746c` | `#928b7e` |
| semantic | `info #4a90d9 · warn #d9a441 · danger #d95a4a · success = green-500` | same, contrast-tuned |

### Typography
- **UI font:** Inter (or system fallback) — clean, neutral, highly legible.
- **Optional mono:** JetBrains Mono / ui-monospace for addresses, IDs, data.
- **Scale (px / line-height), UI base = 14 for balanced density:**
  `xs 12/16 · sm 13/18 · base 14/20 · md 16/24 · lg 18/26 · xl 20/28 · 2xl 24/32 · 3xl 30/38`
- Weights: 400 body · 500 UI/labels · 600 headings/emphasis. Avoid 700 except brand.

### Spacing (4px base) & layout
`space: 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64`.
Grid: 12-col fluid content area; sidebar fixed (240px, collapsible to 56px icon rail);
reading pane min 420px. Density "balanced" → row height ~44px, 8–12px internal padding.

### Radius / elevation / motion
- **Radius:** `sm 4 · md 6 (buttons/inputs) · lg 8 (cards/panels, default) · xl 12 (modals) · pill 999`.
- **Elevation:** dark = surface-layering + faint shadow + 1px border; light = soft shadows
  `e1 0 1 2 /6% · e2 0 4 12 /10% · e3 0 12 32 /16%`. Levels: e0 flat · e1 menus · e2 popovers · e3 modals.
- **Motion:** durations `120 / 180 / 240ms`; easing `cubic-bezier(0.2,0,0,1)` (ease-out) for enters, `cubic-bezier(0.4,0,1,1)` for exits; a spring only for selection/drag. **Respect `prefers-reduced-motion`.**

### Icons & illustration
- **Lucide** (line, rounded), stroke 1.5px, 20px default (16px dense, 24px feature).
- Illustration: minimal, single-accent line spot-art for empty states — friendly, not corporate stock.

### States (must all be designed)
- **Loading:** skeleton rows (list), shimmer summary card (reading) — never spinners for content.
- **Empty:** friendly line-art + one clear CTA ("Nothing here yet — connect Gmail" / "No results — try broader terms" with a *Did you mean* / *Broaden* action).
- **Error:** calm, specific, recoverable ("Couldn't reach Gmail — Retry"), never a raw stack.
- **Success:** toast + inline confirmation; destructive actions show **preview → confirm → undo**.

### Components (catalogue)
Buttons (`primary` green / `secondary` surface / `ghost` / `danger`) · icon-button · input
· **search field** (hero variant) · **filter chip** (removable, typed) · segmented control ·
toggle · dropdown menu · **context menu** · **command palette** · **email row** (avatar,
sender, subject, one-line intent, badges, time, hover-actions) · **sender chip/avatar** ·
**thread summary card** · **category badge** · **priority indicator** · tabs · tooltip ·
toast · modal · **side sheet** (mobile reading) · skeletons · empty-state · pagination /
**virtualised infinite scroll** · avatar/initials · progress/VRAM meter (AI panel).

---

## Part D — Themes (both fully polished)

### Dark (default)
Layered **warm charcoal** surfaces (`#1a1917` → `#34302c`), warm off-white text, green
accent nudged for on-dark contrast, faint borders to separate layers. Avoids pure black;
depth via surface elevation + hairline borders, not heavy shadow.

### Light
**Genuine white** base (`#ffffff`) with warm off-white surfaces — *not grey-pretending-to-
be-white*. Generous whitespace, soft shadows for elevation, restrained green accent.
Premium, low-noise, highly readable.

Both share tokens; only the neutral map + shadow strategy differ. Theme follows a
`data-theme` attribute; **dark is the design source of truth**, light is derived and
independently QA'd.

---

## Part E — Interaction design
- **Hover:** rows raise to `surface-2`, reveal quick-actions (archive/snooze/label/unsub).
- **Selection:** checkbox on hover + click-row-to-open; shift/⌘-click multi-select; a
  sticky **bulk action bar** slides up when >1 selected.
- **Search:** instant results, **live filtering** as chips are added/removed, suggestions +
  recent on focus (see [05](05-search-redesign.md)).
- **Previews:** hover peek + inline reading; attachments preview in a lightbox.
- **Drag & drop:** rows → labels/categories/cleanup; respects reduced-motion.
- **Notifications:** toasts (non-blocking), with undo for reversible actions.
- **Transitions:** pane content crossfades; mobile reading slides up as a sheet.
- **Scrolling:** **virtualised list** (mandatory for 100k+ rows) with sticky lane headers.

---

## Part F — Accessibility review (baseline; deeper a11y deferred)
Baked in cheaply now: AA-tuned contrast via the ramps, visible focus rings, `prefers-
reduced-motion`, **non-colour-only** state, semantic HTML + ARIA on lists/dialogs/menus,
full keyboard reachability of core actions. **Deferred to pre-launch backlog** (per brief):
high-contrast mode, formal screen-reader passes, font-scaling controls, colour-blind audit.

---

## Part G — Migration strategy (strangler, low-risk)
1. **Introduce tokens + component library** (Tailwind config from this doc) — no behaviour change.
2. **Rebuild the shell** (sidebar / top-bar / search-home) around the existing API.
3. **Migrate screen-by-screen behind a feature flag** (`ui.v2`): Search → Reading → List →
   Cleanup → Analytics (the old draggable dashboard *becomes* Analytics).
4. **Keep the API stable**; frontend-only migration. Delete old screens once parity is verified.
5. Ship per-screen via the `develop → staging` pipeline; each screen is its own epic (see [Git plan](10-git-plan.md)).

## Part H — Future design opportunities
Pop-out / multi-window reading · dockable panels · custom accent picker · additional themes
· a Tauri/Electron shell if a true desktop build is ever wanted · plugin-contributed widgets
on the Analytics canvas · command-palette extensibility.