maz-ui 5.1.1 → 5.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/docs/agents/agents-md.md +32 -17
  2. package/docs/agents/claude-rule.md +32 -17
  3. package/docs/components/maz-input-number.md +1 -1
  4. package/docs/components/maz-input-phone-number.md +1 -1
  5. package/docs/components/maz-input.md +1 -1
  6. package/docs/components/maz-select-country.md +2 -2
  7. package/docs/ecosystem/icons/index.md +7 -4
  8. package/docs/ecosystem/mcp.md +47 -2
  9. package/docs/ecosystem/node/setup-agents.md +76 -3
  10. package/docs/guide/ai-agents.md +51 -17
  11. package/docs/manifest.json +1 -1
  12. package/docs/rules.md +32 -17
  13. package/package.json +27 -9
package/docs/agents/agents-md.md CHANGED
@@ -1,41 +1,56 @@
1
1
  ## maz-ui
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  ### Look it up before you write it
6
6
 
7
- Before creating a component, composable, helper, icon or style, check what maz-ui offers:
7
+ - **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`.
8
+ - **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, the `maz-ui` of the app).
8
9
 
9
- - **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`.
10
- - **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.
10
+ Never guess an API: only use documented props, events, slots and imports.
11
11
 
12
- Never guess an API: only use props, events, slots and imports that are documented.
12
+ ### Which package for what
13
+
14
+ `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).
13
15
 
14
16
  ### Components
15
17
 
16
- - 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`...
18
+ - 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`...
17
19
  - 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`.
18
- - Feedback and overlays: `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states.
20
+ - A button with only an icon needs an `aria-label`.
21
+
22
+ ### Feedback, overlays and forms
23
+
24
+ - `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states, `MazSkeleton` / `MazSpinner` while data loads.
25
+ - 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).
19
26
  - Forms: `useFormValidator` / `useFormField` with your Standard Schema library (Zod, Valibot, ArkType).
20
27
 
21
28
  ### Icons
22
29
 
23
- 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">`.
30
+ Use `@maz-ui/icons`, never inline SVG nor another icon library. Pick the format by usage:
31
+
32
+ - **Icon props** (`<MazBtn :start-icon>`, `<MazIcon :icon>`...): the raw SVG string, the lightest, `@maz-ui/icons/raw/MazTrash`.
33
+ - **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`).
34
+ - **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.
35
+ - `<img>` or CSS only for multicolor icons (flags, logos): `@maz-ui/icons/svg/<name>.svg`, the text color does not apply there.
24
36
 
25
- ### Helpers and composables
37
+ ### Helpers
26
38
 
27
- 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`...
39
+ 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`...
40
+
41
+ ### Texts and languages
42
+
43
+ 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.
28
44
 
29
45
  ### Styling with Tailwind
30
46
 
31
47
  The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`) and the project usually extends it. Only use theme tokens:
32
48
 
33
- - **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.
34
-
35
- - 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`.
36
- - 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.
49
+ - **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.
50
+ - 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`.
51
+ - 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.
37
52
  - 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`.
38
- - **No `maz:` prefix** in this project: it is internal to the maz-ui library and its documentation.
53
+ - **No `maz:` prefix** in this project: it is internal to the maz-ui library.
39
54
  - In custom CSS, use the variables: `var(--maz-primary)`, `var(--maz-rounded-md)`, `calc(var(--maz-space) * 4)`.
40
55
 
41
56
  ### Theme
@@ -44,8 +59,8 @@ Brand colors, fonts, radius and spacing come from a `@maz-ui/themes` preset (`de
44
59
 
45
60
  ### Imports
46
61
 
47
- - 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`.
48
- - With `@maz-ui/nuxt`, components and composables are auto-imported: do not import them.
62
+ - 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`.
63
+ - 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.
49
64
 
50
65
  ### Before you finish
51
66
 
package/docs/agents/claude-rule.md CHANGED
@@ -1,41 +1,56 @@
1
1
  # maz-ui
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  ### Look it up before you write it
6
6
 
