kevogaba/finaxis-frontend / .agents/skills/material-ui-tailwind
material-ui-tailwind
VerifiedIntegrates Material UI with Tailwind CSS v4 using cascade layers (enableCssLayer, @layer order) and documents Tailwind v3 interoperability (preflight, important, injectFirst, portals). Use when combining MUI with Tailwind utilities, slotProps className, or theme token bridges.
| File | Kind | Size |
|---|---|---|
| AGENTS.md | markdown | 7.9 KB |
| README.md | markdown | 657 B |
| SKILL.md | skill md | 1.5 KB |
| reference.md | markdown | 1.1 KB |
AGENTS.md
View on GitHub# 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
1. [Tailwind CSS v4 (preferred)](#tailwind-css-v4-preferred)
2. [Next.js specifics](#nextjs-specifics)
3. [Vite and other SPAs](#vite-and-other-spas)
4. [Applying utilities to MUI components](#applying-utilities-to-mui-components)
5. [Theme tokens in Tailwind (`@theme`)](#theme-tokens-in-tailwind-theme)
6. [VS Code IntelliSense](#vs-code-intellisense)
7. [Tailwind CSS v3 (legacy)](#tailwind-css-v3-legacy)
8. [Troubleshooting](#troubleshooting)
9. [Further reading](#further-reading)
---
## Tailwind CSS v4 (preferred)
### Goals
1. Generate Tailwind with the `@layer` directive.
2. Order layers so `mui` comes before `utilities`, so Tailwind utilities override MUI predictably.
See [Tailwind CSS v4 integration—Overview](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#overview).
### Layer stack (typical)
At the top of your global CSS (example from docs):
```css
@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
1. 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.
2. App Router: `<AppRouterCacheProvider options={{ enableCssLayer: true }}>` in the root layout. `suppressHydrationWarning` on `<html>` appears in the doc example when relevant.
3. 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).
For 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).
---
## Vite and other SPAs
1. `StyledEngineProvider` with `enableCssLayer`.
2. `GlobalStyles` injecting `@layer theme, base, mui, components, utilities;` before the app tree.
See [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).
Example repo: [material-ui-vite-tailwind-ts](https://github.com/mui/material-ui/tree/master/examples/material-ui-vite-tailwind-ts).
---
## Applying utilities to MUI components
- `className`: root element of the component.
- `slotProps.{slot}.className`: interior [slots](https://mui.com/material-ui/customization/overriding-component-structure.md#interior-slots).
See [Tailwind CSS v4 integration—Usage](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#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):
```css
@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](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#extend-material-ui-classes) when you need it all.
See [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).
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](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md#tailwind-css-intellisense-for-vs-code).
Snippet also lives in [reference.md](reference.md).
---
## Tailwind CSS v3 (legacy)
Use the interoperability guide, not the v4 page:
1. Install Tailwind v3 per upstream docs.
2. `corePlugins: { preflight: false }` so MUI `CssBaseline` owns base resets.
3. `important: '#__next'` or `'#root'`; App Router may need `id="__next"` on `<body>` manually.
4. `StyledEngineProvider` with `injectFirst` (or Emotion `prepend: true` cache) for injection order.
5. Theme `defaultProps` `container` on `Modal`, `Dialog`, `Popover`, `Popper` to the same root as `important`.
See [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).
---
## Troubleshooting
v4: 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).
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](https://mui.com/material-ui/integrations/tailwindcss/tailwindcss-v4.md) |
| CSS layers (MUI concepts) | [CSS Layers](https://mui.com/material-ui/customization/css-layers.md) |
| Interior slots | [Overriding component structure—Interior slots](https://mui.com/material-ui/customization/overriding-component-structure.md#interior-slots) |
| Tailwind v3 + MUI | [Interoperability—Tailwind CSS v3](https://mui.com/material-ui/integrations/interoperability.md#tailwind-css-v3) |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |