Skip to content

Commit 91a3c34

Browse files
mapache-salvajemapache-salvaje
mapache-salvaje
and
mapache-salvaje
authored
[docs] Add agent skills for styling, theming, Next.js, and Tailwind CSS integrations (#48187)
Co-authored-by: mapache-salvaje <mapache@salvaje.com>
1 parent 5d3f123 commit 91a3c34

23 files changed

Lines changed: 1048 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,19 @@ import Button from '@mui/material/Button'; // Good
162162
import { Button } from '@mui/material'; // Avoid in packages
163163
```
164164

165+
## Agent Skills
166+
167+
Packaged guidance for common integration topics lives under `skills/`. Each skill is a self-contained directory:
168+
169+
| Skill | Focus |
170+
| :--------------------------------------------------------------------- | :---------------------------------------------------------- |
171+
| [skills/material-ui-styling](./skills/material-ui-styling/AGENTS.md) | `sx`, `styled()`, theme overrides, slots, global CSS |
172+
| [skills/material-ui-theming](./skills/material-ui-theming/AGENTS.md) | `createTheme`, design tokens, `colorSchemes`, CSS variables |
173+
| [skills/material-ui-nextjs](./skills/material-ui-nextjs/AGENTS.md) | App/Pages Router, Emotion cache, `next/font`, `Link`, SSR |
174+
| [skills/material-ui-tailwind](./skills/material-ui-tailwind/AGENTS.md) | Tailwind v4 `@layer`, `enableCssLayer`, v3 interop |
175+
176+
Read the relevant `AGENTS.md` when helping users with those topics.
177+
165178
## Pre-PR Checklist
166179

167180
1. `pnpm prettier` - Format code

‎docs/data/material/integrations/nextjs/nextjs.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,60 @@ Then, replace the Next.js Link with the wrapper component:
165165
</Button>
166166
```
167167

168+
### URL-driven UI and the Suspense boundary
169+
170+
When client components use Next.js App Router hooks that read the URL—for example `useSearchParams()` from `next/navigation` for filters, tabs, or pagination—Next.js expects a `<Suspense>` boundary around that part of the React tree.
171+
Without it, you may see build failures or runtime messages about a missing Suspense boundary (behavior depends on your Next.js version and static vs dynamic rendering).
172+
173+
This pattern is common with Material UI: `Table`, `Tabs`, `TextField`, and other controls are often implemented as client components that sync to the query string.
174+
175+
Recommended structure: keep `page.tsx` as a server component when possible, and wrap only the client subtree that calls `useSearchParams` in `<Suspense>`.
176+
177+
Avoid `fallback={null}` (or an empty fallback) for UI that reserves space in the layout (toolbars, filters, tab bars, and similar).
178+
The server and the initial streamed HTML then omit that subtree, and the real content appears only after the client hydrates, which often causes layout shift and hurts CLS.
179+
Prefer a fallback whose size and structure approximate the final UI, for example Material UI `Skeleton` inside `Stack` or `Box` with the same `minHeight`, flex direction, and breakpoints as the loaded component.
180+
181+
```tsx title="app/orders/page.tsx"
182+
import { Suspense } from 'react';
183+
import Box from '@mui/material/Box';
184+
import Skeleton from '@mui/material/Skeleton';
185+
import Stack from '@mui/material/Stack';
186+
import OrdersToolbar from './OrdersToolbar';
187+
188+
function OrdersToolbarFallback() {
189+
return (
190+
<Stack
191+
direction="row"
192+
spacing={2}
193+
useFlexGap
194+
sx={{ flexWrap: 'wrap', alignItems: 'center', minHeight: 56 }}
195+
>
196+
<Skeleton
197+
variant="rounded"
198+
height={40}
199+
sx={{ minWidth: 200, flexGrow: { xs: 1, sm: 0 } }}
200+
/>
201+
<Skeleton variant="rounded" width={120} height={40} />
202+
<Box sx={{ flexGrow: 1 }} />
203+
<Skeleton variant="rounded" width={100} height={40} />
204+
</Stack>
205+
);
206+
}
207+
208+
export default function Page() {
209+
return (
210+
<Suspense fallback={<OrdersToolbarFallback />}>
211+
<OrdersToolbar />
212+
</Suspense>
213+
);
214+
}
215+
```
216+
217+
`OrdersToolbar` would be a file marked with `'use client'` that calls `useSearchParams()` and renders Material UI components.
218+
Adjust the fallback's layout and Skeleton sizes so they match your real toolbar (or filter row) as closely as possible.
219+
220+
For details and version-specific notes, see the Next.js documentation for [`useSearchParams`](https://nextjs.org/docs/app/api-reference/functions/use-search-params).
221+
168222
## Pages Router
169223

170224
This section walks through the Material UI integration with the Next.js [Pages Router](https://nextjs.org/docs/pages/building-your-application), for both [Server-side Rendering](https://nextjs.org/docs/pages/building-your-application/rendering/server-side-rendering) (SSR) and [Static Site Generation](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation) (SSG).

‎skills/README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Material UI agent skills
2+
3+
Packaged guidance for AI agents and humans. Each skill is a directory under `skills/` with this layout:
4+
5+
```text
6+
skills/
7+
├── README.md # this file
8+
├── material-ui-styling/ # sx vs styled vs theme vs global CSS
9+
│ ├── AGENTS.md # full guide (read for complete detail)
10+
│ ├── SKILL.md # entry point + index
11+
│ ├── README.md
12+
│ ├── metadata.json
13+
│ └── reference.md
14+
├── material-ui-theming/ # createTheme, tokens, dark mode, CSS variables
15+
│ ├── AGENTS.md
16+
│ ├── SKILL.md
17+
│ ├── README.md
18+
│ ├── metadata.json
19+
│ └── reference.md
20+
├── material-ui-nextjs/ # Next.js App/Pages Router, cache, fonts, Link
21+
│ ├── AGENTS.md
22+
│ ├── SKILL.md
23+
│ ├── README.md
24+
│ ├── metadata.json
25+
│ └── reference.md
26+
└── material-ui-tailwind/ # Tailwind v4 layers + v3 interoperability
27+
├── AGENTS.md
28+
├── SKILL.md
29+
├── README.md
30+
├── metadata.json
31+
└── reference.md
32+
```
33+
34+
## Files in each skill
35+
36+
| File | Purpose |
37+
| :-------------- | :------------------------------------------------------------------ |
38+
| `AGENTS.md` | Full guide — the canonical source of truth for all agents and tools |
39+
| `SKILL.md` | Entry point and index (frontmatter + section summary) |
40+
| `README.md` | Human-readable overview |
41+
| `metadata.json` | Machine-readable metadata (version, references) |
42+
| `reference.md` | Quick-reference cheat sheet (imports, API shapes) |
43+
44+
## Discovery
45+
46+
The root `AGENTS.md` lists each skill and links directly to `skills/<name>/AGENTS.md`. Any agent that reads `AGENTS.md` files will find the skills from there.
47+
48+
## Adding a skill
49+
50+
1. Create `skills/<kebab-case-name>/` with `AGENTS.md`, `SKILL.md`, `README.md`, `metadata.json` (optional: `reference.md`).
51+
2. Add an entry to the table in the root `AGENTS.md` linking to the new `AGENTS.md`.
52+
3. List the new skill in the catalog below.
53+
54+
## Catalog
55+
56+
| Folder | Focus |
57+
| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------- |
58+
| [material-ui-styling](./material-ui-styling/) | Choosing styling scope: `sx`, `styled()`, theme overrides, global CSS; slots and state |
59+
| [material-ui-theming](./material-ui-theming/) | Theme object, design tokens, `colorSchemes`, `cssVariables` / `theme.vars`, TypeScript augmentation |
60+
| [material-ui-nextjs](./material-ui-nextjs/) | `@mui/material-nextjs`, App/Pages Router, Emotion cache, `next/font`, CSS layers, Next `Link` + MUI |
61+
| [material-ui-tailwind](./material-ui-tailwind/) | Tailwind v4 `@layer` + `enableCssLayer`; `className` / `slotProps`; v3 preflight / `important` / `injectFirst` |

‎skills/material-ui-nextjs/AGENTS.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Material UI and Next.js
2+
3+
Version 1.0.0
4+
5+
> Note: This document is for agents and LLMs integrating Material UI with Next.js. Source: `docs/data/material/integrations/nextjs/nextjs.md` and related integration docs in this repository.
6+
7+
---
8+
9+
## Abstract
10+
11+
Material UI uses Emotion for styles. On Next.js you must wire an Emotion cache so SSR and streaming produce correct CSS (prefer injecting styles into `head` instead of only `body`). The `@mui/material-nextjs` package supplies `AppRouterCacheProvider` (App Router) and `AppCacheProvider` / `DocumentHeadTags` (Pages Router). Material UI components ship as client components (`"use client"`); they still SSR but are not React Server Components. Match the package import suffix (for example `v15-appRouter`) to your Next.js major version.
12+
13+
---
14+
15+
## Table of contents
16+
17+
1. [App Router (recommended)](#app-router-recommended)
18+
2. [Pages Router](#pages-router)
19+
3. [Fonts (`next/font`)](#fonts-nextfont)
20+
4. [CSS theme variables and SSR](#css-theme-variables-and-ssr)
21+
5. [Other styling stacks (CSS layers)](#other-styling-stacks-css-layers)
22+
6. [Next.js Link and `component` prop](#nextjs-link-and-component-prop)
23+
7. [Further reading](#further-reading)
24+
25+
---
26+
27+
## App Router (recommended)
28+
29+
### Dependencies
30+
31+
Have `@mui/material` and `next` installed, then add:
32+
33+
- `@mui/material-nextjs`
34+
- `@emotion/cache`
35+
36+
Example: `pnpm add @mui/material-nextjs @emotion/cache`
37+
38+
### Root layout
39+
40+
In `app/layout.tsx`, wrap everything under `<body>` with `AppRouterCacheProvider` from the entry that matches your Next major, for example:
41+
42+
`import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';`
43+
44+
(Use the `v1X-appRouter` path that matches your Next.js version if not on v15.)
45+
46+
Why: it collects CSS from MUI System during server rendering and streaming so styles attach predictably; it is recommended so styles go to `<head>` instead of only `<body>`. See [Next.js integration—Configuration](https://mui.com/material-ui/integrations/nextjs.md#configuration).
47+
48+
### Optional cache `options`
49+
50+
Pass `options` to `AppRouterCacheProvider` to override [Emotion cache options](https://emotion.sh/docs/@emotion/cache#options), for example `key: 'css'` (the default MUI key is `mui`). See [Next.js integration—Custom cache (optional)](https://mui.com/material-ui/integrations/nextjs.md#custom-cache-optional).
51+
52+
### URL hooks and Suspense
53+
54+
Dashboards and internal tools often combine MUI client components with URL-driven UI (filters, tabs, pagination) using `useSearchParams()` from `next/navigation`.
55+
56+
Next.js expects a `<Suspense>` boundary around the part of the tree that uses `useSearchParams` (and similar patterns that opt the route into client-side rendering), otherwise you can get build failures or runtime errors about a missing Suspense boundary.
57+
58+
Practical pattern: keep `app/.../page.tsx` as a server component when possible; render a client subtree that uses components such as `Table`, `Tabs`, or `TextField` and is tied to the query string inside `<Suspense>` from that server page. Do not use `fallback={null}` for UI that occupies layout space (toolbars, filters, and similar); it tends to cause layout shift when the client mounts. Use a fallback that matches the real layout (for example `Skeleton` with `Stack` or `Box` and the same `minHeight` and rough dimensions as the final UI). Full example: [Next.js integration—URL-driven UI and the Suspense boundary](https://mui.com/material-ui/integrations/nextjs.md#url-driven-ui-and-the-suspense-boundary).
59+
60+
Official reference: [Next.js—`useSearchParams`](https://nextjs.org/docs/app/api-reference/functions/use-search-params) (static rendering and Suspense notes vary by major version).
61+
62+
---
63+
64+
## Pages Router
65+
66+
### Dependencies
67+
68+
Add `@mui/material-nextjs`, `@emotion/cache`, and `@emotion/server`.
69+
70+
Example: `pnpm add @mui/material-nextjs @emotion/cache @emotion/server`
71+
72+
### `_document.tsx`
73+
74+
- Import `DocumentHeadTags` and `documentGetInitialProps` from the `v15-pagesRouter` (or matching `v1X-pagesRouter`) entry.
75+
- Render `<DocumentHeadTags {...props} />` inside `<Head>`.
76+
- Assign `getInitialProps` to call `documentGetInitialProps`.
77+
78+
### `_app.tsx`
79+
80+
Wrap the app with `AppCacheProvider` from the same major entry (for example `v15-pagesRouter`).
81+
82+
### Optional: custom cache and cascade layers
83+
84+
- Pass a custom `emotionCache` into `documentGetInitialProps` options when needed.
85+
- For `@layer`, use `createEmotionCache({ enableCssLayer: true })` from `@mui/material-nextjs`, pass it from `_document` and align `_app` with the same cache pattern. See [Next.js integration—Cascade layers (optional)](https://mui.com/material-ui/integrations/nextjs.md#cascade-layers-optional).
86+
87+
### TypeScript
88+
89+
Extend `Document` props with `DocumentHeadTagsProps` from the same import path. See [Next.js integration—TypeScript](https://mui.com/material-ui/integrations/nextjs.md#typescript).
90+
91+
---
92+
93+
## Fonts (`next/font`)
94+
95+
App Router: theme modules that call `createTheme` need `'use client'` when they are consumed from server components. Use `next/font/google` (or local fonts), set `variable: '--font-…'`, put `className={font.variable}` on `<html>` (or as in docs), and set `typography.fontFamily` to `'var(--font-…)'`. Wrap with `ThemeProvider` inside `AppRouterCacheProvider` as needed.
96+
97+
Pages Router: similar pattern in `pages/_app.tsx` with `AppCacheProvider` and `ThemeProvider`.
98+
99+
Details: [Next.js integration—Font optimization](https://mui.com/material-ui/integrations/nextjs.md#font-optimization) (App) and [Next.js integration—Font optimization](https://mui.com/material-ui/integrations/nextjs.md#font-optimization-1) (Pages).
100+
101+
---
102+
103+
## CSS theme variables and SSR
104+
105+
Enable `cssVariables: true` in `createTheme` when using [CSS theme variables](https://mui.com/material-ui/customization/css-theme-variables/overview.md). For SSR flicker and `InitColorSchemeScript`, follow [CSS theme variables—Preventing SSR flickering](https://mui.com/material-ui/customization/css-theme-variables/configuration.md#preventing-ssr-flickering) and [CSS theme variables overview—Advantages](https://mui.com/material-ui/customization/css-theme-variables/overview.md#advantages). Add `suppressHydrationWarning` to `<html>` when using `colorSchemes` — the color scheme attribute is written client-side on first render and will otherwise produce a React hydration mismatch.
106+
107+
---
108+
109+
## Other styling stacks (CSS layers)
110+
111+
If you combine MUI with Tailwind CSS, CSS Modules, or other global CSS, set `enableCssLayer: true` on `AppRouterCacheProvider`:
112+
113+
`<AppRouterCacheProvider options={{ enableCssLayer: true }}>`
114+
115+
That wraps MUI output in `@layer mui` so anonymous layers can override as intended. See [Next.js integration—Using other styling solutions](https://mui.com/material-ui/integrations/nextjs.md#using-other-styling-solutions) and [MDN—@layer](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@layer).
116+
117+
---
118+
119+
## Next.js Link and `component` prop
120+
121+
Next.js v16: passing `next/link` directly into `component` can trigger "Functions cannot be passed directly to Client Components". Fix: a small client re-export:
122+
123+
```tsx
124+
'use client';
125+
import Link, { LinkProps } from 'next/link';
126+
export default Link;
127+
```
128+
129+
Import that wrapper and use `component={Link}` on `Button` and similar. See [Next.js integration—Next.js v16 Client Component restriction](https://mui.com/material-ui/integrations/nextjs.md#nextjs-v16-client-component-restriction).
130+
131+
Pages Router and theme-wide patterns: see [Routing libraries—Next.js Pages Router](https://mui.com/material-ui/integrations/routing.md#nextjs-pages-router) and the [material-ui-nextjs-pages-router-ts example](https://github.com/mui/material-ui/tree/master/examples/material-ui-nextjs-pages-router-ts).
132+
133+
---
134+
135+
## Further reading
136+
137+
| Topic | Link |
138+
| :------------------------------- | :----------------------------------------------------------------------------------------------------- |
139+
| Full integration guide | [Next.js integration](https://mui.com/material-ui/integrations/nextjs.md) |
140+
| Example (App Router, TypeScript) | [material-ui-nextjs-ts](https://github.com/mui/material-ui/tree/master/examples/material-ui-nextjs-ts) |
141+
| Routing + Link adapters | [Routing libraries](https://mui.com/material-ui/integrations/routing.md) |
142+
| RSC vs SSR (terminology) | [React WG discussion](https://github.com/reactwg/server-components/discussions/4) |
143+
144+
Import path cheat sheet: [reference.md](reference.md).

‎skills/material-ui-nextjs/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Material UI + Next.js (agent skill)
2+
3+
Integration guide for Material UI with the Next.js App Router and Pages Router: Emotion cache via `@mui/material-nextjs`, `ThemeProvider`, `next/font`, CSS layers with other tools, and `Link` usage.
4+
5+
## Files in this folder
6+
7+
| File | Purpose |
8+
| :------------ | :----------------------------- |
9+
| AGENTS.md | Full agent/LLM document |
10+
| SKILL.md | Entry point and index |
11+
| metadata.json | Version, abstract, references |
12+
| reference.md | Import paths and layout sketch |

‎skills/material-ui-nextjs/SKILL.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
name: material-ui-nextjs
3+
description: Integrates Material UI with Next.js App and Pages routers using @mui/material-nextjs, Emotion cache providers, next/font, CSS layers with Tailwind/CSS Modules, Link component prop patterns, CSS theme variables SSR notes, and App Router useSearchParams + Suspense. Use when setting up or debugging MUI in a Next.js app.
4+
license: MIT
5+
metadata:
6+
author: mui
7+
version: '1.0.0'
8+
---
9+
10+
# Material UI and Next.js
11+
12+
Agent skill for Next.js + Material UI wiring (SSR/streaming, cache providers, fonts, layers, Link, App Router URL state). SKILL.md is the entry; AGENTS.md is the full guide.
13+
14+
## When to apply
15+
16+
- New App Router or Pages Router app using `@mui/material`
17+
- Styles missing, wrong order, or in `body` instead of `head`
18+
- `next/font` + `ThemeProvider` / `createTheme`
19+
- Tailwind or CSS Modules + MUI (`enableCssLayer`)
20+
- `Button` + `component={Link}` or Next.js v16 client boundary errors
21+
- `useSearchParams` / URL-driven MUI views and Suspense boundaries
22+
23+
## Sections in AGENTS.md
24+
25+
| Area | Topics |
26+
| :------------ | :-------------------------------------------------------------------------------------- |
27+
| App Router | `AppRouterCacheProvider`, `@emotion/cache`, `options`, `useSearchParams` + `<Suspense>` |
28+
| Pages Router | `_document`, `_app`, `DocumentHeadTags`, `AppCacheProvider` |
29+
| Fonts | `'use client'` theme, `next/font`, CSS variables on `html` |
30+
| CSS variables | `cssVariables`, SSR flicker docs |
31+
| CSS layers | `enableCssLayer`, Tailwind / other CSS |
32+
| Link | Client wrapper, routing guide, examples repo |
33+
34+
## Full guide
35+
36+
Read [AGENTS.md](./AGENTS.md) for complete steps and doc links.
37+
38+
[reference.md](./reference.md) lists import paths and provider shape.

‎skills/material-ui-nextjs/metadata.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "1.0.0",
3+
"organization": "Material UI",
4+
"abstract": "Documents Next.js integration for Material UI: AppRouterCacheProvider and Pages Router Document/App cache wiring, Emotion options, next/font with themes, CSS theme variables and SSR flicker pointers, enableCssLayer for Tailwind/CSS Modules, and Next.js Link client-wrapper patterns.",
5+
"references": [
6+
"https://mui.com/material-ui/integrations/nextjs.md",
7+
"https://mui.com/material-ui/integrations/routing.md",
8+
"https://github.com/mui/material-ui/tree/master/examples/material-ui-nextjs-ts",
9+
"https://nextjs.org/docs/app"
10+
]
11+
}

0 commit comments

Comments
 (0)