docs: add Design System v4 migration implementation plan

9 tasks: CSS foundation, icon rail sidebar, component sweep (~200 files across 6 directory-group commits), landing page, cleanup. Plan reviewed and all issues addressed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-22 00:01:33 -04:00
parent 1de0b50ce4
commit 6efabff090
1 changed files with 665 additions and 0 deletions
--- a/docs/superpowers/plans/2026-03-22-design-system-v4-migration.md
+++ b/docs/superpowers/plans/2026-03-22-design-system-v4-migration.md
@@ -0,0 +1,665 @@
+# 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>"
+```