7
- Before creating a component, composable, helper, icon or style, check what maz-ui offers:
7
+ - **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`.
8
+ - **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, the `maz-ui` of the app).
8
9
 
9
- - **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`.
10
- - **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.
10
+ Never guess an API: only use documented props, events, slots and imports.
11
11
 
12
- Never guess an API: only use props, events, slots and imports that are documented.
12
+ ### Which package for what
13
+
14
+ `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).
13
15
 
14
16
  ### Components
15
17
 
16
- - 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`...
18
+ - 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`...
17
19
  - 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`.
18
- - Feedback and overlays: `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states.
20
+ - A button with only an icon needs an `aria-label`.
21
+
22
+ ### Feedback, overlays and forms
23
+
24
+ - `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states, `MazSkeleton` / `MazSpinner` while data loads.
25
+ - 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).
19
26
  - Forms: `useFormValidator` / `useFormField` with your Standard Schema library (Zod, Valibot, ArkType).
20
27
 
21
28
  ### Icons
22
29
 
23
- 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">`.
30
+ Use `@maz-ui/icons`, never inline SVG nor another icon library. Pick the format by usage:
31
+
32
+ - **Icon props** (`<MazBtn :start-icon>`, `<MazIcon :icon>`...): the raw SVG string, the lightest, `@maz-ui/icons/raw/MazTrash`.
33
+ - **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`).
34
+ - **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.
35
+ - `<img>` or CSS only for multicolor icons (flags, logos): `@maz-ui/icons/svg/<name>.svg`, the text color does not apply there.
24
36
 
25
- ### Helpers and composables
37
+ ### Helpers
26
38
 
27
- 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`...
39
+ 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`...
40
+
41
+ ### Texts and languages
42
+
43
+ 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.
28
44
 
29
45
  ### Styling with Tailwind
30
46
 
31
47
  The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`) and the project usually extends it. Only use theme tokens:
32
48
 
33
- - **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.
34
-
35
- - 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`.
36
- - 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.
49
+ - **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.
50
+ - 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`.
51
+ - 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.
37
52
  - 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`.
38
- - **No `maz:` prefix** in this project: it is internal to the maz-ui library and its documentation.
53
+ - **No `maz:` prefix** in this project: it is internal to the maz-ui library.
39
54
  - In custom CSS, use the variables: `var(--maz-primary)`, `var(--maz-rounded-md)`, `calc(var(--maz-space) * 4)`.
40
55
 
41
56
  ### Theme
@@ -44,8 +59,8 @@ Brand colors, fonts, radius and spacing come from a `@maz-ui/themes` preset (`de
44
59
 
45
60
  ### Imports
46
61
 
47
- - 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`.
48
- - With `@maz-ui/nuxt`, components and composables are auto-imported: do not import them.
62
+ - 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`.
63
+ - 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.
49
64
 
50
65
  ### Before you finish
51
66
 
package/docs/components/maz-input-number.md CHANGED
@@ -61,7 +61,7 @@ You can remove the buttons with the props `hide-buttons`
61
61
  - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of the input number component.
62
62
  - `hide-buttons` (`boolean`, default: `false`): Whether to hide the increment and decrement buttons or not.
63
63
  - `text-center` (`boolean`, default: `true`): Whether to center the text inside the input or not.
64
- - `inputmode` (`"none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"numeric"`): The inputmode attribute for the input.
64
+ - `inputmode` (`"text" | "none" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"numeric"`): The inputmode attribute for the input.
65
65
  - `block` (`boolean`): The input will be displayed in full width.
66
66
  - `error` (`boolean`, default: `false`): Will display the input in error state.
67
67
  - `hint` (`string`): The hint text to display below the input.
