SKILL.md

MUI v7 Patterns

Purpose

Material-UI v7 (released March 2025) patterns for component usage, styling with sx prop, theme integration, and responsive design.

Note: MUI v7 breaking changes from v6:

Deep imports no longer work - use package exports field

onBackdropClick removed from Modal - use onClose instead

All components now use standardized slots and slotProps pattern

CSS layers support via enableCssLayer config (works with Tailwind v4)

When to Use This Skill

Styling components with MUI sx prop

Using MUI components (Box, Grid, Paper, Typography, etc.)

Theme customization and usage

Responsive design with MUI breakpoints

MUI-specific utilities and hooks

Quick Start

Basic MUI Component

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

import type { SxProps, Theme } from '@mui/material';

const styles: Record<string, SxProps<Theme>> = {

  container: {

    p: 2,

    display: 'flex',

    flexDirection: 'column',

    gap: 2,

  },

  header: {

    mb: 3,

    fontSize: '1.5rem',

    fontWeight: 600,

  },

};

function MyComponent() {

  return (

    <Paper sx={styles.container}>

      <Typography sx={styles.header}>

        Title

      </Typography>

      <Button variant="contained">

        Action

      </Button>

    </Paper>

  );

}

Styling Patterns

Inline Styles (= 100 lines)

For complex components, create separate style file:

// UserProfile.styles.ts

import type { SxProps, Theme } from '@mui/material';

export const userProfileStyles: Record<string, SxProps<Theme>> = {

  container: {

    p: 3,

    maxWidth: 800,

    mx: 'auto',

  },

  header: {

    display: 'flex',

    justifyContent: 'space-between',

    alignItems: 'center',

    mb: 3,

  },

  // ... many more styles

};

// UserProfile.tsx

import { userProfileStyles as styles } from './UserProfile.styles';

function UserProfile() {

  return <Box sx={styles.container}>...</Box>;

}

Common Components

Layout Components

// Box - Generic container

<Box sx={{ p: 2, bgcolor: 'background.paper' }}>

  Content

</Box>

// Paper - Elevated surface

<Paper elevation={2} sx={{ p: 3 }}>

  Content

</Paper>

// Container - Centered content with max-width

<Container maxWidth="lg">

  Content

</Container>

// Stack - Flex container with spacing

<Stack spacing={2} direction="row">

  <Item />

  <Item />

</Stack>

Grid System

import { Grid } from '@mui/material';

// 12-column grid

<Grid container spacing={2}>

  <Grid item xs={12} md={6}>

    Left half

  </Grid>

  <Grid item xs={12} md={6}>

    Right half

  </Grid>

</Grid>

// Responsive grid

<Grid container spacing={3}>

  <Grid item xs={12} sm={6} md={4} lg={3}>

    Card

  </Grid>

  {/* Repeat for more cards */}

</Grid>

Typography

<Typography variant="h1">Heading 1</Typography>

<Typography variant="h2">Heading 2</Typography>

<Typography variant="body1">Body text</Typography>

<Typography variant="caption">Small text</Typography>

// With custom styling

<Typography

  variant="h4"

  sx={{

    color: 'primary.main',

    fontWeight: 600,

    mb: 2,

  }}

>

  Custom Heading

</Typography>

Buttons

// Variants

<Button variant="contained">Contained</Button>

<Button variant="outlined">Outlined</Button>

<Button variant="text">Text</Button>

// Colors

<Button variant="contained" color="primary">Primary</Button>

<Button variant="contained" color="secondary">Secondary</Button>

<Button variant="contained" color="error">Error</Button>

// With icons

import { Add as AddIcon } from '@mui/icons-material';

<Button startIcon={<AddIcon />}>Add Item</Button>

Theme Integration

Using Theme Values

import { useTheme } from '@mui/material';

function Component() {

  const theme = useTheme();

  return (

    <Box

      sx={{

        p: 2,

        bgcolor: theme.palette.primary.main,

        color: theme.palette.primary.contrastText,

        borderRadius: theme.shape.borderRadius,

      }}

    >

      Themed box

    </Box>

  );

}

Theme in sx Prop

<Box

  sx={{

    // Access theme in sx

    color: 'primary.main',          // theme.palette.primary.main

    bgcolor: 'background.paper',     // theme.palette.background.paper

    p: 2,                            // theme.spacing(2)

    borderRadius: 1,                 // theme.shape.borderRadius

  }}

>

  Content

</Box>

// Callback for advanced usage

