mui

Name: mui
Author: Softaworks

MUIMaterial-UIReactFrontendUI Componentssx propThemeResponsive Design

⭐ 2.0k📄 MIT🕒 2026-03-05Source ↗

Install this skill

npx skills add softaworks/agent-toolkit

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

MUI v7 provides a framework for building UI components in React and React Native environments. It standardizes component structure through a unified slots and slotProps system, replacing older prop-based configurations. This toolkit emphasizes type-safe styling using the sx prop, which allows direct access to theme tokens like palette colors, spacing units, and border radii. Developers can enforce consistency across applications by integrating custom themes that scale with responsive breakpoints. The framework now mandates explicit package exports for imports to ensure compatibility with modern build systems and supports CSS layers for fine-grained style control. By utilizing native Material Design patterns, the system simplifies the creation of functional interfaces, such as grids, containers, and interactive forms, while maintaining predictable layout behavior across varying screen resolutions and viewports.

When to Use This Skill

•Building responsive dashboard layouts using Grid and Box primitives
•Implementing custom design systems using theme provider overrides
•Creating interactive forms with standard Material button and input variants
•Structuring complex component layouts with separate style files for maintainability
•Handling adaptive typography and spacing based on screen size

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

“create a responsive grid layout using MUI components
“style this box using the sx prop with theme values
“define a theme for my MUI components
“refactor this component to use MUI slots and slotProps
“align typography and spacing with Material Design standards

Pro Tips

💡Always define complex `sx` props outside the component as a constant object to improve readability and maintainability, especially for conditional styles.
💡Leverage MUI's theme customization features to create a robust design system, ensuring consistent styling across your application rather than applying individual `sx` props everywhere.
💡Utilize the `slots` and `slotProps` pattern for advanced customization of internal component elements, providing more control without ejecting from the MUI component.

What this skill does

•Type-safe style definitions via sx props using theme context
•Standardized component customization through slots and slotProps
•Responsive grid system with native breakpoint support
•Direct theme token access for colors, spacing, and typography
•CSS layer integration for complex style management

When not to use it

✕Prototypes requiring zero-dependency or ultra-lightweight bundles
✕Projects needing highly customized non-Material aesthetics
✕Situations where full control over raw CSS without abstraction is mandatory

Example workflow

Configure the ThemeProvider with custom design tokens
Initialize standard layout components like Box or Container
Define styles using sx props for localized component logic
Move complex style objects into separate files for large components
Implement responsiveness using standard breakpoint tokens

Prerequisites

–React or React Native project environment
–Familiarity with TypeScript for sx prop typing

Pitfalls & limitations

!Failing to use package exports causing import errors
!Overusing inline sx objects leading to unreadable JSX
!Ignoring the shift from onBackdropClick to onClose in Modals

FAQ

How do I access theme values inside the sx prop?

The sx prop automatically resolves theme tokens. You can pass strings like 'primary.main' or 'background.paper' directly to theme-aware properties.

What happened to deep imports in MUI v7?

Deep imports are no longer supported. You must use the official package exports to ensure proper build optimization and type resolution.

How should I structure styles for large components?

Move styles exceeding 100 lines into a separate .styles.ts file and import them as a Record<string, SxProps<Theme>> to keep your component logic clean.

How it compares

MUI v7 offers a structured design system with enforced patterns, whereas manual CSS or standard Tailwind requires manual coordination of spacing, typography, and component accessibility.

Source & trust

⭐ 2.0k stars📄 MIT🕒 Updated 2026-03-05

View original skill on GitHub →

📄 Full skill instructions — original source: softaworks/agent-toolkit

# 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 components with simple styling, define styles at the top:

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

const componentStyles: Record<string, SxProps<Theme>> = {
  container: {
    p: 2,
    display: 'flex',
    flexDirection: 'column',
  },
  header: {
    mb: 2,
    color: 'primary.main',
  },
  button: {
    mt: 'auto',
    alignSelf: 'flex-end',
  },
};

function Component() {
  return (
    <Box sx={componentStyles.container}>
      <Typography sx={componentStyles.header}>Header</Typography>
      <Button sx={componentStyles.button}>Action</Button>
    </Box>
  );
}

### Separate Styles File (>= 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,
    '&: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](resources/styling-guide.md) - Advanced styling patterns
- [component-library.md](resources/component-library.md) - Component examples
- [theme-customization.md](resources/theme-customization.md) - Theme setup

By Softaworks

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/mui/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/softaworks/agent-toolkit/mui/SKILL.md
Cursor: ~/.cursor/skills/softaworks/agent-toolkit/mui/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/softaworks/agent-toolkit/mui/SKILL.md