resolutionflow/docs/plans/2026-02-15-visual-qa-design-migration.md

Visual QA & Design System Migration — Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Fix the collapsed sidebar scaling issue and migrate all pages from old monochrome design patterns to the new purple gradient accent design system.

Architecture: Systematic find-and-replace across 15 frontend files, replacing old monochrome CSS utilities (glass-card, text-white/N, border-white/N, bg-white text-black buttons) with new design tokens (bg-card border-border, text-foreground, border-border, bg-gradient-brand). Sidebar collapsed state gets a layout fix.

Tech Stack: React, Tailwind CSS v3, Lucide React

---

Pattern Replacement Reference

Every task below uses this table. Keep it open.

OLD Pattern	NEW Pattern	Context
glass-card rounded-2xl	bg-card border border-border rounded-xl	Card containers
glass-card rounded-xl	bg-card border border-border rounded-xl	Card containers
bg-black or bg-black/50	bg-card	Input/section backgrounds
text-white (on headings)	text-foreground + add font-heading	Primary heading text
text-white (on body text)	text-foreground	Primary body text
text-white/70	text-muted-foreground	Secondary text
text-white/40	text-muted-foreground	Muted text
text-white/60	text-muted-foreground	Button secondary text
border-white/10	border-border	Standard borders
border-white/[0.06]	border-border	Subtle borders
border-white/20	border-border	Toggle/active borders
bg-white/10	bg-accent	Hover/active backgrounds
hover:bg-white/10	hover:bg-accent	Hover states
hover:text-white	hover:text-foreground	Hover text
bg-white text-black hover:bg-white/90	bg-gradient-brand text-white shadow-lg shadow-primary/20 hover:opacity-90	Primary buttons
bg-white px-N py-N text-black ... hover:bg-white/90	bg-gradient-brand text-white shadow-lg shadow-primary/20 hover:opacity-90	Primary buttons (multi-class)
border-white/10 ... text-white/60 ... hover:bg-white/10	border-border text-muted-foreground hover:bg-accent hover:text-foreground	Secondary buttons
focus:border-white/30 focus:ring-white/20	focus:border-primary focus:ring-1 focus:ring-primary/20	Input focus
placeholder:text-white/40	placeholder:text-muted-foreground	Input placeholders
bg-white/10 px-2.5 py-0.5 (badges)	bg-accent rounded-full px-2 text-[0.6875rem] font-label	Badge/chip styling

---

Task 1: Fix Collapsed Sidebar Layout

Files:

• Modify: frontend/src/components/layout/Sidebar.tsx
• Modify: frontend/src/index.css

Problem: When the sidebar is collapsed, the navigation divider doesn't span the full height (top to bottom), and the expand icon is extremely small — suggests the entire collapsed column isn't sizing correctly.

Step 1: Fix collapsed sidebar to be a proper full-height flex column

In Sidebar.tsx, the collapsed state renders a <div className="px-2 py-3 space-y-1"> with nav icons but doesn't fill the column. The <nav> wrapper has flex flex-col but the collapsed branch lacks structure to fill it.

Replace the collapsed branch (lines 115-127) to add full-height structure with proper icon sizing and dividers:

