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: 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).
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).
• 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).

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.