# Design System v4 Migration — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Migrate ResolutionFlow's frontend from glassmorphism/gradient aesthetic to a flat, high-contrast dark theme with an icon rail sidebar, as defined in DESIGN-SYSTEM.md.

**Architecture:** Five phases executed sequentially. Phase 1 rewrites CSS tokens and adds compatibility shims. Phase 2 rebuilds the sidebar as an icon rail. Phase 3 sweeps ~200 component files replacing old patterns. Phase 4 updates the landing page. Phase 5 removes shims and cleans up.

**Tech Stack:** React 19, Tailwind CSS v4, CSS custom properties, Lucide React

**Spec:** `docs/superpowers/specs/2026-03-22-design-system-v4-migration.md`

**Design system reference:** `DESIGN-SYSTEM.md` (project root)

---

## File Map

### Phase 1 — CSS Foundation
| Action | File |
|--------|------|
| Rewrite | `frontend/src/index.css` |

### Phase 2 — Icon Rail Sidebar
| Action | File |
|--------|------|
| Rewrite | `frontend/src/components/layout/Sidebar.tsx` |
| Modify | `frontend/src/components/layout/AppLayout.tsx` |
| Modify | `frontend/src/components/layout/TopBar.tsx` |
| Modify | `frontend/src/components/common/BrandLogo.tsx` and `BrandWordmark.tsx` |

### Phase 3 — Component Sweep (~200 files)
| Action | Files |
|--------|-------|
| Modify | All `.tsx` files in `components/` and `pages/` that reference old patterns |

### Phase 4 — Landing Page
| Action | File |
|--------|------|
| Modify | `frontend/src/pages/LandingPage.tsx` |
| Modify | `frontend/src/styles/landing.css` |

### Phase 5 — Cleanup
| Action | File |
|--------|------|
| Modify | `frontend/src/index.css` (remove shims) |
| Modify | `CLAUDE.md` (verify no stale references) |

---

## Task 1: Rewrite CSS Foundation (index.css)

**Files:**
- Modify: `frontend/src/index.css`
- Reference: `DESIGN-SYSTEM.md` (project root)

- [ ] **Step 1: Rewrite the `@theme` block with new color tokens**

Replace the entire `@theme { ... }` block. New tokens from DESIGN-SYSTEM.md:

```css
@theme {
  /* ── Surface colors ────────────────────────────── */
  --color-bg-page: #0c0d10;
  --color-bg-sidebar: #0f1118;
  --color-bg-card: #14161d;
  --color-bg-card-hover: #191c25;
  --color-bg-input: #191c25;
  --color-bg-code: #0e1017;
  --color-bg-elevated: #1c1f2a;

  /* ── Text colors ───────────────────────────────── */
  --color-text-heading: #f0f2f5;
  --color-text-primary: #e2e5eb;
  --color-text-secondary: #848b9b;
  --color-text-muted: #4f5666;
  --color-text-rail-label: #6b7280;

  /* ── Border colors ─────────────────────────────── */
  --color-border-default: #1e2130;
  --color-border-hover: #2a2f3d;

  /* ── Accent (cyan) ─────────────────────────────── */
  --color-accent: #22d3ee;
  --color-accent-hover: #06b6d4;
  --color-accent-dim: rgba(34,211,238,0.10);
  --color-accent-text: #67e8f9;

  /* ── Semantic colors ───────────────────────────── */
  --color-success: #34d399;
  --color-success-dim: rgba(52,211,153,0.10);
  --color-warning: #fbbf24;
  --color-warning-dim: rgba(251,191,36,0.10);
  --color-danger: #f87171;
  --color-danger-dim: rgba(248,113,113,0.10);

  /* ── Tailwind semantic mappings ─────────────────── */
  --color-background: #0c0d10;
  --color-foreground: #e2e5eb;
  --color-card: #14161d;
  --color-card-foreground: #e2e5eb;
  --color-popover: #14161d;
  --color-popover-foreground: #e2e5eb;
  --color-primary: #22d3ee;
  --color-primary-foreground: #ffffff;
  --color-secondary: #1c1f2a;
  --color-secondary-foreground: #e2e5eb;
  --color-muted: #1c1f2a;
  --color-muted-foreground: #848b9b;
  --color-accent-tw: #1c1f2a;
  --color-accent-foreground: #e2e5eb;
  --color-destructive: #f87171;
  --color-destructive-foreground: #ffffff;
  --color-border: #1e2130;
  --color-input: #191c25;
  --color-ring: #22d3ee;

  /* ── Radii ─────────────────────────────────────── */
  --radius-sm: 5px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-xl: 16px;

  /* ── Fonts ─────────────────────────────────────── */
  --font-sans: 'IBM Plex Sans', system-ui, -apple-system, sans-serif;
  --font-heading: 'Bricolage Grotesque', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
  /* Deprecated alias — remove in Phase 5 */
  --font-label: 'JetBrains Mono', monospace;

  /* ── Animations ────────────────────────────────── */
  --animate-fade-in: fade-in 200ms ease-out;
  --animate-fade-in-up: fade-in-up 200ms ease-out;
  --animate-slide-in-left: slide-in-from-left 200ms ease-out;
  --animate-slide-in-bottom: slide-in-from-bottom 200ms ease-out;
  --animate-scale-in: scale-in 150ms ease-out;

  @keyframes fade-in {
    from { opacity: 0; } to { opacity: 1; }
  }
  @keyframes fade-in-up {
    from { opacity: 0; transform: translateY(4px); } to { opacity: 1; transform: translateY(0); }
  }
  @keyframes slide-in-from-left {
    from { transform: translateX(-100%); } to { transform: translateX(0); }
  }
  @keyframes slide-in-from-bottom {
    from { opacity: 0; transform: translateY(16px); } to { opacity: 1; transform: translateY(0); }
  }
  @keyframes scale-in {
    from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); }
  }
  @keyframes fadeIn {
    from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: translateY(0); }
  }
}
```

