AGENTS.md

1# Material UI styling
2 
3Version 1.0.0 (Material UI v9)
4 
5> **Version notice:** This skill targets Material UI v9 (`>=9.0.0 <10.0.0`). If you are using a different major version, verify the API details before following this guidance.
6 
7> Note: This document is for agents and LLMs maintaining or generating Material UI code. It follows [How to customize](https://mui.com/material-ui/customization/how-to-customize.md) and related sources in this repository (`docs/data/material/customization/`, `docs/data/system/`).
8 
9---
10 
11## Abstract
12 
13Material UI stacks four strategies from narrowest to broadest scope. Pick the smallest scope that solves the problem to avoid scattering global rules. The `sx` prop is the default for one-off tweaks; `styled()` is for reusable wrappers; the theme's `components` API is for app-wide consistency; `GlobalStyles` / `CssBaseline` is for baseline HTML or cross-cutting globals.
14 
15---
16 
17## Table of contents
18 
191. [Quick decision (use in order)](#quick-decision-use-in-order)
202. [One-off: `sx` prop](#1-one-off-sx-prop)
213. [Reusable: `styled()`](#2-reusable-styled)
224. [Global theme: `createTheme({ components })`](#3-global-theme-createtheme-components)
235. [Global CSS: `GlobalStyles` / `CssBaseline`](#4-global-css-globalstyles--cssbaseline)
246. [`sx` vs `styled()`](#sx-vs-styled-differences-agents-should-know)
257. [Imports and consistency](#imports-and-consistency)
268. [Further reading](#further-reading-repo--site)
27 
28---
29 
30## Quick decision (use in order)
31 
321. Single instance or local layout? → [`sx`](https://mui.com/system/getting-started/the-sx-prop/)
332. Same override in many places? → [`styled()`](https://mui.com/system/styled/) around the MUI component (or a thin wrapper component)
343. All instances of a component should look different by default? → [`theme.components`](https://mui.com/material-ui/customization/theme-components.md) (`styleOverrides`, `variants`, `defaultProps`)
354. Global element baselines (for example all `h1`) or non-component CSS? → [`GlobalStyles`](https://mui.com/material-ui/api/global-styles.md) or [`CssBaseline`](https://mui.com/material-ui/react-css-baseline.md) overrides
36 
37Do not jump to global theme overrides for a one-off screen; do not use `sx` for large repeated systems if a themed variant or `styled()` wrapper is clearer.
38 
39---
40 
41## 1. One-off: `sx` prop
42 
43Use when: changing one instance (or a small inline case) with access to the theme.
44 
45- All Material UI components support `sx`.
46- Supports theme shortcuts (`palette`, `spacing`, breakpoints, etc.), pseudo-selectors, nested selectors, and responsive objects.
47- Array syntax: `sx={[base, condition && extra]}` merges styles conditionally — entries applied in order, falsy entries skipped. Prefer this over object spread for conditional `sx`.
48 
49Nested parts (slots): target internal slots with global class fragments, for example `'& .MuiSlider-thumb'`. Discover the slot name in DevTools; the pattern is `Mui[Component]-[slot]`. Do not rely on the full hashed class string. Use only the stable `Mui*` fragment.
50 
51State styles: MUI uses global state classes (`.Mui-disabled`, `.Mui-selected`, etc.) with specificity comparable to pseudo-classes. Override with increased specificity (for example combine with your class or the component root), never bare global state selectors alone.
52 
53```css
54/* Bad: affects every component using .Mui-error */
55.Mui-error {
56  color: red;
57}
58 
59/* Good: scoped to OutlinedInput root */
60.MuiOutlinedInput-root.Mui-error {
61  color: red;
62}
63```
64 
65See [How to customize—State classes](https://mui.com/material-ui/customization/how-to-customize.md#state-classes).
66 
67`className`: use when integrating with external CSS or CSS Modules; combine with the same slot/state rules as above.
68 
69---
70 
71## 2. Reusable: `styled()`
72 
73Use when: the same customized component appears in multiple places and deserves a named component.
74 
75```ts
76import { styled } from '@mui/material/styles';
77```
78 
79- Prefer `@mui/material/styles` when using Material UI so the default theme matches the rest of the app.
80- `styled()` adds theme integration, optional `name` / `slot` for theme overrides, and `sx` on the result (unless disabled).
81- For custom props, use `shouldForwardProp` so DOM/React does not receive invalid attributes. Extend the component's prop types in TypeScript.
82 
83Dynamic styling: prefer CSS variables or conditional style objects in the style callback; avoid per-field functions inside the style object for readability (see [styled() docs](https://mui.com/system/styled/)).
84 
85---
86 
87## 3. Global theme: `createTheme({ components })`
88 
89Use when: default look of `Button`, `TextField`, etc. should change everywhere.
90 
91- `defaultProps`: change defaults (for example `disableRipple` on `MuiButtonBase`).
92- `styleOverrides`: target slots (`root`, `input`, …) with plain CSS-in-JS objects; nested selectors allowed. Use the callback form `root: ({ ownerState, theme }) => ({ ... })` to branch on the component's resolved props without extra class names.
93- `variants`: map props to extra styles (built-in props like `variant: 'outlined'` or custom values you document for your design system).
94 
95Caveat: the theme is not tree-shakable. For heavy one-off customizations, a new component is often better than bloating the theme.
96 
97Full API: [Themed components](https://mui.com/material-ui/customization/theme-components.md).
98 
99---
100 
101## 4. Global CSS: `GlobalStyles` / `CssBaseline`
102 
103Use when: styling raw HTML elements or app-wide snippets that are not tied to a single MUI component instance.
104 
105- Prefer hoisting `<GlobalStyles />` to a module-level constant so the style tag does not churn on re-renders.
106- `styles` can be a callback for theme access.
107- Can extend `MuiCssBaseline` `styleOverrides` if the app already uses `CssBaseline`.
108 
109---
110 
111## `sx` vs `styled()`: differences agents should know
112 
113| Topic                                        | `sx`               | `styled()` style object                                      |
114| :------------------------------------------- | :----------------- | :----------------------------------------------------------- |
115| Theme spacing shorthand (`m`, `p`, `gap`, …) | Yes                | No. Use `theme.spacing()` in a function or plain CSS values. |
116| Meaning of numeric padding like `1`          | Theme spacing unit | Pixels, not `theme.spacing(1)`                               |
117| Theme palette strings (`'primary.main'`)     | Yes                | Use `theme` in a function                                    |
118 
119To reuse `sx` logic inside `styled()`, use theme's `unstable_sx` (see [styled()—Difference with the sx prop](https://mui.com/system/styled/#difference-with-the-sx-prop)).
120 
121---
122 
123## Imports and consistency
124 
125- In application code, prefer one-level imports from packages (for example `@mui/material/Button`) to avoid pulling the entire barrel.
126- Use `sx` for system layout shortcuts (`p`, `gap`, `mt`, etc.) on MUI components; use component props only for behavior documented by that component.
127 
128---
129 
130## Further reading (repo / site)
131 
132| Topic                   | Doc                                                                                          |
133| :---------------------- | :------------------------------------------------------------------------------------------- |
134| Choosing strategy       | [How to customize](https://mui.com/material-ui/customization/how-to-customize.md)            |
135| `sx` reference          | [The sx prop](https://mui.com/system/getting-started/the-sx-prop/)                           |
136| `styled()` API          | [styled()](https://mui.com/system/styled/)                                                   |
137| Theme per component     | [Themed components](https://mui.com/material-ui/customization/theme-components.md)           |
138| System property mapping | [System properties](https://mui.com/system/properties/)                                      |
139| State / class naming    | [State classes](https://mui.com/material-ui/customization/how-to-customize.md#state-classes) |
140 
141For MUI-specific class and state tables, see [reference.md](reference.md).
142