@maz-ui/mcp 5.1.1 → 5.2.0-beta.0

package/docs/agents/agents-md.md

@@ -1,41 +1,56 @@
 ## maz-ui
 
-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.
+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
 
-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"), `get_component_api`, `find_icons`, `get_theme_tokens`, `get_doc`, `review_code`.
+- **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, the `maz-ui` of the app).
 
-- **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 documented props, events, slots and imports.
 
-Never guess an API: only use props, events, slots and imports that are documented.
+### 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>`), `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`...
+- 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` (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.
+- A button with only an icon needs an `aria-label`.
+
+### Feedback, overlays and forms
+
+- `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states, `MazSkeleton` / `MazSpinner` while data loads.
+- These composables need their plugin. Vue: `app.use(ToastPlugin)` from `maz-ui/plugins/toast` (`DialogPlugin`, `WaitPlugin`, `AosPlugin` likewise). Nuxt: `mazUi: { plugins: { toast: true } }`, off by default like the directives (`mazUi.directives.vTooltip`, or import the directive).
 - 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: `<MazBtn :start-icon="MazTrash">`.
+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 and composables
+### Helpers
 
-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`...
+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 (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.
+- **Project tokens first**: the Tailwind entry of the project adds its own `@theme` tokens, variants and utilities, and the `definePreset` file sets the brand values. `get_theme_tokens` lists both (or read these files). When a value is missing, add a token to the project `@theme` 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`, `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: no `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.
+- **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
@@ -44,8 +59,8 @@ Brand colors, fonts, radius and spacing come from a `@maz-ui/themes` preset (`de
 
 ### 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.
+- 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`. 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. Icons are not: import them. The theme and the translations are set in the `mazUi` options of `nuxt.config`, not with the `MazUi` Vue plugin.
 
 ### Before you finish
 

package/docs/agents/claude-rule.md

@@ -1,41 +1,56 @@
 # maz-ui
 
-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.
+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
 
-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"), `get_component_api`, `find_icons`, `get_theme_tokens`, `get_doc`, `review_code`.
+- **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, the `maz-ui` of the app).
 
-- **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 documented props, events, slots and imports.
 
-Never guess an API: only use props, events, slots and imports that are documented.
+### 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>`), `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`...
+- 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` (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.
+- A button with only an icon needs an `aria-label`.
+
+### Feedback, overlays and forms
+
+- `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states, `MazSkeleton` / `MazSpinner` while data loads.
+- These composables need their plugin. Vue: `app.use(ToastPlugin)` from `maz-ui/plugins/toast` (`DialogPlugin`, `WaitPlugin`, `AosPlugin` likewise). Nuxt: `mazUi: { plugins: { toast: true } }`, off by default like the directives (`mazUi.directives.vTooltip`, or import the directive).
 - 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: `<MazBtn :start-icon="MazTrash">`.
+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 and composables
+### Helpers
 