- [ ] **Step 2: Replace `:root` variables**

Replace the `:root` block (lines 168-192) with:

```css
:root {
  --sidebar-w: 72px;
  --sidebar-w-pinned: 260px;
  --ease-out-smooth: cubic-bezier(0.4, 0, 0.2, 1);
}
```

- [ ] **Step 3: Add compatibility shims**

Replace the old `@utility` blocks (glass-card, glass-card-static, active-glow, text-gradient-brand) with shims:

```css
/* ── Deprecated shims — remove after Phase 3 sweep ── */
@utility glass-card {
  background: var(--color-bg-card);
  border: 1px solid var(--color-border-default);
  border-radius: 8px;
  transition: border-color 200ms ease;
  &:hover {
    border-color: var(--color-border-hover);
  }
}

@utility glass-card-static {
  background: var(--color-bg-card);
  border: 1px solid var(--color-border-default);
  border-radius: 8px;
}

@utility text-gradient-brand {
  color: var(--color-accent-text);
}

@utility active-glow {
  /* no-op — glow removed in v4 */
}

@utility bg-gradient-brand-hover {
  /* Shim — maps to brightness hover until components are swept */
  &:hover { filter: brightness(1.1); }
}
```

Remove the old gradient `--background-image-*` theme values. Remove `breatheGlow`, `bellWobble`, `slideDown`, `slideInRight`, `fadeInRight`, `pulse-dot`, `stagger-fade-in` keyframes. Remove `stagger-item` utility.

- [ ] **Step 4: Add new base component classes**

Add after the shims:

```css
/* ── New component base classes ─────────────────── */
@utility card-flat {
  background: var(--color-bg-card);
  border: 1px solid var(--color-border-default);
  border-radius: 8px;
}

@utility card-interactive {
  background: var(--color-bg-card);
  border: 1px solid var(--color-border-default);
  border-radius: 8px;
  transition: border-color 200ms ease;
  &:hover {
    border-color: var(--color-border-hover);
  }
}

@utility btn-primary {
  background: var(--color-accent);
  color: #ffffff;
  font-weight: 550;
  border-radius: 5px;
  padding: 9px 16px;
  font-size: 13px;
  transition: filter 150ms ease;
  &:hover {
    filter: brightness(1.1);
  }
}

@utility btn-ghost {
  background: transparent;
  color: var(--color-text-secondary);
  border: 1px solid var(--color-border-default);
  border-radius: 5px;
  padding: 9px 16px;
  font-size: 13px;
  transition: background 150ms ease, color 150ms ease, border-color 150ms ease;
  &:hover {
    background: var(--color-bg-elevated);
    color: var(--color-text-primary);
    border-color: var(--color-border-hover);
  }
}
```

- [ ] **Step 5: Update layout utilities**

Update `.app-shell` grid columns:

```css
.app-shell {
  display: grid;
  grid-template-columns: var(--sidebar-w) 1fr;
  grid-template-rows: 1fr; /* No topbar row — topbar is inside main content now, or handled differently */
  height: 100vh;
  overflow: hidden;
  transition: grid-template-columns 200ms ease;
}

.app-shell--pinned {
  --sidebar-w: 260px;
}

@media (max-width: 767px) {
  .app-shell {
    grid-template-columns: 1fr;
  }
}
```

