docs/plans/2026-03-03-aesthetic-redesign-design.md

@@ -0,0 +1,368 @@
+# ResolutionFlow Aesthetic Redesign — Design Document
+
+> **Date:** March 3, 2026
+> **Status:** Approved
+> **Reference Mockup:** `/tmp/mockup-j-slate-ice-modern.html`
+
+---
+
+## Problem Statement
+
+The current purple gradient theme (`#818cf8` → `#a78bfa`) feels generic and AI-generated. It doesn't convey the professional credibility MSP engineers expect from their daily tooling. The redesign aims for a **sharp, modern** aesthetic that stands out while remaining easy on the eyes during long troubleshooting sessions.
+
+## Design Direction: Slate & Ice Modern
+
+Dark glassmorphism with an ice-cyan accent. Cool charcoal backgrounds, frosted-glass cards with backdrop blur, orchestrated page-load animations, and bold display typography.
+
+---
+
+## Color Palette
+
+### Core Colors
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| `--background` | `#101114` | Page background, body |
+| `--surface` | `#14161a` | Sidebar/topbar base behind blur |
+| `--card` / glass-bg | `rgba(24, 26, 31, 0.55)` | Card backgrounds (semi-transparent) |
+| `--card-hover` | `rgba(24, 26, 31, 0.7)` | Card hover state |
+| `--foreground` | `#f8fafc` | Primary text |
+| `--muted-foreground` | `#8891a0` | Secondary text, nav labels |
+| `--muted-dim` | `#5a6170` | Section labels, timestamps |
+| `--border` | `rgba(255, 255, 255, 0.06)` | Default borders |
+| `--border-hover` | `rgba(255, 255, 255, 0.12)` | Hover/active borders |
+
+### Accent Colors
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| `--primary` | `#06b6d4` | Accent gradient start, active indicators |
+| `--primary-light` | `#22d3ee` | Accent gradient end, highlights |
+| `--gradient-brand` | `linear-gradient(135deg, #06b6d4, #22d3ee)` | Primary buttons, avatar, active accent bar, logo "Flow" text |
+
+### Functional Colors (unchanged semantics)
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| `--success` | `#34d399` / emerald-400 | Completed, positive |
+| `--warning` | `#fbbf24` / amber-400 | In-progress, caution |
+| `--error` | `#f43f5e` / rose-500 | Error, critical, notification dots |
+| `--info` | `#60a5fa` / blue-400 | Informational |
+
+### Accessibility Notes
+
+- Cyan accent is safe for deuteranopia, protanopia, and tritanopia
+- Always pair status colors with icons (not color alone)
+- Use shape differentiation (filled vs outline icons) alongside color for colorblind users
+- `#f8fafc` on `#101114` background exceeds WCAG AAA contrast ratio
+
+---
+
+## Typography
+
+### Font Stack
+
+| Role | Font | Weights | Google Fonts |
+|------|------|---------|-------------|
+| `font-heading` | **Bricolage Grotesque** | 400, 600, 700, 800 | Yes |
+| `font-body` (default) | **IBM Plex Sans** | 400, 500, 600 | Yes |
+| `font-label` | **JetBrains Mono** | 400, 500 | Yes |
+
+### Hierarchy
+
+| Element | Font | Size | Weight | Color |
+|---------|------|------|--------|-------|
+| Page greeting / hero | Bricolage Grotesque | 36px | 800 | `--foreground` |
+| Stat values | Bricolage Grotesque | 30px | 800 | cyan gradient text |
+| Card titles | Bricolage Grotesque | 16px | 700 | `--foreground` |
+| Body text | IBM Plex Sans | 14px | 400-500 | `--foreground` |
+| Nav items | IBM Plex Sans | 14px | 500 | `--muted-foreground` → `--foreground` on hover/active |
+| Section labels | JetBrains Mono | 10px | 500 | `--muted-dim`, uppercase, `letter-spacing: 0.1em` |
+| Timestamps / metadata | JetBrains Mono | 11-12px | 400 | `--muted-foreground` |
+| Stat labels | IBM Plex Sans | 13px | 500 | `--muted-foreground` |
+
+---
+
+## Glassmorphism System
+
+### Card Variants
+
+**Interactive glass card** (`.glass-card`):
+```css
+background: rgba(24, 26, 31, 0.55);
+backdrop-filter: blur(16px);
+border: 1px solid rgba(255, 255, 255, 0.06);
+border-radius: 16px;
+box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+/* Hover */
+transform: scale(1.02);
+border-color: rgba(255, 255, 255, 0.12);
+box-shadow: 0 12px 40px rgba(0, 0, 0, 0.4), 0 0 0 1px rgba(255, 255, 255, 0.08);
+```
+
+**Static glass card** (`.glass-card-static`): Same as above without hover transform.
+
+### Shell Blur Levels
+
+| Element | Blur | Background |
+|---------|------|-----------|
+| Sidebar | `blur(12px)` | `rgba(16, 17, 20, 0.5)` |
+| Topbar | `blur(20px)` | `rgba(16, 17, 20, 0.6)` |
+| Cards | `blur(16px)` | `rgba(24, 26, 31, 0.55)` |
+
+### Ambient Atmosphere
+
+Two fixed `pointer-events: none` gradient orbs behind the app shell:
+- **Cyan orb**: top-right, 600x600px, `rgba(6, 182, 212, 0.15)`, blur(60px)
+- **Purple orb**: bottom-left, 500x500px, `rgba(99, 102, 241, 0.08)`, blur(50px)
+
+---
+
+## Component Specifications
+
+### Primary Button
+
+```css
+background: linear-gradient(135deg, #06b6d4, #22d3ee);
+color: #101114;
+font-weight: 600;
+border-radius: 10px;
+padding: 10px 20px;
+/* Hover: opacity 0.9; Active: scale(0.97) */
+```
+
+### Secondary Button
+
+```css
+background: rgba(255, 255, 255, 0.04);
+border: 1px solid rgba(255, 255, 255, 0.06);
+color: #f8fafc;
+border-radius: 10px;
+/* Hover: border brightens to rgba(255, 255, 255, 0.12) */
+```
+
+### Search Bar
+
+- `width: 320px`, expands to `400px` on focus
+- Background: `rgba(255, 255, 255, 0.04)`, focus: `rgba(255, 255, 255, 0.06)`
+- Focus border: `rgba(6, 182, 212, 0.3)` — cyan tint
+- Rounded: `border-radius: 12px`
+
+### Active Nav Item
+
+- Background: `rgba(6, 182, 212, 0.1)` with scaleX reveal animation
+- Left accent bar: 3px wide, cyan gradient, `border-radius: 0 3px 3px 0`
+- Text: `--foreground` (white)
+
+### Avatar
+
+- 34x34px, `border-radius: 10px` (rounded square)
+- Cyan gradient background, dark text
+- Hover: `scale(1.08)`
+
+### Notification Dot
+
+- 8px circle, `#f43f5e` (rose), 2px solid `#101114` border
+
+### Scrollbar
+
+- 6px wide, transparent track
+- Thumb: `rgba(255,255,255,0.08)`, hover: `rgba(255,255,255,0.12)`
+
+---
+
+## Animations
+
+### Page Load Sequence (orchestrated)
+
+| Element | Animation | Delay | Duration |
+|---------|-----------|-------|----------|
+| Topbar | slideDown (Y: -100% → 0) | 200ms | 400ms |
+| Sidebar | slideInLeft (X: -100% → 0) | 250ms | 400ms |
+| Greeting | fadeInUp (Y: 20px → 0) | 400ms | 400ms |
+| Stat cards | fadeInUp cascade | 500ms, 570ms, 640ms, 710ms | 350ms each |
+| Activity items | fadeInUp stagger | 750ms + 40ms each | 300ms each |
+| Quick actions | fadeInRight (X: 30px → 0) | 800ms | 400ms |
+
+### Micro-interactions
+
+| Element | Effect |
+|---------|--------|
+| Glass cards | `scale(1.02)` + border/shadow upgrade on hover |
+| Buttons | `scale(0.97)` on `:active` |
+| Notification bell | wobble keyframe (rotate ±8° → 0) on hover |
+| First stat card | `breatheGlow` — pulsing cyan shadow, 3s infinite |
+| Nav items | Background scaleX reveal from left on hover |
+| Search bar | Width expansion 320→400px on focus |
+| Avatar | `scale(1.08)` on hover |
+
+### Easing
+
+- Primary: `cubic-bezier(0.4, 0, 0.2, 1)` — smooth deceleration
+- Bounce (optional): `cubic-bezier(0.34, 1.56, 0.64, 1)` — slight overshoot
+
+---
+
+## Dashboard Layout
+
+### Grid Structure
+
+```
+Row 1: Greeting + date (full width)
+Row 2: Weekly Calendar (flex-grow) + Quick Actions (fixed width) — equal height
+Row 3: My Open Sessions (flex-grow) + Stats 2x2 grid (fixed width) — equal height
+Row 4: Recent Activity (full width)
+```
+
+### Weekly Calendar Panel
+
+- 5 tall day columns (Mon–Fri), equal width
+- Today column: highlighted with cyan gradient top bar
+- Events appear inline within day columns with colored left border (4px)
+  - Cyan left-border: default events
+  - Amber left-border: maintenance events
+- Empty days show "No events" in muted text
+- Calendar and quick actions stretch to match height (`align-items: stretch`)
+- Future: Outlook/Gmail/PSA calendar sync integration
+
+### Quick Actions Panel
+
+4 glass cards in a vertical stack:
+1. New Flow (+ icon, cyan accent)
+2. Resume Session (play icon, emerald accent)
+3. Browse Library (book icon, amber accent)
+4. Invite Team (user-plus icon, purple accent)
+
+### My Open Sessions Panel
+
+- Shows 3 oldest open sessions
+- Each row: colored dot + flow name + "Step X of Y" + time ago + Resume button
+- Resume button: small cyan gradient pill
+
+### Stats Panel (2x2 Grid)
+
+4 stat cards:
+1. Active Flows — with `breatheGlow` animation
+2. This Week (sessions)
+3. Avg Resolution (time)
+4. Team Members
+
+Each: stat value (30px Bricolage Grotesque, cyan gradient text) + label + trend indicator
+
+### Recent Activity Panel
+
+- Full width, 5 activity items
+- Each: icon (colored background circle) + description + JetBrains Mono timestamp
+- Staggered fadeInUp animation on page load
+
+---
+
+## Sidebar Structure
+
+1. **Logo bar** (56px height, matches topbar): Decision-tree icon SVG + "Resolution" white + "Flow" cyan gradient
+2. **Pinned Flows**: 3 pinned items with cyan pin icons
+3. **Divider**
+4. **Navigation**:
+   - Dashboard (active)
+   - All Flows → Troubleshooting / Projects / Maintenance (sub-items)
+   - Step Library
+   - Sessions
+   - Exports
+5. **Divider**
+6. **Footer** (pushed to bottom): User avatar + name + role badge
+
+No categories section. No workspace switcher.
+
+---
+
+## Topbar Structure
+
+- Left: Search bar with search icon + "Search flows..." placeholder + keyboard shortcut badge
+- Right: Help icon + Notification bell (with dot) + User avatar (rounded square, cyan gradient)
+- Subtle cyan gradient underline glow at center-bottom
+
+---
+
+## Logo
+
+The existing decision-tree SVG icon is retained but recolored with the cyan gradient (`#06b6d4` → `#22d3ee`). Nodes have decreasing opacity down the tree (0.9 → 0.7 → 0.5). Connector lines use the gradient stroke at 0.4–0.5 opacity.
+
+Wordmark: "Resolution" in `#f8fafc` + "Flow" with `background: linear-gradient(135deg, #06b6d4, #22d3ee)` + `-webkit-background-clip: text`.
+
+---
+
+## Shadow System
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--shadow-float` | `0 8px 32px rgba(0,0,0,0.3)` | Default card shadow |
+| `--shadow-float-hover` | `0 12px 40px rgba(0,0,0,0.4), 0 0 0 1px rgba(255,255,255,0.08)` | Hovered card |
+| `--shadow-cyan-glow` | `0 8px 32px rgba(6,182,212,0.08)` | Cyan-tinted glow |
+
+---
+
+## Migration Notes
+
+### What Changes
+
+| Current | New |
+|---------|-----|
+| Purple gradient (`#818cf8` → `#a78bfa`) | Ice cyan gradient (`#06b6d4` → `#22d3ee`) |
+| Plus Jakarta Sans (headings) | Bricolage Grotesque (headings) |
+| Inter (body) | IBM Plex Sans (body) |
+| Outfit (labels) | JetBrains Mono (labels) |
+| Flat `bg-card` cards | Glassmorphism with `backdrop-filter: blur()` |
+| No page-load animations | Orchestrated entrance sequence |
+| No hover scaling on cards | `scale(1.02)` hover lift |
+| `bg-gradient-brand` = purple | `bg-gradient-brand` = cyan |
+| `text-gradient-brand` = purple | `text-gradient-brand` = cyan |
+
+### What Stays the Same
+
+- CSS Grid app shell layout (sidebar + topbar + main)
+- Dark-first theme (dark only, no light mode)
+- Lucide React icons
+- Zustand state management
+- Component architecture and routing
+- Functional color semantics (green=success, amber=warning, red=error)
+- "Flows" terminology, "ResolutionFlow" branding
+- BrandLogo.tsx component structure (just recolor the SVG + gradient)
+
+### New Dashboard Panels (Feature Work)
+
+- **Weekly Calendar**: New component, requires date logic, event display, future calendar sync API
+- **My Open Sessions**: Queries 3 oldest open sessions (existing API with sort + limit)
+- Stat cards and Recent Activity already exist — layout rearrangement only
+
+---
+
+## Implementation Scope
+
+### Phase 1: Design System Foundation
+- Update CSS variables in `index.css`
+- Update `tailwind.config.js` (colors, fonts, gradients)
+- Add Google Fonts imports (Bricolage Grotesque, IBM Plex Sans, JetBrains Mono)
+- Create glassmorphism utility classes
+- Create animation keyframes and stagger classes
+- Update `BrandLogo.tsx` SVG colors
+
+### Phase 2: Shell & Navigation
+- Update sidebar glassmorphism + nav item styles
+- Update topbar glassmorphism + search bar
+- Update active nav indicator (purple → cyan accent bar)
+
+### Phase 3: Component Updates
+- Update button variants (primary gradient, secondary)
+- Update card components to glass-card pattern
+- Update stat cards, activity items, badges
+- Update form inputs (focus states)
+
+### Phase 4: Dashboard Redesign
+- Rearrange dashboard layout (greeting → calendar+actions → sessions+stats → activity)
+- Build Weekly Calendar component
+- Build My Open Sessions panel
+- Add orchestrated page-load animations
+
+### Phase 5: Page-by-Page Sweep
+- Update all remaining pages to use new design tokens
+- Ensure consistency across tree editor, session pages, admin pages, etc.