-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`...
+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 (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.
+- **Project tokens first**: the Tailwind entry of the project adds its own `@theme` tokens, variants and utilities, and the `definePreset` file sets the brand values. `get_theme_tokens` lists both (or read these files). When a value is missing, add a token to the project `@theme` 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`, `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: no `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.
+- **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
@@ -44,8 +59,8 @@ Brand colors, fonts, radius and spacing come from a `@maz-ui/themes` preset (`de
 
 ### 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.
+- 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`. 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. Icons are not: import them. The theme and the translations are set in the `mazUi` options of `nuxt.config`, not with the `MazUi` Vue plugin.
 
 ### Before you finish
 

package/docs/components/maz-alert.md

@@ -227,7 +227,7 @@ You can use either title, content, or both.
 
 - `title` (`string`): Title of the alert.
 - `content` (`string`): Content of the alert.
-- `icon` (`any`): Icon of the alert - can be a component or icon name string.
+- `icon` (`string | IconComponent`): Icon of the alert - can be a component or icon name string.
 - `hide-icon` (`boolean`, default: `false`): Hide the icon.
 - `color` (`MazAlertColor`, default: `"info"`): Color of the alert. Values: `'success'`, `'warning'`, `'destructive'`, `'info'`, `'primary'`, `'secondary'`, `'accent'`, `'contrast'` (non exhaustive).
 - `icon-size` (`MazIconSize`, default: `"md"`): Size of the icon.

package/docs/components/maz-bottom-sheet.md

@@ -217,7 +217,7 @@ The bottom sheet is a modal `dialog` labelled by its `title` and described by it
 
 - `model-value` (`boolean`, `v-model`): Modal's model value.
 - `title` (`string`): Title of the bottom sheet in the header.
-- `icon` (`any`): Icon displayed on the left of the header. Accepts an icon value or a full `MazIconProps` object.
+- `icon` (`MazIconLike`): Icon displayed on the left of the header. Accepts an icon value or a full `MazIconProps` object.
 - `max-width` (`` `${number}rem` | `${number}px` | `${number}em` | `${number}vw` | `${number}vh` | `${number}vmin` | `${number}vmax` | `${number}%` | `${number}ch` | `${number}cm` | `${number}mm` | `${number}in` | `${number}ex` | `${number}pc` | `${number... ``, default: `"40rem"`): Bottom sheet's max-width, applied from the tablet breakpoint and up (full-width below).
 - `hide-close-button` (`boolean`, default: `false`): Remove the close button in the header.
 - `hide-header` (`boolean`, default: `false`): Remove the whole header.

package/docs/components/maz-btn.md

@@ -406,9 +406,9 @@ When `to` attribute is provided, the component automatically becomes a `<RouterL
 - `loading` (`boolean`, default: `false`): Enable the button loader.
 - `disabled` (`boolean`, default: `false`): Disable the button.
 - `fab` (`boolean`, default: `false`): If true, the button will have a fab style.
-- `icon` (`any`): The icon to display in the fab variant. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) for the common case, or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, flipIconForRtl, …).
-- `start-icon` (`any`): The icon to display on the inline-start edge (left in LTR, right in RTL). Accepts a bare value or a full `MazIconProps` object.
-- `end-icon` (`any`): The icon to display on the inline-end edge (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `icon` (`MazIconLike`): The icon to display in the fab variant. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) for the common case, or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, flipIconForRtl, …).
+- `start-icon` (`MazIconLike`): The icon to display on the inline-start edge (left in LTR, right in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `end-icon` (`MazIconLike`): The icon to display on the inline-end edge (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
 - `padding` (`boolean`, default: `true`): Apply the padding of the button, set it to `false` to remove it.
 - `justify` (`"center" | "end" | "start" | "space-between" | "space-around" | "space-evenly"`, default: `"center"`): Choose how the elements are aligned in the button.
 - `active` (`boolean`, default: `false`): If true, the button will have an active state.

package/docs/components/maz-container.md

@@ -226,8 +226,8 @@ Use the `header` slot to fully customize the header, or use `title`, `icon-start
 - `rounded-size` (`MazRoundedSize`, default: `'md'`): Size of the rounded. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
 - `transparent` (`boolean`, default: `false`): Remove background color.
 - `overflow-hidden` (`boolean`, default: `true`): Hide overflow.
-- `start-icon` (`any`): Icon displayed on the inline-start edge of the header (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
-- `end-icon` (`any`): Icon displayed on the inline-end edge of the header (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `start-icon` (`MazIconLike`): Icon displayed on the inline-start edge of the header (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
+- `end-icon` (`MazIconLike`): Icon displayed on the inline-end edge of the header (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
 - `icon-size` (`MazIconSize`, default: `"md"`): Size of the icon.
 - `block` (`boolean`, default: `false`): Display the container in full width.
 - `content-class` (`string`): Additional class to add to the content wrapper.

package/docs/components/maz-dropdown.md

@@ -376,7 +376,7 @@ The trigger button exposes the menu state (`aria-haspopup="menu"`, `aria-expande
 - `menu-panel-class` (`ClassValue`): Additional CSS classes to apply to the dropdown menu panel Useful for customizing the dropdown appearance (background, border, etc.).
 - `menu-panel-style` (`StyleValue`): Inline styles to apply to the dropdown menu panel Useful for custom styling. You may use `!important` to override default styles.
 - `block` (`boolean`, default: `false`): Makes the dropdown button expand to full width of its container.
-- `dropdown-icon` (`any`): Icon to use instead of the default chevron for the dropdown indicator Custom icon to display in place of the default chevron. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
+- `dropdown-icon` (`MazIconLike`): Icon to use instead of the default chevron for the dropdown indicator Custom icon to display in place of the default chevron. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
 - `dropdown-icon-animation` (`boolean`, default: `true`): Controls whether the dropdown icon rotates when the dropdown is opened.
 - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): Size of the dropdown button.
 - `transition` (`string`, default: `"scale-pop"`): Transition to use when the dropdown is opened or closed. Values: `'scale-pop'`, `'scale-fade'`, `'string'` (non exhaustive).

package/docs/components/maz-dropzone.md

@@ -355,8 +355,8 @@ Customize the upload request using `uploadUrl`, `requestOptions` and `transformB
 
 ### Events
 
-- `@error` (payload: `values: { files: File[] | null; event: DragEvent | null; code: MazDropzoneErrorCode; }`): Event emitted when an error occurs
 - `@add` (payload: `value: File`): Event emitted when a file is added to the dropzone
+- `@error` (payload: `values: { files: File[] | null; event: DragEvent | null; code: MazDropzoneErrorCode; }`): Event emitted when an error occurs
 - `@drop` (payload: `values: { files: File[] | null; event: DragEvent; }`): Event emitted when files are dropped in the dropzone
 - `@update:modelValue` (payload: `value: MazDropzoneFileData[]`)
 - `@enter` (payload: `values: { files: File[] | null; event: DragEvent; }`): Event emitted when dragged files enter the dropzone

package/docs/components/maz-icon.md

@@ -191,8 +191,8 @@ Source: [Heroicons](https://heroicons.com/) - see also the [icon set page](../ec
 
 ### Props
 
-- `icon` (`any`): The icon to render. Accepts: - A Vue component (e.g. `import { MazStar } from '@maz-ui/icons/static/MazStar'`) - A URL or `data:` URI to a `.svg` file (`'/icons/star.svg'`, `'data:image/svg+xml,…'`) - A raw SVG string (`'<svg viewBox="0 0 24 24">…</svg>'`) The component detects the format and renders accordingly.
-- `fallback` (`any`, default: `MazQuestionMarkCircle`): Fallback icon used when: - `icon` is not provided - `icon` is a URL that fails to load or returns invalid SVG Same shape as `icon`. Defaults to the imported `MazQuestionMarkCircle` if neither `icon` nor `fallback` resolves to anything renderable.
+- `icon` (`MazIconValue`): The icon to render. Accepts: - A Vue component (e.g. `import { MazStar } from '@maz-ui/icons/static/MazStar'`) - A URL or `data:` URI to a `.svg` file (`'/icons/star.svg'`, `'data:image/svg+xml,…'`) - A raw SVG string (`'<svg viewBox="0 0 24 24">…</svg>'`) The component detects the format and renders accordingly.
+- `fallback` (`MazIconValue`, default: `MazQuestionMarkCircle`): Fallback icon used when: - `icon` is not provided - `icon` is a URL that fails to load or returns invalid SVG Same shape as `icon`. Defaults to the imported `MazQuestionMarkCircle` if neither `icon` nor `fallback` resolves to anything renderable.
 - `size` (`MazIconSize`): Predefined keyword (`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) or any CSS length.
 - `title` (`string`): Sets a `<title>` element inside the SVG for screen-reader accessibility.
 - `svg-attributes` (`Record<string, string | number>`): Extra attributes to merge onto the rendered `<svg>` root.

