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

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