---
applyTo: "src/**/*.tsx,src/**/*.ts"
description: Material UI conventions
---

# Material UI (MUI)

- Check the installed `@mui/material` major in `package.json` and follow that version's API (for example, the Grid API changed across majors). Don't mix in examples from other versions.
- Theme first: colors, typography, spacing, shape and component defaults live in `src/theme.ts` via `createTheme`, provided once with `ThemeProvider` and `CssBaseline` at the root. No hex colors or pixel font sizes in components; use `theme.palette.*`, `theme.typography.*`, `theme.spacing()`.
- Component-wide overrides go in `theme.components.<MuiX>.defaultProps/styleOverrides`, not repeated `sx` on every instance.
- Styling: `sx` for one-off layout tweaks; `styled()` for reusable styled components. Don't mix in another CSS-in-JS library or inline `style` objects.
- Layout with `Stack`, `Box` and `Grid` using responsive values (`{ xs: 12, md: 6 }`). Use breakpoints from the theme, not hardcoded media queries.
- Import from the package root or path imports consistently with the repo; icons from `@mui/icons-material/IconName` path imports to keep dev builds fast.
- Dark mode via the theme's color schemes or palette mode; test both if the app supports them.
- Accessibility: every `IconButton` has an `aria-label`; form fields use `TextField` `label` (not placeholder-only) and `helperText` for errors; `Dialog` has `aria-labelledby`; don't remove focus outlines.
- Forms: connect inputs to the repo's form library (React Hook Form `Controller` or equivalent) and validation schema; show errors with `error` + `helperText`.
- Data grids and date pickers come from `@mui/x-*` packages; check the license tier before using Pro/Premium-only features.
- Keep components small: page components compose feature components; no 300-line JSX trees.
- Tests with Testing Library query by role and label (`getByRole('button', { name: /save/i })`), not by MUI class names.