Overview

Migrate the MUI theme system to Tailwind CSS design tokens and CSS variables.

Parent Issue: #18993
Estimated Duration: 5-7 days
Priority: High
Depends on: #18994 (Setup)

Theme Usage Analysis

• 806 theme property references across the codebase
• 7 direct theme/styles imports
• 1 useMediaQuery usage
• 1 createTheme usage
• 1 useTheme usage

Current Theme Structure

MUI Theme Properties Used

• theme.palette.* - Color system
• theme.spacing() - Spacing scale
• theme.breakpoints.* - Responsive breakpoints
• theme.typography.* - Typography scale
• theme.shadows.* - Shadow system
• theme.shape.* - Border radius
• theme.zIndex.* - Z-index scale

Tasks

Design Token Migration

• Audit all theme.palette references
• Convert color palette to CSS variables
• Migrate spacing system to Tailwind scale
• Update typography scale
• Convert shadow system
• Migrate border radius values
• Update z-index scale

Breakpoint Migration

• Convert theme.breakpoints to Tailwind breakpoints
• Update useMediaQuery usage
• Migrate responsive design patterns
• Update container queries

Dark Mode Migration

• Convert MUI dark mode to Tailwind dark mode
• Update CSS variable definitions
• Migrate theme switching logic
• Test dark/light mode transitions

Component Theme Integration

• Update ThemeProvider implementation
• Migrate theme-dependent components
• Convert styled-components to Tailwind
• Update theme context usage

Implementation Strategy

Phase 1: Foundation (Days 1-2)

• Set up CSS variables for colors
• Configure Tailwind with design tokens
• Create theme utility functions
• Update base styles

Phase 2: Color Migration (Days 3-4)

• Convert all palette references
• Update component color usage
• Migrate semantic color tokens
• Test color consistency

Phase 3: Layout & Typography (Days 5-6)

• Migrate spacing references
• Update typography scale
• Convert responsive patterns
• Update component layouts

Phase 4: Polish & Testing (Day 7)

• Final theme adjustments
• Dark mode testing
• Performance optimization
• Documentation updates

Color System Migration

Primary Colors

/* CSS Variables */
:root {
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 84% 4.9%;
  --secondary: 210 40% 96%;
  --secondary-foreground: 222.2 84% 4.9%;
  --muted: 210 40% 96%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96%;
  --accent-foreground: 222.2 84% 4.9%;
}

[data-theme="dark"] {
  --primary: 222.2 84% 4.9%;
  --primary-foreground: 210 40% 98%;
  /* ... */
}

Tailwind Configuration

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
        },
        // ...
      },
    },
  },
}

Migration Patterns

Color References

// Before (MUI)
color: theme.palette.primary.main
backgroundColor: theme.palette.background.paper

// After (Tailwind)
className="text-primary bg-background"

Spacing References

// Before (MUI)
padding: theme.spacing(2)
margin: theme.spacing(1, 2)

// After (Tailwind)
className="p-2 mx-2 my-1"

Responsive Design

// Before (MUI)
[theme.breakpoints.up('md')]: {
  display: 'flex'
}

// After (Tailwind)
className="md:flex"

Files to Update

Core Theme Files

• src/contexts/ThemeProvider.tsx
• src/theme/ directory
• Global CSS files
• Component style files

High Usage Files

• Components with heavy theme usage
• Layout components
• Form components
• Navigation components

Acceptance Criteria

• All theme references converted to Tailwind
• Dark mode works correctly
• No visual regressions
• Performance is maintained or improved
• CSS bundle size is optimized
• All theme tests pass

Testing Requirements

• Visual regression testing
• Dark/light mode testing
• Responsive design testing
• Performance testing
• Cross-browser compatibility

Documentation

• Design token documentation
• Theme migration guide
• Dark mode implementation
• Responsive design patterns