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:

```tsx
{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:

```tsx
{/* 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**

```bash
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**

```bash
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**

```bash
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**

```bash
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**

```bash
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**

```bash
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**

```bash
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**

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

```bash
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**

```bash
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**

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