package/docs/components/maz-input-phone-number.md CHANGED
@@ -518,7 +518,7 @@ interface MazInputPhoneNumberData {
518
518
  - `block` (`boolean`, default: `false`): The input will be displayed in full width.
519
519
  - `orientation` (`"row" | "col" | "responsive"`, default: `"responsive"`): Orientation of the inputs in the component.
520
520
  - `country-select-attributes` (`Record<string, unknown>`, default: `{ name: "country", autocomplete: "off", style: { width: "14rem", }, }`): Meta attributes of the country input.
521
- - `phone-input-attributes` (`(Record<string, unknown> & { name: string; inputmode: "none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal" | undefined; autocomplete: string; })`, default: `{ name: "phone", autocomplete: "tel", inputmode: "tel", }`): Meta attributes of the phone number input.
521
+ - `phone-input-attributes` (`(Record<string, unknown> & { name: string; inputmode: "text" | "none" | "search" | "url" | "email" | "tel" | "numeric" | "decimal" | undefined; autocomplete: string; })`, default: `{ name: "phone", autocomplete: "tel", inputmode: "tel", }`): Meta attributes of the phone number input.
522
522
  - `assistive-text` (`string`): Helper text displayed below the input to provide additional context or validation feedback.
523
523
  - `hint` (`string`): Alternative text that replaces the label when provided. Useful for contextual hints.
524
524
 
package/docs/components/maz-input.md CHANGED
@@ -305,7 +305,7 @@ Use the attribute `rounded-size` with a value in `'none' | 'sm' | 'md' | 'lg' |
305
305
  - `hint` (`string`): Alternative text that replaces the label when provided. Useful for contextual hints.
306
306
  - `input-classes` (`string`): Additional CSS classes to apply specifically to the input wrapper element.
307
307
  - `border` (`boolean`, default: `true`): Controls whether the input has a visible border. Set to false for borderless inputs.
308
- - `inputmode` (`"none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"text"`): HTML inputmode attribute that provides hints for virtual keyboards on mobile devices.
308
+ - `inputmode` (`"text" | "none" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"text"`): HTML inputmode attribute that provides hints for virtual keyboards on mobile devices.
309
309
  - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): Controls the height and text size of the input component.
310
310
  - `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.
311
311
  - `auto-focus` (`boolean`, default: `false`): Automatically focuses the input when the component mounts.
package/docs/components/maz-select-country.md CHANGED
@@ -479,12 +479,12 @@ This ensures consistent internationalization across your application while provi
479
479
  - `codes-type` (`CodesType`, default: `defined by displayNamesOptions.type (if 'region', 'country' is used, otherwise 'iso')`): Codes type. Values: `'iso'`, `'bcp'`, `'country'`, `'all'` (non exhaustive).
480
480
  - `open` (`boolean`, default: `false`): Open the select.
481
481
  - `model-value` (`Option["code"]`, `v-model`): The value of the select.
482
- - `disabled` (`boolean`): Disable the component.
483
482
  - `block` (`boolean`): The input will be displayed in full width.
483
+ - `disabled` (`boolean`): Disable the component.
484
484
  - `required` (`boolean`): Make the input required in the form.
485
485
  - `label` (`string`): The label of the select.
486
- - `search-function` (`((query: string, options: Option[]) => Option[] | undefined)`): Replace the default search function to provide a custom search function.
487
486
  - `placeholder` (`string`): The placeholder of the select.
487
+ - `search-function` (`((query: string, options: Option[]) => Option[] | undefined)`): Replace the default search function to provide a custom search function.
488
488
  - `transition` (`string`, default: `'scale-fade'`): The transition name of the panel list options.
489
489
  - `prefer-position` (`MazPopoverPreferPosition`, default: `'bottom-start'`): The prefer position of the list.
490
490
  - `fallback-position` (`MazPopoverFallbackPosition`, default: `'top-start'`): The fallback position of the list.
package/docs/ecosystem/icons/index.md CHANGED
@@ -138,11 +138,14 @@ import { MazStar } from '@maz-ui/icons/raw/MazStar'
138
138
 
139
139
  **When to use which variant:**
140
140
 
141
- | Variant | Bundle cost | Use case |
141
+ | Usage | Variant | Import |
142
142
  | --- | --- | --- |
143
- | `static` | Vue component, eager | Default. Few icons per page, simplest path. |
144
- | `lazy` | Vue component, async chunk | Many icons but most off-screen at first paint. |
145
- | `raw` | Inline SVG string | Same icon repeated many times in a list/table; or you want zero component overhead. |
143
+ | 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` |
144
+ | Directly in a template (`<MazStar class="size-5" />`) | `static`: Vue component, rendered immediately | `@maz-ui/icons/static/MazStar` |
145
+ | Icons not visible at first render (`v-if`, menus, dialogs, tabs) | `lazy`: async component, loaded when displayed | `@maz-ui/icons/lazy/MazStar` |
146
+ | `<img>` or CSS, for multicolor icons (flags, logos) | SVG file | `@maz-ui/icons/svg/star.svg` |
147
+
148
+ 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.
146
149
 
147
150
  **Benefits:**
148
151
 
package/docs/ecosystem/mcp.md CHANGED
@@ -43,13 +43,42 @@ In Claude Code, they are available as `/maz-ui:build`, `/maz-ui:audit` and `/maz
43
43
 
44
44
  ## Version-matched docs
45
45
 
46
- 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).
46
+ 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).
47
47
 
48
48
  To force a folder, pass `--docs <dir>` or set `MAZ_UI_DOCS_DIR`.
49
49
 
50
+ 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:
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "maz-ui": {
56
+ "type": "stdio",
57
+ "command": "npx",
58
+ "args": ["-y", "@maz-ui/mcp@latest", "--docs", "apps/web/node_modules/maz-ui/docs"]
59
+ }
60
+ }
61
+ }
62
+ ```
63
+
50
64
  ## Configuration
51
65
 
52
- `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`.
66
+ `npx @maz-ui/mcp init` writes the configuration of Claude Code, Cursor and VS Code for you.
67
+
68
+ ### In a project: install it
69
+
70
+ Install `@maz-ui/mcp` as a dev dependency of the project root, then run `init`:
71
+
72
+ ```bash
73
+ pnpm add -D @maz-ui/mcp
74
+ pnpm exec maz-ui-mcp init
75
+ ```
76
+
77
+ 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.
78
+
79
+ ### By hand
80
+
81
+ 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.
53
82
 
54
83
  ### Claude Code
55
84
 
@@ -158,6 +187,22 @@ const findings = reviewCode('<template><MazBtn color="red" /></template>', {
158
187
  })
159
188
  ```
160
189
 
190
+ ## Troubleshooting
191
+
192
+ ### The server does not start: `connection timed out`
193
+
194
+ 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:
195
+
196
+ - install `@maz-ui/mcp` in the project and run `init` again (see In a project: install it),
197
+ - or pin a version instead of `@latest`: `npx -y @maz-ui/mcp@5.1.0` only queries the registry on the first start,
198
+ - or raise the timeout of Claude Code: `MCP_TIMEOUT=60000 claude`.
199
+
200
+ Measure the start time of a command up to the `initialize` response:
201
+
202
+ ```bash
203
+ 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)
204
+ ```
205
+
161
206
  ## Debugging
162
207
 
163
208
  ```bash
package/docs/ecosystem/node/setup-agents.md CHANGED
@@ -41,8 +41,11 @@ The content comes from the `docs/agents` folder of the `maz-ui` package installe
41
41
  Guarantees:
42
42
 
43
43
  - A file it did not generate is never overwritten (it is reported as `skip`).
44
+ - 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.
44
45
  - In `AGENTS.md`, only the delimited section is managed: your content stays as is.
45
46
  - 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.
47
+ - 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.
48
+ - 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.
46
49
  - Without `CLAUDE.md` in the project, Claude Code reads `AGENTS.md`: the Claude rule is then skipped to avoid loading the rules twice.
47
50
  - Running it again is idempotent: unchanged files are reported as `unchanged`.
48
51
 
@@ -65,11 +68,79 @@ setupAgents({
65
68
  remove: false,
66
69
  // Folder of the maz-ui agent docs, default: node_modules/maz-ui/docs
67
70
  docsDir: undefined,
68
- // Command of the MCP server, default: npx -y @maz-ui/mcp@latest
69
- mcpServer: { command: 'npx', args: ['-y', '@maz-ui/mcp@latest'] },
71
+ // Version pinned in the npx command when the project does not install @maz-ui/mcp, default: latest
72
+ mcpVersion: '5.1.0',
73
+ // Command of the MCP server, default: mcpServerCommand(rootDir, mcpVersion, tool)
74
+ mcpServer: undefined,
75
+ // Tool whose agents are configured, default: MAZ_UI_AGENTS_TOOL
76
+ tool: undefined,
77
+ // Rules of the tool, required with another tool than maz-ui, default: the agent docs of docsDir
78
+ agentDocs: undefined,
70
79
  })
