Material UI (MUI) Development Skill

A Claude Code skill for building applications with Material UI — covering component usage, theme customization, the sx prop, responsive design, and MUI v7 patterns for React applications.

When to Use This Skill

Choose this skill when:

• Building React UIs with Material UI components
• Customizing MUI themes (colors, typography, spacing)
• Using the sx prop for component-level styling
• Implementing responsive layouts with MUI's breakpoint system
• Migrating between MUI versions (v5 → v6 → v7)
• Creating custom MUI components with consistent theming

Consider alternatives when:

• You want a utility-first CSS approach (use Tailwind CSS)
• You need a headless component library (use Radix or Headless UI)
• You're not using React (MUI is React-only)

Quick Start

Copy
# Install MUI v7
npm install @mui/material @emotion/react @emotion/styled
npm install @mui/icons-material  # Optional: icon library

Copy
// App setup with theme provider
import { ThemeProvider, createTheme } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';

const theme = createTheme({
  palette: {
    primary: { main: '#2563eb' },
    secondary: { main: '#7c3aed' },
    mode: 'light',
  },
  typography: {
    fontFamily: '"Inter", "Roboto", "Helvetica", sans-serif',
  },
  shape: { borderRadius: 8 },
});

function App() {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      <MyContent />
    </ThemeProvider>
  );
}

Core Concepts

Component Categories

Category	Components	Purpose
Layout	Box, Container, Grid, Stack	Page structure, spacing
Input	TextField, Select, Checkbox, Radio	Form controls
Navigation	AppBar, Drawer, Tabs, Breadcrumbs	App navigation
Data Display	Table, List, Card, Typography	Content presentation
Feedback	Alert, Snackbar, Dialog, Skeleton	User feedback
Surface	Paper, Accordion, Card	Content containers

The sx Prop

Copy
import { Box, Typography, Button } from '@mui/material';

function StyledCard() {
  return (
    <Box sx={{
      p: 3,                          // padding: theme.spacing(3)
      m: 2,                          // margin: theme.spacing(2)
      bgcolor: 'background.paper',   // theme palette reference
      borderRadius: 2,               // theme.shape.borderRadius * 2
      boxShadow: 3,                  // theme.shadows[3]
      '&:hover': {
        boxShadow: 6,
        transform: 'translateY(-2px)',
      },
      // Responsive values
      width: { xs: '100%', sm: '50%', md: '33%' },
      display: { xs: 'block', md: 'flex' },
    }}>
      <Typography variant="h6" color="text.primary">
        Card Title
      </Typography>
      <Button variant="contained" sx={{ mt: 2 }}>
        Action
      </Button>
    </Box>
  );
}

Theme Customization

Copy
const theme = createTheme({
  palette: {
    primary: { main: '#2563eb', light: '#60a5fa', dark: '#1d4ed8' },
    secondary: { main: '#7c3aed' },
    error: { main: '#ef4444' },
    background: { default: '#fafafa', paper: '#ffffff' },
  },
  typography: {
    h1: { fontSize: '2.5rem', fontWeight: 700 },
    h2: { fontSize: '2rem', fontWeight: 600 },
    body1: { fontSize: '1rem', lineHeight: 1.6 },
    button: { textTransform: 'none' },  // Disable uppercase buttons
  },
  components: {
    MuiButton: {
      defaultProps: { disableElevation: true },
      styleOverrides: {
        root: { borderRadius: 8, padding: '8px 16px' },
        contained: { fontWeight: 600 },
      },
    },
    MuiTextField: {
      defaultProps: { variant: 'outlined', size: 'small' },
    },
  },
});

Configuration

Parameter	Type	Default	Description
palette.mode	string	"light"	Color mode: light, dark
palette.primary.main	string	"#1976d2"	Primary brand color
typography.fontFamily	string	"Roboto"	Default font family
shape.borderRadius	number	4	Base border radius in pixels
spacing	number	8	Base spacing unit in pixels
breakpoints	object	{ xs: 0, sm: 600, md: 900, lg: 1200, xl: 1536 }	Responsive breakpoints
components	object	{}	Component-level default props and overrides

Best Practices

1. Use the sx prop for one-off styles, theme for global patterns — apply sx for component-specific adjustments; use theme.components for styles that should be consistent across all instances of a component.

2. Reference theme tokens, not raw values in sx — use p: 2 not padding: '16px', and color: 'primary.main' not color: '#1976d2'; token references automatically adapt to theme changes and dark mode.

3. Disable button text transform globally — MUI's default textTransform: 'uppercase' on buttons is a common complaint; set typography.button.textTransform: 'none' in your theme.

4. Use responsive values in sx for breakpoint-based styling — width: { xs: '100%', md: '50%' } is cleaner and more readable than media query wrappers.

5. Compose with Stack and Grid instead of manual spacing — <Stack spacing={2}> and <Grid container spacing={3}> handle gaps consistently; avoid manual margin/padding between sibling elements.

Common Issues

Dark mode flash on page load — The initial render uses light mode before the theme applies. Use getInitialColorSchemeScript() from @mui/material/styles for server-rendered apps to prevent the flash.

Bundle size is too large — MUI with all icons can add 200KB+ to your bundle. Use direct imports (@mui/icons-material/Search not @mui/icons-material) and tree-shaking to include only used components.

Custom theme colors don't appear in TypeScript autocomplete — Extend MUI's type definitions with module augmentation to add custom palette colors so sx={{ color: 'custom.main' }} gets type checking.