docs: discovery blueprint + multi-provider design (#8)

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

@@ -0,0 +1,182 @@
+# 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.