<Box

  sx={(theme) => ({

    color: theme.palette.primary.main,

    '&#x26;:hover': {

      color: theme.palette.primary.dark,

    },

  })}

>

  Hover me

</Box>

Responsive Design

Breakpoints

// Mobile-first responsive values

<Box

  sx={{

    width: {

      xs: '100%',    // 0-600px

      sm: '80%',     // 600-900px

      md: '60%',     // 900-1200px

      lg: '40%',     // 1200-1536px

      xl: '30%',     // 1536px+

    },

  }}

>

  Responsive width

</Box>

// Responsive display

<Box

  sx={{

    display: {

      xs: 'none',    // Hidden on mobile

      md: 'block',   // Visible on desktop

    },

  }}

>

  Desktop only

</Box>

Responsive Typography

<Typography

  sx={{

    fontSize: {

      xs: '1rem',

      md: '1.5rem',

      lg: '2rem',

    },

    lineHeight: {

      xs: 1.5,

      md: 1.75,

    },

  }}

>

  Responsive text

</Typography>

Forms

import { TextField, Stack, Button } from '@mui/material';

<Box component="form" onSubmit={handleSubmit}>

  <Stack spacing={2}>

    <TextField

      label="Email"

      type="email"

      value={email}

      onChange={(e) => setEmail(e.target.value)}

      fullWidth

      required

      error={!!errors.email}

      helperText={errors.email}

    />

    <Button type="submit" variant="contained">Submit</Button>

  </Stack>

</Box>

Common Patterns

Card Component

import { Card, CardContent, CardActions, Typography, Button } from '@mui/material';

<Card>

  <CardContent>

    <Typography variant="h5" component="div">

      Title

    </Typography>

    <Typography variant="body2" color="text.secondary">

      Description

    </Typography>

  </CardContent>

  <CardActions>

    <Button size="small">Learn More</Button>

  </CardActions>

</Card>

Dialog/Modal

import { Dialog, DialogTitle, DialogContent, DialogActions, Button } from '@mui/material';

<Dialog open={open} onClose={handleClose}>

  <DialogTitle>Confirm Action</DialogTitle>

  <DialogContent>

    Are you sure you want to proceed?

  </DialogContent>

  <DialogActions>

    <Button onClick={handleClose}>Cancel</Button>

    <Button onClick={handleConfirm} variant="contained">

      Confirm

    </Button>

  </DialogActions>

</Dialog>

Loading States

import { CircularProgress, Skeleton } from '@mui/material';

// Spinner

<Box sx={{ display: 'flex', justifyContent: 'center', p: 3 }}>

  <CircularProgress />

</Box>

// Skeleton

<Stack spacing={1}>

  <Skeleton variant="text" width="60%" />

  <Skeleton variant="rectangular" height={200} />

  <Skeleton variant="text" width="40%" />

</Stack>

MUI-Specific Hooks

useMuiSnackbar

import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

function Component() {

  const { showSuccess, showError, showInfo } = useMuiSnackbar();

  const handleSave = async () => {

    try {

      await saveData();

      showSuccess('Saved successfully');

    } catch (error) {

      showError('Failed to save');

    }

  };

  return <Button onClick={handleSave}>Save</Button>;

}

Icons

import { Add as AddIcon, Delete as DeleteIcon } from '@mui/icons-material';

import { Button, IconButton } from '@mui/material';

<Button startIcon={<AddIcon />}>Add</Button>

<IconButton onClick={handleDelete}><DeleteIcon /></IconButton>

Best Practices

1. Type Your sx Props

import type { SxProps, Theme } from '@mui/material';

// ✅ Good

const styles: Record<string, SxProps<Theme>> = {

  container: { p: 2 },

};

// ❌ Avoid

const styles = {

  container: { p: 2 }, // No type safety

};

2. Use Theme Tokens

// ✅ Good: Use theme tokens

<Box sx={{ color: 'primary.main', p: 2 }} />

// ❌ Avoid: Hardcoded values

<Box sx={{ color: '#1976d2', padding: '16px' }} />

3. Consistent Spacing

// ✅ Good: Use spacing scale

<Box sx={{ p: 2, mb: 3, mt: 1 }} />

// ❌ Avoid: Random pixel values

<Box sx={{ padding: '17px', marginBottom: '25px' }} />

Additional Resources

For more detailed patterns, see:

styling-guide.md - Advanced styling patterns

component-library.md - Component examples

theme-customization.md - Theme setup

mui