{sidebarCollapsed ? (
  <>
    {/* Collapsed: icon-only nav */}
    <div className="flex flex-col items-center px-1.5 py-3 space-y-1">
      <NavItem href="/" icon={LayoutGrid} label="Dashboard" collapsed />
      <NavItem href="/trees" icon={Box} label="All Flows" matchPaths={['/trees', '/flows']} collapsed />
      <NavItem href="/my-trees" icon={PenLine} label="Flow Editor" collapsed />
      <NavItem href="/sessions" icon={Clock} label="Sessions" badge={activeSessionCount || undefined} collapsed />
      <NavItem href="/shares" icon={FileText} label="Exports" collapsed />
      <NavItem href="/step-library" icon={Bookmark} label="Step Library" collapsed />
    </div>
  </>
) : (

In the footer section (lines 173-189), ensure the toggle button has adequate sizing in collapsed mode:

{/* Footer */}
<div className={cn(
  'border-t border-[hsl(var(--border-subtle))]',
  sidebarCollapsed ? 'px-1.5 py-2' : 'px-3 py-2 space-y-0.5'
)}>
  {!sidebarCollapsed && (
    <>
      <NavItem href="/account" icon={Users} label="Team" />
      <NavItem href="/account" icon={Settings} label="Settings" />
    </>
  )}
  <button
    onClick={toggleSidebar}
    className={cn(
      'flex items-center justify-center rounded-lg text-muted-foreground hover:bg-[hsl(var(--sidebar-hover))] hover:text-foreground transition-colors',
      sidebarCollapsed ? 'w-full p-2.5' : 'w-full gap-3 px-3 py-2 text-[0.8125rem] font-medium'
    )}
    title={sidebarCollapsed ? 'Expand sidebar' : 'Collapse sidebar'}
  >
    {sidebarCollapsed ? <PanelLeftOpen size={20} /> : <PanelLeftClose size={18} />}
    {!sidebarCollapsed && <span>Collapse</span>}
  </button>
</div>

Step 2: Verify build passes

Run: cd frontend && npm run build Expected: Build succeeds with no errors.

Step 3: Commit

git add frontend/src/components/layout/Sidebar.tsx
git commit -m "fix: collapsed sidebar layout scaling and toggle button size"

---

Task 2: Migrate Auth Pages (Login, Register, ChangePassword, ResetPassword)

Files:

• Modify: frontend/src/pages/LoginPage.tsx
• Modify: frontend/src/pages/RegisterPage.tsx
• Modify: frontend/src/pages/ChangePasswordPage.tsx
• Modify: frontend/src/pages/ResetPasswordPage.tsx

Step 1: Apply replacements to all four files

Each file has the same three patterns:

1. glass-card rounded-2xl → bg-card border border-border rounded-xl
2. border-white/10 bg-black/50 → border-border bg-card
3. bg-white ... text-black ... hover:bg-white/90 → bg-gradient-brand text-white shadow-lg shadow-primary/20 hover:opacity-90

Also check for:

• Missing font-heading on page titles
• text-white → text-foreground
• Input focus states: focus:border-white/30 focus:ring-white/20 → focus:border-primary focus:ring-1 focus:ring-primary/20
• Placeholder colors: placeholder:text-white/40 → placeholder:text-muted-foreground

Step 2: Verify build passes

Run: cd frontend && npm run build

Step 3: Commit

git add frontend/src/pages/LoginPage.tsx frontend/src/pages/RegisterPage.tsx frontend/src/pages/ChangePasswordPage.tsx frontend/src/pages/ResetPasswordPage.tsx
git commit -m "refactor: migrate auth pages to new design system"

---

Task 3: Migrate TreeLibraryPage

Files:

• Modify: frontend/src/pages/TreeLibraryPage.tsx

Step 1: Apply replacements

This file has extensive old patterns:

• Primary buttons: bg-white ... text-black hover:bg-white/90 → bg-gradient-brand text-white shadow-lg shadow-primary/20 hover:opacity-90
• Cards: glass-card → bg-card border border-border rounded-xl
• Inputs: border-white/10 bg-black/50 text-white placeholder:text-white/40 → border-border bg-card text-foreground placeholder:text-muted-foreground
• Focus states: focus:border-white/30 focus:ring-white/20 → focus:border-primary focus:ring-1 focus:ring-primary/20
• Text: text-white → text-foreground, text-white/40 → text-muted-foreground
• Borders: border-white/10 → border-border
• Badges: bg-white/10 → bg-accent
• Select dropdowns: border-white/10 bg-black/50 → border-border bg-card
• Add font-heading to page title heading

Step 2: Verify build passes

Run: cd frontend && npm run build

Step 3: Commit

git add frontend/src/pages/TreeLibraryPage.tsx
git commit -m "refactor: migrate TreeLibraryPage to new design system"

---

Task 4: Migrate SessionHistoryPage and SessionDetailPage

Files:

• Modify: frontend/src/pages/SessionHistoryPage.tsx
• Modify: frontend/src/pages/SessionDetailPage.tsx

Step 1: Apply replacements

SessionHistoryPage:

• text-white heading → text-foreground + font-heading
• text-white/40 → text-muted-foreground
• border-white/[0.06] → border-border
• glass-card rounded-2xl → bg-card border border-border rounded-xl
• Primary buttons: bg-white ... text-black hover:bg-white/90 → gradient
• Secondary buttons: border-white/10 ... text-white/60 ... hover:bg-white/10 → border-border text-muted-foreground hover:bg-accent

SessionDetailPage:

• text-white font-bold → text-foreground font-heading font-bold
• text-white/40 → text-muted-foreground
• bg-white/10 badges → bg-accent
• Primary buttons: old → gradient
• border-white/10 bg-black/50 → border-border bg-card
• border-white/10 bg-transparent → border-border bg-card

Step 2: Verify build passes

Run: cd frontend && npm run build

Step 3: Commit

git add frontend/src/pages/SessionHistoryPage.tsx frontend/src/pages/SessionDetailPage.tsx
git commit -m "refactor: migrate session pages to new design system"

---

Task 5: Migrate TreeEditorPage

Files:

• Modify: frontend/src/pages/TreeEditorPage.tsx

Step 1: Apply replacements

• glass-card rounded-2xl → bg-card border border-border rounded-xl
• Primary buttons: bg-white ... text-black hover:bg-white/90 → gradient
• border-white/[0.06] → border-border
• text-lg font-semibold text-white → text-lg font-heading font-semibold text-foreground
• Dark mode mixed patterns: bg-yellow-100 ... dark:bg-yellow-900/30 dark:text-yellow-400 → just bg-yellow-900/30 text-yellow-400 border border-yellow-500/20 (we're dark-only)
• bg-white/10 text-white toggle states → bg-accent text-foreground
• border-white/10 bg-black/50 → border-border bg-card

Step 2: Verify build passes

Run: cd frontend && npm run build

Step 3: Commit

git add frontend/src/pages/TreeEditorPage.tsx
git commit -m "refactor: migrate TreeEditorPage to new design system"

---

Task 6: Migrate TreeNavigationPage

Files:

• Modify: frontend/src/pages/TreeNavigationPage.tsx

This is the largest file with the most old patterns.

Step 1: Apply replacements

• text-white headings → text-foreground + font-heading
• text-white/40 → text-muted-foreground
• glass-card rounded-2xl → bg-card border border-border rounded-xl
• glass-card → bg-card border border-border
• border-white/10 bg-black/50 → border-border bg-card
• border-white/10 → border-border
• border-white/[0.06] → border-border
• bg-white/10 → bg-accent
• text-white/70 hover:bg-white/10 hover:text-white → text-muted-foreground hover:bg-accent hover:text-foreground
• Primary buttons: bg-white ... text-black hover:bg-white/90 → gradient
• border-purple-700 bg-purple-900/20 → border-primary/30 bg-primary/10 (use design tokens, not hardcoded colors)
• bg-white/10 px-2.5 py-0.5 badges → bg-accent rounded-full px-2 text-[0.6875rem] font-label

Step 2: Verify build passes

Run: cd frontend && npm run build

Step 3: Commit

git add frontend/src/pages/TreeNavigationPage.tsx
git commit -m "refactor: migrate TreeNavigationPage to new design system"

---

Task 7: Migrate Session Sharing Components

Files:

• Modify: frontend/src/pages/MySharesPage.tsx
• Modify: frontend/src/pages/SharedSessionPage.tsx
• Modify: frontend/src/components/session/ShareSessionModal.tsx

Step 1: Apply replacements

MySharesPage:

• text-white heading → text-foreground + font-heading
• text-white/40 → text-muted-foreground
• glass-card rounded-xl → bg-card border border-border rounded-xl
• Primary buttons: old → gradient

SharedSessionPage:

• glass-card w-full max-w-md rounded-2xl → bg-card border border-border w-full max-w-md rounded-xl
• bg-white ... text-black hover:bg-white/90 → gradient
• border-white/[0.06] → border-border
• text-lg font-semibold text-white → text-lg font-heading font-semibold text-foreground
• text-lg text-white/70 → text-lg text-muted-foreground

ShareSessionModal:

• glass-card rounded-2xl → bg-card border border-border rounded-xl
• border-white/[0.06] → border-border
• border-white/20 bg-white/10 toggle → border-border bg-accent
• border-white/10 bg-black/50 → border-border bg-card
• Primary buttons: old → gradient

Step 2: Verify build passes

Run: cd frontend && npm run build

Step 3: Commit

git add frontend/src/pages/MySharesPage.tsx frontend/src/pages/SharedSessionPage.tsx frontend/src/components/session/ShareSessionModal.tsx
git commit -m "refactor: migrate session sharing components to new design system"

---

Task 8: Clean Up Legacy CSS

Files:

• Modify: frontend/src/index.css

Step 1: Remove workspace dropdown animation (dead code)

Remove the comment and @keyframes dropIn block (lines 115-119) — it was for the workspace switcher dropdown that no longer exists.

Step 2: Verify build passes

Run: cd frontend && npm run build

Step 3: Commit

git add frontend/src/index.css
git commit -m "chore: remove workspace dropdown animation (dead code)"

---

Task 9: Final Grep Audit

Step 1: Grep for remaining old patterns

Search for all remaining instances of old patterns across the entire frontend:

grep -rn "glass-card\|text-white/\|border-white/\|bg-white text-black\|bg-black/50\|hover:bg-white/" frontend/src/ --include="*.tsx" --include="*.ts"

Any hits are stragglers to fix.

Step 2: Grep for dark mode toggles

grep -rn "dark:" frontend/src/ --include="*.tsx" --include="*.ts"

We're dark-only — dark: prefixes are dead code and should be cleaned to just the dark variant.

Step 3: Fix any stragglers found

Step 4: Verify build passes

Run: cd frontend && npm run build

Step 5: Commit

git add -A
git commit -m "refactor: clean up remaining old monochrome patterns"