Design System Refactor 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: Refactor all ~90 TSX files to follow DESIGN.md design systems — Premium UI for public/booking pages, MONO for admin — by replacing hardcoded hex values with CSS variables and fixing border-radius violations.

Architecture: Systematic find/replace approach with explicit CSS variable mapping. Each file type (booking, admin, shows) has a consistent substitution pattern. Admin interfaces convert from current Premium UI dark theme to MONO stark white/black theme.

Tech Stack: Tailwind CSS v4 (CSS-first config), CSS custom properties, CVA variants

Critical Decision Required FIRST

Admin Design System: MONO or Premium UI?

If admin stays Premium UI → 3-day simpler refactor (just CSS var substitution) If admin converts to MONO → 7-10 day full refactor

Recommend: Keep admin on Premium UI for now (matches current visual design, faster to ship). Create separate ADMIN.md design note to revisit MONO migration later.

This plan assumes: Admin stays on Premium UI — adjust tasks if decision changes.

CSS Variable Substitution Map

Premium UI (Booking, Shows, Public pages)

File Inventory by Area

Area 1: Booking Flow (15 files, ~2-3 days)

Area 2: Shows Pages (5 files, ~1 day)

Area 3: Admin Components (30 files, ~1-2 days) — Keeping Premium UI

Area 4: UI Components Library (~50 files, ~1-2 days)

Most already correct. Verify and fix:

• components/ui/button.tsx — DONE (gold variant fixed)
• components/ui/input.tsx — verify CSS vars
• components/ui/card.tsx — verify CSS vars
• components/ui/dialog.tsx — TBD
• components/ui/dropdown-menu.tsx — TBD
• components/ui/select.tsx — TBD
• components/ui/calendar.tsx — TBD
• components/ui/badge.tsx — TBD

Task Breakdown

Phase 1: Booking Flow Components

Task 1: Fix show-card.tsx

Files:

• Modify: apps/frontend/components/booking/show-card.tsx

• Step 1: Read current file

