metabuilder/docs/RADIX_TO_MUI_MIGRATION.md

UI Framework Migration Summary

Date: December 25, 2025
Migration: Radix UI + Tailwind CSS → Material-UI + SASS

Changes Made

1. Dependencies Updated

Removed

• All @radix-ui/* packages (28 packages)
• tailwind-merge
• tw-animate-css
• class-variance-authority
• clsx
• lucide-react
• @heroicons/react
• @phosphor-icons/react
• next-themes (replaced with custom MUI theme provider)
• sonner (use MUI Snackbar instead)
• vaul (use MUI Drawer instead)
• embla-carousel-react (use MUI components)
• react-resizable-panels (use MUI Grid/Stack)
• react-day-picker (use @mui/x-date-pickers)
• input-otp (create custom with MUI TextField)

Added

• @mui/material ^6.3.1
• @mui/icons-material ^6.3.1
• @mui/x-data-grid ^7.24.2
• @mui/x-date-pickers ^7.24.1
• @emotion/react ^11.13.5
• @emotion/styled ^11.13.5

2. New Files Created

1. /frontends/nextjs/src/theme/mui-theme.ts

   • Light and dark theme configurations
   • Custom color palettes matching project design
   • Typography setup for IBM Plex Sans, Space Grotesk, JetBrains Mono
   • Component style overrides

2. /UI_STANDARDS.md (project root)

   • Clear policy against Radix UI and Tailwind
   • Quick start guide for MUI
   • Component alternatives table
   • Instructions for AI assistants and developers

3. /docs/UI_MIGRATION.md

   • Complete component mapping reference
   • Code examples for common patterns
   • Tailwind to MUI sx prop conversion guide
   • SASS module pattern examples
   • Migration checklist

4. /frontends/nextjs/src/components/ui/README.md

   • Warning about legacy components
   • Quick reference for developers
   • Links to migration resources

3. Modified Files

1. /frontends/nextjs/package.json

   • Updated dependencies (see above)
   • All Radix UI removed from devDependencies
   • Material-UI added to dependencies

2. /frontends/nextjs/src/app/providers.tsx

   • Replaced next-themes ThemeProvider with MUI ThemeProvider
   • Added custom theme context with mode switching
   • Integrated CssBaseline for consistent baseline styles
   • Added useTheme hook for accessing theme state

3. /frontends/nextjs/src/app/layout.tsx

   • Removed Tailwind className from body
   • Removed sonner Toaster component
   • Simplified layout (fonts still loaded via CDN)

4. /.github/copilot-instructions.md

   • Added UI Components & Styling section at top of Code Conventions
   • Clear warnings against Radix UI and Tailwind
   • Component mapping examples
   • Updated Styling section to reference MUI theme file

Installation Instructions

To apply these changes:

cd frontends/nextjs

# Remove old dependencies and install new ones
rm -rf node_modules package-lock.json
npm install

# Verify installation
npm list @mui/material @mui/icons-material

Next Steps for Developers

Immediate Actions Required

1. Run npm install to get the new dependencies
2. Review migration guide at /docs/UI_MIGRATION.md
3. Update existing components that use Radix UI or Tailwind classes

Migrating Existing Components

When you encounter a component using the old system:

1. Replace Radix UI imports with MUI equivalents
2. Convert Tailwind className props to MUI sx props or SCSS
3. Use @mui/icons-material for icons
4. Test in both light and dark modes

Example Migration

Before:

import { Dialog, DialogContent } from '@/components/ui/dialog'
import { Button } from '@/components/ui/button'

<div className="flex gap-4 p-6 bg-gray-100">
  <Button className="bg-blue-500 text-white">
    Click me
  </Button>
  <Dialog>
    <DialogContent className="max-w-2xl">
      Content
    </DialogContent>
  </Dialog>
</div>

After:

import { Dialog, DialogContent, Button, Box } from '@mui/material'

<Box sx={{ display: 'flex', gap: 2, p: 3, bgcolor: 'grey.100' }}>
  <Button variant="contained" color="primary">
    Click me
  </Button>
  <Dialog>
    <DialogContent sx={{ maxWidth: 600 }}>
      Content
    </DialogContent>
  </Dialog>
</Box>

Breaking Changes

⚠️ All existing UI components in /src/components/ui/ are now legacy and should not be used.

Components that currently import from these files will break until migrated. The files remain temporarily for reference but should be considered deprecated.

High-Priority Components to Migrate

Based on grep search, these components have heavy Radix UI usage:

• User Management forms
• Error fallback components
• Dialog-based workflows
• Form inputs and selects
• Navigation menus
• Data tables

Benefits of This Change

1. Single UI Library: Reduced complexity, easier maintenance
2. Better Theming: Integrated light/dark mode with MUI theme system
3. More Features: Data grids, date pickers, advanced components out of the box
4. Better Documentation: MUI has comprehensive docs and examples
5. Consistency: One styling approach (SASS + sx prop) instead of multiple
6. TypeScript: Better type safety with MUI components
7. Accessibility: MUI components follow WCAG guidelines

Resources

• UI Standards: /UI_STANDARDS.md
• Migration Guide: /docs/UI_MIGRATION.md
• Theme Config: /frontends/nextjs/src/theme/mui-theme.ts
• MUI Docs: https://mui.com/material-ui/
• MUI Icons: https://mui.com/material-ui/material-icons/

Support

Questions about migration? Check:

1. /docs/UI_MIGRATION.md - Complete examples
2. GitHub Copilot - Updated with new standards
3. MUI documentation - Comprehensive component guides

---

Status: ✅ Infrastructure complete. Individual component migration in progress.