@maz-ui/mcp 5.1.0 → 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-card.md

@@ -288,7 +288,7 @@ type MazGalleryImage =
 
 ### Props
 
-- `orientation` (`"column" | "column-reverse" | "row" | "row-reverse"`, default: `"column"`): Card variant: Must be `column | row | row-reverse | column-reverse`.
+- `orientation` (`"row" | "column" | "column-reverse" | "row-reverse"`, default: `"column"`): Card variant: Must be `column | row | row-reverse | column-reverse`.
 - `href` (`string`): Make card a link (footer area excluded).
 - `to` (`string | et | X`): Make card a link with a router-link or nuxt-link (footer area excluded).
 - `href-target` (`string`, default: `"_self"`): Target option of link: Muse be one of `_blank | _self | _parent | _top | framename`.

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-dialog-confirm.md

@@ -174,10 +174,10 @@ type Size = 'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
 - `message` (`string`): Dialog message displayed in the body.
 - `reject-text` (`string`): Text for the reject button - will be applied only if buttons props is not provided.
 - `reject-props` (`(Omit<MazBtnProps, "type"> & MazDialogConfirmButton)`, default: `{ color: 'destructive', type: 'reject', text: 'Cancel', response: 'reject' }`): Props for the reject button - will be applied only if buttons props is not provided.
-- `hide-reject-button` (`boolean`, default: `true`): Whether to display the reject button.
+- `hide-reject-button` (`boolean`, default: `false`): Hide the reject button (unset: the value of `useMazDialogConfirm().data`, else shown).
 - `accept-text` (`string`): Text for the accept button.
 - `accept-props` (`(Omit<MazBtnProps, "type"> & MazDialogConfirmButton)`, default: `{ color: 'success', type: 'accept', text: 'Confirm', response: 'accept' }`): Props for the accept button - will be applied only if buttons props is not provided.
-- `hide-accept-button` (`boolean`, default: `true`): Whether to display the accept button.
+- `hide-accept-button` (`boolean`, default: `false`): Hide the accept button (unset: the value of `useMazDialogConfirm().data`, else shown).
 - `buttons` (`MazDialogConfirmButton[]`): Buttons to display in the footer.
 - `model-value` (`boolean`): Modal's model value.
 - `hide-close-button` (`boolean`): Remove the close button in header.

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

@@ -130,12 +130,12 @@ If no `to` or `href` is provided, the component will be a `button` by default. Y
 - `target` (`string`, default: `"_self"`): The target of the link. Values: `'_blank'`, `'_self'`, `'_parent'`, `'_top'` (non exhaustive).
 - `download` (`string`): The download of the link.
 - `rel` (`string`): The rel of the link.
-- `aria-label` (`string`): The aria-label of the link.
+- `aria-label` (`string`): The aria-label of the link (or of the button).
 - `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-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/composables/use-dialog.md

@@ -26,7 +26,8 @@ More info about [dialog plugin](../plugins/dialog.md) in its documentation
 
 ```vue
 <script lang="ts" setup>
-import { useDialog, useToast } from 'maz-ui/composables'
+import { useDialog } from 'maz-ui/composables/useDialog'
+import { useToast } from 'maz-ui/composables/useToast'
 
 const dialog = useDialog()
 

package/docs/ecosystem/icons/index.md

@@ -79,16 +79,16 @@ import { MazCheck, MazHeart, MazUser } from '@maz-ui/icons'
 
 <template>
   <div>
-    <MazCheck class="text-green-500" />
-    <MazUser class="w-6 h-6" />
-    <MazHeart class="text-red-500 hover:scale-110 transition-transform" />
+    <MazCheck class="text-success" />
+    <MazUser class="size-6" />
+    <MazHeart class="text-destructive hover:scale-110 transition-transform" />
   </div>
 </template>
 ```
 
 #### Lazy Icons
 
-Lazy icons are prefixed with `Lazy` and use `defineAsyncComponent` under the hood. Use them when you want to reduce your initial bundle size:
+Lazy icons use `defineAsyncComponent` under the hood. Use them when you want to reduce your initial bundle size. From the `lazy/` sub-paths they keep their name; from the `@maz-ui/icons` root (and with the resolver) they are prefixed with `Lazy` (`LazyMazCheck`):
 
 ```vue
 <script setup lang="ts">
