AGENTS.md

1# Material UI theming and design tokens
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 implementing themes and design tokens with Material UI. Grounded in `docs/data/material/customization/` (theming, palette, dark-mode, css-theme-variables, typography, spacing, shape).
8 
9---
10 
11## Abstract
12 
13A Material UI theme is a single object of design tokens (palette, typography, spacing, shape, breakpoints, etc.) plus optional per-component defaults (`theme.components`). Apps typically call `createTheme` once (or in composed steps), pass the result to `ThemeProvider` near the root, and read values with `useTheme`, `sx`, or `styled`. For system-driven light/dark, prefer `colorSchemes` and related APIs over a static `palette.mode`-only setup when you need toggling, tab sync, and SSR-friendly behavior; enable `cssVariables` when you want `theme.vars`, fewer theme nests for dark regions, and clearer debugging via `--mui-*` CSS variables.
14 
15---
16 
17## Table of contents
18 
191. [Core setup](#core-setup)
202. [Where tokens live (design token map)](#where-tokens-live-design-token-map)
213. [Palette quick facts](#palette-quick-facts)
224. [Color schemes vs palette-only dark](#color-schemes-vs-palette-only-dark)
235. [CSS theme variables (`cssVariables: true`)](#css-theme-variables-cssvariables-true)
246. [Typography and spacing](#typography-and-spacing)
257. [Composing and merging themes](#composing-and-merging-themes)
268. [Nesting `ThemeProvider`](#nesting-themeprovider)
279. [Custom tokens (brand-specific design keys)](#custom-tokens-brand-specific-design-keys)
2810. [Windows High Contrast mode (`enhanceHighContrast`)](#windows-high-contrast-mode-enhancehighcontrast)
2911. [Further reading](#further-reading)
30 
31---
32 
33## Core setup
34 
351. `import { createTheme, ThemeProvider } from '@mui/material/styles'` (Material UI default theme).
362. Build a theme with `createTheme({ ... })`; wrap the app in `<ThemeProvider theme={theme}>` so descendants receive context.
373. Use `<CssBaseline />` inside the provider when you want baseline element styles and correct dark background behavior (see [Dark mode](https://mui.com/material-ui/customization/dark-mode.md)).
38 
39Access in components: `useTheme()` from `@mui/material/styles`.
40 
41---
42 
43## Where tokens live (design token map)
44 
45| Area          | Role                                                                                    | Doc                                                                                |
46| :------------ | :-------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- |
47| `palette`     | Semantic colors (`primary`, `secondary`, `error`, …), text, background, divider, action | [Palette](https://mui.com/material-ui/customization/palette.md)                    |
48| `typography`  | `fontFamily`, `fontSize`, variants (`h1` through `body2`, `button`, …)                  | [Typography](https://mui.com/material-ui/customization/typography.md)              |
49| `spacing`     | `theme.spacing(n)` scale (default 8px per unit)                                         | [Spacing](https://mui.com/material-ui/customization/spacing.md)                    |
50| `shape`       | `borderRadius` (default 4); optional extra radii need TypeScript augmentation           | [Shape](https://mui.com/material-ui/customization/shape.md)                        |
51| `breakpoints` | Responsive keys for `sx` / media queries                                                | [Breakpoints](https://mui.com/material-ui/customization/breakpoints.md)            |
52| `zIndex`      | Layering tokens                                                                         | [z-index](https://mui.com/material-ui/customization/z-index.md)                    |
53| `transitions` | Duration / easing helpers                                                               | [Transitions](https://mui.com/material-ui/customization/transitions.md)            |
54| `components`  | `defaultProps`, `styleOverrides`, `variants` per `Mui*` key                             | [Themed components](https://mui.com/material-ui/customization/theme-components.md) |
55 
56Full defaults: [Default theme explorer](https://mui.com/material-ui/customization/default-theme.md).
57 
58---
59 
60## Palette quick facts
61 
62- Each palette color is usually `main`, `light`, `dark`, `contrastText`. Supplying `main` alone is often enough; `createTheme` can derive the rest.
63- Use `@mui/material/colors` (for example `purple[500]`) for Material Design hues when building a palette.
64- `palette.mode: 'dark'` forces a dark palette for the whole theme; if you use a fully custom palette with dark mode, ensure values match the mode (see [Dark mode](https://mui.com/material-ui/customization/dark-mode.md)).
65 
66---
67 
68## Color schemes vs palette-only dark
69 
70- `colorSchemes` (for example `colorSchemes: { dark: true }`) enables built-in behavior: system preference, tab sync, optional transition disable on scheme change, storage, etc. Docs recommend it over the older, narrower palette-only approach for those features.
71- If both `colorSchemes` and `palette` are set, `palette` takes precedence. Avoid accidental overrides.
72- `useColorScheme` reads/updates mode for toggling. `mode` can be `undefined` on the first render; handle that to avoid hydration mismatches.
73- `ThemeProvider` supports `storageManager`, `disableTransitionOnChange`, `noSsr`, etc., for color-scheme UX and SSR (see [Dark mode](https://mui.com/material-ui/customization/dark-mode.md)).
74 
75---
76 
77## CSS theme variables (`cssVariables: true`)
78 
79- Set `cssVariables: true` in `createTheme` so components use `var(--mui-...)` values. Prefer `theme.vars` in style callbacks when variables are enabled (mirrors palette/typography as CSS var references). See [Usage](https://mui.com/material-ui/customization/css-theme-variables/usage.md).
80- Do not pass a custom `vars` key into `createTheme`. That key is reserved and autogenerated for this feature.
81- For dark-specific styles with CSS variables, use `theme.applyStyles('dark', { ... })` rather than branching on `theme.palette.mode` in ways that cause flicker (see docs warning in [Usage](https://mui.com/material-ui/customization/css-theme-variables/usage.md) and [Configuration](https://mui.com/material-ui/customization/css-theme-variables/configuration.md)).
82- `InitColorSchemeScript`: place before any rendered content to prevent the initial color-scheme flash. App Router: inside `<body>` before `{children}` in `app/layout.tsx`. Pages Router: in `_document.tsx` before `<Main />`. See [Preventing SSR flickering](https://mui.com/material-ui/customization/css-theme-variables/configuration.md#preventing-ssr-flickering).
83- Trade-offs: larger HTML (both schemes' variables), possible FCP impact; benefits include less JavaScript work on scheme switch and better SSR dark experience. See [Overview](https://mui.com/material-ui/customization/css-theme-variables/overview.md).
84- `CssVarsProvider` is superseded by `ThemeProvider` with the same capabilities. Use `ThemeProvider`.
85 
86---
87 
88## Typography and spacing
89 
90- Typography uses `rem`; default root sizing is documented on [Typography](https://mui.com/material-ui/customization/typography.md). Adjust `typography.fontSize` or per-variant sizes as needed; `responsiveFontSizes(theme)` can scale typography across breakpoints.
91- `theme.spacing(k)` follows the configured scale; `sx` spacing shorthands use the same system. Array-based `spacing` in the theme has limitations (negative / fractional / `'auto'`). Prefer a function if you need full expressiveness (see [Spacing](https://mui.com/material-ui/customization/spacing.md)).
92 
93---
94 
95## Composing and merging themes
96 
97- When one token should derive from another, build in steps: call `createTheme` with base options, then `createTheme(theme, { ... })` using the first result (see [Theming—Using theme options to define other options](https://mui.com/material-ui/customization/theming.md#theme-composition-using-theme-options-to-define-other-options)).
98- Avoid relying on multiple arguments to `createTheme` for merging; only the first argument is formally processed. Deep-merge yourself (for example `deepmerge` from `@mui/utils`) and pass a single object for forward compatibility (see [Theming—createTheme(options, ...args)](https://mui.com/material-ui/customization/theming.md#createtheme-options-args-theme)).
99 
100---
101 
102## Nesting `ThemeProvider`
103 
104Inner provider overrides outer. Pass `theme={(outer) => createTheme({ ...outer, ... })}`-style functions only when intentionally extending the parent theme (see [Theming—Nesting the theme](https://mui.com/material-ui/customization/theming.md#nesting-the-theme)).
105 
106---
107 
108## Custom tokens (brand-specific design keys)
109 
110Add keys on the theme (for example `status.danger`) inside `createTheme`, then augment TypeScript with `declare module '@mui/material/styles'` on `Theme` and `ThemeOptions` (see [Theming—Custom variables](https://mui.com/material-ui/customization/theming.md#custom-variables)). For extra palette fields, follow [Palette customization](https://mui.com/material-ui/customization/palette.md) patterns.
111 
112Do not use `theme.vars` as a custom property name; it is private to CSS variables support.
113 
114---
115 
116## Windows High Contrast mode (`enhanceHighContrast`)
117 
118`enhanceHighContrast` is a theme enhancer (same pattern as `responsiveFontSizes`) that adds `@media (forced-colors: active)` overrides to MUI components, improving visibility in Windows High Contrast / Forced Colors mode.
119 
120```js
121import { createTheme, enhanceHighContrast } from '@mui/material/styles';
122 
123const theme = enhanceHighContrast(createTheme());
124```
125 
126- It accepts a fully-created theme and returns an enhanced copy — call it **after** `createTheme`, not inside it.
127- By default it uses CSS system color keywords (`Highlight`, `HighlightText`, `ButtonBorder`, etc.).
128- Override individual tokens via the second argument to align with your brand:
129 
130```js
131const theme = enhanceHighContrast(createTheme(), {
132  activeBackground: 'SelectedItem', // e.g. toggled/active controls
133  activeText: 'SelectedItemText',
134});
135```
136 
137- Only pass [CSS system color keywords](https://www.w3.org/TR/css-color-4/#css-system-colors) as token values — those are the values the browser guarantees will contrast with their paired tokens.
138- See [Palette—Windows High Contrast mode](https://mui.com/material-ui/customization/palette.md#windows-high-contrast-mode) for the full token list and a live demo.
139 
140---
141 
142## Further reading
143 
144| Topic                          | Link                                                                                                           |
145| :----------------------------- | :------------------------------------------------------------------------------------------------------------- |
146| Theming overview & API         | [Theming](https://mui.com/material-ui/customization/theming.md)                                                |
147| Dark mode & toggling           | [Dark mode](https://mui.com/material-ui/customization/dark-mode.md)                                            |
148| CSS variables overview         | [CSS theme variables](https://mui.com/material-ui/customization/css-theme-variables/overview.md)               |
149| Windows High Contrast mode     | [Palette—High Contrast mode](https://mui.com/material-ui/customization/palette.md#windows-high-contrast-mode)  |
150| Color tool / brand hues        | [Color](https://mui.com/material-ui/customization/color.md)                                                    |
151| TypeScript theme customization | [TypeScript—Customization of `Theme`](https://mui.com/material-ui/guides/typescript.md#customization-of-theme) |
152 
153TypeScript snippet templates: [reference.md](reference.md).
154