AI agents
Make Claude Code, Cursor, GitHub Copilot, Codex and the other AI coding agents use maz-ui and its ecosystem instead of re-implementing it - project rules, MCP server, version-matched docs, llms.txt and automatic code review.
Why
Left alone, coding agents rebuild what maz-ui already provides: native buttons instead of MazBtn, lodash instead of @maz-ui/utils, inline SVG instead of @maz-ui/icons, bg-blue-500 instead of the theme colors. They also guess APIs from outdated training data.
maz-ui gives them four things:
| What | Where | |
|---|---|---|
| Rules | How to use maz-ui in your project, loaded automatically by the agent | .claude/rules/maz-ui.md, AGENTS.md |
| Version-matched docs | Agent-ready markdown of the installed version: guides, component APIs, icons, Tailwind tokens | node_modules/maz-ui/agent-docs/, node_modules/@maz-ui/<package>/agent-docs/ |
| MCP server | Search by need, exact component APIs, icons, theme tokens, setup guides, code review | npx @maz-ui/mcp |
| Code review | Static checks against the real maz-ui APIs, in the agent loop and in CI | review_code tool, npx @maz-ui/mcp review |
Quick start
Run this command at the root of your project:
npx @maz-ui/mcp initIt detects the agents you use and configures them, using the docs of the maz-ui version installed in the project:
| Agent | Rules | MCP server |
|---|---|---|
| Claude Code | .claude/rules/maz-ui.md (always loaded) | .mcp.json |
| Cursor | AGENTS.md | .cursor/mcp.json |
| GitHub Copilot (VS Code) | AGENTS.md | .vscode/mcp.json |
| Codex, Windsurf, Zed, Gemini CLI... | AGENTS.md | global config of the agent (see MCP) |
When no agent is detected, it configures Claude Code and AGENTS.md. Commit the generated files: your whole team and your CI agents get them.
In a project without maz-ui (only @maz-ui/utils or @maz-ui/node, for example), it only registers the MCP server, which serves the docs bundled with @maz-ui/mcp: the rules are about the maz-ui components and are written once maz-ui is installed. Pass --docs <dir> to write them anyway.
For a fast start of the MCP server, install it in the project first (pnpm add -D @maz-ui/mcp): the configs then start the installed version through your package manager, in about a second and at the version of your lockfile, instead of downloading it with npx. See MCP server.
It never overwrites your own instructions
- Your
CLAUDE.mdis never touched: Claude Code loads.claude/rules/maz-ui.mdon top of it. - In
AGENTS.md, maz-ui only manages the section between<!-- BEGIN:maz-ui -->and<!-- END:maz-ui -->. - In the MCP config files, only the
maz-uientry is added, the formatting and comments of the file are preserved. An existing server running@maz-ui/mcpunder another name is kept as is. - A file you created yourself with the same path is never overwritten.
- If you edit the generated rules, your edits are kept and the rules are no longer updated: delete the file (or the section) to get the rules of a new maz-ui version. To add your own rules, write them in another file or outside the section.
Options
npx @maz-ui/mcp init --targets claude,agents-md,cursor,vscode # choose the agents
npx @maz-ui/mcp init --no-rules # MCP server only
npx @maz-ui/mcp init --no-mcp # rules only
npx @maz-ui/mcp init --dry-run # show the changes
npx @maz-ui/mcp init --remove # remove everything init addedRun it again after upgrading maz-ui: the rules follow the installed version.
Nuxt: opt-in
With @maz-ui/nuxt, set agents.mcp: true to connect the agents detected in the project to the maz-ui MCP server when you start the dev server: the module adds the maz-ui entry to their MCP config (.mcp.json, .cursor/mcp.json, .vscode/mcp.json). The instructions of the MCP server already give the maz-ui rules to the agents. Nothing is written by default.
export default defineNuxtConfig({
modules: ['@maz-ui/nuxt'],
mazUi: {
// default: { rules: false, mcp: false }
agents: {
mcp: true, // register the maz-ui MCP server
rules: true, // also write .claude/rules/maz-ui.md and the AGENTS.md section
targets: ['claude', 'agents-md'], // default: the detected agents
},
// or enable everything: agents: true
},
})It only runs in development (never in CI, in tests or during builds), writes nothing when no agent is detected, keeps the files in sync with the installed maz-ui version and never overwrites files it does not own. In a monorepo, it writes at the root of the workspace, where the agents start (agents.dir to choose another folder).
Monorepos with several Nuxt apps
Each app syncs the agent files when it starts (nuxt dev, nuxt prepare), and all of them write at the root of the workspace:
- Same options in every app: the first app writes the files, the next ones find them up to date and write nothing.
- Different options: they add up. An app with
rules: falsedoes not remove the rules written by an app withrules: true(onlynpx @maz-ui/mcp init --removeremoves them), and thetargetsof each app are added. Withagents.dir, each app writes in its own folder. - Apps started together (
nx run-many -t dev,turbo dev): the files are written atomically, an app never reads a file another app is writing. - Different maz-ui versions per app: the rules of the most recent version are kept, an app with an older maz-ui never downgrades them. Align the versions (a pnpm catalog, for example) to get the same rules everywhere.
One MCP server for the whole workspace
Started at the root, the MCP server serves the docs of the first maz-ui it finds: in the root node_modules, then in the workspaces of the monorepo (pnpm-workspace.yaml or the workspaces field of package.json), in their order. When the apps install different maz-ui versions, an agent working on one app can get the docs of the version of another app. Align the versions, or point the server to the docs of an app with --docs (see Version-matched docs).
Without any file in the project
The MCP server carries the rules in its instructions: registering it once for your user is enough, in every project, without writing anything in them.
- Claude Code: install the plugin, or run
claude mcp add maz-ui --scope user -- npx -y @maz-ui/mcp@latest. - Cursor, Windsurf, Codex...: add the server to the global MCP config of the agent (see MCP).
Write the project files (init, the Nuxt option) when your whole team, or agents without MCP, need the rules.
Version-matched docs
Every package of the ecosystem ships the documentation of its own version for agents in its agent-docs/ folder, so a package released on its own (@maz-ui/eslint-config, @maz-ui/stylelint-config, @maz-ui/upgrade) is never documented by another version. maz-ui also lists the other packages in its index:
node_modules/maz-ui/agent-docs/
├── README.md # index of its pages and of the other packages, start here
├── rules.md # the rules below
├── manifest.json # machine-readable index, component APIs, tokens
├── components/maz-btn.md # usage, examples and full API of each component
├── composables/ directives/ plugins/ guide/
└── reference/tailwind-tokens.md # every Tailwind class and CSS variable of the theme
node_modules/@maz-ui/icons/agent-docs/ # ecosystem/icons.md, reference/icons.md (the 860+ icon names)
node_modules/@maz-ui/themes/agent-docs/ # same layout for each package: README.md, manifest.json, pagesThe pages are the ones of this website, cleaned for agents: no live demos, every example as code, and the full API of each component (props with their accepted values, v-model, events, slots) generated from the TypeScript sources.
Agents read the docs of your version, not what they remember from their training data. The MCP server serves the same files.
MCP server
The MCP server gives agents tools that work with the needs they have, and verify their code:
| Tool | Purpose |
|---|---|
search_docs | Find what maz-ui provides for a need ("confirm before delete", "phone input", "debounce search") |
get_component_api | Exact props, values, events, slots of up to 10 components |
find_icons | Icons by meaning ("delete", "settings", "france flag") with their imports |
get_theme_tokens | The theme of your project (preset, @theme tokens, variants, utilities) and every Tailwind class and CSS variable of maz-ui |
get_doc | Any page of the docs, or only some sections |
list_docs | The whole catalog |
get_setup_guide | Installation in a Vue or Nuxt app, with or without Tailwind |
review_code | Review files against the installed maz-ui |
See MCP for the configuration of each agent.
Claude Code plugin
The maz-ui plugin bundles the MCP server, a maz-ui skill (rules and workflow) and a hook that reviews every .vue, .ts and .css file Claude edits, so it fixes maz-ui mistakes before you see them.
/plugin marketplace add LouisMazel/maz-ui
/plugin install maz-ui@maz-uiThe plugin works in every project, init configures one project for your whole team: use both or either.
Review hook without the plugin
The review hook of the plugin is the review --hook mode of the CLI. To use it alone, add it to .claude/settings.json (shared with your team) or .claude/settings.local.json (your machine only):
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [{ "type": "command", "command": "npx -y @maz-ui/mcp@latest review --hook", "timeout": 90 }]
}
]
}
}Each file Claude edits is reviewed; the errors and warnings are sent back to Claude, which fixes them.
Code review in CI
The checks of review_code are also available from the command line:
npx @maz-ui/mcp review "src/**/*.{vue,ts,css}"
npx @maz-ui/mcp review app --min-severity warning --max-warnings 0
npx @maz-ui/mcp review src --format jsonThe command exits with an error code when it finds errors (or more warnings than --max-warnings).
| Rule | Severity | Detects |
|---|---|---|
unknown-component | error | <MazButton> (did you mean MazBtn?) |
unknown-prop | warning | A prop the component does not have (colour) |
invalid-prop-value | error | color="red" on a component that accepts primary, secondary... |
boolean-prop-string | error | disabled="false" (a truthy string) |
unknown-model, unknown-event, unknown-slot | error | v-model:foo, @clik, <template #captions> |
unknown-icon | error | An icon that does not exist in @maz-ui/icons |
prefer-maz-component | warning | <button>, <input>, <select>, <textarea>, <dialog>... (a <button> that is a clickable card, with a layout, a component or a title and a subtitle, or an empty hit area, is left alone) |
inline-svg | warning | SVG icons written inline |
icon-button-label | warning | A MazBtn that only shows an icon, without text, content nor aria-label |
prefer-ecosystem, prefer-utils | warning / info | lodash, VueUse, toast, icon, tooltip, date picker... libraries that maz-ui already covers |
theme-colors | warning | Default Tailwind palette (bg-blue-500, text-gray-600, bg-white) |
hardcoded-color | warning | bg-[#1d90ff], color: #fff |
internal-prefix | error | The internal maz: prefix |
tailwind-v3 | warning | bg-opacity-50, flex-shrink-0... |
missing-reference | error | @apply in a SFC style block without @reference |
manual-dark-mode | warning | Dark mode handled by hand instead of useTheme() |
root-import, internal-import | error | Runtime imports from maz-ui (types only) or from src/dist |
nuxt-auto-import | info | Imports that @maz-ui/nuxt already auto-imports |
When something is intended, ignore it with a comment on the line above (<!-- maz-ui-review-ignore prefer-maz-component -->, // maz-ui-review-ignore theme-colors), or maz-ui-review-ignore-file for a whole file. Give the reason after --: <!-- maz-ui-review-ignore theme-colors -- frame over the video -->.
llms.txt
The documentation is also published for agents that browse the web:
- maz-ui.com/llms.txt: index of every page
- maz-ui.com/llms-full.txt: the whole documentation in one file
- Each page as markdown:
https://maz-ui.com/components/maz-btn.md
The rules
This is what init, the Nuxt option, the Claude Code plugin and the MCP server teach to your agents:
This project is built with maz-ui and its ecosystem. Reuse what it provides instead of re-implementing it: most UI elements, helpers, icons and styles you need already exist.
Look it up before you write it
- MCP server
maz-ui(when available):search_docs(describe the need: "confirm before delete"),get_component_api,find_icons,get_theme_tokens,get_doc,review_code. - Version-matched docs in
node_modules/maz-ui/agent-docs/andnode_modules/@maz-ui/<package>/agent-docs/(start withnode_modules/maz-ui/agent-docs/README.md, which lists the other packages; in a monorepo, the packages of the app).
Never guess an API: only use documented props, events, slots and imports.
Which package for what
maz-ui (components, composables, directives, plugins), @maz-ui/themes (brand colors, fonts, dark mode), @maz-ui/icons (icons, logos, flags), @maz-ui/utils (helpers), @maz-ui/translations (texts of the components), @maz-ui/nuxt (Nuxt module).
Components
- Use
Maz*components instead of native elements or hand-made widgets:MazBtn(not<button>),MazLink,MazInput,MazSelect,MazCheckbox,MazDialog,MazDrawer,MazPopover,MazDropdown,MazTabs,MazTable,MazCard,MazAvatar,MazBadge,MazAlert,MazDatePicker,MazInputPhoneNumber,MazDropzone,MazPagination... - Prop values are typed: colors are
primary | secondary | accent | info | success | warning | destructive | contrast | transparent(plussurfaceon some components), sizesmini | xs | sm | md | lg | xl. - A button with only an icon needs an
aria-label.
Feedback, overlays and forms
useToast()for notifications,useDialog()orMazDialogConfirmfor confirmations,useWait()for loading states,MazSkeleton/MazSpinnerwhile data loads.- These composables need their plugin. Vue:
app.use(ToastPlugin)frommaz-ui/plugins/toast(DialogPlugin,WaitPlugin,AosPluginlikewise). Nuxt:mazUi: { plugins: { toast: true } }, off by default like the directives (mazUi.directives.vTooltip, or import the directive). - Forms:
useFormValidator/useFormFieldwith your Standard Schema library (Zod, Valibot, ArkType).
Icons
Use @maz-ui/icons, never inline SVG nor another icon library. Pick the format by usage:
- Icon props (
<MazBtn :start-icon>,<MazIcon :icon>...): the raw SVG string, the lightest,@maz-ui/icons/raw/MazTrash. - Directly in a template: the component,
@maz-ui/icons/static/MazTrash, then<MazTrash class="size-5 text-muted" />(size and color from the text:1em,currentColor). - Not visible at first render (
v-if, menus, dialogs, tabs): the lazy component,@maz-ui/icons/lazy/MazTrash. Never for icons visible on load: each one is an extra request. <img>or CSS only for multicolor icons (flags, logos):@maz-ui/icons/svg/<name>.svg, the text color does not apply there.
Helpers
Use @maz-ui/utils/helpers/<name> and the maz-ui composables instead of lodash, VueUse or hand-written code: debounce, throttle, sleep, isEqual, formatCurrency, formatDate, formatNumber, formatPhoneNumber, capitalize, normalizeString, getCookie / setCookie, useBreakpoints, useWindowSize, useTimer, useIdleTimeout, useSwipe, vClickOutside, vTooltip, vLazyImg...
Texts and languages
The texts built in the components come from @maz-ui/translations: change the language with useTranslations().setLocale('fr') and customize the texts in its options, not in every component.
Styling with Tailwind
The maz-ui theme is exposed to Tailwind (@import 'maz-ui/tailwindcss/theme.css') and the project usually extends it. Only use theme tokens:
- Project tokens first: the Tailwind entry of the project adds its own
@themetokens, variants and utilities, and thedefinePresetfile sets the brand values.get_theme_tokenslists both (or read these files). When a value is missing, add a token to the project@themeinstead of an arbitrary value. - Colors:
primary,secondary,accent,info,success,warning,destructive,contrast(each with-foregroundand-50to-950),surface,foreground,muted,divider,overlay,bg-container,bg-input. Example:bg-surface text-foreground border-divider. - Never the default Tailwind palette (
bg-blue-500,text-gray-600,bg-white,text-black) nor hard-coded colors (#fff,rgb(),bg-[#...]). Theme colors already adapt to dark mode: nodark:color overrides. - Radius
rounded-*, shadowsshadow-smtoshadow-xlandshadow-elevation, spacing scale (p-4,gap-2), breakpointsmob-*,tab-*,lap-*(plussmto2xl), utilitiesflex-center,padded-container. - No
maz:prefix in this project: it is internal to the maz-ui library. - In custom CSS, use the variables:
var(--maz-primary),var(--maz-rounded-md),calc(var(--maz-space) * 4).
Theme
Brand colors, fonts, radius and spacing come from a @maz-ui/themes preset (definePreset), not from overrides scattered in CSS. Use useTheme() for dark mode and presets (toggleDarkMode, setColorMode, updateTheme), never toggle the dark class or store the mode yourself.
Imports
- Deep imports:
maz-ui/components/MazBtn,maz-ui/composables/useToast,maz-ui/directives/vTooltip,maz-ui/plugins/toast,@maz-ui/utils/helpers/debounce,@maz-ui/icons/raw/MazTrash. Themaz-uiroot entry only exports types. Never import frommaz-ui/srcormaz-ui/dist. - With
@maz-ui/nuxt, components and composables are auto-imported: do not import them. Icons are not: import them. The theme and the translations are set in themazUioptions ofnuxt.config, not with theMazUiVue plugin.
Before you finish
Run review_code (MCP) on the files you changed, or npx @maz-ui/mcp review <files>, and fix every finding.