Component library
Material UI (MUI)
Investedmarkdown record for Material UI (MUI) json record for Material UI (MUI)
Material UI is one of the most heavily invested design systems in AI affordances, on both sides of the fence. For consumers it ships an official @mui/mcp stdio server (three tools: useMuiDocs, fetchDocs, and a paid generateReactCode backed by the MUI Recipes service, optionally grounded in a Figma frame), a curated per-package llms.txt at https://mui.com/material-ui/llms.txt whose every entry is a .md twin of a docs page, and, newest and most interesting, four versioned Agent Skills checked into the repo under skills/ (styling, theming, Next.js, Tailwind) with SKILL.md/AGENTS.md/metadata.json layout and an explicit muiVersion: ">=9.0.0 <10.0.0" compatibility range. For builders, mui/material-ui carries a 241-line AGENTS.md (CLAUDE.md is a three-line pointer to it) with a hard pre-PR validation checklist, and the org keeps shared Claude Code skills in mui/mui-public/.claude/skills (a very elaborate pr-review skill with effort tiers and a verbatim subagent scope contract) that other MUI repos re-use. The notable gaps: no Figma Code Connect, no shadcn-style machine-readable component registry, and no llms-full.txt.
For consumers — building with it
Very well served, and improving fast. Three stacked layers. (1) Retrieval: a curated per-package llms.txt plus a .md twin for every docs page, consumable directly or through the official @mui/mcp server whose tool descriptions mandate their own use and whose fetcher is host-allowlisted to mui.com; (2) Judgement: four versioned Agent Skills that encode the decisions models get wrong (sx vs styled vs theme vs global, CSS-variable theming, Next.js Emotion cache/SSR, Tailwind v4 cascade layers with enableCssLayer), each with a compatibility semver range pinning them to v9; (3) Generation: the commercial Recipes backend behind generateReactCode, with Figma-frame grounding and a muiPairing version target. The install docs even anticipate the agent ignoring the MCP and hand you a rule file to fix it. What is missing is anything shadcn-registry-shaped: no machine-readable component registry JSON, no CLI that pulls component source into a project, and no distributed .cursorrules templates or ‘add to Cursor’ buttons.
For builders — maintaining it
Mature and unusually well-factored for a project this size. mui/material-ui has a 241-line root AGENTS.md as the single source (CLAUDE.md is a deliberate three-line pointer, no .cursorrules, no copilot-instructions.md, no committed .mcp.json), covering pnpm-only enforcement, monorepo layout, an error-message contract with a babel minify marker and an error-code registry, testing conventions, an axe-core a11y enrollment system whose generated JSON files CI checks for staleness, and a 7-step pre-PR gauntlet ending in the Vale prose linter. Reusable Claude Code skills live one level up in mui/mui-public (.claude/skills + .agents/skills, dual-namespaced): a heavyweight effort-tiered pr-review skill and circleci-why-flaky; mui/base-ui mirrors the layout with base-ui-review. No evidence of AI-authored codemods, AI triage bots, or AI-disclosure language in CONTRIBUTING.md.
Affordances · 8
Concrete AI-facing artifacts this system ships. Expand for snippets and links.
MCP server@mui/mcp — official MUI MCP serverofficialconsumers
stdio MCP server published to npm as @mui/mcp, now developed in mui/mui-x under packages/mcp and backed by the shared @mui/x-agent-tools package. Exposes three tools: useMuiDocs(sources) returns the docs catalog (llms.txt URLs + summaries) for one or more MUI packages; fetchDocs(urls) fetches full docs page content, hard-restricted to MUI origins; generateReactCode({prompt, threadId?, designContext?, muiPairing?, model?}) generates React + Material UI code from natural language, optionally grounded in a Figma frame, and requires a MUI_RECIPES_API_KEY from console.mui.com. Docs tools are free; codegen is the commercial hook. Install docs cover VS Code, Cursor, Windsurf, JetBrains, Zed (there is a first-party ‘MUI MCP’ Zed extension) and Claude Code.
description: ` You must use this tool to answer any questions related to MUI components or documentation. The description of the tool contains links to llms.txt files that the user has made available. ${availablePackagesText} 1. Pick the most suitable entry from the above list and use it as the "sources" argument. You can pass either the llms.txt URL or just the package name (e.g. "@mui/x-data-grid"); both resolve to the same docs. If it's just one, let it be an array with one entry. 2. Analyze the URLs listed in the llms.txt file. They are returned as absolute URLs, ready to pass to the next tool call. 3. Then fetch specific documentation pages relevant to the user's question with the subsequent tool call. `,~44,290 npm downloads/month. The Zed extension supports optional
preferred_themeandcomponent_filterfields.Agent skillskills/ — four official Material UI Agent Skillsofficialconsumers
Checked into the mui/material-ui repo root as
skills/: material-ui-styling, material-ui-theming, material-ui-nextjs, material-ui-tailwind. Each is a self-contained directory with SKILL.md (Anthropic-style YAML frontmatter: name, description, license, metadata.author/version), AGENTS.md (the canonical full guide), README.md (human), metadata.json (machine-readable: version, muiVersion semver range, abstract, canonical reference URLs), and reference.md (cheat sheet). Discovery is deliberately layered: the root AGENTS.md carries a table linking to each skills/<name>/AGENTS.md so ‘any agent that reads AGENTS.md files will find the skills from there’.--- name: material-ui-styling description: Chooses the right Material UI styling approach (sx, styled, theme overrides, global CSS) from official MUI guidance. Use when styling @mui/material components, customizing themes, overriding slots, or comparing sx vs styled. license: MIT metadata: author: mui version: '1.0.0' --- # Material UI styling Agent skill for picking the correct styling layer in Material UI (narrowest scope first). SKILL.md is the entry and index; AGENTS.md is the full guide. ## When to apply - Choosing among `sx`, `styled()`, theme `components`, or global CSS for a change - Overriding component slots or state safely - Comparing `sx` vs `styled()` semantics (spacing, theme shortcuts)Version-pinned to Material UI v9. metadata.json declares muiVersion “>=9.0.0 <10.0.0” and every AGENTS.md opens with a version notice telling the agent to verify API details on a different major.
llms.txtPer-package llms.txt + .md twin for every docs pageofficialconsumers
https://mui.com/material-ui/llms.txt is a 156-line curated index: one bullet per docs page, each linking to a
.mdvariant (e.g. https://mui.com/material-ui/react-button.md, ~33 KB of raw markdown) with a one-line description. Grouped under ## Components and further sections. MUI X has its own at https://mui.com/x/llms.txt (~66 KB). This per-package split is exactly what useMuiDocs consumes as its ‘sources’ argument. Notably there is NO root https://mui.com/llms.txt, no llms-full.txt, and no llms.txt for Joy UI, MUI System, Base UI, or Toolpad: all 404.# Material UI This is the documentation for the Material UI package. It contains comprehensive guides, components, and utilities for building user interfaces. ## Components - [App Bar React component](https://mui.com/material-ui/react-app-bar.md): The App Bar displays information and actions relating to the current screen. - [Backdrop React Component](https://mui.com/material-ui/react-backdrop.md): The Backdrop component narrows the user's focus to a particular element on the screen. - [How to customize](https://mui.com/material-ui/customization/how-to-customize.md): Learn how to customize Material UI components by taking advantage of different strategies for specific use cases. - [React Autocomplete component](https://mui.com/material-ui/react-autocomplete.md): The autocomplete is a normal text input enhanced by a panel of suggested options.AI docs pageGetting started > Model Context Protocol (MCP) for MUIofficialconsumers
The only AI-specific page in the Material UI docs nav (alongside installation, usage, templates...). Frames MCP as an anti-hallucination measure: ‘Quoting real, direct sources in answers’, ‘Linking to actual documentation—no imaginary links that lead to 404s’, ‘Using component code from officially published registries’. Includes per-editor install JSON, an MCP Inspector debugging recipe, and a copy-paste rule file for when the agent ignores the MCP.
The page’s own markdown twin is fetchable at https://mui.com/material-ui/getting-started/mcp.md. No /getting-started/ai/ or /getting-started/agents/ page exists (both 404).
AGENTS.mdRoot AGENTS.md (with CLAUDE.md pointer)officialbuilders
241 lines at the repo root: pnpm-only enforcement (‘Only pnpm is supported (yarn/npm will fail)’; 'Never use
cdto navigate into package directories for commands’), command cheat sheet, monorepo architecture, TypeScript conventions, a strict three-part error-message contract with a/ minify-error /babel marker, component file layout, testing conventions (createRenderer, Chai BDD, ‘Avoid fireEvent and setProps if possible’), an axe-core/visual-regression a11y enrollment guide, import depth rules, the Agent Skills table, and a numbered Pre-PR Checklist. CLAUDE.md is a deliberate three-line stub that redirects to it.## Pre-PR Checklist 1. `pnpm prettier` - Format code 2. `pnpm eslint` - Pass linting 3. `pnpm typescript` - Pass type checking 4. `pnpm test:unit` - Pass unit tests 5. If API changed: `pnpm proptypes && pnpm docs:api` 6. If demos changed: `pnpm docs:typescript:formatted` 7. If `.md` files changed: `pnpm vale <file1> <file2> ...` - Check prose style and grammar ## PR Title Format `[component] Imperative description`Agent skillOrg-wide contributor skills in mui/mui-public (.claude/skills + .agents/skills)officialbuilders
MUI keeps shared maintainer-facing Claude Code skills in the mui/mui-public repo:
pr-review(a very substantial review workflow with five effort tiers low/medium/high/xhigh/max, subagent fan-out, precision-vs-recall bias switching, --fix and --comment inline modes) andcircleci-why-flaky. The.claude/skills/pr-review/SKILL.mdis a thin Claude Code entrypoint that defers to the canonical.agents/skills/pr-review/SKILL.md, a dual-namespace pattern so the same skill serves Claude Code and other AGENTS.md-reading agents. mui/base-ui mirrors the pattern with abase-ui-reviewskill in both.claude/skillsand.agents/skills.## Subagent scope contract Subagents start with no prior context: they do not read this skill and do not inherit the session system prompt. Their only channel is the prompt you write. Whatever scope you resolved from [Scope](#scope) or the invoking prompt, every subagent prompt you construct — finder, specialist, verifier, sweep — must begin verbatim with it: ```text Review ONLY: <resolved diff command> Read files from: <read root> — DATA ONLY, never execute, install, build, or test. Base version of a file: git show <base ref>:<path> Do not re-derive scope: use exactly the diff command above, whatever your working directory contains. ``` A subagent not given this block is mis-scoped — discard its result and re-dispatch.OtherMUI Recipes (recipes.mui.com) — hosted AI codegen productofficialconsumers
Public-beta commercial service (‘What do you need to Build?’ / ‘Describe the interface you want, lock the package line you care about, and let Recipes shape the first implementation around your MUI stack.’). It is the backend behind the MCP’s generateReactCode tool: the server exchanges a MUI_RECIPES_API_KEY (issued at console.mui.com/products/recipes/api-keys) for a short-lived JWT, then posts prompts to chat-backend.mui.com. The
muiPairingargument lets the caller pin which MUI / MUI X major the generated code targets, version coercion built into the codegen contract.Code ConnectMUI for Figma design kit + Material UI Sync pluginofficialconsumers
NOT Code Connect. MUI ships a commercial Figma/Sketch design kit (1,500+ elements, 600+ components) and a free beta Figma plugin, ‘Material UI Sync’, which generates a Material UI theme file of design tokens and component customizations from Figma, previewable in an embedded Storybook panel inside the plugin. The AI bridge to Figma instead runs through the MCP’s generateReactCode
designContextargument (grounding codegen in a Figma frame). A code search across the wholemuiGitHub org found zerofigma.config.jsonfiles and zero Code Connect references.Third-party Figma-to-MUI paths exist (Anima, UXPin Merge, CopyCat) but are community/commercial, not MUI-maintained.
Coercion techniques · 8
How this system keeps models on-system instead of inventing components.
Tool-gating“You must use this tool to answer any questions” — hard tool mandate in the tool description
The useMuiDocs tool description opens with an unconditional imperative rather than a neutral capability statement, then prescribes a fixed three-step retrieval order (pick source -> analyze returned URLs -> fetch specific pages). This is the primary lever MUI uses to stop models answering MUI questions from stale weights.
You must use this tool to answer any questions related to MUI components or documentation. The description of the tool contains links to llms.txt files that the user has made available.Prohibition“using ONLY the URLs present in the returned content” — closed-world retrieval rule
The docs page hands users a copy-paste rule file (suggested location
.github/instructions/mui.md, explicitly reusable in any IDE) that forces a loop: call useMuiDocs, then fetchDocs restricted to URLs the previous tool returned, repeat until saturated, and only then answer. The capitalised ONLY is the coercive core: it forbids the agent from inventing or guessing doc URLs, which is the exact hallucination mode the page complains about.## Use the mui-mcp server to answer any MUI questions -- - 1. call the "useMuiDocs" tool to fetch the docs of the package relevant in the question - 2. call the "fetchDocs" tool to fetch any additional docs if needed using ONLY the URLs present in the returned content. - 3. repeat steps 1-2 until you have fetched all relevant docs for the given question - 4. use the fetched content to answer the questionTool-gatingHost allowlist enforced in code (agent physically cannot fetch off-system)
Rather than trusting the prompt to keep the agent on mui.com, fetchDocs is wrapped in an SSRF-style URL guard: only mui.com, *.mui.com, and Netlify docs previews are fetchable, and the outputSchema even tells the model that a blocked URL returns an error string. Prompt-level ‘only use MUI docs’ becomes a runtime invariant. The comment is candid about the residual prompt-injection surface.
/** * Hosts MUI serves docs / `llms.txt` from. Allowlist only: nothing else is fetchable, no matter how * an attacker host is spelled or resolves (private IPs, IPv4-mapped, redirects, DNS rebinding). * * Known boundary: this trusts any `*.mui.com` subdomain, any port on `mui.com`, and any Netlify site * matching `*--material-ui-docs.netlify.app`. Docs fetches carry no credentials, so the worst case is * prompt injection from attacker-controlled content, not a key leak. */ function isMuiDocsHost(host: string): boolean { return ( host === 'mui.com' || host.endsWith('.mui.com') || // Netlify deploy previews: `<context>--material-ui-docs.netlify.app` (plus the base host). host === 'material-ui-docs.netlify.app' || host.endsWith('--material-ui-docs.netlify.app') ); }Curated contextNarrowest-scope-first decision ladder for styling
The styling skill’s whole job is to stop agents reaching for the biggest hammer. It encodes a four-rung ordered ladder (sx -> styled() -> theme.components -> GlobalStyles/CssBaseline) with an explicit two-sided prohibition at the bottom, plus slot/state-class rules that ban bare global selectors and hashed class names ('Do not rely on the full hashed class string. Use only the stable
Mui*fragment.'). It is paired with a bad/good CSS exemplar.## Quick decision (use in order) 1. Single instance or local layout? → [`sx`](https://mui.com/system/getting-started/the-sx-prop/) 2. Same override in many places? → [`styled()`](https://mui.com/system/styled/) around the MUI component (or a thin wrapper component) 3. All instances of a component should look different by default? → [`theme.components`](https://mui.com/material-ui/customization/theme-components.md) (`styleOverrides`, `variants`, `defaultProps`) 4. Global element baselines (for example all `h1`) or non-component CSS? → [`GlobalStyles`](https://mui.com/material-ui/api/global-styles.md) or [`CssBaseline`](https://mui.com/material-ui/react-css-baseline.md) overrides Do not jump to global theme overrides for a one-off screen; do not use `sx` for large repeated systems if a themed variant or `styled()` wrapper is clearer.Registry metadataVersion-fencing the skill so the agent self-invalidates on the wrong major
Every skill carries a machine-readable semver range in metadata.json AND a prose version notice at the top of AGENTS.md instructing the agent to verify API details if the project is on a different major. Combined with the MCP’s
muiPairingcodegen argument, this is MUI’s answer to the biggest failure mode for a 10-year-old library: models confidently emitting v4/v5-era APIs into a v9 codebase.# Material UI styling 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: This document is for agents and LLMs maintaining or generating Material UI code. It follows [How to customize](https://mui.com/material-ui/customization/how-to-customize.md) and related sources in this repository (`docs/data/material/customization/`, `docs/data/system/`).Curated contextTwo-tier skill layout: SKILL.md as router, AGENTS.md as payload
Deliberate progressive disclosure. SKILL.md is frontmatter + a ‘When to apply’ trigger list + a numbered priority index of the sections in AGENTS.md; the model only pulls the full guide when a trigger matches. metadata.json duplicates the canonical .md doc URLs so an agent (or the MCP) can jump straight to source. The README explicitly designates AGENTS.md as ‘the canonical source of truth for all agents and tools’.
## Files in each skill | File | Purpose | | :-------------- | :------------------------------------------------------------------ | | `AGENTS.md` | Full guide — the canonical source of truth for all agents and tools | | `SKILL.md` | Entry point and index (frontmatter + section summary) | | `README.md` | Human-readable overview | | `metadata.json` | Machine-readable metadata (version, references) | | `reference.md` | Quick-reference cheat sheet (imports, API shapes) | ## Discovery 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.Validation loopMandatory contributor validation loop (7-step pre-PR checklist incl. a prose linter)
Builder-side. The root AGENTS.md ends with an ordered gauntlet the agent must run before proposing a PR: prettier, eslint, tsc, unit tests, then conditional regeneration steps,
pnpm proptypes && pnpm docs:apiif the API changed,pnpm docs:typescript:formattedif demos changed (demos must be authored in TypeScript, JS is generated), andpnpm valefor prose. CI independently fails if generated a11y JSON is stale (‘CI fails if any are stale’), so the loop is enforced, not advisory.### API Documentation After changing component props or TypeScript declarations: ```bash pnpm proptypes && pnpm docs:api ``` ### Docs demos Always author the TypeScript version of the demos. To generate the JavaScript variant, run: ```bash pnpm docs:typescript:formatted ```Validation loopEffort-tiered review skill with precision/recall bias switching
Builder-side. MUI’s shared pr-review skill goes well past ‘review the diff’. It exposes five named effort levels that change subagent fan-out AND the model’s error preference: medium is a precision bias (‘every finding actionable’), high/xhigh/max deliberately flip to recall (‘missed bug ships’), with max adding verifier subagents for surviving candidates. It also instructs finders not to self-censor: ‘Finders that silently drop half-believed candidates bypass verify step — dominant cause of misses.’
Medium effort = **precision** bias: every finding actionable. **high**, **xhigh**, **max** shift to **recall**; missed bug ships. Surface uncertain findings when mechanism realistic, label clearly. ## Effort levels - **low** — fastest: bug-only hunk pass. Skip Tests, Simplifications, Docs, test/fixture hunks. Flag only high-confidence runtime-correctness bugs visible from hunk alone. - **medium** (default) — one agent reviews Bugs, Tests, Simplifications, Docs, plus triggered API design/performance concerns, then verifies locally. Precision bias. Add one bug/regression subagent only for large, risky, fragile diffs. - **max** — `xhigh` plus verifier subagents for surviving candidates. Highest cost, strongest recall bias.
Platform integrations
Figma
Official MUI for Figma design kit (commercial, 600+ Material UI / MUI X / Joy UI components, 1,500+ elements) plus the free beta ‘Material UI Sync’ Figma community plugin, which generates a Material UI theme file of design tokens and component customizations from Figma with an embedded Storybook preview panel. Separately, the MCP’s generateReactCode accepts a designContext to ground codegen in a Figma frame. No Figma Code Connect anywhere in the mui org.
Storybook
No public Storybook for the Material UI component library itself; mui.com’s own docs site with live demos is the canonical surface, and there is no Storybook MCP/addon integration. Storybook appears only as the embedded preview panel inside the Material UI Sync Figma plugin.
Other
UXPin Merge renders real Material UI React components in the design tool (third-party). Anima and CopyCat offer Figma-to-MUI conversion (third-party, not MUI-maintained). No Supernova, Knapsack, or zeroheight integration found.
Gaps & open questions
Not found, despite direct probing: (1) no root https://mui.com/llms.txt and no llms-full.txt (both 404); llms.txt exists only for /material-ui/ and /x/; Joy UI, MUI System, Base UI and Toolpad all 404. (2) No machine-readable component registry: https://mui.com/r/registry.json and /material-ui/registry.json both 404, even though the MCP docs page claims a benefit of ‘Using component code from officially published registries’; it was not possible to locate the registry that sentence refers to. (3) No Figma Code Connect: a GitHub code search across org:mui returned 0 hits for code-connect and 0 figma.config.json files. (4) No .cursorrules, .cursor/rules/, .github/copilot-instructions.md, .claude/ directory, or .mcp.json in mui/material-ui (all probed, all 404); the org’s Claude skills live in mui/mui-public and mui/base-ui instead. (5) No dedicated /getting-started/ai/ or /getting-started/agents/ docs page; MCP is the only AI page in the nav. (6) No distributed ‘add to Cursor/Claude’ one-click install buttons found on the MCP page. (7) this study did not verify any community/third-party MUI MCP server: an npm registry search for ‘mui mcp’ surfaced only the official @mui/mcp. (8) generateReactCode is gated behind a paid MUI_RECIPES_API_KEY, so it was not possible to observe its system prompt or the constraints it imposes on generated code. The on-system coercion happening server-side at chat-backend.mui.com is a black box. (9) No evidence found of AI-assisted codemods (MUI’s @mui/codemod migrations appear to remain deterministic jscodeshift transforms) or of AI triage bots in .github/workflows; the AI-sounding priority-support-validation-prompt.yml is a plain templated support-key comment, not an LLM. (10) CONTRIBUTING.md was not read in full, so any AI-contribution policy language there is unverified.
Sources
- mui.com/material-ui/getting-started/mcp/ (opens in new tab)
- mui.com/material-ui/getting-started/mcp.md (opens in new tab)
- mui.com/material-ui/llms.txt (opens in new tab)
- mui.com/material-ui/getting-started/design-resources.md (opens in new tab)
- raw.githubusercontent.com/mui/material-ui/HEAD/AGENTS.md (opens in new tab)
- raw.githubusercontent.com/mui/material-ui/HEAD/CLAUDE.md (opens in new tab)
- raw.githubusercontent.com/mui/material-ui/HEAD/skills/README.md (opens in new tab)
- raw.githubusercontent.com/mui/material-ui/HEAD/skills/material-ui-styling/SKILL.md (opens in new tab)
- raw.githubusercontent.com/mui/material-ui/HEAD/skills/material-ui-styling/AGENTS.md (opens in new tab)
- raw.githubusercontent.com/mui/material-ui/HEAD/skills/material-ui-theming/metadata.json (opens in new tab)
- raw.githubusercontent.com/mui/material-ui/HEAD/skills/material-ui-tailwind/AGENTS.md (opens in new tab)
- raw.githubusercontent.com/mui/mui-x/HEAD/packages/mcp/README.md (opens in new tab)
- raw.githubusercontent.com/mui/mui-x/HEAD/packages/x-agent-tools/src/docs/tools.ts (opens in new tab)
- raw.githubusercontent.com/mui/mui-x/HEAD/packages/x-agent-tools/src/docs/url-guard.ts (opens in new tab)
- raw.githubusercontent.com/mui/mui-public/HEAD/.agents/skills/pr-review/SKILL.md (opens in new tab)