Full documentation of maz-ui (https://maz-ui.com). Rules first, then every page.
---
title: "maz-ui rules for AI agents"
description: "How to use maz-ui and its ecosystem in this project: look-up workflow, components, icons, helpers, Tailwind theme tokens, imports."
---
# maz-ui rules for AI agents
> These rules and the docs in `node_modules/maz-ui/docs` match the installed version of maz-ui (`node_modules/maz-ui/package.json`).
This project is built with **maz-ui** and its ecosystem (`@maz-ui/themes`, `@maz-ui/icons`, `@maz-ui/utils`, `@maz-ui/translations`, `@maz-ui/nuxt`). 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
Before creating a component, composable, helper, icon or style, check what maz-ui offers:
- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete", "phone input"), `get_component_api` (exact props, events, slots), `find_icons`, `get_theme_tokens` (Tailwind classes of the project and of maz-ui), `get_doc`, `review_code`.
- **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, resolve `maz-ui` from the app package). Read the relevant page before using an API.
Never guess an API: only use props, events, slots and imports that are documented.
### Components
- Use `Maz*` components instead of native elements or hand-made widgets: `MazBtn` (not ``), `MazInput`, `MazSelect`, `MazCheckbox`, `MazSwitch`, `MazTextarea`, `MazDialog`, `MazDialogConfirm`, `MazDrawer`, `MazBottomSheet`, `MazPopover`, `MazDropdown`, `MazTabs`, `MazTable`, `MazCard`, `MazAvatar`, `MazBadge`, `MazAlert`, `MazSkeleton`, `MazSpinner`, `MazDatePicker`, `MazInputPhoneNumber`, `MazDropzone`, `MazStepper`, `MazSidebar`, `MazPagination`...
- Prop values are typed: colors are `primary | secondary | accent | info | success | warning | destructive | contrast | transparent` (plus `surface` on some components), sizes `mini | xs | sm | md | lg | xl`.
- Feedback and overlays: `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states.
- Forms: `useFormValidator` / `useFormField` with your Standard Schema library (Zod, Valibot, ArkType).
### Icons
Use `@maz-ui/icons` (860+ icons: `MazTrash`, `MazXMark`, `MazMagnifyingGlass`, `MazFlagFR`, `MazLogoVue`...). Never inline SVG or add another icon library. Pass icon components to icon props: ``.
### Helpers and composables
Use `@maz-ui/utils` and maz-ui composables instead of lodash, VueUse or hand-written code: `debounce`, `throttle`, `sleep`, `isEqual`, `capitalize`, `formatCurrency`, `formatDate`, `formatNumber`, `formatPhoneNumber`, `getCookie`/`setCookie`, `useBreakpoints`, `useWindowSize`, `useTimer`, `useIdleTimeout`, `useSwipe`, `vClickOutside`, `vTooltip`, `vLazyImg`...
### 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 (the CSS file that imports `maz-ui/tailwindcss/theme.css`) adds its own `@theme` tokens (fonts, animations, colors...), `@custom-variant` and `@utility`, and the `definePreset` file sets the brand values of the maz-ui tokens. `get_theme_tokens` lists both; without the MCP server, read these files. When a value is missing, add a token to the project `@theme` and use its class instead of an arbitrary value.
- Colors: `primary`, `secondary`, `accent`, `info`, `success`, `warning`, `destructive`, `contrast` (each with `-foreground` and `-50` to `-950`), `surface`, `foreground`, `muted`, `divider`, `overlay`, plus `bg-container` and `bg-input`. Example: `bg-surface text-foreground border-divider`, `bg-primary text-primary-foreground`, `text-muted`.
- Never use 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: do not add `dark:` color overrides.
- Radius `rounded-*`, shadows `shadow-sm` to `shadow-xl` and `shadow-elevation`, spacing scale (`p-4`, `gap-2`), breakpoints `mob-*`, `tab-*`, `lap-*` (plus `sm` to `2xl`), utilities `flex-center`, `padded-container`.
- **No `maz:` prefix** in this project: it is internal to the maz-ui library and its documentation.
- 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/utils/helpers/debounce`, `@maz-ui/icons/static/MazTrash`. The `maz-ui` root entry only exports types. Never import from `maz-ui/src` or `maz-ui/dist`.
- With `@maz-ui/nuxt`, components and composables are auto-imported: do not import them.
### Before you finish
Run `review_code` (MCP) on the files you changed, or `npx @maz-ui/mcp review `, and fix every finding.
---
source: https://maz-ui.com/guide/ai-agents.md
---
---
title: "AI agents"
description: "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."
package: "maz-ui"
url: "https://maz-ui.com/guide/ai-agents"
---
# 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.
- Package: `maz-ui`
- Web: https://maz-ui.com/guide/ai-agents
## 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/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:
```bash
npx @maz-ui/mcp init
```
It 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](../ecosystem/mcp.md)) |
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.
**Tip: It never overwrites your own instructions**
- Your `CLAUDE.md` is never touched: Claude Code loads `.claude/rules/maz-ui.md` on top of it.
- In `AGENTS.md`, maz-ui only manages the section between `` and ``.
- In the MCP config files, only the `maz-ui` entry is added, the formatting and comments of the file are preserved. An existing server running `@maz-ui/mcp` under another name is kept as is.
- A file you created yourself with the same path is never overwritten.
### Options
```bash
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 added
```
Run it again after upgrading maz-ui: the rules follow the installed version.
### Nuxt: connected by default
With [`@maz-ui/nuxt`](../ecosystem/nuxt.md), the agents detected in the project are connected to the maz-ui MCP server when you start the dev server: the module only 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, so no rule file is written by default.
```ts
export default defineNuxtConfig({
modules: ['@maz-ui/nuxt'],
mazUi: {
// default: { rules: false, mcp: true }
agents: {
rules: true, // also write .claude/rules/maz-ui.md and the AGENTS.md section
targets: ['claude', 'agents-md'], // default: the detected agents
},
// or disable it: agents: false
},
})
```
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).
### 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](../ecosystem/mcp.md#configuration)).
Write the project files (`init`, the Nuxt option) when your whole team, or agents without MCP, need the rules.
## Version-matched docs
Each `maz-ui` release ships its documentation for agents in `node_modules/maz-ui/docs/`:
```txt
node_modules/maz-ui/docs/
├── README.md # index of every page, start here
├── rules.md # the rules below
├── manifest.json # machine-readable index, component APIs, icons, tokens
├── components/maz-btn.md # usage, examples and full API of each component
├── composables/ directives/ plugins/ guide/
├── ecosystem/ # themes, translations, icons, nuxt, utils, node...
└── reference/
├── tailwind-tokens.md # every Tailwind class and CSS variable of the theme
└── icons.md # the 860+ icon names
```
The 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](../ecosystem/mcp.md) 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.
```txt
/plugin marketplace add LouisMazel/maz-ui
/plugin install maz-ui@maz-ui
```
The 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):
```json
{
"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:
```bash
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 json
```
The command exits with an error code when it finds errors (or more warnings than `--max-warnings`).
| Rule | Severity | Detects |
| --- | --- | --- |
| `unknown-component` | error | `` (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`, `` |
| `unknown-icon` | error | An icon that does not exist in `@maz-ui/icons` |
| `prefer-maz-component` | warning | ``, ``, `