- [ ] **Step 6: Update base body styles**

```css
body {
  @apply bg-background text-foreground font-sans;
  color: var(--color-text-primary);
  background-color: var(--color-bg-page);
}
```

- [ ] **Step 7: Keep React Flow, Sonner, scrollbar, and accessibility styles**

These stay mostly unchanged — just verify they reference the correct new variable names. Update any references to removed variables.

- [ ] **Step 8: Verify build**

Run: `cd frontend && npm run build`
Expected: Build succeeds. App looks different (shims mapping old classes to flat styles) but is functional.

- [ ] **Step 9: Commit**

```bash
git add frontend/src/index.css
git commit -m "refactor: rewrite CSS foundation for Design System v4

New flat dark color tokens, remove glass/gradient utilities,
add compatibility shims for phased migration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
```

---

## Task 2: Icon Rail Sidebar

**Files:**
- Rewrite: `frontend/src/components/layout/Sidebar.tsx`
- Modify: `frontend/src/components/layout/AppLayout.tsx`
- Modify: `frontend/src/components/layout/TopBar.tsx`
- Modify: `frontend/src/components/common/BrandLogo.tsx`
- Reference: `DESIGN-SYSTEM.md` → Layout Architecture, Icon Rail Sidebar sections

This is a complex task. The sidebar has three states: icon rail (72px), flyout (hovering), and pinned (260px). Read the current `Sidebar.tsx` and `AppLayout.tsx` fully before starting.

- [ ] **Step 1: Read current sidebar and layout**

Read `frontend/src/components/layout/Sidebar.tsx` and `frontend/src/components/layout/AppLayout.tsx` completely to understand current nav structure, items, mobile handling, and grid layout.

- [ ] **Step 2: Implement icon rail sidebar**

Rewrite `Sidebar.tsx` with:
- Default: 72px icon rail with `bg-[var(--color-bg-sidebar)]`
- Logo mark at top: 30px cyan gradient square with lightning bolt SVG
- Nav items: 20px Lucide icon + 10px label text underneath, centered
- Horizontal dividers between RESOLVE / KNOWLEDGE / INSIGHTS sections
- Active item: `bg-[var(--color-accent-dim)]` background, `text-[var(--color-accent-text)]` on icon + label
- Inactive: `text-[var(--color-text-rail-label)]`, opacity 0.6 default, 0.85 hover
- User avatar at bottom
- Pin toggle button below avatar

Nav items (same as current, just icon + short label):
- Dashboard (LayoutDashboard)
- Sessions (Activity) — with count badge
- Escalations (AlertTriangle)
- Divider
- Flows (GitBranch)
- Steps (Layers)
- Scripts (Code2)
- Builder (Wand2)
- Review (ListChecks)
- Divider
- Exports (Download)
- Analytics (BarChart3)
- FP Analytics (Rocket)

Footer: User Guides, Feedback, Account (as icons), Pin/Unpin toggle

- [ ] **Step 3: Implement flyout panels**

On hover of a nav item, show a 220px flyout panel to the right:
- `bg-[var(--color-bg-card)]` with `border border-[var(--color-border-default)]`
- `box-shadow: 0 4px 12px rgba(0,0,0,0.3)`
- 150ms ease-out transition (opacity + translateX)
- Also opens on keyboard focus/Enter
- Closes on Escape, mouse leave from both rail item and flyout, or focus-out
- `max-height: 70vh; overflow-y: auto` for long sub-item lists
- Sub-items match current sidebar children (e.g., Flows → All Flows, Troubleshooting, Projects, Maintenance)

- [ ] **Step 4: Implement pinned state**

Clicking pin button:
- Expands sidebar to 260px with full text labels, section headers, badges
- Updates `--sidebar-w` CSS variable to `260px`
- Shows unpin button in sidebar header
- Persists preference to localStorage (`sidebarPinned: true/false`)
- Active item gets 3px left accent bar

- [ ] **Step 5: Mobile handling**

Below `sm` breakpoint:
- Icon rail hidden
- Hamburger button in top-left corner
- Opens full-screen overlay with pinned sidebar content
- Close button (X) in overlay header

- [ ] **Step 6: Update AppLayout.tsx**

