maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/guide/ai-agents.md

@@ -0,0 +1,237 @@
+---
+title: "AI agents"
+description: "Make Claude Code, Cursor, GitHub Copilot, Codex and the other AI coding agents use maz-ui and its ecosystem instead of re-implementing it - project rules, MCP server, version-matched docs, llms.txt and automatic code review."
+package: "maz-ui"
+url: "https://maz-ui.com/guide/ai-agents"
+---
+
+# AI agents
+
+> Make Claude Code, Cursor, GitHub Copilot, Codex and the other AI coding agents use maz-ui and its ecosystem instead of re-implementing it - project rules, MCP server, version-matched docs, llms.txt and automatic code review.
+
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/ai-agents
+
+## Why
+
+Left alone, coding agents rebuild what maz-ui already provides: native buttons instead of `MazBtn`, lodash instead of `@maz-ui/utils`, inline SVG instead of `@maz-ui/icons`, `bg-blue-500` instead of the theme colors. They also guess APIs from outdated training data.
+
+maz-ui gives them four things:
+
+| | What | Where |
+| --- | --- | --- |
+| **Rules** | How to use maz-ui in your project, loaded automatically by the agent | `.claude/rules/maz-ui.md`, `AGENTS.md` |
+| **Version-matched docs** | Agent-ready markdown of the installed version: guides, component APIs, icons, Tailwind tokens | `node_modules/maz-ui/docs/` |
+| **MCP server** | Search by need, exact component APIs, icons, theme tokens, setup guides, code review | `npx @maz-ui/mcp` |
+| **Code review** | Static checks against the real maz-ui APIs, in the agent loop and in CI | `review_code` tool, `npx @maz-ui/mcp review` |
+
+## Quick start
+
+Run this command at the root of your project:
+
+```bash
+npx @maz-ui/mcp init
+```
+
+It detects the agents you use and configures them, using the docs of the maz-ui version installed in the project:
+
+| Agent | Rules | MCP server |
+| --- | --- | --- |
+| Claude Code | `.claude/rules/maz-ui.md` (always loaded) | `.mcp.json` |
+| Cursor | `AGENTS.md` | `.cursor/mcp.json` |
+| GitHub Copilot (VS Code) | `AGENTS.md` | `.vscode/mcp.json` |
+| Codex, Windsurf, Zed, Gemini CLI... | `AGENTS.md` | global config of the agent (see [MCP](../ecosystem/mcp.md)) |
+
+When no agent is detected, it configures Claude Code and `AGENTS.md`. Commit the generated files: your whole team and your CI agents get them.
+
+**Tip: It never overwrites your own instructions**
+
+- Your `CLAUDE.md` is never touched: Claude Code loads `.claude/rules/maz-ui.md` on top of it.
+- In `AGENTS.md`, maz-ui only manages the section between `<!-- BEGIN:maz-ui -->` and `<!-- END:maz-ui -->`.
+- In the MCP config files, only the `maz-ui` entry is added, the formatting and comments of the file are preserved. An existing server running `@maz-ui/mcp` under another name is kept as is.
+- A file you created yourself with the same path is never overwritten.
+
+### Options
+
+```bash
+npx @maz-ui/mcp init --targets claude,agents-md,cursor,vscode  # choose the agents
+npx @maz-ui/mcp init --no-rules                                # MCP server only
+npx @maz-ui/mcp init --no-mcp                                  # rules only
+npx @maz-ui/mcp init --dry-run                                 # show the changes
+npx @maz-ui/mcp init --remove                                  # remove everything init added
+```
+
+Run it again after upgrading maz-ui: the rules follow the installed version.
+
+### Nuxt: connected by default
+
+With [`@maz-ui/nuxt`](../ecosystem/nuxt.md), the agents detected in the project are connected to the maz-ui MCP server when you start the dev server: the module only adds the `maz-ui` entry to their MCP config (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`). The instructions of the MCP server already give the maz-ui rules to the agents, so no rule file is written by default.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt'],
+  mazUi: {
+    // default: { rules: false, mcp: true }
+    agents: {
+      rules: true, // also write .claude/rules/maz-ui.md and the AGENTS.md section
+      targets: ['claude', 'agents-md'], // default: the detected agents
+    },
+    // or disable it: agents: false
+  },
+})
+```
+
+It only runs in development (never in CI, in tests or during builds), writes nothing when no agent is detected, keeps the files in sync with the installed maz-ui version and never overwrites files it does not own.
+
+### Without any file in the project
+
+The MCP server carries the rules in its instructions: registering it once for your user is enough, in every project, without writing anything in them.
+
+- Claude Code: install the plugin, or run `claude mcp add maz-ui --scope user -- npx -y @maz-ui/mcp@latest`.
+- Cursor, Windsurf, Codex...: add the server to the global MCP config of the agent (see [MCP](../ecosystem/mcp.md#configuration)).
+
+Write the project files (`init`, the Nuxt option) when your whole team, or agents without MCP, need the rules.
+
+## Version-matched docs
+
+Each `maz-ui` release ships its documentation for agents in `node_modules/maz-ui/docs/`:
+
+```txt
+node_modules/maz-ui/docs/
+├── README.md                     # index of every page, start here
+├── rules.md                      # the rules below
+├── manifest.json                 # machine-readable index, component APIs, icons, tokens
+├── components/maz-btn.md         # usage, examples and full API of each component
+├── composables/  directives/  plugins/  guide/
+├── ecosystem/                    # themes, translations, icons, nuxt, utils, node...
+└── reference/
+    ├── tailwind-tokens.md        # every Tailwind class and CSS variable of the theme
+    └── icons.md                  # the 860+ icon names
+```
+
+The pages are the ones of this website, cleaned for agents: no live demos, every example as code, and the full API of each component (props with their accepted values, `v-model`, events, slots) generated from the TypeScript sources.
+
+Agents read the docs of **your** version, not what they remember from their training data. The MCP server serves the same files.
+
+## MCP server
+
+The MCP server gives agents tools that work with the needs they have, and verify their code:
+
+| Tool | Purpose |
+| --- | --- |
+| `search_docs` | Find what maz-ui provides for a need ("confirm before delete", "phone input", "debounce search") |
+| `get_component_api` | Exact props, values, events, slots of up to 10 components |
+| `find_icons` | Icons by meaning ("delete", "settings", "france flag") with their imports |
+| `get_theme_tokens` | Every Tailwind class and CSS variable of the theme |
+| `get_doc` | Any page of the docs, or only some sections |
+| `list_docs` | The whole catalog |
+| `get_setup_guide` | Installation in a Vue or Nuxt app, with or without Tailwind |
+| `review_code` | Review files against the installed maz-ui |
+
+See [MCP](../ecosystem/mcp.md) for the configuration of each agent.
+
+## Claude Code plugin
+
+The maz-ui plugin bundles the MCP server, a `maz-ui` skill (rules and workflow) and a hook that reviews every `.vue`, `.ts` and `.css` file Claude edits, so it fixes maz-ui mistakes before you see them.
+
+```txt
+/plugin marketplace add LouisMazel/maz-ui
+/plugin install maz-ui@maz-ui
+```
+
+The plugin works in every project, `init` configures one project for your whole team: use both or either.
+
+## Code review in CI
+
+The checks of `review_code` are also available from the command line:
+
+```bash
+npx @maz-ui/mcp review "src/**/*.{vue,ts,css}"
+npx @maz-ui/mcp review app --min-severity warning --max-warnings 0
+npx @maz-ui/mcp review src --format json
+```
+
+The command exits with an error code when it finds errors (or more warnings than `--max-warnings`).
+
+| Rule | Severity | Detects |
+| --- | --- | --- |
+| `unknown-component` | error | `<MazButton>` (did you mean `MazBtn`?) |
+| `unknown-prop` | warning | A prop the component does not have (`colour`) |
+| `invalid-prop-value` | error | `color="red"` on a component that accepts `primary`, `secondary`... |
+| `boolean-prop-string` | error | `disabled="false"` (a truthy string) |
+| `unknown-model`, `unknown-event`, `unknown-slot` | error | `v-model:foo`, `@clik`, `<template #captions>` |
+| `unknown-icon` | error | An icon that does not exist in `@maz-ui/icons` |
+| `prefer-maz-component` | warning | `<button>`, `<input>`, `<select>`, `<textarea>`, `<dialog>`... |
+| `inline-svg` | warning | SVG icons written inline |
+| `prefer-ecosystem`, `prefer-utils` | warning / info | lodash, VueUse, toast, icon, tooltip, date picker... libraries that maz-ui already covers |
+| `theme-colors` | warning | Default Tailwind palette (`bg-blue-500`, `text-gray-600`, `bg-white`) |
+| `hardcoded-color` | warning | `bg-[#1d90ff]`, `color: #fff` |
+| `internal-prefix` | error | The internal `maz:` prefix |
+| `tailwind-v3` | warning | `bg-opacity-50`, `flex-shrink-0`... |
+| `missing-reference` | error | `@apply` in a SFC style block without `@reference` |
+| `manual-dark-mode` | warning | Dark mode handled by hand instead of `useTheme()` |
+| `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.
+
+## llms.txt
+
+The documentation is also published for agents that browse the web:
+
+- [maz-ui.com/llms.txt](https://maz-ui.com/llms.txt): index of every page
+- [maz-ui.com/llms-full.txt](https://maz-ui.com/llms-full.txt): the whole documentation in one file
+- Each page as markdown: `https://maz-ui.com/components/maz-btn.md`
+
+## The rules
+
+This is what `init`, the Nuxt option, the Claude Code plugin and the MCP server teach to your agents:
+
+This project is built with **maz-ui** and its ecosystem (`@maz-ui/themes`, `@maz-ui/icons`, `@maz-ui/utils`, `@maz-ui/translations`, `@maz-ui/nuxt`). Reuse what it provides instead of re-implementing it: most UI elements, helpers, icons and styles you need already exist.
+
+### Look it up before you write it
+
+Before creating a component, composable, helper, icon or style, check what maz-ui offers:
+
+- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete", "phone input"), `get_component_api` (exact props, events, slots), `find_icons`, `get_theme_tokens` (Tailwind classes), `get_doc`, `review_code`.
+- **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, resolve `maz-ui` from the app package). Read the relevant page before using an API.
+
+Never guess an API: only use props, events, slots and imports that are documented.
+
+### Components
+
+- Use `Maz*` components instead of native elements or hand-made widgets: `MazBtn` (not `<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`...
+- Prop values are typed: colors are `primary | secondary | accent | info | success | warning | destructive | contrast | transparent` (plus `surface` on some components), sizes `mini | xs | sm | md | lg | xl`.
+- Feedback and overlays: `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states.
+- Forms: `useFormValidator` / `useFormField` with your Standard Schema library (Zod, Valibot, ArkType).
+
+### Icons
+
+Use `@maz-ui/icons` (860+ icons: `MazTrash`, `MazXMark`, `MazMagnifyingGlass`, `MazFlagFR`, `MazLogoVue`...). Never inline SVG or add another icon library. Pass icon components to icon props: `<MazBtn :start-icon="MazTrash">`.
+
+### Helpers and composables
+
+Use `@maz-ui/utils` and maz-ui composables instead of lodash, VueUse or hand-written code: `debounce`, `throttle`, `sleep`, `isEqual`, `capitalize`, `formatCurrency`, `formatDate`, `formatNumber`, `formatPhoneNumber`, `getCookie`/`setCookie`, `useBreakpoints`, `useWindowSize`, `useTimer`, `useIdleTimeout`, `useSwipe`, `vClickOutside`, `vTooltip`, `vLazyImg`...
+
+### Styling with Tailwind
+
+The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`). Only use its tokens:
+
+- Colors: `primary`, `secondary`, `accent`, `info`, `success`, `warning`, `destructive`, `contrast` (each with `-foreground` and `-50` to `-950`), `surface`, `foreground`, `muted`, `divider`, `overlay`, plus `bg-container` and `bg-input`. Example: `bg-surface text-foreground border-divider`, `bg-primary text-primary-foreground`, `text-muted`.
+- Never use the default Tailwind palette (`bg-blue-500`, `text-gray-600`, `bg-white`, `text-black`) nor hard-coded colors (`#fff`, `rgb()`, `bg-[#...]`). Theme colors already adapt to dark mode: do not add `dark:` color overrides.
+- Radius `rounded-*`, shadows `shadow-sm` to `shadow-xl` and `shadow-elevation`, spacing scale (`p-4`, `gap-2`), breakpoints `mob-*`, `tab-*`, `lap-*` (plus `sm` to `2xl`), utilities `flex-center`, `padded-container`.
+- **No `maz:` prefix** in this project: it is internal to the maz-ui library and its documentation.
+- In custom CSS, use the variables: `var(--maz-primary)`, `var(--maz-rounded-md)`, `calc(var(--maz-space) * 4)`.
+
+### Theme
+
+Brand colors, fonts, radius and spacing come from a `@maz-ui/themes` preset (`definePreset`), not from overrides scattered in CSS. Use `useTheme()` for dark mode and presets (`toggleDarkMode`, `setColorMode`, `updateTheme`), never toggle the `dark` class or store the mode yourself.
+
+### Imports
+
+- Deep imports: `maz-ui/components/MazBtn`, `maz-ui/composables/useToast`, `maz-ui/directives/vTooltip`, `@maz-ui/utils/helpers/debounce`, `@maz-ui/icons/static/MazTrash`. The `maz-ui` root entry only exports types. Never import from `maz-ui/src` or `maz-ui/dist`.
+- With `@maz-ui/nuxt`, components and composables are auto-imported: do not import them.
+
+### Before you finish
+
+Run `review_code` (MCP) on the files you changed, or `npx @maz-ui/mcp review <files>`, and fix every finding.

package/docs/guide/browser-support.md

@@ -0,0 +1,88 @@
+---
+title: "Browser support"
+description: "Maz-UI v5 browser compatibility matrix and the native CSS features it depends on."
+package: "maz-ui"
+url: "https://maz-ui.com/guide/browser-support"
+---
+
+# Browser support
+
+> Maz-UI v5 browser compatibility matrix and the native CSS features it depends on.
+
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/browser-support
+
+Maz-UI v5 is built on **Tailwind CSS v4**, which relies on modern native CSS features with no polyfill path. If your audience still uses older browsers, stay on Maz-UI v4.
+
+## Minimum versions
+
+| Browser            | Minimum |
+| ------------------ | ------- |
+| **Chromium** (Chrome, Edge, Opera, Brave, Arc, …) | **111** (March 2023) |
+| **Safari** (macOS, iOS, iPadOS) | **16.4** (March 2023) |
+| **Firefox** | **128** (July 2024) |
+| **Samsung Internet** | **22** (2023) |
+
+On the Android side: Chrome 111+ is bundled with Android 13+ devices and is available as an update on anything from Android 7. WebView apps built against API level 24+ get Chromium 111+ automatically.
+
+Anything older than the versions above will not render the design system correctly. The most common failure mode is colors looking wrong (because `color-mix()` doesn't resolve) or cascade layers being ignored.
+
+## Why these minimums
+
+Maz-UI v5 + Tailwind v4 uses the following native CSS features:
+
+### `color-mix()`
+
+Used for every alpha modifier (`bg-primary/50`, the custom `color-mix(in srgb, var(--X) 60%, transparent)` generated by the `@maz-ui/upgrade` package for `hsl(var(--X) / 60%)`, etc.).
+
+[Browser support · caniuse](https://caniuse.com/?search=color-mix) - supported everywhere since Chromium 111 / Safari 16.4 / Firefox 128.
+
+### `@property`
+
+Used internally by Tailwind v4 to declare typed custom properties with default values. Powers the `--tw-translate-x`, `--tw-rotate`, etc. that back transform utilities.
+
+[Browser support · caniuse](https://caniuse.com/?search=%40property) - supported everywhere since Chromium 111 / Safari 16.4 / Firefox 128.
+
+### Native CSS nesting
+
+Used by Tailwind v4 internally and by Maz-UI utilities like `cap-f` (`&::first-letter`). v4 does not run a CSS-nesting preprocessor; the output relies on the browser parsing nested rules directly.
+
+[Browser support · caniuse](https://caniuse.com/css-nesting) - supported everywhere since Chromium 112 / Safari 16.5 / Firefox 117.
+
+### `:has()` selector
+
+Used by a few Maz-UI utilities for parent-aware styling.
+
+[Browser support · caniuse](https://caniuse.com/css-has) - supported everywhere since Chromium 105 / Safari 15.4 / Firefox 121.
+
+## Testing on older browsers
+
+If you need to support a browser older than the matrix above:
+
+1. **Stay on Maz-UI v4** - it keeps Tailwind v3 and targets Chromium 90+, Safari 14+, Firefox 90+.
+2. **Check your real audience** using your analytics tool before bumping to v5. "Support everything" is often outdated advice in 2026 - most teams can comfortably drop anything older than Chromium 111.
+
+## Testing on the minimum versions
+
+Playwright can install exact minimum-version browsers for regression testing:
+
+```bash
+pnpm add -D @playwright/test
+npx playwright install chromium@111 firefox@128 webkit@16.4
+```
+
+Then run your visual tests against that matrix in CI.
+
+## What happens on unsupported browsers
+
+- **`color-mix` unsupported** - any utility that goes through an alpha modifier (`bg-primary/50`, the custom overlay colors in MazDialog / MazBackdrop) falls back to the base color with no transparency. Visual regression but not a crash.
+- **`@property` unsupported** - transform, translate, rotate, scale utilities don't animate smoothly because the custom properties aren't interpolatable without `@property`.
+- **Cascade layers unsupported** - the order of Maz-UI styles vs app styles becomes non-deterministic, so resets and utilities can override app styles (or vice versa) unpredictably.
+
+The safe recommendation is: detect at app boot and show an "unsupported browser" screen if you can't guarantee the minimum matrix.
+
+## See also
+
+- [Migration v4 → v5](./migration-v5.md) - the full upgrade guide
+- [Tailwind v4 browser support](https://tailwindcss.com/blog/tailwindcss-v4#browser-support) - upstream notes
+- [Tailwind CSS integration](./tailwind.md) - how the design system plugs into your own Tailwind

package/docs/guide/getting-started.md

@@ -0,0 +1,191 @@
+---
+title: "Getting Started"
+description: "Build Vue and Nuxt applications faster with Maz-UI v5 - The modern, modular component library"
+package: "maz-ui"
+url: "https://maz-ui.com/guide/getting-started"
+---
+
+# Getting Started
+
+> Build Vue and Nuxt applications faster with Maz-UI v5 - The modern, modular component library
+
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/getting-started
+
+**Tip: **Why Maz-UI?****
+
+- 🌱 **Tree-shaking** - Import only what you need
+- 🛠️ **TypeScript-first** - Full type safety out of the box
+- 🚀 **Performance** - Tree-shaking benefits and maximum optimization
+- 🎨 **Theming system** - Customizable themes and dark mode support (5 presets available) - [@maz-ui/themes](../ecosystem/themes.md)
+- 💨 **Optional Tailwind bridge** - Already have a Tailwind v4 setup? Expose your active maz-ui theme tokens (colors, radius, breakpoints, custom utilities) to your own Tailwind config - [Tailwind integration](./tailwind.md)
+- 🌐 **Internationalization** - Locale management and tree-shakable imports - [@maz-ui/translations](../ecosystem/translations.md)
+- 🎨 **Icon library** - Comprehensive collection of SVG icons designed for performance and flexibility (860+ icons) - [@maz-ui/icons](../ecosystem/icons/index.md)
+- 🧰 **Nuxt module** - Effortless Maz-UI integration with auto-imports - [@maz-ui/nuxt](../ecosystem/nuxt.md)
+- 🤖 **AI agents** - Make Claude Code, Cursor, Copilot and Codex use maz-ui instead of re-implementing it - [AI agents](./ai-agents.md), [@maz-ui/mcp](../ecosystem/mcp.md)
+
+**Tip: Migrating from v4?**
+
+Run `npx @maz-ui/upgrade ./` to handle the mechanical part of the migration (CSS subpath imports, prop renames, CSS var renames, Nuxt config keys, custom preset color keys, and `package.json` version bumps). See the [v5 migration guide](./migration-v5.md) for the rest.
+
+## Guides
+
+Start by choosing your framework:
+
+- [Install maz-ui with Vue](./vue.md)
+- [Install maz-ui with Nuxt](../ecosystem/nuxt.md)
+
+## Ecosystem Packages
+
+Extend Maz-UI with our specialized companion packages:
+
+### @maz-ui/themes
+
+**Advanced Theming System**
+
+Modern theme system with OKLCh color scales, runtime preset switching, and dark mode support.
+
+```bash
+npm install @maz-ui/themes
+```
+
+**Features:**
+
+- 🎨 Native `light-dark()` + `color-scheme` + OKLCh scales via relative color syntax
+- 🌓 Smart dark mode - `class` or `media` strategies, with smooth transitions on toggle
+- ✨ Optional animated theme switch via View Transitions (`setColorMode(..., { animate: true })`)
+- ⚡ `runtime` and `buildtime` rendering strategies
+- 🍪 Active preset persisted across reloads (opt-out)
+- 🛡️ Full TypeScript support
+
+[→ View Theme Documentation](../ecosystem/themes.md)
+
+---
+
+### @maz-ui/translations
+
+**Internationalization (i18n)**
+
+Internationalization library for Maz-UI.
+
+```bash
+npm install @maz-ui/translations
+```
+
+**Features:**
+
+- 🌐 Internationalization of Maz-UI components
+- 🔄 Locale management
+- 📦 Tree-shakable imports
+- 🛠️ TypeScript support
+
+[→ View Translations Documentation](../ecosystem/translations.md)
+
+---
+
+### @maz-ui/icons
+
+**Optimized Icon Library**
+
+Comprehensive collection of SVG icons designed for performance and flexibility.
+
+```bash
+npm install @maz-ui/icons
+```
+
+**Features:**
+
+- 860+ icons
+- Usable as Vue components (e.g. `<MazStar />`)
+- Tree-shakable imports
+- Multiple sizes and variants
+- Full TypeScript definitions
+
+[→ Browse Icon Library](../ecosystem/icons/index.md)
+
+---
+
+### @maz-ui/mcp
+
+**Make your AI coding agents use maz-ui**
+
+```bash
+npx @maz-ui/mcp init
+```
+
+**Features:**
+
+- Rules for Claude Code, Cursor, GitHub Copilot, Codex... without touching your own instructions
+- MCP server: search by need, component APIs, icons, Tailwind theme tokens, docs of the installed version
+- Code review against the installed maz-ui, in the agent loop and in CI
+- Claude Code plugin and automatic setup with the Nuxt module
+
+[→ View AI agents guide](./ai-agents.md)
+
+## Performance Optimizations
+
+### Tree-Shaking Benefits
+
+Maz-UI v5 is built with tree-shaking in mind. Import only what you need for optimal bundle sizes:
+
+```typescript
+/**
+ * Components
+ */
+
+// ✅ Import specific components (good)
+import { MazBtn, MazCard, MazInput } from 'maz-ui/components'
+// ✅✅ Direct component import (most optimized)
+import MazBtn from 'maz-ui/components/MazBtn'
+import MazCard from 'maz-ui/components/MazCard'
+import MazInput from 'maz-ui/components/MazInput'
+
+/**
+ * Composables
+ */
+
+// ✅ Import composable from index file
+import { useBreakpoints, useToast } from 'maz-ui/composables'
+
+// ✅✅ Direct composable import (most optimized)
+import { useToast } from 'maz-ui/composables/useToast'
+import { useBreakpoints } from 'maz-ui/composables/useBreakpoints'
+
+/**
+ * Directives
+ */
+
+// ✅ Import directive from index file
+import { vClickOutside } from 'maz-ui/directives'
+
+// ✅✅ Direct directive import (most optimized)
+import { vClickOutside } from 'maz-ui/directives/vClickOutside'
+
+// ✅✅✅ Even better: auto-import does this automatically
+// Components, composables, and utilities are imported only when used
+
+/**
+ * Plugins
+ */
+
+// ✅ Import plugin from index file
+import { MazUi } from 'maz-ui/plugins'
+// ✅✅ Direct plugin import (most optimized)
+import { MazUi } from 'maz-ui/plugins/maz-ui'
+
+/**
+ * Utilities
+ */
+
+// ❌ Avoid importing everything
+import { formatCurrency, debounce } from '@maz-ui/utils'
+// ✅ Import from @maz-ui/utils
+import { debounce } from '@maz-ui/utils/helpers/debounce'
+import { formatCurrency } from '@maz-ui/utils/helpers/formatCurrency'
+```
+
+**Tip: Maximum Optimization**
+
+**Direct imports** (e.g., `import MazBtn from 'maz-ui/components/MazBtn'`) are the most optimized approach as they bypass index files completely. This ensures the smallest possible bundle size and fastest build times.
+
+## Next Steps

package/docs/guide/global-defaults.md

@@ -0,0 +1,103 @@
+---
+title: "Global component defaults"
+description: "Set default prop values once for every Maz-UI component through the MazUi plugin or the Nuxt module"
+package: "maz-ui"
+url: "https://maz-ui.com/guide/global-defaults"
+---
+
+# Global component defaults
+
+> Set default prop values once for every Maz-UI component through the MazUi plugin or the Nuxt module
+
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/global-defaults
+
+Instead of repeating the same prop on every instance (`<MazBtn rounded-size="lg" />` everywhere), you can set a default once and let every component pick it up.
+
+## Priority
+
+A resolved prop always follows this order, from highest to lowest priority:
+
+1. The prop set on the component instance
+2. `defaults.<ComponentName>` (per-component default)
+3. `defaults.global` (cross-cutting default)
+4. The library's built-in default
+
+A global default **never** overrides a prop set on the instance. Without any `defaults` config, every component keeps its built-in default, so this feature is fully opt-in and backward compatible.
+
+## Vue
+
+Pass `defaults` to the `MazUi` plugin:
+
+```ts
+import { MazUi } from 'maz-ui/plugins/maz-ui'
+import { mazUi as mazUiPreset } from '@maz-ui/themes/presets/mazUi'
+import 'maz-ui/style.css'
+
+app.use(MazUi, {
+  theme: { preset: mazUiPreset },
+  defaults: {
+    global: { roundedSize: 'lg' },
+    MazBtn: { roundedSize: 'full' }, // wins over global for MazBtn
+    MazCard: { bordered: false, elevation: true },
+    MazContainer: { bordered: false },
+  },
+})
+```
+
+## Nuxt
+
+Set it in `nuxt.config` under the `mazUi` key:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt'],
+  mazUi: {
+    defaults: {
+      global: { roundedSize: 'lg' },
+      MazBtn: { roundedSize: 'full' },
+      MazCard: { bordered: false, elevation: true },
+    },
+  },
+})
+```
+
+## `global` vs per-component
+
+- `defaults.global` holds **cross-cutting** props shared by many components: `roundedSize`, `size` and `flagSrc`. Set them once and every component that exposes them picks the value up.
+- `defaults.<ComponentName>` holds **per-component** props (including booleans such as `bordered`, `elevation`, `padding`). A per-component entry always wins over `global`.
+
+```ts
+defaults: {
+  global: { roundedSize: 'lg', size: 'sm' },
+  MazBtn: { roundedSize: 'full' }, // MazBtn is 'full', everything else 'lg'
+}
+```
+
+## Type safety
+
+`defaults` is fully typed. Each component entry is typed as `Partial<ComponentNameProps>`, so you get autocompletion and a TypeScript error on an unknown or mistyped prop:
+
+```ts
+defaults: {
+  MazBtn: { roundedSiz: 'lg' }, // ❌ TS error: 'roundedSiz' does not exist
+}
+```
+
+## Globalizable props
+
+| Prop | Type | Components |
+| --- | --- | --- |
+| `roundedSize` | `MazRoundedSize` (`'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'`) | `MazBtn`, `MazBtnGroup`, `MazContainer`, `MazInput`, `MazTextarea`, `MazTable`, `MazBadge`, `MazAlert`, `MazAvatar`, `MazSkeleton`, `MazTimeline` |
+| `flagSrc` | `MazCountryFlagSrc` (URL template or function, e.g. `loadCountryFlag` from `maz-ui/country-flags`) | `MazSelectCountry`, `MazInputPhoneNumber` (see [flags source](../components/maz-select-country.md#flags-source)) |
+| `size` | `MazSize` (`'mini' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`) | `MazBtn`, `MazBtnGroup`, `MazBadge`, `MazInput`, `MazSelect`, `MazSelectCountry`, `MazInputNumber`, `MazInputTags`, `MazInputPhoneNumber`, `MazCheckbox`, `MazRadio`, `MazRadioButtons`, `MazDropdown`, `MazPagination`, `MazTable`, `MazTimeline` |
+| `bordered`, `elevation`, `padding`, `transparent`, `overflowHidden` | `boolean` | `MazContainer` |
+| `bordered`, `elevation`, `padding`, `radius`, `scale`, `overflowHidden` | `boolean` | `MazCard` |
+
+**Tip: Note**
+
+Components whose `size` is a free CSS length (`MazSizeUnit`, e.g. `MazSpinner`, `MazAvatar`, `MazDrawer`, `MazSlider`, `MazCircularProgressBar`, `MazFullscreenLoader`) do not take the global `size` token - the value would not be valid for them. `MazAlert` and `MazTimeline` keep their own wider `roundedSize` scale; a `defaults.global.roundedSize` value still applies to them, and their extra steps (`2xl`, `3xl`) are reachable through their per-component entry.
+
+## Relation to the theme system
+
+This is **not** a duplicate of [`@maz-ui/themes`](../ecosystem/themes.md). The theme system controls *what a token looks like* (the CSS value of `rounded-md`, `shadow-elevation`, colors…). Global defaults control *which prop value a component selects by default* (whether `MazBtn` defaults to `roundedSize="lg"`). Both work together: the theme defines what `lg` renders as, the defaults decide which step a component uses.