71
80
  ```
72
81
 
82
+ ## Use it for another tool
83
+
84
+ `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`:
85
+
86
+ ```ts
87
+ import type { AgentsTool } from '@maz-ui/node'
88
+ import { setupAgents } from '@maz-ui/node'
89
+
90
+ const tool: AgentsTool = {
91
+ // Key of the MCP server, `.claude/rules/relizy.md` and markers of the generated content
92
+ name: 'relizy',
93
+ // Package that ships the MCP server, and the bin and arguments that start it
94
+ mcpPackage: 'relizy',
95
+ mcpBin: 'relizy',
96
+ mcpArgs: ['mcp'],
97
+ // Written in the header of the generated rules
98
+ generatedBy: '`relizy mcp init`',
99
+ // Line under the title of the rules, default: `> relizy <version> is installed: these rules match this version.`
100
+ versionNote: version => `> relizy ${version} is installed: these rules match this version.`,
101
+ }
102
+
103
+ setupAgents({
104
+ rootDir: process.cwd(),
105
+ tool,
106
+ agentDocs: {
107
+ directory: '/path/to/relizy/agent-docs',
108
+ version: '1.14.0',
109
+ claudeRule: '# relizy\n\n...',
110
+ agentsMdSection: '## relizy\n\n...',
111
+ },
112
+ mcpVersion: '1.14.0',
113
+ })
114
+ ```
115
+
116
+ | Written for the tool | relizy | maz-ui (`MAZ_UI_AGENTS_TOOL`) |
117
+ | --- | --- | --- |
118
+ | Claude Code rule | `.claude/rules/relizy.md` | `.claude/rules/maz-ui.md` |
119
+ | `AGENTS.md` section | `<!-- BEGIN:relizy -->` ... `<!-- END:relizy -->` | `<!-- BEGIN:maz-ui -->` ... `<!-- END:maz-ui -->` |
120
+ | MCP server entry | `relizy` | `maz-ui` |
121
+ | Command, package installed with pnpm | `pnpm exec relizy mcp` | `pnpm exec maz-ui-mcp` |
122
+ | Command, package not installed | `npx -y relizy@<mcpVersion> mcp` | `npx -y @maz-ui/mcp@<mcpVersion>` |
123
+
124
+ 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.
125
+
126
+ ## Command of the MCP server
127
+
128
+ ```ts
129
+ import { mcpServerCommand } from '@maz-ui/node'
130
+
131
+ mcpServerCommand(process.cwd(), '5.1.0')
132
+ ```
133
+
134
+ | Project | Command |
135
+ | --- | --- |
136
+ | Installs `@maz-ui/mcp` with pnpm | `pnpm exec maz-ui-mcp` |
137
+ | Installs `@maz-ui/mcp` with yarn | `yarn run maz-ui-mcp` |
138
+ | Installs `@maz-ui/mcp` with bun | `bun x --no-install maz-ui-mcp` |
139
+ | Installs `@maz-ui/mcp` with npm | `npx --no-install maz-ui-mcp` |
140
+ | Does not install it | `npx -y @maz-ui/mcp@<mcpVersion>` |
141
+
142
+ 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`).
143
+
73
144
  ## Result
74
145
 
75
146
  ```ts
@@ -79,6 +150,8 @@ const result = setupAgents({ rootDir: process.cwd(), dryRun: true })
79
150
 
80
151
  result.version // version of the installed maz-ui
81
152
  result.targets // configured agents
153
+ result.mcpServer // { command, args } registered in the MCP configs
154
+ result.localMcpServer // false when the server runs through npx -y
82
155
  result.changes // [{ file: '.mcp.json', action: 'create' | 'update' | 'remove' | 'unchanged' | 'skip', reason?: string }]
83
156
  ```
84
157
 