Run: Read apps/frontend/components/booking/show-card.tsx Expected: See hardcoded hex values bg-[#2E2E2E], text-[#C5A059], text-[#808080], bg-[#4d4d4d], text-[#1a1a1a]

• Step 2: Replace hardcoded hex with CSS variables

Replace each occurrence using the substitution map:

bg-[#2E2E2E] → bg-[var(--color-surface)]
text-[#C5A059] → text-[var(--color-gold)]
text-[#808080] → text-[var(--color-muted-foreground)]
bg-[#4d4d4d] → bg-[var(--color-surface)]/50 (or var(--color-border))
text-[#1a1a1a] → keep as-is (contrast text on gold)

• Step 3: Verify and commit

Run: grep -E '\[#[0-9A-Fa-f]{6}\]' apps/frontend/components/booking/show-card.tsx Expected: No matches

Commit: git add components/booking/show-card.tsx && git commit -m "refactor(booking): use CSS vars in show-card"

Task 2: Fix step-indicator.tsx

Files:

• Modify: apps/frontend/components/booking/step-indicator.tsx

• Step 1: Read current file

• Step 2: Replace hardcoded hex

Substitutions:

bg-[#C5A059] → bg-[var(--color-gold)]
text-[#1a1a1a] → inline #1a1a1a (contrast on gold)
text-[#C5A059] → text-[var(--color-gold)]
bg-[#3d3d3d] → bg-[var(--color-surface)]
text-[#808080] → text-[var(--color-muted-foreground)]
bg-[#4d4d4d] → bg-[var(--color-border)]

• Step 3: Verify and commit

Run: grep -E '\[#[0-9A-Fa-f]{6}\]' apps/frontend/components/booking/step-indicator.tsx Expected: No matches

Commit: git add components/booking/step-indicator.tsx && git commit -m "refactor(booking): use CSS vars in step-indicator"

Task 3: Fix checkout-form.tsx

Files:

• Modify: apps/frontend/components/booking/checkout-form.tsx

• Step 1: Read current file

• Step 2: Replace hardcoded hex

Substitutions:

text-[#808080] → text-[var(--color-muted-foreground)]
border-[#4d4d4d] → border-[var(--color-border)]
bg-[#C5A059] → bg-[var(--color-gold)]
text-[#1a1a1a] → inline #1a1a1a

• Step 3: Verify and commit

Commit: git add components/booking/checkout-form.tsx && git commit -m "refactor(booking): use CSS vars in checkout-form"

Task 4: Fix calendar-section.tsx

Files:

• Modify: apps/frontend/components/booking/calendar-section.tsx

• Step 1: Read current file

• Step 2: Replace hardcoded hex + fix border-radius

Substitutions:

bg-[#2E2E2E] → bg-[var(--color-surface)]
text-[#C5A059] → text-[var(--color-gold)]
text-[#e6e6e6] → text-[var(--color-foreground)]
bg-[#3d3d3d] → bg-[var(--color-surface)]/80
text-[#4d4d4d] → text-[var(--color-muted-foreground)]
rounded-lg → rounded-[var(--radius)]
rounded-full → rounded-full (keep for pills)

• Step 3: Verify and commit

Commit: git add components/booking/calendar-section.tsx && git commit -m "refactor(booking): use CSS vars and radius in calendar-section"

Task 5: Fix step-tickets.tsx

Files:

• Modify: apps/frontend/components/booking/step-tickets.tsx

• Step 1: Read current file

• Step 2: Replace hardcoded hex

Substitutions:

bg-[#2E2E2E] → bg-[var(--color-surface)]
text-[#C5A059] → text-[var(--color-gold)]
text-[#808080] → text-[var(--color-muted-foreground)]
text-[#e6e6e6] → text-[var(--color-foreground)]
bg-[#C5A059] → bg-[var(--color-gold)]

• Step 3: Verify and commit

Commit: git add components/booking/step-tickets.tsx && git commit -m "refactor(booking): use CSS vars in step-tickets"

Task 6: Batch fix remaining booking components

Files:

• Modify: checkout-summary.tsx

• Modify: confirmation-display.tsx

• Modify: ticket-selector.tsx

• Modify: addon-card.tsx

• Modify: sticky-cart.tsx

• Modify: countdown-timer.tsx

• Modify: payment-form.tsx

• Modify: guest-form.tsx

• Modify: booking-layout.tsx

• Modify: booking-steps.tsx

• Step 1: Run bulk audit

Run: grep -rEn '\[#[0-9A-Fa-f]{6}\]' apps/frontend/components/booking/ Expected: List of remaining hardcoded hex values

• Step 2: Fix each file systematically

For each file, read and apply CSS var substitutions per the map.

• Step 3: Verify and commit

Run: grep -rEn '\[#[0-9A-Fa-f]{6}\]' apps/frontend/components/booking/ Expected: No matches

Commit: git add components/booking/ && git commit -m "refactor(booking): CSS vars for remaining components"

Phase 2: Shows Pages

Task 7: Fix show-detail-client.tsx

Files:

• Modify: apps/frontend/components/shows/show-detail-client.tsx

• Step 1: Read current file

• Step 2: Replace hardcoded hex + fix border-radius

Substitutions:

bg-[#1a1a1a] → bg-[var(--color-background)]
bg-[#2E2E2E] → bg-[var(--color-surface)]
text-[#C5A059] → text-[var(--color-gold)]
text-[#e6e6e6] → text-[var(--color-foreground)]
text-[#808080] → text-[var(--color-muted-foreground)]
border-[#DEC89E] → border-[var(--color-gold-border)]
rounded-full → rounded-full (keep for badges)
rounded-lg → rounded-[var(--radius)]

• Step 3: Verify and commit

Commit: git add components/shows/show-detail-client.tsx && git commit -m "refactor(shows): use CSS vars in show-detail-client"

Task 8: Fix show-occurrence-list.tsx

Files:

• Modify: apps/frontend/components/shows/show-occurrence-list.tsx

• Step 1: Read and fix

Substitutions:

border-[#4d4d4d] → border-[var(--color-border)]
text-[#e6e6e6] → text-[var(--color-foreground)]
text-[#808080] → text-[var(--color-muted-foreground)]
text-[#C5A059] → text-[var(--color-gold)]

• Step 2: Verify and commit

Commit: git add components/shows/show-occurrence-list.tsx && git commit -m "refactor(shows): use CSS vars in show-occurrence-list"

Task 9: Batch fix remaining shows components

Files:

• Modify: show-hero.tsx

• Modify: show-gallery.tsx

• Step 1: Audit and fix remaining shows files

Run: grep -rEn '\[#[0-9A-Fa-f]{6}\]' apps/frontend/components/shows/ Expected: No matches after fix

• Step 2: Commit

Commit: git add components/shows/ && git commit -m "refactor(shows): CSS vars for remaining components"

Phase 3: Admin Components (Premium UI — keeping current dark theme)

Task 10: Fix metric-card.tsx

Files:

• Modify: apps/frontend/components/admin/metric-card.tsx

• Step 1: Read current file

• Step 2: Replace hardcoded hex + fix border-radius

Substitutions:

bg-[#1a1a1a] → bg-[var(--color-background)] (or bg-card)
border-[#333333] → border-[var(--color-border)]
text-[#808080] → text-[var(--color-muted-foreground)]
text-[#C5A059] → text-[var(--color-gold)]
text-[#e6e6e6] → text-[var(--color-foreground)]
rounded-lg → rounded-[var(--radius)]

• Step 3: Verify and commit

Commit: git add components/admin/metric-card.tsx && git commit -m "refactor(admin): use CSS vars in metric-card"

Task 11: Fix sidebar.tsx

Files:

• Modify: apps/frontend/components/admin/sidebar.tsx

• Step 1: Read current file

• Step 2: Replace hardcoded hex + fix border-radius

Substitutions:

border-[#333333] → border-[var(--color-border)]
text-[#C5A059] → text-[var(--color-gold)]
bg-[#C5A059]/10 → bg-[var(--color-gold)]/10
text-[#808080] → text-[var(--color-muted-foreground)]
text-[#e6e6e6] → text-[var(--color-foreground)]
bg-[#0a0a0f] → bg-[var(--color-background)]
rounded-lg → rounded-[var(--radius)]
rounded-full → rounded-full (keep for pills/avatars)

• Step 3: Verify and commit

Commit: git add components/admin/sidebar.tsx && git commit -m "refactor(admin): use CSS vars in sidebar"

Task 12: Fix ticket-detail.tsx (checkin)

Files:

• Modify: apps/frontend/components/admin/checkin/ticket-detail.tsx

• Step 1: Read and fix

Substitutions:

bg-[#2E2E2E] → bg-[var(--color-surface)]
rounded-lg → rounded-[var(--radius)]
text-[#C5A059] → text-[var(--color-gold)]
bg-[#C5A059]/20 → bg-[var(--color-gold)]/20
rounded-full → rounded-full (keep)

• Step 2: Commit

Commit: git add components/admin/checkin/ticket-detail.tsx && git commit -m "refactor(admin): use CSS vars in ticket-detail"

Task 13: Batch fix remaining admin components

Files:

• Modify: stat-badge.tsx, occurrence-preview.tsx, occurrence-modal.tsx

• Modify: reservation-table.tsx, at-risk-list.tsx, recent-reservations.tsx

• Modify: addon-row.tsx, show-table-row.tsx

• Modify: addons-table.tsx, addon-form-dialog.tsx

• Modify: batch-generation-form.tsx, show-form.tsx

• Modify: cancel-modal.tsx, expanded-day-dialog.tsx

• Modify: calendar-day.tsx, reservations-skeleton.tsx

• Modify: calendar-legend.tsx, occurrence-calendar.tsx

• Modify: day-toggle.tsx, addons-page.tsx

• Step 1: Run bulk audit

Run: grep -rEn '\[#[0-9A-Fa-f]{6}\]' apps/frontend/components/admin/ Expected: List of remaining hardcoded hex values

• Step 2: Fix each file systematically

For each file:

1. Read the file
2. Apply CSS var substitutions
3. Replace rounded-lg → rounded-[var(--radius)] (except where rounded-full is semantically correct for pills/avatars)
4. Verify no hardcoded hex remains

• Step 3: Verify and commit

Run: grep -rEn '\[#[0-9A-Fa-f]{6}\]' apps/frontend/components/admin/ Expected: No matches

Commit: git add components/admin/ && git commit -m "refactor(admin): CSS vars for all components"

Phase 4: UI Components Library

Task 14: Verify UI component library

Files:

• Modify: components/ui/dialog.tsx

• Modify: components/ui/dropdown-menu.tsx

• Modify: components/ui/select.tsx

• Modify: components/ui/calendar.tsx

• Modify: components/ui/badge.tsx

• Step 1: Audit UI components

Run: grep -rEn '\[#[0-9A-Fa-f]{6}\]' apps/frontend/components/ui/ Expected: May show button.tsx if not yet fixed (should be done)

• Step 2: Fix any remaining issues

For any UI component with hardcoded hex, apply substitutions.

• Step 3: Commit

Commit: git add components/ui/ && git commit -m "refactor(ui): verify and fix CSS vars in component library"

Phase 5: Global Verification

Task 15: Final audit

• Step 1: Run full project scan

Run: grep -rEn '\[#[0-9A-Fa-f]{6}\]' apps/frontend/components/ apps/frontend/app/ Expected: Only legitimate uses (e.g., inline #1a1a1a for gold foreground contrast, or in comments)

• Step 2: Check border-radius consistency

Run: grep -rEn 'rounded-lg' apps/frontend/components/admin/ (should have none after refactor) Expected: No matches in admin (should use var(--radius) instead)

• Step 3: Run typecheck

Run: cd apps/frontend && npx tsc --noEmit Expected: No type errors

• Step 4: Test key pages

Test in browser:

• Homepage (Premium UI)

• Shows page (Premium UI)

• Booking flow (Premium UI)

• Admin dashboard (Premium UI)

• Step 5: Final commit

Commit: git commit -m "chore: complete design system refactor - all CSS vars" (if any remaining changes)

Self-Review Checklist

• All hardcoded hex values replaced with CSS variables
• rounded-lg replaced with rounded-[var(--radius)] in Premium UI contexts
• rounded-full kept for pills/avatars where semantically correct
• No functional changes — only visual/CSS substitutions
• Typecheck passes
• All phases committed separately for easy rollback

Future: MONO Admin Migration (Not in Scope)

If admin migrates to MONO design system:

1. Background: #ffffff everywhere
2. Text/borders: #292929
3. Replace --color-gold usage with #292929 accents
4. Replace all rounded-[var(--radius)] with rounded-none
5. Update metric-card.tsx, sidebar.tsx, etc. with MONO variants

Estimated: 3-4 additional days.