Design System Refactoring Guide: Luxury Editorial Overhaul

A case study on transforming a SaaS application from a standard design system to a luxury editorial aesthetic, using AI-assisted development with Cursor and the Superdesign workflow.

---

Executive Summary

This guide documents how we refactored an entire application (~70 files, 3,500+ lines changed) from a standard shadcn/ui design system to a luxury editorial aesthetic inspired by high-end fashion magazines (Vogue, Kinfolk) and luxury brands (Chanel, Hermès, Aesop).

Key Outcomes:

• 69 files modified across components, routes, and styling
• Complete design token overhaul (colors, typography, spacing)
• Removal of dark mode for light-only luxury theme
• Addition of signature visual effects (paper noise, grid lines, slow animations)

---

Table of Contents

1. The Power of a Detailed Design Specification
2. Superdesign Integration
3. The Approach
4. Full Design System Specification
5. Codebase Architecture That Made It Easy
6. Implementation Walkthrough
7. Key Files and Changes
8. Lessons Learned
9. Replicating This Workflow

---

The Power of a Detailed Design Specification

The single most important factor in this refactor's success was the comprehensive design specification provided upfront. Here's why it worked:

What Made the Specification Effective

1. Explicit Values, Not Vague Descriptions

Instead of saying "use a warm color palette," we specified exact hex values:

❌ Vague: "Use warm, luxury colors"
✅ Specific: "--background: #F9F8F6 (Alabaster) — Not pure white. This off-white feels like expensive paper."

2. Semantic Naming with Context

Each token included its purpose and reasoning:

--background: #F9F8F6;  /* Warm Alabaster — feels like expensive paper or linen */
--foreground: #1A1A1A;  /* Rich Charcoal — not pure black, softer, more sophisticated */
--accent: #D4AF37;      /* Metallic Gold — use sparingly, for hover states only */

3. Anti-Patterns Were Explicit

The spec included 13 specific "DO NOT" rules:

