MUI (Material UI) Skill

Material UI for React with theming, sx prop, and accessibility patterns for v5+.

When to Use

• MUI components (Button, Box, Grid, etc.)
• MUI theming and customization
• Accessible Material Design UIs
• MUI X components (DataGrid, Charts)

Don't use for:

• Non-MUI React (use react skill)
• Vanilla CSS (use css skill)

---

| Component library patterns | ✅ Yes | ✅ Yes | components.md (required) |
| Theme customization / dark mode | ✅ Yes | ✅ Yes | theming.md (required) |
| Advanced styling (sx, styled API) | ✅ Yes | ✅ Yes | customization.md (required) |
| Tables, DataGrid, Lists | ✅ Yes | ✅ Yes | data-display.md (required) |
| Form validation, Select, Autocomplete | ✅ Yes | ✅ Yes | forms.md (required) |
| Multiple advanced features | ✅ Yes | ✅ Yes | All relevant references |

Available References

All reference files located in skills/mui/references/:

• README.md: Overview of all MUI references and navigation guide
• components.md: Button, TextField, Typography, layouts, navigation (required for component patterns)
• theming.md: createTheme, palette, dark mode, component overrides (required for theme customization)
• customization.md: sx prop, styled API, custom variants, performance (required for advanced styling)
• data-display.md: Table, DataGrid, List, Card patterns (required for data display)
• forms.md: TextField validation, Select, Autocomplete, Formik integration (required for forms)

Conditional Language

• "MUST read" → Obligatory - Read immediately before proceeding
• "CHECK" or "Consider" → Suggested - Read if you need deeper understanding
• "OPTIONAL" → Ignorable - Read only for learning or edge cases

Example: Theme Task

1. User: "Dark mode with custom palette"
2. Read: SKILL.md
3. Decision Tree: "Dark mode? → theming.md"
4. Read: theming.md
5. Execute: createTheme + ThemeProvider

---

Use when:

• Building with MUI components
• MUI theming and design systems
• sx prop or styled API customization
• Consistent spacing/typography/colors
• MUI + React integration

Don't use for:

• Tailwind CSS (use tailwindcss skill)
• Plain CSS/HTML (use css/html skills)
• Custom libraries (use react skill)

---

Critical Patterns

✅ REQUIRED: Use ThemeProvider

// ✅ CORRECT: Wrap app with ThemeProvider
import { ThemeProvider, createTheme } from '@mui/material';

const theme = createTheme({ /* config */ });

<ThemeProvider theme={theme}>
  <App />
</ThemeProvider>

// ❌ WRONG: Using MUI without theme (inconsistent styling)
<App /> // No ThemeProvider

✅ REQUIRED: Use sx Prop for One-Off Styles

// ✅ CORRECT: sx prop with theme values
<Box sx={{ p: 2, bgcolor: 'primary.main' }}>

// ❌ WRONG: Inline styles (loses theme consistency)
<Box style={{ padding: '16px', backgroundColor: '#1976d2' }}>

✅ REQUIRED: Use MUI Components Over Custom HTML

// ✅ CORRECT: MUI components with built-in accessibility
<Button variant="contained" onClick={handleClick}>Submit</Button>

// ❌ WRONG: Custom HTML without accessibility
<div className="button" onClick={handleClick}>Submit</div>

---

Conventions

MUI Specific

• Use MUI components over custom HTML when available
• Implement theme provider for consistent styling
• Use sx prop for one-off styling
• Leverage styled API for reusable styled components
• Follow MUI's accessibility guidelines

---

Decision Tree

One-off styling? → Use sx prop with theme values: sx={{ p: 2, bgcolor: 'primary.main' }}.

Reusable styled component? → Use styled() API to create custom components. [CRITICAL] See references/customization.md for styled API patterns.

Global theme change? → Configure in createTheme(), apply via ThemeProvider. [CRITICAL] See references/theming.md for theme setup.

Need custom variant? → Extend theme with component variants in theme configuration. [CRITICAL] See references/customization.md for variant patterns.

Responsive styling? → Use theme breakpoints: sx={{ p: { xs: 1, md: 2 } }} or theme.breakpoints.up('md').

Dark mode? → Create separate light/dark themes, toggle via ThemeProvider. [CRITICAL] See references/theming.md for dark mode implementation.

Custom component? → Extend MUI component with styled API or composition pattern. [CRITICAL] See references/components.md for component patterns.

Building forms? → Use TextField, Select, Autocomplete with validation. [CRITICAL] See references/forms.md for form patterns.

Displaying tables/lists? → Use Table, DataGrid, List components. [CRITICAL] See references/data-display.md for data display patterns.

---

Example

import { Button, Box, ThemeProvider, createTheme } from '@mui/material';

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
  },
});

<ThemeProvider theme={theme}>
  <Box sx={{ p: 2 }}>
    <Button variant="contained" color="primary">
      Click Me
    </Button>
  </Box>
</ThemeProvider>

---

Edge Cases

Theme nesting: Nested ThemeProviders merge; use for component overrides.

SSR styling: Use ServerStyleSheets to prevent FOUC.

Custom breakpoints: createTheme({ breakpoints: { values: { mobile: 0, tablet: 640 } } }).

sx performance: Frequent re-renders → use styled() over sx.

Icon sizing: Use fontSize prop for consistency.

---

Resources

• components.md — Button, TextField, Typography, layout components
• theming.md — createTheme, ThemeProvider, dark mode
• customization.md — sx prop, styled API, variants
• data-display.md — Table, DataGrid, List patterns
• forms.md — TextField validation, Select, Autocomplete
• mui-x-charts.md — Charts: LineChart, BarChart, PieChart (use only when viz required)
• https://mui.com/material-ui/getting-started/
• https://mui.com/material-ui/customization/theming/