maz-ui 5.1.0-beta.0 → 5.1.0

package/docs/ecosystem/translations.md

@@ -1,13 +1,13 @@
 ---
 title: "Translations (i18n)"
-description: "Internationalization for Maz-UI components."
+description: "Internationalization of the maz-ui components with @maz-ui/translations: built-in locales, custom messages, lazy loading and runtime locale switching with useTranslations"
 package: "@maz-ui/translations"
 url: "https://maz-ui.com/ecosystem/translations"
 ---
 
 # Translations (i18n)
 
-> Internationalization for Maz-UI components.
+> Internationalization of the maz-ui components with @maz-ui/translations: built-in locales, custom messages, lazy loading and runtime locale switching with useTranslations
 
 - Package: `@maz-ui/translations`
 - Import: `import { useTranslations } from '@maz-ui/translations'` or `import { fr } from '@maz-ui/translations'`

package/docs/ecosystem/utils/country-code-to-unicode-flag.md

@@ -1,11 +1,11 @@
 ---
-title: "country-code-to-unicode-flag"
+title: "countryCodeToUnicodeFlag"
 description: "Convert country code in unicode flag"
 package: "@maz-ui/utils"
 url: "https://maz-ui.com/ecosystem/utils/country-code-to-unicode-flag"
 ---
 
-# country-code-to-unicode-flag
+# countryCodeToUnicodeFlag
 
 > Convert country code in unicode flag
 

package/docs/guide/ai-agents.md

@@ -81,7 +81,7 @@ export default defineNuxtConfig({
 })
 ```
 
-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.
+It only runs in development (never in CI, in tests or during builds), writes nothing when no agent is detected, keeps the files in sync with the installed maz-ui version and never overwrites files it does not own. In a monorepo, it writes at the root of the workspace, where the agents start (`agents.dir` to choose another folder).
 
 ### Without any file in the project
 
@@ -122,7 +122,7 @@ The MCP server gives agents tools that work with the needs they have, and verify
 | `search_docs` | Find what maz-ui provides for a need ("confirm before delete", "phone input", "debounce search") |
 | `get_component_api` | Exact props, values, events, slots of up to 10 components |
 | `find_icons` | Icons by meaning ("delete", "settings", "france flag") with their imports |
-| `get_theme_tokens` | Every Tailwind class and CSS variable of the theme |
+| `get_theme_tokens` | The theme of your project (preset, `@theme` tokens, variants, utilities) and every Tailwind class and CSS variable of maz-ui |
 | `get_doc` | Any page of the docs, or only some sections |
 | `list_docs` | The whole catalog |
 | `get_setup_guide` | Installation in a Vue or Nuxt app, with or without Tailwind |
@@ -141,6 +141,25 @@ The maz-ui plugin bundles the MCP server, a `maz-ui` skill (rules and workflow)
 
 The plugin works in every project, `init` configures one project for your whole team: use both or either.
 
+### Review hook without the plugin
+
+The review hook of the plugin is the `review --hook` mode of the CLI. To use it alone, add it to `.claude/settings.json` (shared with your team) or `.claude/settings.local.json` (your machine only):
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [{ "type": "command", "command": "npx -y @maz-ui/mcp@latest review --hook", "timeout": 90 }]
+      }
+    ]
+  }
+}
+```
+
+Each file Claude edits is reviewed; the errors and warnings are sent back to Claude, which fixes them.
+
 ## Code review in CI
 
 The checks of `review_code` are also available from the command line:
@@ -173,7 +192,7 @@ The command exits with an error code when it finds errors (or more warnings than
 | `root-import`, `internal-import` | error | Runtime imports from `maz-ui` (types only) or from `src`/`dist` |
 | `nuxt-auto-import` | info | Imports that `@maz-ui/nuxt` already auto-imports |
 
-When something is intended, ignore it with a comment on the line above (`<!-- maz-ui-review-ignore prefer-maz-component -->`, `// maz-ui-review-ignore theme-colors`), or `maz-ui-review-ignore-file` for a whole file.
+When something is intended, ignore it with a comment on the line above (`<!-- maz-ui-review-ignore prefer-maz-component -->`, `// maz-ui-review-ignore theme-colors`), or `maz-ui-review-ignore-file` for a whole file. Give the reason after `--`: `<!-- maz-ui-review-ignore theme-colors -- frame over the video -->`.
 
 ## llms.txt
 
@@ -193,7 +212,7 @@ This project is built with **maz-ui** and its ecosystem (`@maz-ui/themes`, `@maz
 
 Before creating a component, composable, helper, icon or style, check what maz-ui offers:
 
-- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete", "phone input"), `get_component_api` (exact props, events, slots), `find_icons`, `get_theme_tokens` (Tailwind classes), `get_doc`, `review_code`.
+- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete", "phone input"), `get_component_api` (exact props, events, slots), `find_icons`, `get_theme_tokens` (Tailwind classes of the project and of maz-ui), `get_doc`, `review_code`.
 - **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, resolve `maz-ui` from the app package). Read the relevant page before using an API.
 
 Never guess an API: only use props, events, slots and imports that are documented.
@@ -215,7 +234,9 @@ Use `@maz-ui/utils` and maz-ui composables instead of lodash, VueUse or hand-wri
 
 ### Styling with Tailwind
 
-The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`). Only use its tokens:
+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.

package/docs/guide/tailwind.md

@@ -273,6 +273,28 @@ Toggle the mode with `useTheme()` (`toggleDarkMode()`, `setColorMode('dark' | 'l
 
 ## Extending the theme
 
+### How the layers fit together
+
+Your theme is built from three layers, from the most global to the most specific:
+
+1. **The preset** (`definePreset` of `@maz-ui/themes`) gives the **values**: it emits runtime CSS variables (`--maz-primary`, `--maz-font-family`, `--maz-rounded-md`, `--maz-motion-fast`...) for the light and dark modes.
+2. **The maz-ui theme** (`maz-ui/tailwindcss/theme.css`) gives the **class names**: it maps each Tailwind token to a preset variable (`--color-primary: var(--maz-primary)`, `--font-display: var(--maz-font-display-stack)`). `bg-primary` or `font-display` therefore follow the active preset and color mode, without rebuild.
+3. **Your Tailwind entry** gives the **project tokens**: everything you declare after the maz-ui imports (`@theme`, `@custom-variant`, `@utility`) adds classes next to the maz-ui ones.
+
+| You want | Put it in | You get |
+| --- | --- | --- |
+| Brand colors, fonts, radius, shadows, motion, spacing | the preset (`colors`, `foundation`, `scales`) | the same maz-ui classes with your values, components included |
+| Background of cards and inputs, button font weight | the preset (`components`) | `bg-container`, `bg-input`, `MazBtn` |
+| A color outside the maz-ui roles (chart series, category) | `@theme { --color-* }` | `bg-<name>`, `text-<name>`... |
+| An animation | `@theme { --animate-* }` + `@keyframes` | `animate-<name>` |
+| A variant (short screens, a state) | `@custom-variant` | `<name>:` |
+| A reusable group of declarations | `@utility` | `<name>` |
+| The width of `padded-container` | `--maz-container-max-width` in your base layer | Container width |
+
+**Warning: Redefining a maz-ui token**
+
+A token you redefine in your `@theme` (`--color-primary`, `--font-sans`, `--radius-md`...) replaces the maz-ui mapping: the class keeps your literal value and **stops following the preset** (preset switch, light and dark values). Change brand values in the preset instead; redefine a token only when you need it, for example to give a literal font name to `@nuxt/fonts` (see Fonts).
+
 ### Brand colors: use a preset
 
 Your brand colors, radius, fonts and spacing belong to a theme preset: every maz-ui component **and** every Tailwind utility (`bg-primary`, `rounded-md`, `font-sans`...) then use them, in light and dark modes.
@@ -321,7 +343,7 @@ For a color outside the maz-ui roles (a chart series, a product category), decla
 
 ### Fonts
 
-The font utilities read the preset (`foundation.font-family`, `font-display-stack`, `font-mono-stack`). You can also override them in your Tailwind entry, after the maz-ui import:
+The font utilities read the preset: `font-sans` uses `foundation.font-family`, `font-display` uses `font-display-stack` and `font-mono` uses `font-mono-stack`. You can also redefine them in your Tailwind entry, after the maz-ui import (keep the same stacks as the preset, the classes no longer follow it):
 
 ```css
 @theme {
@@ -466,6 +488,8 @@ Tailwind v4 processes each SFC `<style>` block in isolation: a block that uses `
 
 Every class and variable of this page is available to AI coding agents, generated from the sources of the installed version: the `get_theme_tokens` tool of the [maz-ui MCP server](../ecosystem/mcp.md), and `node_modules/maz-ui/docs/reference/tailwind-tokens.md`. See [AI agents](./ai-agents.md).
 
+`get_theme_tokens` also reads **your** theme: the Tailwind entries of the project (CSS files with `@theme`, `@custom-variant`, `@utility` or a `tailwindcss` import) and the `definePreset` calls, in every app of a monorepo. Agents get your preset values, your tokens with their comments (`animate-rise`, `font-display`, `short:`...), the tokens that redefine a maz-ui one and the setup problems (missing maz-ui import). A comment above a token in your `@theme` is a good place to say when to use it.
+
 ## Migrating from Tailwind v3
 
 Run the official upgrade tool first, it handles most of the v3 to v4 transition (renamed utilities, `tailwind.config.js` to CSS-first configuration):