AGENTS.md

1# AGENTS.md
2 
3This file provides guidance for AI agents working with code in this repository.
4 
5## Package Manager
6 
7**Only pnpm is supported** (yarn/npm will fail). Use the `-F` flag for workspace operations:
8 
9```bash
10pnpm -F @mui/material add some-package    # Add dependency to a package
11pnpm -F @mui/material build               # Build a specific package
12```
13 
14Never use `cd` to navigate into package directories for commands.
15 
16## Common Commands
17 
18### Development
19 
20```bash
21pnpm install                  # Install deps if necessary
22pnpm docs:dev                 # Start docs dev server only
23```
24 
25### Building
26 
27```bash
28pnpm release:build            # Build all packages (except docs)
29pnpm docs:build               # Build documentation site
30```
31 
32### Testing
33 
34```bash
35pnpm test:unit                # Run all unit tests (jsdom)
36pnpm test:unit ComponentName  # Run tests matching pattern
37pnpm test:unit -t "test name" # Grep for specific test name
38pnpm test:browser             # Run tests in real browsers (Chrome, Firefox, WebKit)
39pnpm test:e2e                 # End-to-end tests
40pnpm test:regressions         # Visual regression tests
41```
42 
43### Code Quality
44 
45```bash
46pnpm prettier                 # Format staged changes
47pnpm eslint                   # Lint with cache
48pnpm typescript               # Type check all packages
49```
50 
51### API Documentation
52 
53After changing component props or TypeScript declarations:
54 
55```bash
56pnpm proptypes && pnpm docs:api
57```
58 
59### Docs demos
60 
61Always author the TypeScript version of the demos. To generate the JavaScript variant, run:
62 
63```bash
64pnpm docs:typescript:formatted
65```
66 
67## Architecture
68 
69This is a monorepo managed by Lerna with Nx for caching. Key packages:
70 
71- `@mui/material` - Core Material UI components
72- `@mui/system` - Styling system (sx prop, styled, theme)
73- `@mui/lab` - Experimental components (new components go here first)
74- `@mui/icons-material` - Material Design icons
75- `@mui/utils` - Internal utilities
76- `@mui/styled-engine` - CSS-in-JS abstraction (Emotion by default)
77 
78Internal packages (not published): `@mui-internal/*`, `@mui/internal-*`
79 
80## Code Conventions
81 
82### TypeScript
83 
84- Use `interface` (not `type`) for component props
85- Export `{ComponentName}Props` interface from component files
86- Path aliases available: `@mui/material` → `./packages/mui-material/src`
87 
88### Errors
89 
90These guidelines only apply for errors thrown from public packages.
91 
92Every error message must:
93 
941. **Say what happened** - Describe the problem clearly
952. **Say why it's a problem** - Explain the consequence
963. **Point toward how to solve it** - Give actionable guidance
97 
98Format:
99 
100- Prefix with `MUI: `
101- Use string concatenation for readability
102- Include a documentation link when applicable (`https://mui.com/r/...`)
103 
104#### Error Minifier
105 
106Use the `/* minify-error */` comment to activate the babel plugin:
107 
108```tsx
109throw /* minify-error */ new Error(
110  'MUI: Expected valid input target. ' +
111    'Did you use a custom `inputComponent` and forget to forward refs? ' +
112    'See https://mui.com/r/input-component-ref-interface for more info.',
113);
114```
115 
116The minifier works with both `Error` and `TypeError` constructors.
117 
118#### After Adding/Updating Errors
119 
120Run `pnpm extract-error-codes` to update `docs/public/static/error-codes.json`.
121 
122**Important:** If the update created a new error code, but the new and original message have the same number of arguments and semantics haven't changed, update the original error in `error-codes.json` instead of creating a new code.
123 
124### Component Structure
125 
126```text
127packages/mui-material/src/Button/
128├── Button.tsx           # Component implementation
129├── Button.d.ts          # TypeScript declarations (for JSDoc API docs)
130├── Button.test.js       # Unit tests
131├── buttonClasses.ts     # CSS classes
132└── index.ts             # Public exports
133```
134 
135### Testing
136 
137- Use `createRenderer()` from `@mui/internal-test-utils`
138- Use Chai BDD-style assertions (`expect(x).to.equal(y)`)
139- Custom matchers: `toErrorDev()`, `toWarnDev()` for console assertions
140- Prefer testing components with full interactions using `user.*` methods. Avoid `fireEvent` and `setProps` if possible.
141- If tests require the browser because, for example, they require layout measurements, restrict it to the Chromium env by using `it.skipIf(isJsdom())` or `describe.skipIf(isJsdom())` (search other tests for example usage if unsure).
142 
143```js
144import { createRenderer } from '@mui/internal-test-utils';
145 
146describe('Button', () => {
147  const { render } = createRenderer();
148 
149  it('renders children', async () => {
150    const handleClick = vi.fn();
151    const { getByRole, user } = render(<Button onClick={handleClick}>Hello</Button>);
152 
153    const button = getByRole('button');
154    expect(button).to.have.text('Hello');
155 
156    await user.click(button);
157    expect(handleClick).toHaveBeenCalledTimes(1);
158  });
159});
160```
161 
162### Accessibility Testing
163 
164axe-core runs inside the visual-regression Playwright loop (`test/regressions/index.test.js`) — no separate browser session. Screenshots and a11y are independent: a demo can opt out of one and still run the other.
165 
166Key files:
167 
168- `test/regressions/demoMeta.ts` — `SCREENSHOT_RULES` and `A11Y_RULES` arrays, matched last-wins (no inheritance: overrides restate every field) against `docs/data/material/components/{slug}/{Demo}` (minimatch globs).
169- `test/regressions/a11y/axe.ts` — asserts `color-contrast` and `link-in-text-block` unless listed in `skipAssertions`.
170- `test/regressions/a11y/a11yReporter.ts` — writes one file per slug at `docs/data/material/components/{slug}/{slug}.a11y.json`. Each file is keyed by demo name, then by axe rule ID. Each rule records a `status` (`pass`, `fail`, or `incomplete`) and WCAG tags.
171 
172Enroll a component (slug-wide, or narrow with brace-glob):
173 
174```ts
175// test/regressions/demoMeta.ts
176{ test: 'docs/data/material/components/alert/*', enabled: true, skipAssertions: ['color-contrast'] },
177{ test: 'docs/data/material/components/buttons/{BasicButtons,ColorButtons}', enabled: true },
178```
179 
180Override a specific demo: append a per-demo rule _after_ the slug-wide rule (last-match-wins; the override must restate every field it wants):
181 
182```ts
183{ test: 'docs/data/material/components/popover/AnchorPlayground', enabled: false }, // Redux isolation
184```
185 
186Run `pnpm test:regressions` to refresh the `*.a11y.json` files. CI fails if any are stale.
187 
188For local iteration, scope the run with vitest's `-t` test-name filter (matched against the `it()` strings, which contain the route). Non-matching tests are skipped — their bodies don't execute, so the browser never navigates to those routes.
189 
190```bash
191# in one terminal
192pnpm test:regressions:server
193 
194# in another — note no `--`, pnpm forwards args directly
195pnpm test:regressions:run -t '/docs-components-buttons/'              # one slug
196pnpm test:regressions:run -t '/docs-components-buttons/BasicButtons$' # one demo
197pnpm test:regressions:run -t '/docs-components-(buttons|chips)/'      # multiple slugs
198```
199 
200Filtered runs only refresh the matched slugs' `*.a11y.json`. Run the unfiltered `pnpm test:regressions` before pushing.
201 
202### Imports
203 
204Use one-level deep imports to avoid bundling entire packages:
205 
206```js
207import Button from '@mui/material/Button'; // Good
208import { Button } from '@mui/material'; // Avoid in packages
209```
210 
211## Agent Skills
212 
213Packaged guidance for common integration topics lives under `skills/`. Each skill is a self-contained directory:
214 
215| Skill                                                                  | Focus                                                       |
216| :--------------------------------------------------------------------- | :---------------------------------------------------------- |
217| [skills/material-ui-styling](./skills/material-ui-styling/AGENTS.md)   | `sx`, `styled()`, theme overrides, slots, global CSS        |
218| [skills/material-ui-theming](./skills/material-ui-theming/AGENTS.md)   | `createTheme`, design tokens, `colorSchemes`, CSS variables |
219| [skills/material-ui-nextjs](./skills/material-ui-nextjs/AGENTS.md)     | App/Pages Router, Emotion cache, `next/font`, `Link`, SSR   |
220| [skills/material-ui-tailwind](./skills/material-ui-tailwind/AGENTS.md) | Tailwind v4 `@layer`, `enableCssLayer`, v3 interop          |
221 
222Read the relevant `AGENTS.md` when helping users with those topics.
223 
224## Pre-PR Checklist
225 
2261. `pnpm prettier` - Format code
2272. `pnpm eslint` - Pass linting
2283. `pnpm typescript` - Pass type checking
2294. `pnpm test:unit` - Pass unit tests
2305. If API changed: `pnpm proptypes && pnpm docs:api`
2316. If demos changed: `pnpm docs:typescript:formatted`
2327. If `.md` files changed: `pnpm vale <file1> <file2> ...` - Check prose style and grammar
233 
234## PR Title Format
235 
236`[component] Imperative description`
237 
238Examples:
239 
240- `[button] Add loading state`
241- `[docs] Fix typo in Grid documentation`
242