package/docs/components/maz-input.md

@@ -310,8 +310,8 @@ Use the attribute `rounded-size` with a value in `'none' | 'sm' | 'md' | 'lg' |
 - `debounce` (`number | boolean`, default: `false`): Enables input debouncing to limit the frequency of value updates. When true, uses 500ms delay. When a number, uses that value as delay in milliseconds.
 - `auto-focus` (`boolean`, default: `false`): Automatically focuses the input when the component mounts.
 - `border-active` (`boolean`, default: `false`): When true, shows the colored border immediately instead of only on focus.
-- `start-icon` (`any`): Icon displayed on the inline-start edge of the input (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, …).
-- `end-icon` (`any`): Icon displayed on the inline-end edge of the input (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `start-icon` (`MazIconLike`): Icon displayed on the inline-start edge of the input (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, …).
+- `end-icon` (`MazIconLike`): Icon displayed on the inline-end edge of the input (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
 - `rounded-size` (`MazRoundedSize`, default: `'md'`): Controls the border radius of the input component. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
 - `block` (`boolean`): Makes the input expand to the full width of its container.
 - `name` (`string`): The name of the input field. Used for form submission and validation.

package/docs/components/maz-link.md

@@ -134,8 +134,8 @@ If no `to` or `href` is provided, the component will be a `button` by default. Y
 - `underline` (`boolean`, default: `false`): Add an underline to the link.
 - `underline-hover` (`boolean`, default: `true`): Add an underline only on hover.
 - `auto-external` (`boolean`, default: `true`): Add an external icon to the link if target is '_blank'.
-- `start-icon` (`any`): Icon displayed on the inline-start edge (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control.
-- `end-icon` (`any`): Icon displayed on the inline-end edge (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `start-icon` (`MazIconLike`): Icon displayed on the inline-start edge (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control.
+- `end-icon` (`MazIconLike`): Icon displayed on the inline-end edge (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
 - `disabled` (`boolean`, default: `false`): The disabled state of the link if the component is a button.
 
 ### Slots

package/docs/components/maz-select-country.md

@@ -484,10 +484,10 @@ This ensures consistent internationalization across your application while provi
 - `required` (`boolean`): Make the input required in the form.
 - `placeholder` (`string`): The placeholder of the select.
 - `label` (`string`): The label of the select.
+- `search-function` (`((query: string, options: Option[]) => Option[] | undefined)`): Replace the default search function to provide a custom search function.
 - `transition` (`string`, default: `'scale-fade'`): The transition name of the panel list options.
 - `prefer-position` (`MazPopoverPreferPosition`, default: `'bottom-start'`): The prefer position of the list.
 - `fallback-position` (`MazPopoverFallbackPosition`, default: `'top-start'`): The fallback position of the list.
-- `search-function` (`((query: string, options: Option[]) => Option[] | undefined)`): Replace the default search function to provide a custom search function.
 - `top-label` (`string`): Static label displayed above the input field. Unlike the floating label, this remains fixed.
 - `autocomplete` (`string`, default: `'off'`): The autocomplete attribute of the input.
 - `option-value-key` (`string`, default: `"code"`): The key of the option value.

package/docs/components/maz-sidebar-menu-button.md

@@ -22,7 +22,7 @@ Used inside [MazSidebar](./maz-sidebar.md): read its page for complete examples.
 
 - `to` (`string | Record<string, unknown>`): Route for router-link navigation.
 - `href` (`string`): URL for anchor navigation.
-- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
+- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
 - `label` (`string`): Label text.
 - `badge` (`MazSidebarMenuButtonBadge`): Badge content. Pass a `string`/`number` for a simple primary badge, or a full `MazBadgeProps` object (with optional `text`) to customise color, size, outlined, ….
 - `tooltip` (`string`): Tooltip text. When provided, shows a tooltip on hover via the `v-tooltip` directive.

package/docs/components/maz-sidebar-menu-sub.md

@@ -21,7 +21,7 @@ Used inside [MazSidebar](./maz-sidebar.md): read its page for complete examples.
 ### Props
 
 - `label` (`string`): Label for the sub-menu trigger button.
-- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
+- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
 - `default-open` (`boolean`, default: `false`): Whether the sub-menu is open by default.
 
 ### Slots

package/docs/components/maz-sidebar.md

@@ -455,7 +455,7 @@ Customize the sidebar width using these CSS custom properties (also settable via
 
 - `to` (`string | Record<string, unknown>`): Route for router-link navigation.
 - `href` (`string`): URL for anchor navigation.
-- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
+- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
 - `label` (`string`): Label text.
 - `badge` (`MazSidebarMenuButtonBadge`): Badge content. Pass a `string`/`number` for a simple primary badge, or a full `MazBadgeProps` object (with optional `text`) to customise color, size, outlined, ….
 - `tooltip` (`string`): Tooltip text. When provided, shows a tooltip on hover via the `v-tooltip` directive.
@@ -482,7 +482,7 @@ Customize the sidebar width using these CSS custom properties (also settable via
 ### Props
 
 - `label` (`string`): Label for the sub-menu trigger button.
-- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
+- `icon` (`MazIconLike`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
 - `default-open` (`boolean`, default: `false`): Whether the sub-menu is open by default.
 
 ### Slots

package/docs/ecosystem/icons/index.md

@@ -138,11 +138,14 @@ import { MazStar } from '@maz-ui/icons/raw/MazStar'
 
 **When to use which variant:**
 
-| Variant | Bundle cost | Use case |
+| Usage | Variant | Import |
 | --- | --- | --- |
-| `static` | Vue component, eager | Default. Few icons per page, simplest path. |
-| `lazy` | Vue component, async chunk | Many icons but most off-screen at first paint. |
-| `raw` | Inline SVG string | Same icon repeated many times in a list/table; or you want zero component overhead. |
+| Icon props of the components (`<MazBtn :start-icon>`, `<MazIcon :icon>`...) | `raw`: SVG string, the lightest, no component nor async chunk | `@maz-ui/icons/raw/MazStar` |
+| Directly in a template (`<MazStar class="size-5" />`) | `static`: Vue component, rendered immediately | `@maz-ui/icons/static/MazStar` |
+| Icons not visible at first render (`v-if`, menus, dialogs, tabs) | `lazy`: async component, loaded when displayed | `@maz-ui/icons/lazy/MazStar` |
+| `<img>` or CSS, for multicolor icons (flags, logos) | SVG file | `@maz-ui/icons/svg/star.svg` |
+
+A `lazy` icon is a separate request: do not use it for icons visible on load. In an `<img>`, an icon does not inherit the color of the text (`currentColor`): keep it for multicolor icons.
 
 **Benefits:**
 

package/docs/ecosystem/mcp.md

@@ -43,13 +43,42 @@ In Claude Code, they are available as `/maz-ui:build`, `/maz-ui:audit` and `/maz
 
 ## Version-matched docs
 