- Grid layout changes from `grid-template-rows: 56px 1fr` to `grid-template-rows: auto 1fr` — TopBar remains a grid row spanning both columns (same as current), but with flat styling
- Grid columns: `var(--sidebar-w) 1fr` (72px default, 260px when pinned via `.app-shell--pinned` class)
- Sidebar pin state: read from `localStorage.getItem('sidebarPinned')` on mount, toggle sets `localStorage.setItem('sidebarPinned', 'true'/'false')` and updates `--sidebar-w` CSS variable on the `.app-shell` element
- Ensure `--sidebar-w` transition is coordinated with sidebar width transition to prevent layout jump on pin/unpin (both use `transition: 200ms ease`)
- Mobile: single column, no sidebar

- [ ] **Step 7: Update TopBar.tsx**

- Remove backdrop blur
- Flat `bg-[var(--color-bg-sidebar)]` or `bg-[var(--color-bg-page)]` background
- `border-b border-[var(--color-border-default)]`
- Remove any glass/gradient styling

- [ ] **Step 8: Update BrandLogo.tsx**

- Replace decision-tree icon SVG with 30px gradient square (cyan, border-radius 8px) + white lightning bolt
- Wordmark: "ResolutionFlow" in Bricolage Grotesque 700, `text-[var(--color-text-heading)]` (no gradient)
- Remove `text-gradient-brand` usage

- [ ] **Step 9: Verify build and test**

Run: `cd frontend && npm run build`
Expected: Build succeeds. Sidebar renders as icon rail. Flyout works on hover. Pin/unpin works.

- [ ] **Step 10: Commit**

```bash
git add frontend/src/components/layout/ frontend/src/components/common/BrandLogo.tsx
git commit -m "refactor: implement icon rail sidebar for Design System v4

72px icon rail with hover flyouts, pin-to-expand toggle,
keyboard accessible, mobile hamburger overlay.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
```

---

## Task 3: Component Sweep — Layout & Dashboard

**Files:**
- Modify: All files in `frontend/src/components/dashboard/` (~16 files)
- Modify: Any remaining layout components

Apply the pattern replacement map from the spec to every file. For each file:

1. Replace `glass-card` / `glass-card-static` → `card-flat` or `card-interactive`
2. Replace `bg-gradient-brand` → `btn-primary` class or `bg-[var(--color-accent)]`
3. Replace `text-gradient-brand` → `text-[var(--color-accent-text)]`
4. Replace `text-foreground` → `text-[var(--color-text-primary)]`
5. Replace `text-muted-foreground` → `text-[var(--color-text-secondary)]`
6. Replace `font-label` on code/monospace → `font-mono`; on labels/badges → `font-sans text-xs`
7. Remove `backdrop-filter`, `shadow-lg shadow-primary/20`, `scale(1.02)` hover
8. Remove atmosphere orb JSX elements
9. Replace `rounded-[10px]` / `rounded-[16px]` → `rounded-lg` (8px)
10. Replace inline `style={{ background: 'rgba(...)' }}` glass surfaces → CSS variable classes

- [ ] **Step 1: Read and update all dashboard components**

Process all `.tsx` files in `frontend/src/components/dashboard/` (~18 files). Apply the pattern replacement map to each.

- [ ] **Step 2: Verify build**

Run: `cd frontend && npm run build`

- [ ] **Step 3: Commit**

```bash
git add frontend/src/components/dashboard/ frontend/src/components/layout/
git commit -m "refactor: migrate dashboard components to Design System v4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
```

---

## Task 4: Component Sweep — FlowPilot

**Files:**
- Modify: All files in `frontend/src/components/flowpilot/` (~12 files)

Same pattern replacement map as Task 3.

- [ ] **Step 1: Read and update all FlowPilot components**

Process all `.tsx` files in `frontend/src/components/flowpilot/` (~17 files). Apply the pattern replacement map to each.

- [ ] **Step 2: Verify build**

Run: `cd frontend && npm run build`

- [ ] **Step 3: Commit**

```bash
git add frontend/src/components/flowpilot/
git commit -m "refactor: migrate FlowPilot components to Design System v4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
```

---

## Task 5: Component Sweep — Pages

**Files:**
- Modify: All files in `frontend/src/pages/` (~25 files)

Same pattern replacement map.

- [ ] **Step 1: Read and update all page components**

Process all `.tsx` files in `frontend/src/pages/` (~41 files). Apply the pattern replacement map to each.

- [ ] **Step 2: Verify build**

Run: `cd frontend && npm run build`

- [ ] **Step 3: Commit**

```bash
git add frontend/src/pages/
git commit -m "refactor: migrate page components to Design System v4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
```

---

## Task 6: Component Sweep — Session, Script Builder, Account

**Files:**
- Modify: `frontend/src/components/session/` (~21 files)
- Modify: `frontend/src/components/script-builder/` (~5 files)
- Modify: `frontend/src/components/account/` (~5 files)

