@maz-ui/mcp 5.0.0 → 5.1.0-beta.0

package/docs/{src/guide → guide}/maz-ui-provider.md

@@ -1,15 +1,16 @@
 ---
-title: MazUiProvider
-description: A component-based alternative to the MazUi plugin for initializing theme and translations, ideal for lazy-loaded pages and micro-frontends.
-head:
-  - - meta
-    - name: keywords
-      content: maz-ui provider, vue provider component, lazy loading, theme provider, translations provider, tree-shaking, code splitting, maz-ui
+title: "MazUiProvider"
+description: "A component-based alternative to the MazUi plugin for initializing theme and translations, ideal for lazy-loaded pages and micro-frontends."
+package: "maz-ui"
+url: "https://maz-ui.com/guide/maz-ui-provider"
 ---
 
-# {{ $frontmatter.title }}
+# MazUiProvider
 
-{{ $frontmatter.description }}
+> A component-based alternative to the MazUi plugin for initializing theme and translations, ideal for lazy-loaded pages and micro-frontends.
+
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/maz-ui-provider
 
 ## Why MazUiProvider?
 
@@ -90,8 +91,8 @@ The entire Maz-UI setup is now code-split into the Dashboard chunk.
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `theme` | `object` | Yes | Theme configuration. Must include `preset`. See [Theming](./themes.md) for details. |
-| `translations` | `object` | Yes | Translations configuration. Must include `locale` and `messages` with at least the current locale's messages. See [Translations](./translations.md) for details. |
+| `theme` | `object` | Yes | Theme configuration. Must include `preset`. See [Theming](../ecosystem/themes.md) for details. |
+| `translations` | `object` | Yes | Translations configuration. Must include `locale` and `messages` with at least the current locale's messages. See [Translations](../ecosystem/translations.md) for details. |
 
 ### theme
 
@@ -109,9 +110,9 @@ interface ThemeOptions {
 }
 ```
 
-::: warning Why is preset required?
+**Warning: Why is preset required?**
+
 Providing the theme preset synchronously avoids FOUC (Flash of Unstyled Content). Without a preset, components would render without their CSS variables until the theme loads, causing a visible flash.
-:::
 
 ### translations
 
@@ -124,7 +125,8 @@ interface TranslationsOptions {
 }
 ```
 
-::: warning Why are locale and messages required?
+**Warning: Why are locale and messages required?**
+
 By default, Maz-UI does not bundle any translations to keep your bundle small. Translation files are loaded asynchronously on demand.
 
 If you don't provide the messages for the current locale synchronously, components like `MazInputPhoneNumber` will briefly show translation keys (e.g. `inputPhoneNumber.countrySelect.placeholder`) instead of actual text until the async loading completes.