-The server serves the documentation of the **maz-ui version installed in your project** (`node_modules/maz-ui/docs`), found from the directory it is started in (monorepos: the root, then `apps/*` and `packages/*`). Without maz-ui installed, it serves the docs bundled with `@maz-ui/mcp` (latest release).
+The server serves the documentation of the **maz-ui version installed in your project** (`node_modules/maz-ui/docs`), found from the directory it is started in (monorepos: the root, then the workspaces of `pnpm-workspace.yaml` or of the `workspaces` field of `package.json`, `apps/*` and `packages/*` by default). Without maz-ui installed, it serves the docs bundled with `@maz-ui/mcp` (latest release).
 
 To force a folder, pass `--docs <dir>` or set `MAZ_UI_DOCS_DIR`.
 
+In a monorepo whose apps install different maz-ui versions, the first maz-ui found wins: an agent working on one app can get the docs of another app. Align the versions, or choose the app whose docs are served:
+
+```json
+{
+  "mcpServers": {
+    "maz-ui": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@maz-ui/mcp@latest", "--docs", "apps/web/node_modules/maz-ui/docs"]
+    }
+  }
+}
+```
+
 ## Configuration
 
-`npx @maz-ui/mcp init` writes the configuration of Claude Code, Cursor and VS Code for you. To configure an agent by hand, start the server with `npx -y @maz-ui/mcp@latest`.
+`npx @maz-ui/mcp init` writes the configuration of Claude Code, Cursor and VS Code for you.
+
+### In a project: install it
+
+Install `@maz-ui/mcp` as a dev dependency of the project root, then run `init`:
+
+```bash
+pnpm add -D @maz-ui/mcp
+pnpm exec maz-ui-mcp init
+```
+
+The MCP configs then start the installed version through your package manager (`pnpm exec maz-ui-mcp`, `yarn run maz-ui-mcp`, `npx --no-install maz-ui-mcp`...): it starts in about a second, needs no download and follows your lockfile. Without it, `init` writes `npx -y @maz-ui/mcp@<version>`, pinned to its own version.
+
+### By hand
+
+The examples below use `npx -y @maz-ui/mcp@latest`, which works without installing anything. In a project, prefer the installed version (`pnpm exec maz-ui-mcp`) or a pinned version (`@maz-ui/mcp@5.1.0`): with a dist-tag, `npx` queries the registry at every start.
 
 ### Claude Code
 
