Overview

Convert all Emotion CSS-in-JS usage to Tailwind utility classes for better performance and maintainability.

Parent Issue: #18993
Estimated Duration: 8-10 days
Priority: High
Depends on: #19001 (Theme System)

Emotion Usage Analysis

• 1,275 css= prop usages
• 187 @emotion/react imports
• 13 @emotion/css imports
• 189 files using Emotion
• 202 total Emotion-related imports

Current Emotion Patterns

Common CSS-in-JS Patterns

• Inline styles with css= prop
• Theme-based styling
• Responsive design with breakpoints
• Pseudo-class styling (hover, focus)
• Complex layout patterns
• Animation and transitions

Tasks

Phase 1: Simple Conversions (Days 1-3)

• Convert basic layout styles (margin, padding, display)
• Migrate color and background styles
• Replace typography styles
• Convert border and border-radius
• Update basic positioning

Phase 2: Responsive Design (Days 4-5)

• Convert breakpoint-based styles
• Migrate responsive layouts
• Update responsive typography
• Convert responsive spacing

Phase 3: Interactive States (Days 6-7)

• Convert hover states
• Migrate focus styles
• Update active states
• Convert disabled styles
• Handle complex pseudo-selectors

Phase 4: Complex Patterns (Days 8-9)

• Convert animations and transitions
• Migrate complex layouts (grid, flexbox)
• Update z-index and positioning
• Convert custom CSS patterns
• Handle edge cases

Phase 5: Cleanup & Optimization (Day 10)

• Remove Emotion dependencies
• Clean up unused CSS
• Optimize Tailwind configuration
• Performance testing
• Final validation

Migration Patterns

Basic Styling

// Before (Emotion)
css={{
  padding: 16,
  margin: '8px 16px',
  backgroundColor: theme.palette.background.paper,
  color: theme.palette.text.primary,
  borderRadius: 4,
}}

// After (Tailwind)
className="p-4 mx-4 my-2 bg-background text-foreground rounded"

Responsive Design

// Before (Emotion)
css={{
  display: 'block',
  [theme.breakpoints.up('md')]: {
    display: 'flex',
    flexDirection: 'row',
  },
}}

// After (Tailwind)
className="block md:flex md:flex-row"

Interactive States

// Before (Emotion)
css={{
  '&:hover': {
    backgroundColor: theme.palette.action.hover,
  },
  '&:focus': {
    outline: `2px solid ${theme.palette.primary.main}`,
  },
}}

// After (Tailwind)
className="hover:bg-accent focus:outline-2 focus:outline-primary"

Complex Layouts

// Before (Emotion)
css={{
  display: 'grid',
  gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))',
  gap: 16,
  alignItems: 'start',
}}

// After (Tailwind)
className="grid grid-cols-[repeat(auto-fit,minmax(300px,1fr))] gap-4 items-start"

Files to Update

High Priority Files (>10 css= usages)

• Layout components
• Form components
• Navigation components
• Dashboard components
• Modal/dialog components

Medium Priority Files (5-10 css= usages)

• Card components
• Button variants
• Input components
• Table components

Low Priority Files (<5 css= usages)

• Utility components
• Icon components
• Simple display components

Implementation Strategy

1. Automated Conversion: Use tools for simple patterns
2. Manual Review: Complex styles need manual conversion
3. Component-by-Component: Migrate entire components at once
4. Testing: Ensure visual parity after each conversion
5. Optimization: Remove unused Emotion code progressively

Custom Tailwind Utilities

For complex patterns that don't map directly to Tailwind:

/* Custom utilities */
@layer utilities {
  .scrollbar-hide {
    -ms-overflow-style: none;
    scrollbar-width: none;
  }
  .scrollbar-hide::-webkit-scrollbar {
    display: none;
  }
}

Acceptance Criteria

• All css= props converted to className
• No Emotion imports remaining
• Visual parity maintained
• Performance improved
• Bundle size reduced
• All tests pass
• No CSS-in-JS runtime overhead

Performance Benefits

• Reduced Bundle Size: Remove Emotion runtime
• Better Caching: Static CSS files
• Faster Rendering: No runtime CSS generation
• Better Tree Shaking: Unused utilities removed
• Improved Dev Experience: Better tooling support

Testing Requirements

• Visual regression testing for all converted components
• Performance benchmarking
• Bundle size analysis
• Cross-browser compatibility
• Mobile responsiveness
• Dark mode functionality

Tools and Utilities

• Tailwind CSS IntelliSense: VS Code extension
• Headwind: Class sorting extension
• Twin.macro: For gradual migration (if needed)
• Custom scripts: For automated pattern conversion

Documentation

• Migration patterns guide
• Custom utility documentation
• Performance optimization guide
• Troubleshooting common issues