- [ ] **Step 1: Update session components**
- [ ] **Step 2: Update script-builder components**
- [ ] **Step 3: Update account components**
- [ ] **Step 4: Verify build**

Run: `cd frontend && npm run build`

- [ ] **Step 5: Commit**

```bash
git add frontend/src/components/session/ frontend/src/components/script-builder/ frontend/src/components/account/
git commit -m "refactor: migrate session, script-builder, account to Design System v4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
```

---

## Task 7: Component Sweep — All Remaining

**Files:**
- Modify: `frontend/src/components/common/` (~22 files)
- Modify: `frontend/src/components/tree-editor/` (~20 files)
- Modify: `frontend/src/components/kb-accelerator/` (~5 files)
- Modify: `frontend/src/components/copilot/` (~3 files)
- Modify: `frontend/src/components/assistant/` (~3 files)
- Modify: `frontend/src/components/analytics/` (~3 files)
- Modify: `frontend/src/components/library/` (~3 files)
- Modify: `frontend/src/components/procedural/` (~3 files)
- Modify: `frontend/src/components/public/` (~3 files)
- Modify: `frontend/src/components/script-editor/` (~6 files)
- Modify: `frontend/src/components/ui/` (any using old patterns)
- Modify: `frontend/src/components/admin/` (~12 files)

- [ ] **Step 1: Update all remaining component directories**

Process each directory. Use the same pattern replacement map.

- [ ] **Step 2: Verify build**

Run: `cd frontend && npm run build`

- [ ] **Step 3: Commit**

```bash
git add frontend/src/components/
git commit -m "refactor: migrate remaining components to Design System v4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
```

---

## Task 8: Landing Page

**Files:**
- Modify: `frontend/src/pages/LandingPage.tsx`
- Modify: Landing page CSS (check if `landing.css` exists or if styles are in `index.css`)

- [ ] **Step 1: Find landing page styles**

```bash
find frontend/src -name "landing*" -o -name "Landing*" | head -10
grep -r "landing" frontend/src/index.css | head -5
```

- [ ] **Step 2: Update landing page**

- Remove ambient glow effects, gradient overlays
- Hero: subtle radial gradient at 15% accent opacity
- Section labels: `font-mono`, 12px, uppercase, `text-[var(--color-accent-text)]`
- Section titles: `font-heading`, `clamp(28px, 4vw, 42px)`, weight 800
- Pricing cards: `card-flat` with featured card getting `border-[var(--color-accent)]`
- Top nav: flat, no blur
- CTAs: `btn-primary` (solid accent)

- [ ] **Step 3: Verify build**

Run: `cd frontend && npm run build`

- [ ] **Step 4: Commit**

```bash
git add frontend/src/pages/LandingPage.tsx frontend/src/styles/landing.css
git commit -m "refactor: migrate landing page to Design System v4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
```

---

## Task 9: Cleanup & Verification

**Files:**
- Modify: `frontend/src/index.css`
- Modify: `CLAUDE.md` (verify)

- [ ] **Step 1: Remove compatibility shims**

Remove from `index.css`:
- The `glass-card` shim utility
- The `glass-card-static` shim utility
- The `text-gradient-brand` shim utility
- The `active-glow` shim utility
- The `--font-label` alias (keep only `--font-mono`)
- Any remaining old gradient references

- [ ] **Step 1.5: Update BrandWordmark.tsx**

Check `frontend/src/components/common/BrandWordmark.tsx` for `text-gradient-brand` usage. Replace with `text-[var(--color-accent-text)]`.

- [ ] **Step 2: Verify no old patterns remain**

```bash
cd frontend && grep -r "glass-card\|glass-stat\|bg-gradient-brand\|text-gradient-brand\|backdrop-filter.*blur\|atmosphere-orb\|active-glow\|breatheGlow\|bellWobble" src/ --include="*.tsx" --include="*.css" | head -20
```

Expected: Zero results (or only in comments/string literals).

- [ ] **Step 3: Verify CLAUDE.md**

Grep CLAUDE.md for any stale references to old design system patterns. Should already be clean from the doc-swap commit, but verify.

- [ ] **Step 4: Final build verification**

Run: `cd frontend && npm run build`
Expected: Clean build with zero errors.

- [ ] **Step 5: Commit**

```bash
git add frontend/src/index.css CLAUDE.md
git commit -m "chore: remove design system v3 compatibility shims

All components migrated to v4 flat dark theme.
No glass-card, gradient, or blur references remain.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
```