AGENTS.md

skills/material-ui-tailwind/AGENTS.md

AGENTS.md

Quality

58/100

Scores the file, not the repository.

Length

738 words

14 headings · 2 code blocks

Repository

99k

— · pushed 0 days ago

Last changed

3 days ago

First indexed 3 days ago.

mui/material-ui/skills/material-ui-tailwind/AGENTS.mdRaw GitHub

1# Material UI and Tailwind CSS
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: For agents and LLMs combining Material UI with Tailwind CSS. Primary source for v4: `docs/data/material/integrations/tailwindcss/tailwindcss-v4.md`. v3: `docs/data/material/integrations/interoperability/interoperability.md` (Tailwind CSS v3).
8 
9---
10 
11## Abstract
12 
13Tailwind CSS v4 integration with Material UI is built on CSS cascade layers: MUI emits styles inside `@layer mui`, and Tailwind's `utilities` layer must come after so utilities can override without `!important`. Enable MUI's layer mode with `enableCssLayer: true` (Next.js via `AppRouterCacheProvider` / shared `createEmotionCache`) or `StyledEngineProvider` with `enableCssLayer` (Vite and other SPAs). Declare layer order (for example `@layer theme, base, mui, components, utilities`) before `@import 'tailwindcss'` (or inject the same string with `GlobalStyles` where the docs show). Tailwind CSS v3 uses a different recipe (preflight off, `important`, `StyledEngineProvider` with `injectFirst`, portal `container`). Prefer v4 for new work when possible.
14 
15---
16 
17## Table of contents
18 
191. [Tailwind CSS v4 (preferred)](#tailwind-css-v4-preferred)
202. [Next.js specifics](#nextjs-specifics)
213. [Vite and other SPAs](#vite-and-other-spas)
224. [Applying utilities to MUI components](#applying-utilities-to-mui-components)
235. [Theme tokens in Tailwind (`@theme`)](#theme-tokens-in-tailwind-theme)
246. [VS Code IntelliSense](#vs-code-intellisense)
257. [Tailwind CSS v3 (legacy)](#tailwind-css-v3-legacy)
268. [Troubleshooting](#troubleshooting)
279. [Further reading](#further-reading)
28 
29---
30 
31## Tailwind CSS v4 (preferred)
32 
33### Goals
34 
351. Generate Tailwind with the `@layer` directive.
362. Order layers so `mui` comes before `utilities`, so Tailwind utilities override MUI predictably.
37 
38See [Tailwind CSS v4 integration—Overview](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#overview).
39 
40### Layer stack (typical)
41 
42At the top of your global CSS (example from docs):
43 
44```css
45@layer theme, base, mui, components, utilities;
46@import 'tailwindcss';
47```
48 
49Adjust file paths to your app (`src/app/global.css`, `styles/global.css`, etc.).
50 
51---
52 
53## Next.js specifics
54 
551. Complete the [Next.js integration—App Router](https://mui.com/material-ui/integrations/nextjs.md#app-router) or [Next.js integration—Pages Router](https://mui.com/material-ui/integrations/nextjs.md#pages-router) setup first.
562. App Router: `<AppRouterCacheProvider options={{ enableCssLayer: true }}>` in the root layout. `suppressHydrationWarning` on `<html>` appears in the doc example when relevant.
573. Pages Router: shared `createEmotionCache({ enableCssLayer: true })` from `@mui/material-nextjs`, passed through `documentGetInitialProps`; `AppCacheProvider` uses the same cache; layer order via `GlobalStyles` as the first child inside `AppCacheProvider`. See [Tailwind CSS v4 integration—Next.js Pages Router](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#nextjs-pages-router).
58 
59For a concise provider checklist, see the material-ui-nextjs skill and [Next.js integration—Using other styling solutions](https://mui.com/material-ui/integrations/nextjs.md#using-other-styling-solutions).
60 
61---
62 
63## Vite and other SPAs
64 
651. `StyledEngineProvider` with `enableCssLayer`.
662. `GlobalStyles` injecting `@layer theme, base, mui, components, utilities;` before the app tree.
67 
68See [Tailwind CSS v4 integration—Vite.js or any other SPA](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#vitejs-or-any-other-spa).
69 
70Example repo: [material-ui-vite-tailwind-ts](https://github.com/mui/material-ui/tree/master/examples/material-ui-vite-tailwind-ts).
71 
72---
73 
74## Applying utilities to MUI components
75 
76- `className`: root element of the component.
77- `slotProps.{slot}.className`: interior [slots](https://mui.com/material-ui/customization/overriding-component-structure.md#interior-slots).
78 
79See [Tailwind CSS v4 integration—Usage](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#usage).
80 
81---
82 
83## Theme tokens in Tailwind (`@theme`)
84 
85To reuse MUI theme variables as Tailwind tokens, map `--mui-*` CSS variables into Tailwind's `@theme`. Minimal example (extend as needed):
86 
87```css
88@theme inline {
89  --color-primary: var(--mui-palette-primary-main);
90  --color-primary-light: var(--mui-palette-primary-light);
91  --color-primary-dark: var(--mui-palette-primary-dark);
92  --color-error: var(--mui-palette-error-main);
93  --color-text-primary: var(--mui-palette-text-primary);
94}
95```
96 
97The full token list (palette, typography, breakpoints, shadows, …) is long and maintained on the doc page. Copy the complete `@theme inline { ... }` block from [Extend Material UI classes](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#extend-material-ui-classes) when you need it all.
98 
99See [Tailwind CSS v4 integration—Extend Material UI classes](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#extend-material-ui-classes) and the linked [playground](https://play.tailwindcss.com/mh7Ym0mGff).
100 
101Requirement: MUI CSS theme variables (`cssVariables: true` in `createTheme`) so the `--mui-*` variables exist. Align with the material-ui-theming skill.
102 
103---
104 
105## VS Code IntelliSense
106 
107For `slotProps` and similar, add `tailwindCSS.experimental.classRegex` in VS Code `settings.json` as in [Tailwind CSS v4 integration—Tailwind CSS IntelliSense for VS Code](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#tailwind-css-intellisense-for-vs-code).
108 
109Snippet also lives in [reference.md](reference.md).
110 
111---
112 
113## Tailwind CSS v3 (legacy)
114 
115Use the interoperability guide, not the v4 page:
116 
1171. Install Tailwind v3 per upstream docs.
1182. `corePlugins: { preflight: false }` so MUI `CssBaseline` owns base resets.
1193. `important: '#__next'` or `'#root'`; App Router may need `id="__next"` on `<body>` manually.
1204. `StyledEngineProvider` with `injectFirst` (or Emotion `prepend: true` cache) for injection order.
1215. Theme `defaultProps` `container` on `Modal`, `Dialog`, `Popover`, `Popper` to the same root as `important`.
122 
123See [Interoperability—Tailwind CSS v3](https://mui.com/material-ui/integrations/interoperability.md#tailwind-css-v3) and [Interoperability—Troubleshooting](https://mui.com/material-ui/integrations/interoperability.md#troubleshooting) (table of root IDs).
124 
125---
126 
127## Troubleshooting
128 
129v4: confirm Tailwind >= v4, layer order, and DevTools cascade layers (`mui` before `utilities`). See [Tailwind CSS v4 integration—Troubleshooting](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#troubleshooting).
130 
131v3: verify `important` selector matches root `id`, `preflight: false`, and `injectFirst`. See the interoperability Troubleshooting subsection linked above.
132 
133---
134 
135## Further reading
136 
137| Topic                     | Link                                                                                                                                        |
138| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ |
139| Tailwind CSS v4 + MUI     | [Tailwind CSS v4 integration](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md)                                       |
140| CSS layers (MUI concepts) | [CSS Layers](https://mui.com/material-ui/customization/css-layers.md)                                                                       |
141| Interior slots            | [Overriding component structure—Interior slots](https://mui.com/material-ui/customization/overriding-component-structure.md#interior-slots) |
142| Tailwind v3 + MUI         | [Interoperability—Tailwind CSS v3](https://mui.com/material-ui/integrations/interoperability.md#tailwind-css-v3)                            |
143

Sections

Material UI and Tailwind CSS
Abstract
Table of contents
Tailwind CSS v4 (preferred)
Goals
Layer stack (typical)
Next.js specifics
Vite and other SPAs
Applying utilities to MUI components
Theme tokens in Tailwind (`@theme`)
VS Code IntelliSense
Tailwind CSS v3 (legacy)
Troubleshooting
Further reading

What it covers

code-style ui

Stack — with the evidence

(1.00)

(1.00)

(1.00)

(1.00)

(0.70)

(0.70)

(0.70)

(0.70)

(0.70)

(0.70)

(0.60)

(0.60)

(0.60)

(0.60)

(0.60)

Format

AGENTS.md

A plain-markdown README for coding agents, deliberately unopinionated: no frontmatter, no globs, no vendor keys. That minimalism is why it became the one file a dozen different agents will read, and why it carries the least per-file targeting power of any format here.

What the corpus says about it

Repository

Owner: mui
Language: —
License: —
Archived: no

All configs in this repo

Also in mui/material-ui

Diff this repo’s formats

One repository carrying more than one format is the comparison this product exists for: does anyone actually write different content in each file, or is one a copy of the other?

The other instruction files in this repository
Repository	Format	Stack	Covers	Score	Changed
mui/material-uiAGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	setupbuildtestlint-format+9	100/100	3 days ago
mui/material-uiskills/material-ui-nextjs/AGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	setupstylearchtypes+2	70/100	3 days ago
mui/material-uiskills/material-ui-styling/AGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	styleui	58/100	3 days ago
mui/material-uiskills/material-ui-theming/AGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	setupstyleui	58/100	3 days ago

Diff against AGENTS.md Diff against skills/material-ui-nextjs/AGENTS.md Diff against skills/material-ui-styling/AGENTS.md Diff against skills/material-ui-theming/AGENTS.md

Similar configs

Same format, overlapping stack, ranked by quality.

Same format, overlapping stack, ranked by quality
Repository	Format	Stack	Covers	Score	Changed
mui/material-uiAGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	setupbuildtestlint-format+9	100/100	3 days ago
SkeneTechnologies/skene-cookbookAGENTS.md · 51	AGENTS.md	pythoneslint+4	setupbuildtestlint-format+7	100/100	2 days ago
wpscanteam/wpscanAGENTS.md · 9.7k	AGENTS.md	rubyvue+3	setupbuildteststyle+6	100/100	2 days ago
code-yeongyu/oh-my-openagentpackages/web/AGENTS.md · 67k	AGENTS.md	typescriptbun+10	setupbuildtestlint-format+6	100/100	2 days ago
aaif-goose/gooseAGENTS.md · 52k	AGENTS.md	rusttypescript+2	setupbuildtestlint-format+6	100/100	3 days ago
n8n-io/n8npackages/@n8n/agents/AGENTS.md · 199k	AGENTS.md	typescriptlangchain+16	buildteststylearch+3	100/100	3 days ago
duckduckgo/content-scope-scriptsspecial-pages/AGENTS.md · 70	AGENTS.md	typescriptjavascript+5	buildteststylearch+3	100/100	3 days ago
TryGhost/Ghoste2e/AGENTS.md · 55k	AGENTS.md	typescriptjavascript+12	setupteststylearch+2	100/100	3 days ago