Imported from stickmanbenn-byte/grumbledemo (
.agents/skills/material-ui-tailwind/AGENTS.md). Install upstream withnpx skills add stickmanbenn-byte/grumbledemo --skill material-ui-tailwind. Copyright stays with the author.
Material UI and Tailwind CSS
Version 1.0.0 (Material UI v9)
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.
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).
Abstract
Tailwind 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.
Table of contents
- Tailwind CSS v4 (preferred)
- 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
Tailwind CSS v4 (preferred)
Goals
- Generate Tailwind with the
@layerdirective. - Order layers so
muicomes beforeutilities, so Tailwind utilities override MUI predictably.
See Tailwind CSS v4 integration—Overview.
Layer stack (typical)
At the top of your global CSS (example from docs):
@layer theme, base, mui, components, utilities;
@import 'tailwindcss';Adjust file paths to your app (src/app/global.css, styles/global.css, etc.).
Next.js specifics
- Complete the Next.js integration—App Router or Next.js integration—Pages Router setup first.
- App Router:
<AppRouterCacheProvider options={{ enableCssLayer: true }}>in the root layout.suppressHydrationWarningon<html>appears in the doc example when relevant. - Pages Router: shared
createEmotionCache({ enableCssLayer: true })from@mui/material-nextjs, passed throughdocumentGetInitialProps;AppCacheProvideruses the same cache; layer order viaGlobalStylesas the first child insideAppCacheProvider. See Tailwind CSS v4 integration—Next.js Pages Router.
For a concise provider checklist, see the material-ui-nextjs skill and Next.js integration—Using other styling solutions.
Vite and other SPAs
StyledEngineProviderwithenableCssLayer.GlobalStylesinjecting@layer theme, base, mui, components, utilities;before the app tree.
See Tailwind CSS v4 integration—Vite.js or any other SPA.
Example repo: material-ui-vite-tailwind-ts.
Applying utilities to MUI components
className: root element of the component.slotProps.{slot}.className: interior slots.
See Tailwind CSS v4 integration—Usage.
Theme tokens in Tailwind (@theme)
To reuse MUI theme variables as Tailwind tokens, map --mui-* CSS variables into Tailwind's @theme. Minimal example (extend as needed):
@theme inline {
--color-primary: var(--mui-palette-primary-main);
--color-primary-light: var(--mui-palette-primary-light);
--color-primary-dark: var(--mui-palette-primary-dark);
--color-error: var(--mui-palette-error-main);
--color-text-primary: var(--mui-palette-text-primary);
}The 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 when you need it all.
See Tailwind CSS v4 integration—Extend Material UI classes and the linked playground.
Requirement: MUI CSS theme variables (cssVariables: true in createTheme) so the --mui-* variables exist. Align with the material-ui-theming skill.
VS Code IntelliSense
For slotProps and similar, add tailwindCSS.experimental.classRegex in VS Code settings.json as in Tailwind CSS v4 integration—Tailwind CSS IntelliSense for VS Code.
Snippet also lives in reference.md.
Tailwind CSS v3 (legacy)
Use the interoperability guide, not the v4 page:
- Install Tailwind v3 per upstream docs.
corePlugins: { preflight: false }so MUICssBaselineowns base resets.important: '#__next'or'#root'; App Router may needid="__next"on<body>manually.StyledEngineProviderwithinjectFirst(or Emotionprepend: truecache) for injection order.- Theme
defaultPropscontaineronModal,Dialog,Popover,Popperto the same root asimportant.
See Interoperability—Tailwind CSS v3 and Interoperability—Troubleshooting (table of root IDs).
Troubleshooting
v4: confirm Tailwind >= v4, layer order, and DevTools cascade layers (mui before utilities). See Tailwind CSS v4 integration—Troubleshooting.
v3: verify important selector matches root id, preflight: false, and injectFirst. See the interoperability Troubleshooting subsection linked above.
Further reading
| Topic | Link |
|---|---|
| Tailwind CSS v4 + MUI | Tailwind CSS v4 integration |
| CSS layers (MUI concepts) | CSS Layers |
| Interior slots | Overriding component structure—Interior slots |
| Tailwind v3 + MUI | Interoperability—Tailwind CSS v3 |