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:

<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:

<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:

<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:

<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:

<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:

<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:

<div className="cp-card cp-transition cp-hover-lift">
  Content
</div>

After:

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

Typography

Before:

<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:

<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:

<h1 className="text-[var(--cp-text-2xl)] font-[var(--cp-font-bold)] leading-[var(--cp-leading-tight)]">
  Title
</h1>

Responsive Utilities

Before:

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

After:

<div className="hidden md:block">Desktop only</div>
<div className="block md:hidden">Mobile only</div>

Accessibility (Screen Reader Only)

Before:

<span className="cp-sr-only">Hidden text</span>

After:

<span className="sr-only">Hidden text</span>

Cards & Badges (No Change)

These remain the same - they're semantic primitives:

// 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:

// 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:

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:

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