@@ -137,7 +139,6 @@ import { fr } from '@maz-ui/translations'
 // Messages for 'fr' are available immediately -- no flash
 const translations = { locale: 'fr', messages: { fr } }
 ```
-:::
 
 ## Plugin vs Provider
 
@@ -153,7 +154,7 @@ const translations = { locale: 'fr', messages: { fr } }
 
 - Your app uses Maz-UI components on most or all pages
 - You want a simple, one-time setup
-- You're using Nuxt (the [Nuxt module](./nuxt.md) handles everything automatically)
+- You're using Nuxt (the [Nuxt module](../ecosystem/nuxt.md) handles everything automatically)
 
 ### When to use the provider
 
@@ -220,7 +221,7 @@ const locale = ref('fr')
       messages: { fr },
     }"
   >
-    <div class="maz:bg-surface maz:text-foreground maz:p-4">
+    <div class="bg-surface text-foreground p-4">
       <h1>My Dashboard</h1>
       <MazBtn color="primary">Action</MazBtn>
       <MazInput placeholder="Search..." />

package/docs/{src/guide → guide}/migration-v5.md

@@ -1,15 +1,22 @@
 ---
-title: Maz-UI v5.0.0 Migration Guide
-description: What changes for you when upgrading from Maz-UI v4 to v5
+title: "Maz-UI v5.0.0 Migration Guide"
+description: "What changes for you when upgrading from Maz-UI v4 to v5"
+package: "maz-ui"
+url: "https://maz-ui.com/guide/migration-v5"
 ---
 
-# {{ $frontmatter.title }}
+# Maz-UI v5.0.0 Migration Guide
 
-Maz-UI v5 is a major release. For **most consumers** the migration is short — you keep installing the package, importing its styles, using the components. Below is what actually changes for you.
+> What changes for you when upgrading from Maz-UI v4 to v5
 
-::: warning Solo maintainer notice
-Maz-UI is maintained by a single developer. After the v5 stable release, **v4 will no longer receive any support** — no security fixes, no backports. Please plan your upgrade.
-:::
+- Package: `maz-ui`
+- Web: https://maz-ui.com/guide/migration-v5
+
+Maz-UI v5 is a major release. For **most consumers** the migration is short - you keep installing the package, importing its styles, using the components. Below is what actually changes for you.
+
+**Warning: Solo maintainer notice**
+
+Maz-UI is maintained by a single developer. After the v5 stable release, **v4 will no longer receive any support** - no security fixes, no backports. Please plan your upgrade.
 
 ## Run the upgrade tool
 
@@ -31,7 +38,7 @@ See the full list of transforms in the [`@maz-ui/upgrade` README](https://github
 
 ## Migrate with the Maz-UI MCP server
 
-You don't have to scroll through this page by hand. The official **[`@maz-ui/mcp`](./mcp.md)** server exposes this guide (and every other Maz-UI doc — components, composables, plugins, helpers) to your AI assistant via the Model Context Protocol. Once it's wired up, the assistant can search the migration guide, pull the exact section it needs, and patch your codebase with full context on what changed in v5.
+You don't have to scroll through this page by hand. The official **[`@maz-ui/mcp`](../ecosystem/mcp.md)** server exposes this guide (and every other Maz-UI doc - components, composables, plugins, helpers) to your AI assistant via the Model Context Protocol. Once it's wired up, the assistant can search the migration guide, pull the exact section it needs, and patch your codebase with full context on what changed in v5.
 
 ### One-time setup
 
@@ -40,7 +47,7 @@ You don't have to scroll through this page by hand. The official **[`@maz-ui/mcp
 claude mcp add maz-ui npx @maz-ui/mcp --scope project
 ```
 
-For Cursor, Windsurf, VS Code Copilot, Cline and Claude Desktop, see the [MCP guide](./mcp.md#ai-assistant-configuration). Then restart your assistant.
+For Cursor, Windsurf, VS Code Copilot, Cline and Claude Desktop, see the [MCP guide](../ecosystem/mcp.md#ai-assistant-configuration). Then restart your assistant.
 
 ### A migration flow that works
 
@@ -56,9 +63,9 @@ For Cursor, Windsurf, VS Code Copilot, Cline and Claude Desktop, see the [MCP gu
 
    > Apply the codemod for "Required changes" sections 2, 3, 6 and 14 (CSS subpath, `rounded-size="base"`, `left-icon`/`right-icon`, Nuxt `injectMainCss`). Show me a diff before saving.
 
-4. **Discuss the judgment calls.** For sections that have more than a rename — `MazIcon` API, `MazChart` `update-mode`, theme preset reshape — let the assistant ask before rewriting:
+4. **Discuss the judgment calls.** For sections that have more than a rename - `MazIcon` API, `MazChart` `update-mode`, theme preset reshape - let the assistant ask before rewriting:
 
-   > For "Required changes" sections 4, 8 and 10–12, do not patch automatically. Tell me which of my call sites are affected and propose options.
+   > For "Required changes" sections 4, 8 and 10-12, do not patch automatically. Tell me which of my call sites are affected and propose options.
 
 5. **Verify.** After patches:
 
@@ -71,18 +78,18 @@ For Cursor, Windsurf, VS Code Copilot, Cline and Claude Desktop, see the [MCP gu
 - *"I see `hsl(var(--maz-primary))` in my CSS. Apply the v5 fix everywhere with the alpha cases handled via `color-mix`."*
 - *"Compare my `MazIcon` usages against the v5 API and split the codemod into a deterministic part (URL/Vue component) and a part you want me to confirm."*
 
-The MCP server is read-only — it ships docs, not code edits — so the assistant still has to write the patches against your repo with whatever tooling it has. But it removes the "did I miss a section?" risk: the guide and the rest of the v5 docs are always one tool call away.
+The MCP server is read-only - it ships docs, not code edits - so the assistant still has to write the patches against your repo with whatever tooling it has. But it removes the "did I miss a section?" risk: the guide and the rest of the v5 docs are always one tool call away.
 
 ## Migration checklist
 
 1. Bump **Node to ≥ 22.12** and confirm your audience has modern browsers (see below).
 2. If your **custom CSS** uses `hsl(var(--maz-<color>))`, simplify to `var(--maz-<color>)`.
 3. Rename `import 'maz-ui/styles'` to `import 'maz-ui/style.css'` (and `maz-ui/aos-styles` → `maz-ui/aos.css`).
-4. Replace any `rounded-size="base"` with `rounded-size="md"` (or drop the prop — the new default is visually identical).
+4. Replace any `rounded-size="base"` with `rounded-size="md"` (or drop the prop - the new default is visually identical).
 5. Replace any **numeric `MazBadge` size** (`size="0.8rem"`, `size="1.2em"`, …) with one of the standardized keywords (`'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`).
-6. **`MazIcon` API simplified** — drop `name`, `path` and `src` props; use a single `icon` prop that accepts a Vue component, a URL/`data:` URI, or a raw SVG string.
-7. Rename **`left-icon` / `right-icon`** to **`start-icon` / `end-icon`** (and the matching slots / `--has-*-icon` classes) on `MazBtn`, `MazInput`, `MazLink`, `MazContainer`, `MazSelect`. Same idea for `MazCard`'s `footer-align` and `MazDrawer`'s `variant` — `'left' | 'right'` becomes `'start' | 'end'`.
-8. **`MazChart`** drops `vue-chartjs` (lighter bundle, no eager registration of unused chart types). The `update-mode` prop now defaults to `'none'` — pass `update-mode="default"` if you want animated data updates.
+6. **`MazIcon` API simplified** - drop `name`, `path` and `src` props; use a single `icon` prop that accepts a Vue component, a URL/`data:` URI, or a raw SVG string.
+7. Rename **`left-icon` / `right-icon`** to **`start-icon` / `end-icon`** (and the matching slots / `--has-*-icon` classes) on `MazBtn`, `MazInput`, `MazLink`, `MazContainer`, `MazSelect`. Same idea for `MazCard`'s `footer-align` and `MazDrawer`'s `variant` - `'left' | 'right'` becomes `'start' | 'end'`.
+8. **`MazChart`** drops `vue-chartjs` (lighter bundle, no eager registration of unused chart types). The `update-mode` prop now defaults to `'none'` - pass `update-mode="default"` if you want animated data updates.
 9. **`MazAvatar` size scale fixed.** A CSS-unit `size` now renders at its real value (`size="2rem"` is a 32px avatar, it was ~96px before). Multiply your unit values by 3 to keep the same render, or switch to a `MazSize` keyword (`'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`). The upgrade tool does the ×3 rewrite for you on static values.
 10. Rename **`MazPullToRefresh`**'s `on-click` prop to `on-refresh` (handled by the upgrade tool).
 11. Replace bare **`from 'maz-ui'`** utility imports with **`from '@maz-ui/utils'`** (the root re-export of utils was removed; handled by the upgrade tool). Components/composables/directives/plugins stay on their subpaths; types remain importable from `maz-ui`.