1. DO NOT use rounded corners — Everything must be 0px border-radius
2. DO NOT use pure black (#000000) or pure white (#FFFFFF)
3. DO NOT use fast animations — Minimum 500ms for interactions
4. DO NOT use vibrant colors — Stick to monochromatic + gold accent

This prevented the AI from falling back to generic patterns.

4. Component-Level Specifications

Each component had detailed styling rules:

### Button
- Shape: Rectangular, 0px border-radius
- Height: h-12 (48px), h-14 large, h-10 small
- Typography: Uppercase, text-xs, tracking-[0.2em]
- Primary Hover: Gold layer slides in from left using transform
- Shadow: 0_4px_16px deepens to 0_8px_24px on hover

5. Motion Timing Was Prescriptive

Not just "slow animations" but specific durations:

Interaction	Duration
Button hovers	duration-500 (500ms)
Color transitions	duration-700 (700ms)
Image effects	duration-[1500ms] to duration-[2000ms]

6. "Bold Factor" Elements Were Enumerated

The 10 signature elements that make the design distinctive:

1. Vertical text labels (writing-mode: vertical-rl)
2. Drop caps (Playfair, 7xl, float-left)
3. Mixed italic headlines with gold emphasis
4. Grayscale images with 1500ms color reveal
5. Visible grid lines (4 vertical)
6. Gold sliding button animation
7. Decorative horizontal lines
8. Extreme type scale (text-9xl headlines)
9. Layered subtle shadows
10. Testimonial multi-layer hover effects

---

Superdesign Integration

What is Superdesign?

Superdesign is a design agent skill that helps with:

1. Finding design inspirations and styles
2. Generating and iterating design drafts on an infinite canvas
3. Analyzing existing codebases to understand UI context

Superdesign Library: Pre-Built Design System Prompts

One of Superdesign's most powerful features is its library of curated design system prompts. Instead of writing a design specification from scratch, you can start with a pre-built prompt and customize it.

Example: Mosaic Grid Architecture Style

From Superdesign Library:

Mosaic Grid Architecture Style

An architectural, technical-blueprint style design system featuring a minimalist mosaic grid, forest green (#1A3C2B) and light-gray paper-textured (#F7F7F5) palette. Optimized for B2B SaaS, developer tools, and high-end agency portfolios. Key features include editorial typography with Space Grotesk, JetBrains Mono labels, bento grid layouts, and 2D flat wireframe aesthetics with zero shadows.

This prompt includes:

• Color palette: Forest green (#1A3C2B), paper-textured cream (#F7F7F5)
• Typography: Space Grotesk headlines, JetBrains Mono for labels
• Layout: Bento grid, mosaic panels, high negative space
• Style tags: neutral, low contrast, industrial, minimal, SaaS landing

How to Use Library Prompts:

1. Browse the Superdesign Library for style inspiration
2. Copy the full prompt or just the style/layout sections
3. Use it directly in superdesign iterate-design-draft -p "..."
4. Customize the tokens to match your brand (swap colors, fonts)

The library provides starting points for many aesthetics:

• Luxury/Editorial (like our refactor)
• Technical/Blueprint
• Playful/Toy-like
• Brutalist/Raw
• Soft/Pastel
• And many more...

The library prompts follow the same structure as our Luxury Editorial spec: explicit values, component rules, anti-patterns, and signature "bold factor" elements.

Why Design Prompts Matter: Avoiding "AI Slop"

As noted by the Superdesign team:

"LLMs often output AI slop design not because of capability, but lack of context & guidance. However, design-related prompts are not straightforward and most people don't know how to prompt it."

This is exactly why we created a comprehensive 500-line design specification. The AI is fully capable of implementing sophisticated designs—it just needs:

1. Explicit values (exact hex codes, not "warm colors")
2. Component-level rules (not just "make buttons look nice")
3. Anti-patterns (what NOT to do is as important as what to do)
4. Signature elements (the "bold factors" that make it distinctive)

The Superdesign Library solves this by providing community-driven design prompts covering styles, animations, and UI components that you can use directly or customize.

How Superdesign Fits This Workflow

Step 1: Init — Analyze the Codebase

When you first use Superdesign, it analyzes your repo and creates context files:

.superdesign/init/
├── components.md   — Shared UI primitives inventory
├── layouts.md      — Full source code of layout components
├── routes.md       — Route/page mapping
└── theme.md        — Design tokens, CSS variables, Tailwind config

This analysis captures your existing design system, which is crucial for:

• Understanding what tokens already exist
• Identifying which components need updating
• Mapping routes to plan page-by-page refactoring

Step 2: Create Design Draft — Faithful Reproduction

Before changing anything, create a draft of your current UI:

superdesign create-design-draft \
  --project-id <id> \
  --title "Current UI" \
  -p "Faithfully reproduce the existing design" \
  --context-file src/Component.tsx

Step 3: Iterate — Apply New Design System

Then iterate with the new design direction:

superdesign iterate-design-draft \
  --draft-id <id> \
  -p "luxury editorial" \
  -p "0px border radius" \
  -p "gold accents" \
  --mode branch \
  --context-file app/components/ui/button.tsx

Step 4: Execute Flow — Extend to Pages

Apply the design across multiple pages:

superdesign execute-flow-pages \
  --draft-id <id> \
  --pages '["pricing", "home", "settings"]' \
  --context-file app/routes/

Why Superdesign + Design Spec Work Together

Superdesign Provides	Design Spec Provides
Visual canvas for iteration	Exact token values
Codebase context analysis	Component-level rules
Before/after comparisons	Anti-patterns to avoid
Multi-page flow planning	Typography hierarchy

The design specification acts as the source of truth that Superdesign references when generating or iterating on designs.

Superdesign's Init Files as Reference

The .superdesign/init/theme.md file captures your current design tokens:

# Theme Analysis

## CSS Variables
:root {
  --radius: 0.65rem;
  --background: oklch(1 0 0);
  --primary: oklch(0.45 0.15 260);
}

## Tailwind Config
- Using CSS-first config in app/app.css
- Semantic color tokens mapped via @theme inline

This becomes your "before" state, making it easy to:

1. See exactly what needs to change
2. Verify nothing was missed
3. Document the transformation

---

The Approach

Step 1: Create a Comprehensive Design Specification

Before writing any code, we created a detailed design system document (<design-system>) that specified:

• Design Philosophy: Core principles and aesthetic direction
• Design Tokens: Colors, typography, spacing, shadows, borders
• Component Styling: Button, Card, Input, and other component specifications
• Layout Principles: Grid systems, spacing, asymmetry rules
• Bold Factor Elements: Signature effects that make the design distinctive
• Anti-Patterns: What NOT to do (critical for AI-assisted development)

Why This Matters: The design specification acts as a contract that both humans and AI can follow consistently across 70+ files.

Step 2: Use Structured Planning with Subagents

We used the plan-with-subagents skill to break down the work into discrete tasks:

Task 1: Update design tokens (CSS variables)
Task 2: Add fonts (root.tsx)
Task 3-6: Refactor core components (Button, Card, Input, etc.)
Task 7: Add visual effects (paper noise, grid lines)
Task 8-11: Refactor pages (marketing, platform, admin, auth)
Task 12: Polish and micro-interactions
Task 13-16: Testing and documentation

Each task was assigned to the appropriate subagent type (generalPurpose for implementation, tester for verification, context-keeper for documentation).

Step 3: Leverage the Frontend Design Skill

The frontend-design skill guided the AI to:

• Choose bold aesthetic directions (not generic AI aesthetics)
• Focus on typography, color, motion, spatial composition
• Implement signature luxury elements (grayscale images, gold accents, slow animations)
• Avoid anti-patterns like rounded corners, harsh shadows, vibrant colors

---

Full Design System Specification

Below is the complete design specification that was provided to the AI. This level of detail is what enabled consistent implementation across 70+ files.

Click to expand the full specification (~500 lines)

Design Philosophy

Core Principles: Elegance through restraint, precision, and depth. This style emulates high-end fashion magazines (Vogue, Harper's Bazaar, Kinfolk) and luxury brand websites (Chanel, Hermès, Aesop). Success depends on:

• Exquisite typography hierarchy
• Generous negative space
• Slow cinematic motion
• Intentional asymmetry
• Layered depth through subtle shadows

Vibe: Sophisticated, Timeless, Expensive, Serene, Curated, Deliberate, Editorial, Tactile.

The Secret: Luxury isn't about adding decoration—it's about removing everything unnecessary and perfecting what remains. Every element must feel intentional and considered.

Colors (Sophisticated Monochrome)

Primary Palette:

Token	Value	Purpose
Background	#F9F8F6 (Warm Alabaster)	Not pure white. Feels like expensive paper or linen.
Foreground	#1A1A1A (Rich Charcoal)	Not pure black. Softer, more sophisticated.
Muted Background	#EBE5DE (Pale Taupe)	Surface elevation, disabled states.
Muted Foreground	#6C6863 (Warm Grey)	Secondary text, captions, metadata.
Accent	#D4AF37 (Metallic Gold)	Use sparingly. Hover states, underlines, focus indicators.
Accent Foreground	#FFFFFF (Pure White)	Only on top of dark backgrounds or gold.

Layering Strategy:

• Use opacity for borders: #1A1A1A at 10-20% opacity
• Dark sections use inverted palette
• Never use pure black or pure white for text

Typography (The Most Critical Element)

Font Pairing:

• Heading Font: "Playfair Display" — Elegant, editorial, high-contrast serif
• Body Font: "Inter" — Clean, modern, highly legible humanist sans-serif

Type Scale:

Element	Size	Line Height	Tracking
Hero Headlines	text-6xl to text-9xl	leading-[0.9]	tracking-tight
Section Headlines	text-5xl to text-7xl	leading-tight	tracking-tight
Subsection Titles	text-3xl to text-4xl	default	default
Body Text	text-base to text-lg	leading-relaxed (1.625)	default
Overlines/Labels	text-xs	default	tracking-[0.25em] to tracking-[0.3em]
Micro-text	text-[10px]	default	tracking-[0.2em]

Font Weight Distribution:

• Playfair: Regular (400) for most, Light (300) for contrast, Italic (400) for emphasis
• Inter: Medium (500) for buttons/links, Regular (400) for body, Light (300) sparingly

Radius & Borders (Architectural Precision)

Border Radius: 0px — Strictly rectangular. No rounded corners anywhere.

Border Treatment:

• Width: Always 1px
• Color: #1A1A1A at full opacity for strong borders, 10-20% for dividers
• Style: Single borders (border-t, border-b) rather than full boxes

Shadows & Effects (Subtle Layered Depth)

Element	Shadow Value
Hero Image	shadow-[0_8px_32px_rgba(0,0,0,0.12)]
Feature Images	shadow-[0_4px_24px_rgba(0,0,0,0.08)]
Blog Images	shadow-[0_4px_20px_rgba(0,0,0,0.06)] → shadow-[0_8px_32px_rgba(0,0,0,0.12)] on hover
Cards	shadow-[0_2px_8px_rgba(0,0,0,0.02)] → shadow-[0_8px_24px_rgba(0,0,0,0.06)] on hover
Primary Buttons	shadow-[0_4px_16px_rgba(0,0,0,0.15)] → shadow-[0_8px_24px_rgba(0,0,0,0.25)] on hover

Paper Noise Texture:

• Subtle SVG noise texture overlay at 2% opacity
• Fixed position, pointer-events disabled, z-index 50
• Creates "expensive paper" tactile feel

Image Treatment:

• Default: Grayscale filter (grayscale)
• Hover: Full color (grayscale-0)
• Transition: duration-[1500ms] to duration-[2000ms]
• Transform: Subtle scale on hover (group-hover:scale-105)

Component Styling

Buttons:

• Shape: Rectangular, 0px border-radius
• Height: h-12 default (48px), h-14 large, h-10 small
• Padding: Generous horizontal (px-8 to px-10)
• Typography: Uppercase, text-xs, tracking-[0.2em], medium weight

Primary Button Hover:

• Gold layer slides in from left using transform
• Initial: translate-x-[-100%]} (off-screen)
• Hover: translate-x-0 (covers button)
• Duration: 500ms with cubic-bezier(0.25, 0.46, 0.45, 0.94)

Cards:

• Background: Transparent (bg-transparent)
• Border: Single top border (border-t) only
• Padding: Generous (p-8 mobile, p-12 desktop)
• Hover: Subtle background shift (hover:bg-[#F9F8F6]/50)

Inputs:

• Border: Bottom only (border-b), no other borders
• Background: Transparent
• Focus: Border changes to gold (focus-visible:border-[#D4AF37])
• Placeholder: Playfair Display font, italic, warm grey

Animation & Motion (Cinematic Timing)

Interaction Type	Duration
Button interactions	duration-500 (500ms)
Color transitions	duration-700 (700ms)
Image effects	duration-[1500ms] to duration-[2000ms]
Background transitions	duration-700 (700ms)

Easing:

• Default: ease-out
• Custom: cubic-bezier(0.25, 0.46, 0.45, 0.94) for smooth luxury feel
• Never: ease-in-out or ease-in (too mechanical)

Layout Principles

Asymmetric Composition:

• Avoid 50/50 splits — use 7/5, 4/4/4, or offset column starts
• Bottom-left alignment for primary content
• Start content at column 2 or 6, leaving deliberate empty space

Vertical Spacing:

• Section padding: py-24 to py-32 (6rem to 8rem)
• Component padding: p-8 to p-12
• If it feels like too much space, it's probably correct

The "Bold Factor" (Non-Genericness)

These 10 signature elements must be present:

1. Vertical Text Labels: writing-mode: vertical-rl for decorative side labels
2. Drop Caps: Large initial letter, Playfair, 7xl, float-left, mr-3
3. Mixed Italic Headlines: Alternate italic words with gold color
4. Grayscale Image Transitions: 1500-2000ms color reveal on hover
5. Visible Grid Lines: 4 fixed vertical lines at 20% opacity
6. Gold Sliding Animation: Primary button hover with translateX transform
7. Decorative Horizontal Lines: h-px w-8 spacing elements
8. Extreme Type Scale: text-9xl headlines with text-[10px] labels
9. Layered Shadows: Subtle shadows that deepen on hover
10. Testimonial Interactions: Multi-layer coordinated hover effects

Anti-Patterns (What to Avoid)

1. DO NOT use rounded corners — 0px border-radius everywhere
2. DO NOT use harsh shadows — Only subtle shadows with low opacity
3. DO NOT use pure black or pure white — Use charcoal and alabaster
4. DO NOT use fast animations — Minimum 500ms, images 1500-2000ms
5. DO NOT use vibrant colors — Monochromatic + gold accent only
6. DO NOT center everything — Use asymmetry, offset columns
7. DO NOT overcrowd spacing — More space is better
8. DO NOT use decorative fonts — Only Playfair and Inter
9. DO NOT use icons prominently — Lucide with thin strokes, sparingly
10. DO NOT make gold dominant — Accent only, not primary
11. DO NOT use small images — Large, prominent, portrait aspect ratios
12. DO NOT use tight tracking on body — Only labels get wide tracking
13. DO NOT skip grayscale filter — All images default to grayscale

---

Color Palette (Summary)

Token	Value	Purpose
--background	#F9F8F6 (Alabaster)	Warm paper-like background
--foreground	#1A1A1A (Charcoal)	Rich text color (not pure black)
--muted	#EBE5DE (Pale Taupe)	Surface elevation, disabled states
--muted-foreground	#6C6863 (Warm Grey)	Secondary text
--accent	#D4AF37 (Metallic Gold)	Hover states, focus indicators
--border	rgba(26, 26, 26, 0.15)	Subtle dividers

Key Insight: The warm undertones (alabaster, not pure white; charcoal, not pure black) create the luxury feel. This is the #1 difference from generic UI.

Typography Pairing

--font-display: "Playfair Display", Georgia, serif;  /* Headlines */
--font-body: "Inter", system-ui, sans-serif;         /* Body text */

Element	Size	Font	Tracking
Hero Headlines	text-6xl to text-9xl	Playfair Display	tracking-tight
Section Headlines	text-5xl to text-7xl	Playfair Display	tracking-tight
Body Text	text-base to text-lg	Inter	default
Labels	text-xs	Inter	tracking-[0.25em]

Border Radius: 0px Everywhere

This is non-negotiable for luxury/editorial design:

--radius: 0;

Sharp corners create architectural precision. Every component was updated to use rounded-none.

Motion: Slow and Cinematic

Interaction	Duration
Button hovers	500ms
Color transitions	700ms
Image effects	1500-2000ms

---

Codebase Architecture That Made It Easy

1. Centralized Design Tokens (app/app.css)

All design decisions flow from CSS variables in a single file:

:root {
  --radius: 0;
  --background: #F9F8F6;
  --foreground: #1A1A1A;
  --accent: #D4AF37;
  /* ... */
}

Why It Helped: Changing 20+ color values in one file automatically propagated to all components using bg-background, text-foreground, etc.

2. shadcn/ui Component Architecture

Components in app/components/ui/ use CSS variables through Tailwind:

// Before: Used semantic tokens
<div className="bg-card text-card-foreground rounded-xl border">

// After: Same tokens, new values + removed rounded
<div className="bg-card text-card-foreground border-t">

Why It Helped: We didn't need to find/replace hex colors. We updated the token values, and styling followed.

3. Tailwind CSS v4 with CSS-First Config

No tailwind.config.js needed. Everything in app/app.css:

@theme inline {
  --color-background: var(--background);
  --color-primary: var(--primary);
  --color-accent: var(--accent);
  /* Maps CSS vars to Tailwind utilities */
}

Why It Helped: Design tokens and Tailwind configuration lived in the same file, making changes atomic.

4. Consistent Component Patterns

Every shadcn component follows the same pattern:

function Component({ className, ...props }) {
  return (
    <element
      className={cn("base-styles", className)}
      {...props}
    />
  )
}

Why It Helped: We could search for patterns like rounded-xl and systematically replace them across all components.

5. Route-Based File Organization

app/routes/
├── marketing/          # All marketing pages
├── platform/           # All platform pages  
├── admin/              # All admin pages
└── authentication/     # All auth pages

Why It Helped: We could tackle pages by domain, ensuring consistent styling within each section.

---

Implementation Walkthrough

Phase 1: Design Token Foundation

File: app/app.css

1. Updated :root color variables to luxury palette
2. Removed .dark block entirely (light-only theme)
3. Set --radius: 0 for sharp corners globally
4. Added paper noise and grid line utilities

/* Before */
:root {
  --radius: 0.65rem;
  --background: oklch(1 0 0);
  --primary: oklch(0.45 0.15 260);  /* Deep Indigo */
}

/* After */
:root {
  --radius: 0;
  --background: #F9F8F6;  /* Alabaster */
  --primary: #1A1A1A;     /* Charcoal */
  --accent: #D4AF37;      /* Gold */
}

Phase 2: Core Component Updates

Button (app/components/ui/button.tsx):

// Key changes
const buttonVariants = cva(
  "... rounded-none tracking-wider uppercase text-xs transition-all duration-500 ...",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-accent shadow-[0_4px_16px_rgba(0,0,0,0.15)] hover:shadow-[0_8px_24px_rgba(0,0,0,0.25)]",
        outline: "border border-foreground bg-transparent hover:bg-foreground hover:text-background",
      },
      size: {
        default: "h-12 px-8",  // Taller buttons
      },
    },
  }
)

Card (app/components/ui/card.tsx):

// Before: Full border + rounded + shadow
"bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm"

// After: Top border only + no rounded
"bg-transparent text-card-foreground flex flex-col border-t border-foreground/15 py-8"

Input (app/components/ui/input.tsx):

// Before: Full border + rounded
"border-input rounded-md border bg-transparent px-3"

// After: Bottom border only
"border-0 border-b border-foreground/30 bg-transparent px-0 focus-visible:border-accent"

Phase 3: Page Refactoring

Pattern for each page:

1. Remove all dark: classes
2. Replace rounded corners with rounded-none
3. Update typography to use Playfair for headlines
4. Add slow transitions (duration-500 to duration-[1500ms])
5. Apply grayscale to images with color reveal on hover

Example from app/routes/home.tsx:

// Hero headline with massive Playfair type
<h1 className="font-serif text-6xl md:text-9xl font-normal tracking-tight leading-[0.9]">
  Market Research,{" "}
  <span className="italic text-accent">Reimagined</span>
</h1>

// Grayscale image with slow color reveal
<img 
  className="grayscale transition-all duration-[1500ms] group-hover:grayscale-0 group-hover:scale-105"
  src="..."
/>

Phase 4: Visual Effects

Paper Noise Texture:

.paper-noise::before {
  content: '';
  position: fixed;
  inset: 0;
  background-image: url("data:image/svg+xml,...");
  opacity: 0.02;
  pointer-events: none;
  z-index: 50;
}

Grid Lines (4 vertical):

<div className="fixed inset-0 pointer-events-none z-40 hidden lg:flex justify-between max-w-[1600px] mx-auto px-16">
  <div className="w-px h-full bg-foreground/10" />
  <div className="w-px h-full bg-foreground/10" />
  <div className="w-px h-full bg-foreground/10" />
  <div className="w-px h-full bg-foreground/10" />
</div>

---

Key Files and Changes

Files Modified (69 total)

Category	Files	Key Changes
Core Styling	app/app.css	Design tokens, removed dark mode, added luxury utilities
Root Layout	app/root.tsx	Added Inter font, paper noise, grid lines
UI Components	14 files in app/components/ui/	0px radius, removed dark classes, updated variants
Marketing	12 pages	Luxury typography, grayscale images, editorial layouts
Platform	15+ components	Border-top cards, slow animations, gold accents
Admin	8 files	Sidebar styling, table formatting
Auth	4 files	Underline inputs, centered forms

Most Impactful Changes

1. app/app.css - 308 lines changed

   • All design tokens updated
   • Dark mode removed (57 lines deleted)
   • New luxury utility classes added

2. app/components/ui/card.tsx - 133 lines changed

   • Complete redesign from bordered cards to border-top editorial style

3. app/routes/marketing/pricing.tsx - 282 lines changed

   • Full page redesign with luxury pricing cards

---

Lessons Learned

What Worked Well

1. Comprehensive Design Spec First

   • The detailed <design-system> document ensured consistency across all changes
   • AI could reference specific values instead of making assumptions

2. Centralized Design Tokens

   • CSS variables in one file made global changes trivial
   • Tailwind's token mapping meant no find/replace for colors

3. Systematic Task Breakdown

   • Plan-with-subagents approach ensured nothing was missed
   • Each task had clear scope and success criteria

4. Anti-Patterns Section

   • Explicitly stating what NOT to do prevented AI from making common mistakes
   • "Never use rounded corners" is clearer than "use sharp corners"

Challenges Encountered

1. Dark Mode Removal

   • Required searching for all dark: prefixes across 70+ files
   • Some components had dark-specific logic that needed refactoring

2. Component Dependencies

   • Some components inherited styles from parent components
   • Required understanding the full component tree

3. Image Handling

   • Not all images worked well with grayscale filter
   • Required case-by-case decisions on which images to filter

Recommendations for Future Refactors

1. Start with the smallest change that has the biggest impact

   • Updating app/app.css tokens changed the entire app instantly

2. Create before/after screenshots

   • Visual documentation helps verify changes are correct

3. Use feature flags for gradual rollout

   • Could have used PostHog flags to A/B test the new design

4. Test on all viewport sizes

   • Luxury design often requires different mobile treatment

---

Replicating This Workflow

Step 1: Create Your Design Specification

Use this template:

# Design System: [Your Style Name]

## Design Philosophy
- Core principles (3-5 bullet points)
- Aesthetic direction
- Key differentiators

## Design Tokens
### Colors
| Token | Value | Purpose |
|-------|-------|---------|
| --background | #... | ... |

### Typography
- Display font: ...
- Body font: ...
- Type scale table

### Spacing & Radius
- Border radius: ...
- Section padding: ...

## Component Styling
### Button
- Base styles: ...
- Variants: ...
- Hover states: ...

### Card
- Structure: ...
- Borders: ...

## Bold Factor Elements
1. [Signature element 1]
2. [Signature element 2]

## Anti-Patterns
1. DO NOT use [specific thing]
2. DO NOT use [specific thing]

Step 2: Set Up Your Codebase

Ensure you have:

• Centralized CSS variables (not scattered hex colors)
• Component library using semantic tokens
• Consistent file organization

Step 3: Use the Skills

1. Attach the frontend-design skill
2. Provide your <design-system> specification
3. Use plan-with-subagents for task breakdown
4. Execute systematically by domain (core → components → pages)

Step 4: Validate

• Visual inspection of all pages
• Check all viewport sizes
• Verify animations and transitions
• Test interactive states (hover, focus, active)

---

Appendix: Tools and Skills Used

Skills Reference

Skill	Purpose	When to Use
frontend-design	Guides creation of distinctive UI with specific aesthetic direction	Attach when making UI changes that need design thinking
plan-with-subagents	Structures complex work into tasks with subagent assignments	Use for multi-file refactors, new features
superdesign	Visual design iteration on infinite canvas	Use for exploring design directions before coding

Superdesign IDE Extension

Superdesign is the first open-source design agent that lives inside your IDE. It works with:

• Cursor (recommended)
• Windsurf
• Claude Code
• VS Code

Key capabilities:

• Prompt-to-IDE: Copy prompts directly into your AI IDE
• Infinite Canvas: Explore multiple design variations in parallel
• Local Storage: Designs saved in .superdesign/ folder
• Fork & Iterate: Create branches of designs to explore different directions

After initializing Superdesign, it adds Cursor rules that enable the agent to generate designs and preview them in the Superdesign canvas (Cmd+Shift+P → "Superdesign: Open Canvas").

Superdesign Commands Reference

# Initialize — analyze repo and create context files
superdesign init

# Create faithful reproduction of current UI
superdesign create-design-draft \
  --project-id <id> \
  --title "Current UI" \
  -p "Faithfully reproduce the existing design" \
  --context-file app/components/ui/button.tsx

# Iterate with new design direction
superdesign iterate-design-draft \
  --draft-id <id> \
  -p "luxury editorial aesthetic" \
  -p "0px border radius" \
  -p "gold accents on hover" \
  --mode branch \
  --context-file app/components/ui/button.tsx

# Extend design to multiple pages
superdesign execute-flow-pages \
  --draft-id <id> \
  --pages '["pricing", "home", "settings"]' \
  --context-file app/routes/

How the Pieces Fit Together

┌─────────────────────────────────────────────────────────────────┐
│                     DESIGN SPECIFICATION                        │
│  (Detailed tokens, rules, anti-patterns, bold factor elements)  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        SUPERDESIGN                              │
│  1. Init → Analyze codebase, create .superdesign/init/ files    │
│  2. Draft → Visual exploration of design directions             │
│  3. Iterate → Refine designs with prompts from spec             │
│  4. Execute → Generate code for multiple pages                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    FRONTEND-DESIGN SKILL                        │
│  Guides AI to implement distinctive UI following the spec       │
│  - Bold aesthetic choices (not generic AI aesthetics)           │
│  - Typography, color, motion, spatial composition focus         │
│  - Anti-pattern avoidance                                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   PLAN-WITH-SUBAGENTS SKILL                     │
│  Breaks work into discrete tasks with subagent assignments      │
│  - Task 1: generalPurpose → Update CSS tokens                   │
│  - Task 2: generalPurpose → Refactor Button component           │
│  - Task 3: tester → Verify implementation                       │
│  - Task 4: context-keeper → Update documentation                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      CURSOR AGENT MODE                          │
│  Executes each task, modifying files across the codebase        │
│  - Reads design spec for reference                              │
│  - Updates CSS variables in app/app.css                         │
│  - Modifies components in app/components/ui/                    │
│  - Refactors pages in app/routes/                               │
└─────────────────────────────────────────────────────────────────┘

Tech Stack That Enabled This

Technology	Why It Helped
Tailwind CSS v4	CSS-first config means tokens and utilities in same file
shadcn/ui	Components use semantic tokens, not hardcoded colors
CSS Custom Properties	Change once in :root, applies everywhere
React Router v7	Route-based file organization for systematic updates
cn() utility	Consistent class merging pattern across all components

---

Commit Reference

Commit: 43d3388 - "refactor: Luxury editorial design system overhaul (#14)"

Stats:

• 69 files changed
• 2,110 insertions
• 1,557 deletions
• Net: +553 lines

Key Files in Commit:

• app/app.css - Design tokens
• app/components/ui/* - Component updates
• app/routes/marketing/* - Marketing pages
• app/routes/platform/* - Platform pages
• app/routes/admin/* - Admin pages
• app/routes/authentication/* - Auth pages