@@ -158,6 +187,22 @@ const findings = reviewCode('<template><MazBtn color="red" /></template>', {
 })
 ```
 
+## Troubleshooting
+
+### The server does not start: `connection timed out`
+
+Claude Code waits 30 seconds for a MCP server to start. The first `npx -y @maz-ui/mcp@latest` downloads the package, and behind a slow or proxied registry (Nexus, Artifactory...) it can exceed this delay. Then:
+
+- install `@maz-ui/mcp` in the project and run `init` again (see In a project: install it),
+- or pin a version instead of `@latest`: `npx -y @maz-ui/mcp@5.1.0` only queries the registry on the first start,
+- or raise the timeout of Claude Code: `MCP_TIMEOUT=60000 claude`.
+
+Measure the start time of a command up to the `initialize` response:
+
+```bash
+time (echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' | npx -y @maz-ui/mcp@latest | head -1)
+```
+
 ## Debugging
 
 ```bash

package/docs/ecosystem/node/setup-agents.md

@@ -41,8 +41,11 @@ The content comes from the `docs/agents` folder of the `maz-ui` package installe
 Guarantees:
 
 - A file it did not generate is never overwritten (it is reported as `skip`).
+- Generated rules edited by hand are kept and no longer updated (`skip`): their header records a checksum of the content. A formatter that only changes the whitespace does not count as an edit. Delete the file (or the `AGENTS.md` section) to get the rules of a new version.
 - In `AGENTS.md`, only the delimited section is managed: your content stays as is.
 - MCP config files are edited in place, keeping their formatting and comments. When a server already runs `@maz-ui/mcp` under another name, nothing is added.
+- An existing entry of the maz-ui MCP server only gets a better command (the installed `@maz-ui/mcp`, a newer pinned version) and keeps its other fields (`env`...). A command written by hand (with `--docs`, for example) is never changed.
+- In a monorepo, rules written by a newer maz-ui and a newer pinned `@maz-ui/mcp` are never downgraded by an app with an older version. Files are written atomically: apps started together never read a half-written file.
 - Without `CLAUDE.md` in the project, Claude Code reads `AGENTS.md`: the Claude rule is then skipped to avoid loading the rules twice.
 - Running it again is idempotent: unchanged files are reported as `unchanged`.
 
@@ -65,11 +68,79 @@ setupAgents({
   remove: false,
   // Folder of the maz-ui agent docs, default: node_modules/maz-ui/docs
   docsDir: undefined,
-  // Command of the MCP server, default: npx -y @maz-ui/mcp@latest
-  mcpServer: { command: 'npx', args: ['-y', '@maz-ui/mcp@latest'] },
+  // Version pinned in the npx command when the project does not install @maz-ui/mcp, default: latest
+  mcpVersion: '5.1.0',
+  // Command of the MCP server, default: mcpServerCommand(rootDir, mcpVersion, tool)
+  mcpServer: undefined,
+  // Tool whose agents are configured, default: MAZ_UI_AGENTS_TOOL
+  tool: undefined,
+  // Rules of the tool, required with another tool than maz-ui, default: the agent docs of docsDir
+  agentDocs: undefined,
 })
 ```
 
+## Use it for another tool
+
+`setupAgents` configures maz-ui by default, but any package that ships an MCP server and rules for AI agents can reuse it with the `tool` option, and get the same guarantees. Its rules are passed with `agentDocs`, since they do not come from the maz-ui docs. For example, [relizy](https://relizy.dev) runs it in `relizy mcp init`:
+
+```ts
+import type { AgentsTool } from '@maz-ui/node'
+import { setupAgents } from '@maz-ui/node'
+
+const tool: AgentsTool = {
+  // Key of the MCP server, `.claude/rules/relizy.md` and markers of the generated content
+  name: 'relizy',
+  // Package that ships the MCP server, and the bin and arguments that start it
+  mcpPackage: 'relizy',
+  mcpBin: 'relizy',
+  mcpArgs: ['mcp'],
+  // Written in the header of the generated rules
+  generatedBy: '`relizy mcp init`',
+  // Line under the title of the rules, default: `> relizy <version> is installed: these rules match this version.`
+  versionNote: version => `> relizy ${version} is installed: these rules match this version.`,
+}
+
+setupAgents({
+  rootDir: process.cwd(),
+  tool,
+  agentDocs: {
+    directory: '/path/to/relizy/agent-docs',
+    version: '1.14.0',
+    claudeRule: '# relizy\n\n...',
+    agentsMdSection: '## relizy\n\n...',
+  },
+  mcpVersion: '1.14.0',
+})
+```
+
+| Written for the tool | relizy | maz-ui (`MAZ_UI_AGENTS_TOOL`) |
+| --- | --- | --- |
+| Claude Code rule | `.claude/rules/relizy.md` | `.claude/rules/maz-ui.md` |
+| `AGENTS.md` section | `<!-- BEGIN:relizy -->` ... `<!-- END:relizy -->` | `<!-- BEGIN:maz-ui -->` ... `<!-- END:maz-ui -->` |
+| MCP server entry | `relizy` | `maz-ui` |
+| Command, package installed with pnpm | `pnpm exec relizy mcp` | `pnpm exec maz-ui-mcp` |
+| Command, package not installed | `npx -y relizy@<mcpVersion> mcp` | `npx -y @maz-ui/mcp@<mcpVersion>` |
+
+Each tool only manages its own files, section and server entry: maz-ui and relizy can be set up in the same project, and removing one (`remove: true` with its `tool`) keeps the other. `mcpServerCommand`, `installsMcpPackage`, `readManagedVersion` and `isEditedManagedContent` also take the tool as last argument.
+
+## Command of the MCP server
+
+```ts
+import { mcpServerCommand } from '@maz-ui/node'
+
+mcpServerCommand(process.cwd(), '5.1.0')
+```
+
+| Project | Command |
+| --- | --- |
+| Installs `@maz-ui/mcp` with pnpm | `pnpm exec maz-ui-mcp` |
+| Installs `@maz-ui/mcp` with yarn | `yarn run maz-ui-mcp` |
+| Installs `@maz-ui/mcp` with bun | `bun x --no-install maz-ui-mcp` |
+| Installs `@maz-ui/mcp` with npm | `npx --no-install maz-ui-mcp` |
+| Does not install it | `npx -y @maz-ui/mcp@<mcpVersion>` |
+
+The package manager comes from the `packageManager` field of `package.json`, else from the lockfile. The installed version starts in about a second and follows the lockfile. A pinned version avoids the registry query that `npx` makes at every start with a dist-tag (`@latest`).
+
 ## Result
 
 ```ts
@@ -79,6 +150,8 @@ const result = setupAgents({ rootDir: process.cwd(), dryRun: true })
 
 result.version // version of the installed maz-ui
 result.targets // configured agents
+result.mcpServer // { command, args } registered in the MCP configs
+result.localMcpServer // false when the server runs through npx -y
 result.changes // [{ file: '.mcp.json', action: 'create' | 'update' | 'remove' | 'unchanged' | 'skip', reason?: string }]
 ```
 
@@ -99,4 +172,4 @@ detectAgentTargets(process.cwd()) // ['claude', 'agents-md']
 
 ## Errors
 
-`setupAgents` throws when the rules are requested and `maz-ui` is not installed in `rootDir` (or its parent folders), or when the installed version does not ship the agent docs: upgrade maz-ui to the latest version. With `rules: false`, only the MCP server is registered and the docs are not needed.
+`setupAgents` throws when the rules are requested and `maz-ui` is not installed in `rootDir` (or its parent folders), or when the installed version does not ship the agent docs: upgrade maz-ui to the latest version. With another `tool`, it throws when the rules are requested without `agentDocs`. With `rules: false`, only the MCP server is registered and the docs are not needed.