@@ -114,7 +121,7 @@ There is no polyfill path. If your audience still relies on older browsers, stay
 
 ### 1. `hsl(var(--maz-<color>))` → `var(--maz-<color>)` in your CSS
 
-The biggest — and usually only — change to chase down in your codebase.
+The biggest - and usually only - change to chase down in your codebase.
 
 **In v4** the CSS variables injected by `@maz-ui/themes` held raw HSL channels (`210 100% 56%`), so you had to wrap them yourself:
 
@@ -207,27 +214,27 @@ rg "rounded-?size\s*=\s*['\"]base['\"]" src/
 <MazIcon :icon="MazStar" />
 
 <!-- v5 -->
-<MazIcon icon="/home.svg" />            <!-- relative URL — `mazIconPath` is prepended in SSR -->
+<MazIcon icon="/home.svg" />            <!-- relative URL - `mazIconPath` is prepended in SSR -->
 <MazIcon icon="/icons/home.svg" />      <!-- absolute path -->
 <MazIcon icon="/assets/star.svg" />
 <MazIcon :icon="MazStar" />              <!-- unchanged -->
 ```
 
-The `mazIconPath` `provide` (and Nuxt's `mazUi.general.defaultMazIconPath`) is still honored — it now acts as a **base URL prefix** for relative URL icons, mainly useful in SSR where `fetch('/icons/home.svg')` cannot resolve without a host.
+The `mazIconPath` `provide` (and Nuxt's `mazUi.general.defaultMazIconPath`) is still honored - it now acts as a **base URL prefix** for relative URL icons, mainly useful in SSR where `fetch('/icons/home.svg')` cannot resolve without a host.
 
 New props:
 
-- `fallback` — same shape as `icon`. Used when `icon` is missing or fails to load. Defaults to `MazQuestionMarkCircle`.
-- `svg-attributes` — extra attributes injected onto the rendered `<svg>`.
-- `flip-icon-for-rtl` — mirror the icon horizontally when the document direction is RTL (useful for chevrons/arrows).
+- `fallback` - same shape as `icon`. Used when `icon` is missing or fails to load. Defaults to `MazQuestionMarkCircle`.
+- `svg-attributes` - extra attributes injected onto the rendered `<svg>`.
+- `flip-icon-for-rtl` - mirror the icon horizontally when the document direction is RTL (useful for chevrons/arrows).
 
 Removed:
 
 - `loaded` and `unloaded` events (only `error` remains, useful for telemetry/fallback wiring).
 
-The `<MazIcon>` rendering also got a small a11y polish — it sets `aria-hidden="true"` by default and switches to `role="img"` (without `aria-hidden`) automatically when an `aria-label` is provided.
+The `<MazIcon>` rendering also got a small a11y polish - it sets `aria-hidden="true"` by default and switches to `role="img"` (without `aria-hidden`) automatically when an `aria-label` is provided.
 
-### 5. New raw icon import path — `@maz-ui/icons/raw/*`
+### 5. New raw icon import path - `@maz-ui/icons/raw/*`
 
 Each bundled icon is now also exported as a **raw SVG string** under the `raw/` subpath. Pass it to `<MazIcon :icon="…" />` to inline the SVG without paying the cost of a Vue component or an async chunk.
 
@@ -242,14 +249,14 @@ import { MazStar } from '@maz-ui/icons/raw/MazStar'
 </template>
 ```
 
-The existing `static/` (eager Vue component) and `lazy/` (async Vue component) entries are still available — pick what fits the situation. See the [icons guide](./icons.md#raw-svg-strings-new-in-v5) for the full decision matrix.
+The existing `static/` (eager Vue component) and `lazy/` (async Vue component) entries are still available - pick what fits the situation. See the [icons guide](../ecosystem/icons/index.md#raw-svg-strings-new-in-v5) for the full decision matrix.
 
-### 6. Logical direction props — `left-icon`/`right-icon` → `start-icon`/`end-icon`
+### 6. Logical direction props - `left-icon`/`right-icon` → `start-icon`/`end-icon`
 
 To make components RTL-correct out of the box, every prop / slot / class that names a *visual* edge has been renamed to a *logical* edge:
 
 - **`left` / `right`** describe a physical position; they don't flip when `dir="rtl"`.
-- **`start` / `end`** follow the inline direction — `start` is the side where reading begins (left in LTR, right in RTL).
+- **`start` / `end`** follow the inline direction - `start` is the side where reading begins (left in LTR, right in RTL).
 
 This is consistent with native CSS (`margin-inline-start`, `padding-inline-end`, `text-align: start`) and with how design systems like Radix UI and MUI handle direction.
 
@@ -263,7 +270,7 @@ This is consistent with native CSS (`margin-inline-start`, `padding-inline-end`,
 | `MazContainer` | `left-icon` / `right-icon` props, `#icon-left` / `#icon-right` slots | `start-icon` / `end-icon` props, `#icon-start` / `#icon-end` slots |
 | `MazSelect` | `#left-icon` / `#right-icon` slots | `#start-icon` / `#end-icon` slots |
 | `MazCard` | `footer-align: 'left' \| 'right'` | `footer-align: 'start' \| 'end'` |
-| `MazDrawer` | `variant: 'left' \| 'right' \| 'top' \| 'bottom'` | `variant: 'start' \| 'end' \| 'top' \| 'bottom'` (`top` / `bottom` unchanged — physical) |
+| `MazDrawer` | `variant: 'left' \| 'right' \| 'top' \| 'bottom'` | `variant: 'start' \| 'end' \| 'top' \| 'bottom'` (`top` / `bottom` unchanged - physical) |
 
 `top` and `bottom` are intentionally kept (block-axis edges that don't flip in RTL).
 
@@ -295,9 +302,9 @@ If you target maz-ui's internal selectors from your own CSS, also rename:
 <MazDrawer variant="end" />
 ```
 
-::: warning Icon names
+**Warning: Icon names**
+
 In v4, a string icon prop (`left-icon="user"`) was an icon **name**, resolved to `${mazIconPath}/user.svg`. In v5, a string is a **URL** or a raw SVG: a bare name renders nothing. Use the URL of the same file (`start-icon="/user.svg"`, `mazIconPath` is still prepended to relative URLs) or an icon component. The `@maz-ui/upgrade` codemod rewrites the static values for you.
-:::
 
 ```bash
 # Quick search to chase down the renames
@@ -308,18 +315,18 @@ rg "(left|right)-icon|(left|right)Icon|footer-align=\"(left|right)\"|variant=\"(
 
 `MazBtn`, `MazInput`, `MazLink`, `MazContainer` and `MazDropdown` all forward their `start-icon` / `end-icon` / `icon` / `dropdown-icon` to an internal `<MazIcon>`. In v5 these props now accept either:
 
-1. **A bare value** — Vue component, URL/`data:` URI, or raw SVG string (the same shape `MazIcon`'s `icon` prop accepts). This is the existing common case.
-2. **A full `MazIconProps` object** — `{ icon, size, title, svgAttributes, fallback, flipIconForRtl }`. Useful when you need to override the inherited size, set a `<title>` for screen readers, or pass per-icon SVG attributes.
+1. **A bare value** - Vue component, URL/`data:` URI, or raw SVG string (the same shape `MazIcon`'s `icon` prop accepts). This is the existing common case.
+2. **A full `MazIconProps` object** - `{ icon, size, title, svgAttributes, fallback, flipIconForRtl }`. Useful when you need to override the inherited size, set a `<title>` for screen readers, or pass per-icon SVG attributes.
 
 ```vue
 <!-- v4 only accepted a bare value -->
 <MazBtn :left-icon="MazStar" />
 
-<!-- v5 — bare value still works -->
+<!-- v5 - bare value still works -->
 <MazBtn :start-icon="MazStar" />
 <MazBtn start-icon="/icons/star.svg" />
 
-<!-- v5 — full props object for fine-grained control -->
+<!-- v5 - full props object for fine-grained control -->
 <MazBtn
   size="sm"
   :start-icon="{
@@ -340,21 +347,21 @@ Falling back to passing `undefined` (or just omitting the prop) opts the icon ou
 What this means for you:
 
 - The peer dependency on `vue-chartjs` is gone. If you were importing anything from it directly, switch to `chart.js`.
-- The `update-mode` prop now **defaults to `'none'`** (previously `'default'`). Subsequent data / options changes no longer animate by default — this is what makes large dashboards stop freezing on prop updates. The initial render still animates per the chart's `options`. Pass `update-mode="default"` to restore the v4 behavior.
-- The re-exported types (`MazChartData`, `MazChartType`, `MazChartUpdateMode`, `MazChartPlugin`, `MazChartDefaultDataPoint`) are unchanged — they now come from `chart.js` instead of `vue-chartjs` but are otherwise the same. The `ChartProps` link in the v4 docs (which pointed to `vue-chartjs/src/types.ts`) is replaced by the `MazChartProps` interface documented on the [MazChart page](../components/maz-chart.md).
+- The `update-mode` prop now **defaults to `'none'`** (previously `'default'`). Subsequent data / options changes no longer animate by default - this is what makes large dashboards stop freezing on prop updates. The initial render still animates per the chart's `options`. Pass `update-mode="default"` to restore the v4 behavior.
+- The re-exported types (`MazChartData`, `MazChartType`, `MazChartUpdateMode`, `MazChartPlugin`, `MazChartDefaultDataPoint`) are unchanged - they now come from `chart.js` instead of `vue-chartjs` but are otherwise the same. The `ChartProps` link in the v4 docs (which pointed to `vue-chartjs/src/types.ts`) is replaced by the `MazChartProps` interface documented on the [MazChart page](../components/maz-chart.md).
 
 ```vue
-<!-- v4 — animated update on every data change -->
+<!-- v4 - animated update on every data change -->
 <MazChart :type :data :options />
 
-<!-- v5 — same call, but data updates skip animations by default -->
+<!-- v5 - same call, but data updates skip animations by default -->
 <MazChart :type :data :options />
 
-<!-- v5 — restore v4 animated updates -->
+<!-- v5 - restore v4 animated updates -->
 <MazChart :type :data :options update-mode="default" />
 ```
 
-If you weren't using `vue-chartjs` directly and were happy with the default animation behavior on every update, you can ignore this — only add `update-mode="default"` where the animation matters.
+If you weren't using `vue-chartjs` directly and were happy with the default animation behavior on every update, you can ignore this - only add `update-mode="default"` where the animation matters.
 
 ### 9. `MazBadge` `size` prop now uses `MazSize`
 
@@ -378,8 +385,8 @@ Approximate mapping if you want to preserve your previous footprint:
 | --- | --- |
 | ≤ 0.65rem (~10px) | `'mini'` |
 | 0.7rem (~11px) | `'xs'` |
-| 0.75–0.8rem (12px) | `'sm'` |
-| 0.85–0.9rem (~14px) | `'md'` (default) |
+| 0.75-0.8rem (12px) | `'sm'` |
+| 0.85-0.9rem (~14px) | `'md'` (default) |
 | 1rem (16px) | `'lg'` |
 | ≥ 1.125rem (18px) | `'xl'` |
 
@@ -390,15 +397,15 @@ The `@maz-ui/upgrade` codemod rewrites the static `rem` sizes to the closest key
 rg "MazBadge[^/]*size=\"[0-9]" src/
 ```
 
-If you really need a custom size, wrap or override via your own class — pass `size="md"` (or omit it) and apply a Tailwind text utility:
+If you really need a custom size, wrap or override via your own class - pass `size="md"` (or omit it) and apply a Tailwind text utility:
 
 ```vue
-<MazBadge size="md" class="maz:text-[0.7rem]" />
+<MazBadge size="md" class="text-[0.7rem]" />
 ```
 
-### 10. Theme preset rename — `background` → `surface`, `border` → `divider`
+### 10. Theme preset rename - `background` → `surface`, `border` → `divider`
 
-Preset keys now use the same names that components and Tailwind utilities have used all along. There is no compatibility alias — rename the keys in your custom preset.
+Preset keys now use the same names that components and Tailwind utilities have used all along. There is no compatibility alias - rename the keys in your custom preset.
 
 ```ts
 // v4
@@ -425,7 +432,7 @@ The runtime CSS variables follow:
 | `--maz-background[-N]` | `--maz-surface[-N]` |
 | `--maz-border[-N]` | `--maz-divider[-N]` |
 
-Tailwind utilities `maz:bg-surface`, `maz:text-surface-700`, `maz:border-divider` are stable — they pointed at these renamed vars even in v4 and continue to work.
+Tailwind utilities `bg-surface`, `text-surface-700`, `border-divider` are stable - they pointed at these renamed vars even in v4 and continue to work.
 
 ```bash
 # Find leftovers
@@ -468,7 +475,7 @@ The single foundation radius is replaced by a full radius scale. Move your value
 }
 ```
 
-The bridge maps every `--maz-rounded-{key}` to its matching Tailwind `--radius-{key}`, so `maz:rounded-md`, `maz:rounded-lg`, etc. all move with your preset.
+The bridge maps every `--maz-rounded-{key}` to its matching Tailwind `--radius-{key}`, so `rounded-md`, `rounded-lg`, etc. all move with your preset.
 
 ### 12. New optional preset blocks: `scales` and `components`
 
@@ -491,7 +498,7 @@ The bridge maps every `--maz-rounded-{key}` to its matching Tailwind `--radius-{
 }
 ```
 
-Both blocks are optional; the bundled presets ship with sensible defaults. New `foundation` keys also landed and are all optional: `font-mono`, `font-display`, `disabled-opacity`, `disabled-cursor`. See the [themes guide](./themes.md) for the full surface.
+Both blocks are optional; the bundled presets ship with sensible defaults. New `foundation` keys also landed and are all optional: `font-mono`, `font-display`, `disabled-opacity`, `disabled-cursor`. See the [themes guide](../ecosystem/themes.md) for the full surface.
 
 ### 13. Theme strategy: `'hybrid'` removed, no more critical CSS
 
@@ -499,10 +506,10 @@ The `@maz-ui/themes` rendering pipeline collapsed back to a single path: the ful
 
 What changed:
 
-- `Strategy` is now `'runtime' | 'buildtime'` — `'hybrid'` no longer exists. The runtime default is `'runtime'`.
+- `Strategy` is now `'runtime' | 'buildtime'` - `'hybrid'` no longer exists. The runtime default is `'runtime'`.
 - `MazUiTheme` plugin options no longer accept `injectCriticalCSS` / `injectFullCSS`.
 - `@maz-ui/nuxt`'s `theme` config no longer accepts `injectAllCSSOnServer`.
-- `generateCSS` / `buildThemeCSS` / `buildSeparateThemeFiles` no longer accept `onlyCritical`, `criticalColors`, `criticalFoundation`, or `includeColorScales`. `buildSeparateThemeFiles` now returns `{ full, lightOnly, darkOnly }` only — no more `critical`.
+- `generateCSS` / `buildThemeCSS` / `buildSeparateThemeFiles` no longer accept `onlyCritical`, `criticalColors`, `criticalFoundation`, or `includeColorScales`. `buildSeparateThemeFiles` now returns `{ full, lightOnly, darkOnly }` only - no more `critical`.
 
 What you need to do:
 
@@ -532,7 +539,7 @@ To keep first-paint clean, **pass the preset object** (not just a string name) s
 
 ### 14. Nuxt module: `mazUi.css.injectMainCss` → `mazUi.css.injectCss`
 
-The Nuxt module config key that toggles the global maz-ui stylesheet has been renamed. The old name is **silently ignored** — your app would build but ship without the maz-ui CSS — so update it.
+The Nuxt module config key that toggles the global maz-ui stylesheet has been renamed. The old name is **silently ignored** - your app would build but ship without the maz-ui CSS - so update it.
 
 ```diff
  export default defineNuxtConfig({
@@ -547,7 +554,7 @@ The Nuxt module config key that toggles the global maz-ui stylesheet has been re
 
 ### 15. `color="background"` → `color="surface"` on components
 
-The components that exposed `color="background"` in their public prop now use `color="surface"`. The visual result is identical — only the literal changes.
+The components that exposed `color="background"` in their public prop now use `color="surface"`. The visual result is identical - only the literal changes.
 
 | Component | v4 | v5 |
 | --- | --- | --- |
@@ -606,7 +613,7 @@ The upgrade tool rewrites static `size="<unit>"` values on `<MazAvatar>` automat
 rg "<MazAvatar[^>]*\bsize=" src/
 ```
 
-### 17. `MazPullToRefresh` — `on-click` → `on-refresh`
+### 17. `MazPullToRefresh` - `on-click` → `on-refresh`
 
 The callback prop of `MazPullToRefresh` was renamed from `on-click` to `on-refresh` to reflect what it actually does: it runs when the refresh is triggered on release, not on a click.
 
@@ -625,7 +632,7 @@ The upgrade tool rewrites this automatically on `<MazPullToRefresh>` tags (both
 rg "<MazPullToRefresh[^>]*\bon-?[Cc]lick" src/
 ```
 
-The component was also rewritten on top of the new [usePullToRefresh](./../composables/use-pull-to-refresh.md) composable. Behavior changes to check:
+The component was also rewritten on top of the new [usePullToRefresh](../composables/use-pull-to-refresh.md) composable. Behavior changes to check:
 
 - **The pull follows the scroll container.** It starts only when the closest scrollable ancestor (or `container-selector`, or the window) is at the top. In v4, only the window scroll was read, so a layout with a scrolling `<main>` refreshed in the middle of a list.
 - **`distance` is now the indicator distance after resistance** (default `80`, was `100` of raw finger movement). With the default `resistance` of `0.5`, the trigger needs about 160px of finger movement. Lower `distance` or raise `resistance` for a shorter gesture.
@@ -636,7 +643,7 @@ The component was also rewritten on top of the new [usePullToRefresh](./../compo
 
 ### 18. Root `maz-ui` import removed for utilities
 
-In v4, the bare `maz-ui` entry re-exported `@maz-ui/utils`, so you could write `import { sleep } from 'maz-ui'`. In v5 that root re-export is gone — import helpers from their package directly:
+In v4, the bare `maz-ui` entry re-exported `@maz-ui/utils`, so you could write `import { sleep } from 'maz-ui'`. In v5 that root re-export is gone - import helpers from their package directly:
 
 ```ts
 // v4
@@ -704,27 +711,27 @@ rg "from 'valibot'" src/
 
 ### Theme colors are now emitted as OKLCh
 
-`@maz-ui/themes` now ships its bundled presets (`mazUi`, `ocean`, `pristine`, `obsidian`, `nova`) in `oklch()` form, and the runtime CSS variables (`--maz-primary`, `--maz-primary-100`, …) therefore hold OKLCh colors. The 50–950 scale is derived in CSS via OKLCh relative color syntax — `oklch(from var(--maz-X) clamp(0, calc(l ± offset), 1) calc(c * mult) h)` — perceptually uniform, chroma-preserving, and live-reactive to base color overrides.
+`@maz-ui/themes` now ships its bundled presets (`mazUi`, `ocean`, `pristine`, `obsidian`, `nova`) in `oklch()` form, and the runtime CSS variables (`--maz-primary`, `--maz-primary-100`, …) therefore hold OKLCh colors. The 50-950 scale is derived in CSS via OKLCh relative color syntax - `oklch(from var(--maz-X) clamp(0, calc(l ± offset), 1) calc(c * mult) h)` - perceptually uniform, chroma-preserving, and live-reactive to base color overrides.
 
 This is **transparent for consumers**:
 
 - Components keep working unchanged.
-- Custom CSS using `var(--maz-<color>)` keeps working — `oklch()` is a regular CSS color.
+- Custom CSS using `var(--maz-<color>)` keeps working - `oklch()` is a regular CSS color.
 - `color-mix(in srgb, var(--maz-primary) 50%, transparent)` still works; `color-mix(in oklab, …)` will give you slightly better blending if you care.
-- Custom presets written in `hsl()`, `rgb()`, `#hex` or the legacy `'210 100% 56%'` form still parse — they get converted to OKLCh on the fly.
+- Custom presets written in `hsl()`, `rgb()`, `#hex` or the legacy `'210 100% 56%'` form still parse - they get converted to OKLCh on the fly.
 
 You only need to do something if you were:
 
-- **Reading the channel format** of a color from `--maz-*` in JS — the value used to be an `hsl(...)` string, it's now an `oklch(...)` string (and at runtime the base may resolve through `light-dark()`). Use `getComputedStyle(...).getPropertyValue(...)` and a CSS color parser if you need channels.
-- **Calling the legacy JS palette helpers** (`generateColorScale`, `adjustColorLightness`, `getContrastColor`, `parseHSL`) — these exports were removed in v5. See [BREAKING — removed exports](#breaking-removed-exports) for replacements.
+- **Reading the channel format** of a color from `--maz-*` in JS - the value used to be an `hsl(...)` string, it's now an `oklch(...)` string (and at runtime the base may resolve through `light-dark()`). Use `getComputedStyle(...).getPropertyValue(...)` and a CSS color parser if you need channels.
+- **Calling the legacy JS palette helpers** (`generateColorScale`, `adjustColorLightness`, `getContrastColor`, `parseHSL`) - these exports were removed in v5. See BREAKING - removed exports for replacements.
 
-Why the switch: OKLCh is perceptually uniform, so generated scales (`primary-50` → `primary-950`) ramp consistently across hues — yellow-700 won't look muddy compared to blue-700 anymore. It also unlocks Display P3 colors when you author a vivid preset.
+Why the switch: OKLCh is perceptually uniform, so generated scales (`primary-50` → `primary-950`) ramp consistently across hues - yellow-700 won't look muddy compared to blue-700 anymore. It also unlocks Display P3 colors when you author a vivid preset.
 
 ### Preset type: `HSL` → `CSSColor`
 
 If you authored a custom preset via `@maz-ui/themes`, the color field type is now the looser `CSSColor = string` instead of the template literal `HSL`.
 
-- Your existing raw values (`'210 100% 56%'`) keep working — they are auto-wrapped in `hsl(...)` at runtime by `normalizeColor`.
+- Your existing raw values (`'210 100% 56%'`) keep working - they are auto-wrapped in `hsl(...)` at runtime by `normalizeColor`.
 - You can now use any CSS color form: `'hsl(210 100% 56%)'`, `'#22c55e'`, `'oklch(0.7 0.15 30)'`, `'rgb(22 194 211)'`.
 - Type checking on custom colors is now permissive. If you want strict validation, keep using the raw HSL form or validate at your boundary.
 
@@ -738,7 +745,7 @@ Tailwind v4 changed the default `border` color from the configured gray to `curr
 
 Most visual regressions were caught during the migration, but keep an eye on:
 
-- Shadows, radius and blur scales — Tailwind v4 shifted a few names (`shadow` → `shadow-sm`, `blur` → `blur-sm`, etc.). Maz-ui components have been updated internally; your own code is affected only if you used these classes directly.
+- Shadows, radius and blur scales - Tailwind v4 shifted a few names (`shadow` → `shadow-sm`, `blur` → `blur-sm`, etc.). Maz-ui components have been updated internally; your own code is affected only if you used these classes directly.
 - `outline-none` → `outline-hidden` (same story).
 
 ### `nova` preset added, bundled palettes refreshed
@@ -747,27 +754,27 @@ Four bundled presets remain (`mazUi`, `pristine`, `ocean`, `obsidian`) plus a ne
 
 | Preset | Identity |
 | --- | --- |
-| `pristine` | Sober Apple — near-black primary, system blue accent, system purple secondary, SF system font, Apple spring easing. |
-| `ocean` | Calm water — teal primary, deep navy secondary, sandy ochre accent. |
-| `obsidian` | Dark luxe — indigo primary, gold accent, fuchsia secondary, snappy expo easing. |
-| `nova` | Modern AI — electric violet primary, cyan accent, hot coral secondary. |
+| `pristine` | Sober Apple - near-black primary, system blue accent, system purple secondary, SF system font, Apple spring easing. |
+| `ocean` | Calm water - teal primary, deep navy secondary, sandy ochre accent. |
+| `obsidian` | Dark luxe - indigo primary, gold accent, fuchsia secondary, snappy expo easing. |
+| `nova` | Modern AI - electric violet primary, cyan accent, hot coral secondary. |
 
 Switching to one of the bundled presets does not require any code change beyond the preset name. If you depended on the previous (washed-out gray) `secondary` color in a custom theme, override it back via `colors.{light,dark}.secondary` in your preset.
 
-### Theming: native CSS rewrite (new — non-breaking by default)
+### Theming: native CSS rewrite (new - non-breaking by default)
 
 The `@maz-ui/themes` CSS pipeline was rewritten to lean on native CSS instead of JS:
 
 - Base colors are now emitted as a single `--maz-X: light-dark(L, D)` declaration. The browser resolves it for you.
 - Color scales `--maz-X-50` through `--maz-X-950` are derived via OKLCh relative color syntax at runtime, so any override on the base color cascades through the whole scale automatically (and preserves its chroma).
 - `:root` declares `color-scheme: light dark` so native widgets (scrollbars, native `<select>`, date pickers, autofill) follow the active mode out of the box.
-- A `<meta name="color-scheme">` tag is **automatically injected** at boot (Vue + Nuxt SSR). No user action — prevents the Flash of inAccurate coloR Theme.
+- A `<meta name="color-scheme">` tag is **automatically injected** at boot (Vue + Nuxt SSR). No user action - prevents the Flash of inAccurate coloR Theme.
 
 Consumer-visible CSS surface is unchanged: `var(--maz-primary)`, `--maz-primary-500`, Tailwind utilities `bg-primary/60`, `bg-primary-500`, etc. all keep working.
 
-#### `lightClass` (new — optional, default `'light'`)
+#### `lightClass` (new - optional, default `'light'`)
 
-Mirror of `darkClass`. When `colorMode === 'light'` and `darkModeStrategy === 'class'`, this class is added to `<html>` to force `color-scheme: only light`. Default `'light'` — set to `false`/custom string if it clashes with an existing class in your app:
+Mirror of `darkClass`. When `colorMode === 'light'` and `darkModeStrategy === 'class'`, this class is added to `<html>` to force `color-scheme: only light`. Default `'light'` - set to `false`/custom string if it clashes with an existing class in your app:
 
 ```ts
 app.use(MazUi, {
@@ -783,26 +790,26 @@ Non-breaking: if you never explicitly forced light, nothing changes.
 
 #### `setColorMode` / `toggleDarkMode` now return `Promise<void>`
 
-Both functions are now async to support the optional `{ animate: true }` parameter (View Transitions). Existing callers that ignored the return value keep working — `await` is only required when you need to chain.
+Both functions are now async to support the optional `{ animate: true }` parameter (View Transitions). Existing callers that ignored the return value keep working - `await` is only required when you need to chain.
 
 ```ts
 const { setColorMode, toggleDarkMode } = useTheme()
 
-// Existing v4 call — still works, return value ignored
+// Existing v4 call - still works, return value ignored
 setColorMode('dark')
 toggleDarkMode()
 
-// v5 — await to chain after the change is applied
+// v5 - await to chain after the change is applied
 await setColorMode('dark')
 
-// v5 — animated full-page switch via document.startViewTransition()
+// v5 - animated full-page switch via document.startViewTransition()
 await toggleDarkMode({ animate: true })
 await setColorMode('dark', { animate: true })
 ```
 
-The View Transitions glue is lazy-imported — when `animate` is not used, it stays out of your boot bundle. Browsers that don't support the API apply the change immediately with no animation.
+The View Transitions glue is lazy-imported - when `animate` is not used, it stays out of your boot bundle. Browsers that don't support the API apply the change immediately with no animation.
 
-#### BREAKING — removed exports
+#### BREAKING - removed exports
 
 The JS-based palette generator is gone. The following helpers used to be exported from `@maz-ui/themes` and **no longer exist** in v5:
 
@@ -817,11 +824,11 @@ The JS-based palette generator is gone. The following helpers used to be exporte
 
 If you were importing any of the removed helpers from `@maz-ui/themes`, replace them before upgrading.
 
-### Preset name persistence (new — opt-out, no breaking change)
+### Preset name persistence (new - opt-out, no breaking change)
 
-`@maz-ui/themes` now persists the active preset name in a `maz-preset` cookie (1-year TTL, `SameSite=Lax`) — same shape as the existing `maz-color-mode` cookie:
+`@maz-ui/themes` now persists the active preset name in a `maz-preset` cookie (1-year TTL, `SameSite=Lax`) - same shape as the existing `maz-color-mode` cookie:
 
-- The cookie is read at boot and **takes priority over `options.preset`** — even when `options.preset` is a preset object. `options.preset` (string or object) is the default the app boots with; the cookie carries the user's last explicit choice and wins.
+- The cookie is read at boot and **takes priority over `options.preset`** - even when `options.preset` is a preset object. `options.preset` (string or object) is the default the app boots with; the cookie carries the user's last explicit choice and wins.
 - It is written after every successful preset resolution and after every `useTheme().updateTheme()` call.
 - If the saved name no longer resolves, the cookie is cleared and the runtime falls back to `options.preset` (or default).
 
@@ -838,27 +845,27 @@ The same option is exposed in the Nuxt module config under `mazUi.theme.persistP
 
 ## Troubleshooting
 
-**Colors look wrong in devtools — I see `hsl(hsl(...))` somewhere.**
+**Colors look wrong in devtools - I see `hsl(hsl(...))` somewhere.**
 You still have `hsl(var(--maz-<color>))` in your CSS. See the required change above.
 
 **A maz-ui component's border is a weird color.**
 Expected if you were overriding `--maz-divider` (renamed from `--maz-border` in v5) with a non-color value. Confirm it's a valid CSS color.
 
 **My custom preset's colors are ignored.**
-Check the preset's type — if you imported `HSL` explicitly, switch to `CSSColor` (or just remove the type annotation). Raw HSL strings still work at runtime.
+Check the preset's type - if you imported `HSL` explicitly, switch to `CSSColor` (or just remove the type annotation). Raw HSL strings still work at runtime.
 
 ## Advanced: you had your own Tailwind setup
 
 If you were already running Tailwind v3 in your app, shipping classes like `maz-flex` yourself, you need the same migration as any Tailwind v3 → v4 upgrade:
 
-1. Run the official Tailwind upgrade tool: `npx @tailwindcss/upgrade` — it handles 95% of the work (utility renames, `@apply !important` syntax, `tailwind.config` → CSS-first, …).
+1. Run the official Tailwind upgrade tool: `npx @tailwindcss/upgrade` - it handles 95% of the work (utility renames, `@apply !important` syntax, `tailwind.config` → CSS-first, …).
 2. Replace any `hsl(var(--maz-<color>))` in your own CSS (see above).
 3. Read the [Tailwind integration](./tailwind.md) page to learn how to import maz-ui's bridge and expose your theme tokens to your own Tailwind config.
 
-This is a niche path — most consumers never wrote maz-prefixed classes in their own code.
+This is a niche path - most consumers never wrote maz-prefixed classes in their own code.
 
 ## See also
 
-- [Tailwind CSS integration](./tailwind.md) — optional, for consumers who have their own Tailwind setup
-- [Theming](./themes.md) — preset authoring and runtime theme switching
-- [Browser Support](./browser-support.md) — exact minimum versions and the features they enable
+- [Tailwind CSS integration](./tailwind.md) - optional, for consumers who have their own Tailwind setup
+- [Theming](../ecosystem/themes.md) - preset authoring and runtime theme switching
+- [Browser Support](./browser-support.md) - exact minimum versions and the features they enable