From 6efabff0904549265b9799bc71005e8ae344a2e9 Mon Sep 17 00:00:00 2001 From: Michael Chihlas Date: Sun, 22 Mar 2026 00:01:33 -0400 Subject: [PATCH] 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) --- .../2026-03-22-design-system-v4-migration.md | 665 ++++++++++++++++++ 1 file changed, 665 insertions(+) create mode 100644 docs/superpowers/plans/2026-03-22-design-system-v4-migration.md diff --git a/docs/superpowers/plans/2026-03-22-design-system-v4-migration.md b/docs/superpowers/plans/2026-03-22-design-system-v4-migration.md new file mode 100644 index 00000000..bafb7c62 --- /dev/null +++ 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) " +``` + +--- + +## 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) " +``` + +--- + +## 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) " +``` + +--- + +## 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) " +``` + +--- + +## 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) " +``` + +--- + +## 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) " +``` + +--- + +## 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) " +``` + +--- + +## 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) " +``` + +--- + +## 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) " +```