Assist_Design/docs/DESIGN-SYSTEM-MIGRATION.md

# Design System Migration Guide

## Overview

We've refactored the design system to be **lean and Tailwind-first**. The utilities file went from **555 lines → 134 lines** by removing duplicated Tailwind utilities and keeping only semantic component primitives.

## What Changed

### ✅ **Kept (Semantic Primitives)**
- `.cp-card`, `.cp-card-sm`, `.cp-card-lg`
- `.cp-badge` and all badge variants
- `.cp-skeleton` (with shimmer animation)
- `.cp-focus-ring`, `.cp-focus-ring-visible`

### ❌ **Removed (Use Tailwind Instead)**
All layout, spacing, typography, and responsive utilities that duplicated Tailwind:
- `.cp-container`, `.cp-page`, `.cp-page-header`, etc.
- `.cp-stack-*`, `.cp-inline-*`, `.cp-grid-*`
- `.cp-grid-cols-*` and responsive variants
- `.cp-transition-*`, `.cp-hover-lift`, `.cp-hover-scale`
- `.cp-text-*`, `.cp-font-*`, `.cp-leading-*`
- `.cp-hidden`, `.cp-block`, `.cp-flex`, etc.
- `.cp-sr-only` (use Tailwind's `sr-only` instead)

## Migration Map

### Layout & Container

**Before:**
```jsx
<div className="cp-container">
  <div className="cp-page">
    <header className="cp-page-header">
      <h1>Dashboard</h1>
    </header>
    <main className="cp-page-content">
      {/* content */}
    </main>
  </div>
</div>
```

**After:**
```jsx
<div className="w-full max-w-7xl mx-auto px-[var(--cp-page-padding)]">
  <div className="min-h-dvh flex flex-col">
    <header className="border-b border-[var(--border)] bg-[var(--background)] px-[var(--cp-page-padding)] py-[var(--cp-space-4)]">
      <h1>Dashboard</h1>
    </header>
    <main className="flex-1 px-[var(--cp-page-padding)] py-[var(--cp-page-padding)]">
      {/* content */}
    </main>
  </div>
</div>
```

### Spacing (Stack & Inline)

**Before:**
```jsx
<div className="cp-stack-lg">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

<div className="cp-inline-sm">
  <span>Label</span>
  <span>Value</span>
</div>
```

**After:**
```jsx
<div className="space-y-[var(--cp-space-4)]">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

<div className="flex items-center gap-[var(--cp-space-2)]">
  <span>Label</span>
  <span>Value</span>
</div>
```

### Grid

**Before:**
```jsx
<div className="cp-grid-lg cp-grid-cols-3 cp-md:grid-cols-2 cp-sm:grid-cols-1">
  <div>Card 1</div>
  <div>Card 2</div>
  <div>Card 3</div>
</div>
```

**After:**
```jsx
<div className="grid gap-[var(--cp-space-4)] grid-cols-1 sm:grid-cols-2 lg:grid-cols-3">
  <div>Card 1</div>
  <div>Card 2</div>
  <div>Card 3</div>
</div>
```

### Transitions & Hover Effects

**Before:**
```jsx
<div className="cp-card cp-transition cp-hover-lift">
  Content
</div>
```

**After:**
```jsx
<div className="cp-card transition-all duration-200 hover:-translate-y-0.5 hover:shadow-[var(--cp-card-shadow-lg)]">
  Content
</div>
```

### Typography

**Before:**
```jsx
<h1 className="cp-text-2xl cp-font-bold cp-leading-tight">Title</h1>
<p className="cp-text-sm cp-font-normal cp-leading-normal cp-text-muted-foreground">
  Description
</p>
```

**After:**
```jsx
<h1 className="text-2xl font-bold leading-tight">Title</h1>
<p className="text-sm font-normal leading-normal text-muted-foreground">
  Description
</p>
```

**If you need exact token values:**
```jsx
<h1 className="text-[var(--cp-text-2xl)] font-[var(--cp-font-bold)] leading-[var(--cp-leading-tight)]">
  Title
</h1>
```

### Responsive Utilities

**Before:**
```jsx
<div className="cp-hidden cp-md:block">Desktop only</div>
<div className="cp-block cp-md:hidden">Mobile only</div>
```

**After:**
```jsx
<div className="hidden md:block">Desktop only</div>
<div className="block md:hidden">Mobile only</div>
```

### Accessibility (Screen Reader Only)

**Before:**
```jsx
<span className="cp-sr-only">Hidden text</span>
```

**After:**
```jsx
<span className="sr-only">Hidden text</span>
```

## Cards & Badges (No Change)

These remain the same - they're semantic primitives:

```jsx
// Cards - still use cp-card classes
<div className="cp-card">
  <div className="cp-card-sm">Small padding</div>
  <div className="cp-card-lg">Large with enhanced shadow</div>
</div>

// Badges - still use cp-badge classes
<span className="cp-badge cp-badge-success">Active</span>
<span className="cp-badge cp-badge-soft-warning">Pending</span>
<span className="cp-badge cp-badge-outline">Neutral</span>

// Skeleton - still use cp-skeleton
<div className="cp-skeleton h-24 w-full"></div>

// Focus ring - still use cp-focus-ring
<button className="cp-focus-ring-visible">Accessible button</button>
```

## Design Token Usage

You can reference design tokens directly in Tailwind classes:

```jsx
// Spacing
<div className="px-[var(--cp-page-padding)] py-[var(--cp-space-6)]">

// Colors
<div className="bg-[var(--primary)] text-[var(--primary-foreground)]">
<div className="border-[var(--border)]">

// Shadows
<div className="shadow-[var(--cp-card-shadow-lg)]">

// Radii
<div className="rounded-[var(--cp-card-radius)]">

// Typography
<h1 className="text-[var(--cp-text-3xl)] font-[var(--cp-font-bold)]">
```

## Benefits

1. **90% smaller CSS** - from 555 lines to 134 lines
2. **No duplication** - Tailwind handles layout, spacing, typography
3. **More flexible** - Direct access to all Tailwind utilities
4. **Design tokens first** - Colors and spacing still centralized
5. **Easier maintenance** - Less custom CSS to maintain
6. **Better DX** - Tailwind's IntelliSense and autocomplete work better

## Search & Replace Patterns

Here are some common patterns you can search for in your codebase:

1. `className="cp-container"` → `className="w-full max-w-7xl mx-auto px-[var(--cp-page-padding)]"`
2. `className="cp-stack-lg"` → `className="space-y-[var(--cp-space-4)]"`
3. `className="cp-inline-sm"` → `className="flex items-center gap-[var(--cp-space-2)]"`
4. `className="cp-grid"` → `className="grid gap-4"`
5. `className="cp-transition"` → `className="transition-all duration-200"`
6. `className="cp-hover-lift"` → `className="hover:-translate-y-0.5 hover:shadow-lg"`
7. `className="cp-text-` → `className="text-` (remove `cp-` prefix)
8. `className="cp-font-` → `className="font-` (remove `cp-` prefix)
9. `className="cp-sr-only"` → `className="sr-only"`

## Example: Complete Component Migration

### Before:
```jsx
export function DashboardPage() {
  return (
    <div className="cp-container">
      <div className="cp-page">
        <header className="cp-page-header">
          <h1 className="cp-text-2xl cp-font-bold">Dashboard</h1>
        </header>
        <main className="cp-page-content">
          <div className="cp-grid-lg cp-grid-cols-3 cp-md:grid-cols-2">
            <div className="cp-card cp-transition cp-hover-lift">
              <div className="cp-inline-sm">
                <Icon className="cp-text-primary" />
                <h2 className="cp-text-lg cp-font-semibold">Stats</h2>
              </div>
              <p className="cp-text-sm cp-text-muted-foreground">Content</p>
            </div>
          </div>
        </main>
      </div>
    </div>
  );
}
```

### After:
```jsx
export function DashboardPage() {
  return (
    <div className="w-full max-w-7xl mx-auto px-[var(--cp-page-padding)]">
      <div className="min-h-dvh flex flex-col">
        <header className="border-b border-[var(--border)] bg-[var(--background)] px-[var(--cp-page-padding)] py-[var(--cp-space-4)]">
          <h1 className="text-2xl font-bold">Dashboard</h1>
        </header>
        <main className="flex-1 px-[var(--cp-page-padding)] py-[var(--cp-page-padding)]">
          <div className="grid gap-[var(--cp-space-4)] grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
            <div className="cp-card transition-all duration-200 hover:-translate-y-0.5 hover:shadow-[var(--cp-card-shadow-lg)]">
              <div className="flex items-center gap-[var(--cp-space-2)]">
                <Icon className="text-primary" />
                <h2 className="text-lg font-semibold">Stats</h2>
              </div>
              <p className="text-sm text-muted-foreground">Content</p>
            </div>
          </div>
        </main>
      </div>
    </div>
  );
}
```

## Notes

- The migration doesn't have to happen all at once
- Both old and new patterns will work during the transition
- Focus on new components using the new approach
- Gradually update old components as you touch them
- The design tokens remain the same, so colors and spacing are consistent