@@ -99,9 +99,9 @@ import { MazUser } from '@maz-ui/icons/lazy/MazUser'
 
 <template>
   <div>
-    <LazyMazCheck class="text-green-500" />
-    <LazyMazUser class="w-6 h-6" />
-    <LazyMazHeart class="text-red-500 hover:scale-110 transition-transform" />
+    <MazCheck class="text-success" />
+    <MazUser class="size-6" />
+    <MazHeart class="text-destructive hover:scale-110 transition-transform" />
   </div>
 </template>
 ```
@@ -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:**
 
@@ -191,17 +194,17 @@ export default defineConfig({
     <!-- Static icons (eagerly loaded) -->
     <MazHome class="nav-icon" />
     <MazUser class="nav-icon" />
-    <MazSettings class="nav-icon" />
+    <MazCog6Tooth class="nav-icon" />
 
     <!-- Lazy icons (async loaded) - prefix with "Lazy" -->
-    <LazyMazLogout class="nav-icon" />
+    <LazyMazArrowRightStartOnRectangle class="nav-icon" />
   </div>
 </template>
 
 <style scoped>
 @reference "../../.vitepress/theme/main.css";
 .nav-icon {
-  @apply w-6 h-6 text-gray-600 hover:text-blue-500 transition-colors cursor-pointer;
+  @apply size-6 text-muted hover:text-primary transition-colors cursor-pointer;
 }
 </style>
 ```
@@ -250,9 +253,9 @@ import UserIcon from '@maz-ui/icons/svg/user.svg?component'
 
 <template>
   <div class="flex items-center gap-2">
-    <CheckIcon class="w-5 h-5 text-green-600" />
-    <UserIcon class="w-6 h-6 text-blue-500" />
-    <HeartIcon class="w-4 h-4 text-red-500 animate-pulse" />
+    <CheckIcon class="size-5 text-success" />
+    <UserIcon class="size-6 text-primary" />
+    <HeartIcon class="size-4 text-destructive animate-pulse" />
   </div>
 </template>
 ```
@@ -286,7 +289,7 @@ onMounted(async () => {
     <img src="@maz-ui/icons/svg/check.svg" alt="Check" class="w-6 h-6">
 
     <!-- Inline SVG with fetch -->
-    <div class="text-blue-500" v-html="checkSvg" />
+    <div class="text-primary" v-html="checkSvg" />
   </div>
 </template>
 ```
@@ -311,19 +314,19 @@ Icons inherit the current text color and can be styled like any other element:
     <MazStar class="text-2xl" />
 
     <!-- Colors -->
-    <MazHeart class="text-red-500" />
-    <MazLeaf class="text-green-600" />
-    <MazSky class="text-blue-400" />
+    <MazHeart class="text-destructive" />
+    <MazCheckCircle class="text-success" />
+    <MazSun class="text-warning" />
 
     <!-- Interactive states -->
-    <MazBtn class="hover:text-blue-500 transition-colors cursor-pointer" />
+    <MazStar class="hover:text-primary transition-colors cursor-pointer" />
 
     <!-- Animations -->
     <MazSpinner class="animate-spin" />
     <MazHeart class="hover:scale-110 transition-transform" />
 
     <!-- With background -->
-    <MazCheck class="p-2 bg-green-100 text-green-600 rounded-full" />
+    <MazCheck class="p-2 bg-success/15 text-success rounded-full" />
   </div>
 </template>
 ```
@@ -504,9 +507,9 @@ export function iconOptimizer(): Plugin {
 ```vue
 <template>
   <div class="flex items-center space-x-4">
-    <MazHome class="w-5 h-5 text-gray-500 hover:text-blue-500 transition-colors" />
-    <MazUser class="w-6 h-6 text-indigo-600" />
-    <MazSettings class="w-4 h-4 text-gray-400 hover:text-gray-600" />
+    <MazHome class="size-5 text-muted hover:text-primary transition-colors" />
+    <MazUser class="size-6 text-secondary" />
+    <MazCog6Tooth class="size-4 text-muted hover:text-foreground" />
   </div>
 </template>
 ```

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