@@ -99,4 +172,4 @@ detectAgentTargets(process.cwd()) // ['claude', 'agents-md']
99
172
 
100
173
  ## Errors
101
174
 
102
- `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.
175
+ `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.
package/docs/guide/ai-agents.md CHANGED
@@ -44,12 +44,17 @@ It detects the agents you use and configures them, using the docs of the maz-ui
44
44
 
45
45
  When no agent is detected, it configures Claude Code and `AGENTS.md`. Commit the generated files: your whole team and your CI agents get them.
46
46
 
47
+ In a project without maz-ui (only `@maz-ui/utils` or `@maz-ui/node`, for example), it only registers the MCP server, which serves the docs bundled with `@maz-ui/mcp`: the rules are about the maz-ui components and are written once maz-ui is installed. Pass `--docs <dir>` to write them anyway.
48
+
49
+ For a fast start of the MCP server, install it in the project first (`pnpm add -D @maz-ui/mcp`): the configs then start the installed version through your package manager, in about a second and at the version of your lockfile, instead of downloading it with `npx`. See [MCP server](../ecosystem/mcp.md#in-a-project-install-it).
50
+
47
51
  **Tip: It never overwrites your own instructions**
48
52
 
49
53
  - Your `CLAUDE.md` is never touched: Claude Code loads `.claude/rules/maz-ui.md` on top of it.
50
54
  - In `AGENTS.md`, maz-ui only manages the section between `<!-- BEGIN:maz-ui -->` and `<!-- END:maz-ui -->`.
51
55
  - In the MCP config files, only the `maz-ui` entry is added, the formatting and comments of the file are preserved. An existing server running `@maz-ui/mcp` under another name is kept as is.
52
56
  - A file you created yourself with the same path is never overwritten.
57
+ - If you edit the generated rules, your edits are kept and the rules are no longer updated: delete the file (or the section) to get the rules of a new maz-ui version. To add your own rules, write them in another file or outside the section.
53
58
 
54
59
  ### Options
55
60
 
@@ -83,6 +88,19 @@ export default defineNuxtConfig({
83
88
 
84
89
  It only runs in development (never in CI, in tests or during builds), writes nothing when no agent is detected, keeps the files in sync with the installed maz-ui version and never overwrites files it does not own. In a monorepo, it writes at the root of the workspace, where the agents start (`agents.dir` to choose another folder).
85
90
 
91
+ ### Monorepos with several Nuxt apps
92
+
93
+ Each app syncs the agent files when it starts (`nuxt dev`, `nuxt prepare`), and all of them write at the root of the workspace:
94
+
95
+ - **Same options in every app**: the first app writes the files, the next ones find them up to date and write nothing.
96
+ - **Different options**: they add up. An app with `rules: false` does not remove the rules written by an app with `rules: true` (only `npx @maz-ui/mcp init --remove` removes them), and the `targets` of each app are added. With `agents.dir`, each app writes in its own folder.
97
+ - **Apps started together** (`nx run-many -t dev`, `turbo dev`): the files are written atomically, an app never reads a file another app is writing.
98
+ - **Different maz-ui versions per app**: the rules of the most recent version are kept, an app with an older maz-ui never downgrades them. Align the versions (a pnpm catalog, for example) to get the same rules everywhere.
99
+
100
+ **Warning: One MCP server for the whole workspace**
101
+
102
+ Started at the root, the MCP server serves the docs of the first maz-ui it finds: in the root `node_modules`, then in the workspaces of the monorepo (`pnpm-workspace.yaml` or the `workspaces` field of `package.json`), in their order. When the apps install different maz-ui versions, an agent working on one app can get the docs of the version of another app. Align the versions, or point the server to the docs of an app with `--docs` (see [Version-matched docs](../ecosystem/mcp.md#version-matched-docs)).
103
+
86
104
  ### Without any file in the project
87
105
 
88
106
  The MCP server carries the rules in its instructions: registering it once for your user is enough, in every project, without writing anything in them.
@@ -182,6 +200,7 @@ The command exits with an error code when it finds errors (or more warnings than
182
200
  | `unknown-icon` | error | An icon that does not exist in `@maz-ui/icons` |
183
201
  | `prefer-maz-component` | warning | `<button>`, `<input>`, `<select>`, `<textarea>`, `<dialog>`... (a `<button>` that is a clickable card, with a layout, a component or a title and a subtitle, or an empty hit area, is left alone) |
184
202
  | `inline-svg` | warning | SVG icons written inline |
203
+ | `icon-button-label` | warning | A `MazBtn` that only shows an icon, without `text`, content nor `aria-label` |
185
204
  | `prefer-ecosystem`, `prefer-utils` | warning / info | lodash, VueUse, toast, icon, tooltip, date picker... libraries that maz-ui already covers |
186
205
  | `theme-colors` | warning | Default Tailwind palette (`bg-blue-500`, `text-gray-600`, `bg-white`) |
187
206
  | `hardcoded-color` | warning | `bg-[#1d90ff]`, `color: #fff` |
@@ -206,42 +225,57 @@ The documentation is also published for agents that browse the web:
206
225
 
207
226
  This is what `init`, the Nuxt option, the Claude Code plugin and the MCP server teach to your agents:
208
227
 
209
- 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.
228
+ 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.
210
229
 
211
230
  ### Look it up before you write it
212
231
 
213
- Before creating a component, composable, helper, icon or style, check what maz-ui offers:
232
+ - **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`.
233
+ - **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, the `maz-ui` of the app).
214
234
 
215
- - **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`.
216
- - **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.
235
+ Never guess an API: only use documented props, events, slots and imports.
217
236
 
218
- Never guess an API: only use props, events, slots and imports that are documented.
237
+ ### Which package for what
238
+
239
+ `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).
219
240
 
220
241
  ### Components
221
242
 
222
- - 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`...
243
+ - 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`...
223
244
  - 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`.
224
- - Feedback and overlays: `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states.
245
+ - A button with only an icon needs an `aria-label`.
246
+
247
+ ### Feedback, overlays and forms
248
+
249
+ - `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states, `MazSkeleton` / `MazSpinner` while data loads.
250
+ - 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).
225
251
  - Forms: `useFormValidator` / `useFormField` with your Standard Schema library (Zod, Valibot, ArkType).
226
252
 
227
253
  ### Icons
228
254
 
229
- 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">`.
255
+ Use `@maz-ui/icons`, never inline SVG nor another icon library. Pick the format by usage:
256
+
257
+ - **Icon props** (`<MazBtn :start-icon>`, `<MazIcon :icon>`...): the raw SVG string, the lightest, `@maz-ui/icons/raw/MazTrash`.
258
+ - **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`).
259
+ - **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.
260
+ - `<img>` or CSS only for multicolor icons (flags, logos): `@maz-ui/icons/svg/<name>.svg`, the text color does not apply there.
230
261
 
231
- ### Helpers and composables
262
+ ### Helpers
232
263
 
233
- 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`...
264
+ 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`...
265
+
266
+ ### Texts and languages
267
+
268
+ 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.
234
269
 
235
270
  ### Styling with Tailwind
236
271
 
237
272
  The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`) and the project usually extends it. Only use theme tokens:
238
273
 
239
- - **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.
240
-
241
- - 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`.
242
- - 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.
274
+ - **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.
275
+ - 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`.
276
+ - 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.
243
277
  - 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`.
244
- - **No `maz:` prefix** in this project: it is internal to the maz-ui library and its documentation.
278
+ - **No `maz:` prefix** in this project: it is internal to the maz-ui library.
245
279
  - In custom CSS, use the variables: `var(--maz-primary)`, `var(--maz-rounded-md)`, `calc(var(--maz-space) * 4)`.
246
280
 
247
281
  ### Theme
@@ -250,8 +284,8 @@ Brand colors, fonts, radius and spacing come from a `@maz-ui/themes` preset (`de
250
284
 
251
285
  ### Imports
252
286
 
253
- - 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`.
254
- - With `@maz-ui/nuxt`, components and composables are auto-imported: do not import them.
287
+ - 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`.
288
+ - 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.
255
289
 
256
290
  ### Before you finish
257
291