# 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.