resolutionflow/docs/superpowers/plans/2026-03-22-design-system-v4-migration.md

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:

@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:

: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:

/* ── 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:

/* ── 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:

.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

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

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

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

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

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

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

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

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

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

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

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

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>"