@maz-ui/mcp 5.0.1-beta.0 → 5.1.0-beta.1

package/docs/{src/ecosystem → ecosystem}/themes.md

@@ -1,13 +1,19 @@
 ---
-title: Theming
-description: Modern and performant theme system for Maz-UI built on native CSS features (light-dark(), color-scheme, color-mix(in oklch)) for v5.
+title: "Theming"
+description: "Modern and performant theme system for Maz-UI built on native CSS features (light-dark(), color-scheme, color-mix(in oklch)) for v5."
+package: "@maz-ui/themes"
+url: "https://maz-ui.com/ecosystem/themes"
 ---
 
-# {{ $frontmatter.title }}
+# Theming
 
-Modern and performant theme system for Maz-UI built on native CSS features (`light-dark()`, `color-scheme`, `color-mix(in oklch)`) for v5.
+> Modern and performant theme system for Maz-UI built on native CSS features (light-dark(), color-scheme, color-mix(in oklch)) for v5.
+
+- Package: `@maz-ui/themes`
+- Import: `import { definePreset, useTheme } from '@maz-ui/themes'` or `import { mazUi } from '@maz-ui/themes/presets/mazUi'`
+- Web: https://maz-ui.com/ecosystem/themes
 
-<NpmBadge package="@maz-ui/themes"></NpmBadge>
+Modern and performant theme system for Maz-UI built on native CSS features (`light-dark()`, `color-scheme`, `color-mix(in oklch)`) for v5.
 
 ## Features
 
@@ -15,7 +21,7 @@ Modern and performant theme system for Maz-UI built on native CSS features (`lig
 - **Native widget theming** - `color-scheme` makes scrollbars, native `<select>`, date pickers and autofill follow the active mode automatically
 - **Animated theme switch** - Optional full-page View Transitions via `setColorMode(..., { animate: true })`
 - **Anti-FART** - `<meta name="color-scheme">` injected at boot to prevent any Flash of inAccurate coloR Theme (no setup needed)
-- **Automatic color scales** - `--maz-X-50` through `--maz-X-950` derived via OKLCh relative color syntax — perceptually uniform and chroma-preserving
+- **Automatic color scales** - `--maz-X-50` through `--maz-X-950` derived via OKLCh relative color syntax - perceptually uniform and chroma-preserving
 - **Performance Strategies** - Runtime injection or build-time generation according to your needs
 - **Strict TypeScript** - Complete types for perfect DX
 - **Zero FOUC** - Pass the preset object up front; the full CSS is injected synchronously on first paint
@@ -23,7 +29,7 @@ Modern and performant theme system for Maz-UI built on native CSS features (`lig
 
 ## Theme Editor
 
-Create your own theme with the [Theme Editor](./../theme-editor.md).
+Create your own theme with the Theme Editor.
 
 ## Quick Usage
 
@@ -55,9 +61,9 @@ app.use(MazUi, {
 })
 ```
 
-::: tip Alternative: MazUiProvider
+**Tip: Alternative: MazUiProvider**
+
 You can also initialize the theme via the [`MazUiProvider`](../guide/maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped themes.
-:::
 
 ### 2. Setup your CSS to support theme foundation and dark mode
 
@@ -80,9 +86,9 @@ const { toggleDarkMode, isDark, updateTheme } = useTheme()
 </script>
 
 <template>
-  <div class="maz:bg-surface maz:text-foreground">
+  <div class="bg-surface text-foreground">
     <button
-      class="maz:rounded-md maz:bg-primary maz:text-primary-foreground"
+      class="rounded-md bg-primary text-primary-foreground"
       @click="toggleDarkMode"
     >
       {{ isDark ? '☀️' : '🌙' }} Toggle theme
@@ -95,21 +101,21 @@ const { toggleDarkMode, isDark, updateTheme } = useTheme()
 
 - `preset`: The theme preset to use
 - `overrides` (optional): Override specific parts of the theme
-- `strategy` (optional, default `'runtime'`): The rendering strategy to use — `'runtime' | 'buildtime'`
-- `darkModeStrategy` (optional, default `'class'`): The dark mode strategy — `'class' | 'media'`, only if you use mode `both`
-- `mode` (optional, default `'both'`): The supported color modes — `'light' | 'dark' | 'both'`
-- `colorMode` (optional, default `'auto'`): The initial color mode — `'light' | 'dark' | 'auto'` (only if mode is `'both'`)
+- `strategy` (optional, default `'runtime'`): The rendering strategy to use - `'runtime' | 'buildtime'`
+- `darkModeStrategy` (optional, default `'class'`): The dark mode strategy - `'class' | 'media'`, only if you use mode `both`
+- `mode` (optional, default `'both'`): The supported color modes - `'light' | 'dark' | 'both'`
+- `colorMode` (optional, default `'auto'`): The initial color mode - `'light' | 'dark' | 'auto'` (only if mode is `'both'`)
 - `darkClass` (optional, default `'dark'`): Class added to `<html>` when `colorMode === 'dark'`
-- `lightClass` (optional, default `'light'`): Class added to `<html>` when `colorMode === 'light'` — mirror of `darkClass`
+- `lightClass` (optional, default `'light'`): Class added to `<html>` when `colorMode === 'light'` - mirror of `darkClass`
 - `persistPreset` (optional, default `true`): Persist the active preset name in the `maz-preset` cookie so it is restored on reload.
 
 ### Preset persistence
 
-When `persistPreset` is enabled (default), `@maz-ui/themes` stores the resolved preset name in a `maz-preset` cookie (1-year TTL, `SameSite=Lax`) — exactly like `maz-color-mode` for the dark/light state. The cookie is:
+When `persistPreset` is enabled (default), `@maz-ui/themes` stores the resolved preset name in a `maz-preset` cookie (1-year TTL, `SameSite=Lax`) - exactly like `maz-color-mode` for the dark/light state. The cookie is:
 
-- **Read at boot** and used to resolve the active preset — even when `options.preset` is provided. `options.preset` (string name **or** preset object) is treated as the *default* the app boots with, while the cookie carries the user's last explicit choice. The cookie wins.
-- **Written** after every successful preset resolution and after every `useTheme().updateTheme()` call (idempotent — no write if the value already matches).
-- **Auto-cleared** when the saved name no longer resolves (e.g. typo, preset removed in a downgrade) — the runtime falls back to `options.preset` (or default) and clears the cookie silently.
+- **Read at boot** and used to resolve the active preset - even when `options.preset` is provided. `options.preset` (string name **or** preset object) is treated as the *default* the app boots with, while the cookie carries the user's last explicit choice. The cookie wins.
+- **Written** after every successful preset resolution and after every `useTheme().updateTheme()` call (idempotent - no write if the value already matches).
+- **Auto-cleared** when the saved name no longer resolves (e.g. typo, preset removed in a downgrade) - the runtime falls back to `options.preset` (or default) and clears the cookie silently.
 
 Custom preset names are stored exactly like bundled ones: `@maz-ui/themes` does not maintain a whitelist. Switch the option off to disable any cookie read/write:
 
@@ -165,85 +171,12 @@ async function forceDark() {
 ```
 
 - Wraps the switch in `document.startViewTransition()` so the browser captures a snapshot of the page before/after and crossfades between them.
-- The View Transition glue is **lazy-imported** — when `animate` is not used, it stays out of the boot bundle.
+- The View Transition glue is **lazy-imported** - when `animate` is not used, it stays out of the boot bundle.
 - **Graceful degradation:** in browsers that don't support the API, the change is applied immediately with no animation (no error thrown).
 
 ## Interactive Demo
 
-<ComponentDemo title="Real-time theme control">
-  <div class="demo-theme-controls">
-    <div class="maz:space-y-4">
-      <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4">
-        <MazBtn color="primary">Primary Button</MazBtn>
-        <MazBtn color="secondary">Secondary Button</MazBtn>
-        <MazBtn color="success">Success Button</MazBtn>
-        <MazBtn color="warning">Warning Button</MazBtn>
-      </div>
-      <div class="theme-controls maz:space-y-4">
-        <div class="maz:flex maz:flex-col maz:gap-4">
-          <label class="maz:text-sm maz:font-medium">Color Mode: {{ colorMode }}</label>
-          <div class="maz:flex maz:gap-2">
-            <MazBtn
-              size="sm"
-              :color="colorMode === 'light' ? 'primary' : 'contrast'"
-              @click="setColorMode('light')"
-            >
-              ☀️ Light
-            </MazBtn>
-            <MazBtn
-              size="sm"
-              :color="colorMode === 'dark' ? 'primary' : 'contrast'"
-              @click="setColorMode('dark')"
-            >
-              🌙 Dark
-            </MazBtn>
-            <MazBtn
-              size="sm"
-              :color="colorMode === 'auto' ? 'primary' : 'contrast'"
-              @click="setColorMode('auto')"
-            >
-              🔄 Auto
-            </MazBtn>
-          </div>
-        </div>
-        <div class="maz:space-y-2">
-          <label class="maz:text-sm maz:font-medium">Preset:</label>
-          <div class="maz:flex maz:gap-2">
-            <MazBtn
-              size="sm"
-              :color="presetName === 'maz-ui' ? 'primary' : 'contrast'"
-              @click="updateTheme('maz-ui')"
-            >
-              Maz-UI
-            </MazBtn>
-            <MazBtn
-              size="sm"
-              :color="presetName === 'ocean' ? 'primary' : 'contrast'"
-              @click="updateTheme('ocean')"
-            >
-              Ocean
-            </MazBtn>
-            <MazBtn
-              size="sm"
-              :color="presetName === 'pristine' ? 'primary' : 'contrast'"
-              @click="updateTheme('pristine')"
-            >
-              Pristine
-            </MazBtn>
-            <MazBtn
-              size="sm"
-              :color="presetName === 'obsidian' ? 'primary' : 'contrast'"
-              @click="updateTheme('obsidian')"
-            >
-              Obsidian
-            </MazBtn>
-          </div>
-        </div>
-      </div>
-    </div>
-  </div>
-
-<template #code>
+**Real-time theme control**
 
 ```vue
 <script setup>
@@ -254,16 +187,16 @@ const { presetName, updateTheme, colorMode, setColorMode } = useTheme()
 
 <template>
   <div class="demo-theme-controls">
-    <div class="maz:space-y-4">
-      <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4">
+    <div class="space-y-4">
+      <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
         <MazBtn color="primary">Primary Button</MazBtn>
         <MazBtn color="secondary">Secondary Button</MazBtn>
         <MazBtn color="success">Success Button</MazBtn>
         <MazBtn color="warning">Warning Button</MazBtn>
       </div>
-      <div class="theme-controls maz:space-y-4">
-        <div class="maz:flex maz:items-center maz:gap-4">
-          <label class="maz:text-sm maz:font-medium">Mode:</label>
+      <div class="theme-controls space-y-4">
+        <div class="flex items-center gap-4">
+          <label class="text-sm font-medium">Mode:</label>
           <MazBtn
             size="sm"
             :color="colorMode === 'light' ? 'primary' : 'secondary'"
@@ -286,9 +219,9 @@ const { presetName, updateTheme, colorMode, setColorMode } = useTheme()
             🔄 Auto
           </MazBtn>
         </div>
-        <div class="maz:space-y-2">
-          <label class="maz:text-sm maz:font-medium">Preset:</label>
-          <div class="maz:flex maz:gap-2">
+        <div class="space-y-2">
+          <label class="text-sm font-medium">Preset:</label>
+          <div class="flex gap-2">
             <MazBtn
               size="sm"
               :color="presetName === 'maz-ui' ? 'primary' : 'secondary'"
@@ -325,9 +258,6 @@ const { presetName, updateTheme, colorMode, setColorMode } = useTheme()
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Available Presets
 
 ### Maz-UI (Default)
@@ -364,7 +294,7 @@ import { obsidian } from '@maz-ui/themes/presets'
 
 ### Nova
 
-A modern startup / AI / creative preset — electric violet primary, hot coral secondary, cyan accent. Tight 0.5rem `md` radius, Geist + Inter font stack, snappy ease-out spring. Built for product / AI surfaces (think Linear, Vercel, OpenAI energy) where the UI itself should feel alive.
+A modern startup / AI / creative preset - electric violet primary, hot coral secondary, cyan accent. Tight 0.5rem `md` radius, Geist + Inter font stack, snappy ease-out spring. Built for product / AI surfaces (think Linear, Vercel, OpenAI energy) where the UI itself should feel alive.
 
 ```typescript
 import { nova } from '@maz-ui/themes/presets'
@@ -374,7 +304,7 @@ import { nova } from '@maz-ui/themes/presets'
 
 ### ⚡ Runtime (Recommended)
 
-CSS is generated and injected synchronously on first paint. Pass the preset object directly (`preset: mazUi`) so the full stylesheet is rendered before the first frame — no FOUC.
+CSS is generated and injected synchronously on first paint. Pass the preset object directly (`preset: mazUi`) so the full stylesheet is rendered before the first frame - no FOUC.
 
 ```typescript
 import { mazUi } from '@maz-ui/themes/presets'
@@ -392,7 +322,7 @@ app.use(MazUi, {
 CSS generated at build-time and included in the bundle.
 You have to build your CSS files before running your app.
 
-See [Build-time](#build-time-strategy-complete-guide) for more details.
+See Build-time for more details.
 
 ```typescript
 import { mazUi } from '@maz-ui/themes/presets'
@@ -409,26 +339,7 @@ app.use(MazUi, {
 
 ### Basic Theme
 
-<br />
-
-<ComponentDemo title="Create your own theme">
-  <MazBtn @click="applyCustomTheme" color="info">
-    Apply Custom Theme
-  </MazBtn>
-  <MazBtn @click="resetTheme" color="secondary" class="maz:ms-2">
-    Reset
-  </MazBtn>
-
-  <div class="maz:mt-4 maz:p-4 maz:bg-primary/10 maz:rounded-md">
-    <p v-if="presetName === 'custom-purple'" class="maz:text-primary maz:font-medium">
-      Custom theme applied with purple colors!
-    </p>
-    <p v-else class="maz:text-primary maz:font-medium">
-      Default theme
-    </p>
-  </div>
-
-<template #code>
+**Create your own theme**
 
 ```typescript
 import { definePreset, MazUiTheme, type ThemePresetOverrides, ocean } from '@maz-ui/themes'
@@ -478,9 +389,6 @@ const { updateTheme } = useTheme()
 updateTheme(customTheme)
 ```
 
-  </template>
-</ComponentDemo>
-
 ### Advanced Theme with Overrides
 
 ```typescript
@@ -517,7 +425,7 @@ const brandTheme = await definePreset({
 
 ### Customizing scales
 
-Each `ThemeScales` entry maps to a Tailwind utility — override the keys you care about and the rest stays untouched:
+Each `ThemeScales` entry maps to a Tailwind utility - override the keys you care about and the rest stays untouched:
 
 ```typescript
 const denseTheme = definePreset({
@@ -525,7 +433,7 @@ const denseTheme = definePreset({
   overrides: {
     name: 'dense',
     foundation: {
-      // Tighter spacing — every p-N / gap-N / m-N rescales
+      // Tighter spacing - every p-N / gap-N / m-N rescales
       space: '0.2rem',
     },
     scales: {
@@ -579,7 +487,7 @@ const surfaceTheme = definePreset({
         'font-weight': '600',
       },
       container: {
-        // Cards / dialogs / popovers / drawers — light = page surface, dark = a tier above
+        // Cards / dialogs / popovers / drawers - light = page surface, dark = a tier above
         bg: { light: 'var(--maz-surface)', dark: 'var(--maz-surface-300)' },
       },
       input: {
@@ -591,11 +499,11 @@ const surfaceTheme = definePreset({
 })
 ```
 
-Components consume these via `maz:bg-container` / `maz:bg-input` Tailwind utilities, so a single override propagates everywhere — no per-component class hunt.
+Components consume these via `bg-container` / `bg-input` Tailwind utilities, so a single override propagates everywhere - no per-component class hunt.
 
 ### Dialog sizing
 
-`components.dialog` controls the width of [`MazDialog`](./../components/maz-dialog.md) on tablet and up. The two keys are emitted as `--maz-dialog-max-width` / `--maz-dialog-min-width` and consumed by the component through `var(--maz-dialog-max-width, 38rem)` / `var(--maz-dialog-min-width, 32rem)`:
+`components.dialog` controls the width of [`MazDialog`](../components/maz-dialog.md) on tablet and up. The two keys are emitted as `--maz-dialog-max-width` / `--maz-dialog-min-width` and consumed by the component through `var(--maz-dialog-max-width, 38rem)` / `var(--maz-dialog-min-width, 32rem)`:
 
 ```typescript
 const wideDialogTheme = definePreset({
@@ -621,7 +529,7 @@ const {
   // Reactive state
   preset, // ComputedRef<ThemePreset>
   presetName, // ComputedRef<string>
-  colorMode, // Ref<'light' | 'dark' | 'auto'> — also accepts assignment (computed setter)
+  colorMode, // Ref<'light' | 'dark' | 'auto'> - also accepts assignment (computed setter)
   isDark, // ComputedRef<boolean>
   strategy, // ComputedRef<'runtime' | 'buildtime'>
   mode, // ComputedRef<'light' | 'dark' | 'both'>
@@ -636,14 +544,14 @@ const {
 // Set the color mode imperatively
 await setColorMode('dark')
 
-// Or assign to `colorMode` — it's a computed with a setter
+// Or assign to `colorMode` - it's a computed with a setter
 colorMode.value = 'dark'
 
 // Animated full-page switch via View Transitions
 await toggleDarkMode({ animate: true })
 ```
 
-`setColorMode` and `toggleDarkMode` are **async** (`Promise<void>`). The promise resolves once the change — and the optional View Transition — has been applied. Callers can ignore the return value when no transition is needed.
+`setColorMode` and `toggleDarkMode` are **async** (`Promise<void>`). The promise resolves once the change - and the optional View Transition - has been applied. Callers can ignore the return value when no transition is needed.
 
 ### Advanced Usage Examples
 
@@ -682,8 +590,6 @@ The build-time strategy allows you to generate your theme CSS files at compile t
 
 #### 1. Generate CSS
 
-::: code-group
-
 ```typescript [Vue]
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -832,8 +738,6 @@ export default defineConfig({
 })
 ```
 
-:::
-
 #### 2. Include in your HTML (Only for Vue users)
 
 ```html
@@ -877,7 +781,7 @@ const files = buildSeparateThemeFiles(preset)
 
 #### `createThemeStylesheet(css, options)`
 
-Creates a `<style>
+Creates a `
 @reference "../../.vitepress/theme/main.css";
 ` tag with the provided CSS.
 
@@ -904,7 +808,7 @@ const styleTag = createThemeStylesheet(css, {
 
 ## Token Reference
 
-Every preset emits the same set of CSS variables on `:root`. With `mode: 'both'`, each base color is a single `light-dark(L, D)` declaration that the browser resolves to the active scheme. Use these names directly in your own CSS — `var(--maz-primary)`, `calc(var(--maz-space) * 4)`, etc.
+Every preset emits the same set of CSS variables on `:root`. With `mode: 'both'`, each base color is a single `light-dark(L, D)` declaration that the browser resolves to the active scheme. Use these names directly in your own CSS - `var(--maz-primary)`, `calc(var(--maz-space) * 4)`, etc.
 
 ### Foundation
 
@@ -914,9 +818,9 @@ Single-value design tokens. Set via `foundation.<key>` on the preset.
 | --- | --- | --- | --- |
 | `base-font-size` | `--maz-base-font-size` | `14px` | Anchors `rem` for the whole app. Apply on `html { font-size: var(--maz-base-font-size) }`. |
 | `border-width` | `--maz-border-width` | `1px` | Default border for components and the global `*::before/::after` reset. |
-| `space` | `--maz-space` | `0.25rem` | Base step for every Tailwind spacing utility (`maz:p-1`, `maz:gap-2`, …). |
+| `space` | `--maz-space` | `0.25rem` | Base step for every Tailwind spacing utility (`p-1`, `gap-2`, …). |
 | `font-family` | `--maz-font-family` | preset-specific | Sans / body font stack. Bridged to Tailwind `--font-sans`. |
-| `font-mono-stack` | `--maz-font-mono-stack` | `ui-monospace, …` | Monospace stack — `MazInputCode`, `<code>`, `<kbd>`. Bridged to `--font-mono`. |
+| `font-mono-stack` | `--maz-font-mono-stack` | `ui-monospace, …` | Monospace stack - `MazInputCode`, `<code>`, `<kbd>`. Bridged to `--font-mono`. |
 | `font-display-stack` | `--maz-font-display-stack` | same as `font-family` | Display / heading stack. Bridged to `--font-display`. |
 | `motion-fast` | `--maz-motion-fast` | `100ms` | Bridged to Tailwind `--duration-fast`. |
 | `motion-normal` | `--maz-motion-normal` | `200ms` | Default transition duration (`--default-transition-duration`). |
@@ -931,28 +835,28 @@ Single-value design tokens. Set via `foundation.<key>` on the preset.
 
 ### Colors
 
-Defined per mode under `colors.light` / `colors.dark`. Each base color also gets an automatic 50–950 scale.
+Defined per mode under `colors.light` / `colors.dark`. Each base color also gets an automatic 50-950 scale.
 
 | Preset key | CSS variable (base) | Auto scale | Notes |
 | --- | --- | --- | --- |
 | `surface` | `--maz-surface` | `--maz-surface-50..900` | Page / container background. |
 | `foreground` | `--maz-foreground` | `--maz-foreground-50..900` | Default text color. |
 | `primary` | `--maz-primary` | `--maz-primary-50..900` | Brand color. |
-| `primary-foreground` | `--maz-primary-foreground` | — | Text on `bg-primary`. |
+| `primary-foreground` | `--maz-primary-foreground` | - | Text on `bg-primary`. |
 | `secondary` | `--maz-secondary` | `--maz-secondary-50..900` | |
-| `secondary-foreground` | `--maz-secondary-foreground` | — | |
+| `secondary-foreground` | `--maz-secondary-foreground` | - | |
 | `accent` | `--maz-accent` | `--maz-accent-50..900` | |
-| `accent-foreground` | `--maz-accent-foreground` | — | |
-| `info` | `--maz-info` | `--maz-info-50..900` | Status — informational. |
-| `info-foreground` | `--maz-info-foreground` | — | |
-| `success` | `--maz-success` | `--maz-success-50..900` | Status — success. |
-| `success-foreground` | `--maz-success-foreground` | — | |
-| `warning` | `--maz-warning` | `--maz-warning-50..900` | Status — warning. |
-| `warning-foreground` | `--maz-warning-foreground` | — | |
-| `destructive` | `--maz-destructive` | `--maz-destructive-50..900` | Status — error / danger. |
-| `destructive-foreground` | `--maz-destructive-foreground` | — | |
+| `accent-foreground` | `--maz-accent-foreground` | - | |
+| `info` | `--maz-info` | `--maz-info-50..900` | Status - informational. |
+| `info-foreground` | `--maz-info-foreground` | - | |
+| `success` | `--maz-success` | `--maz-success-50..900` | Status - success. |
+| `success-foreground` | `--maz-success-foreground` | - | |
+| `warning` | `--maz-warning` | `--maz-warning-50..900` | Status - warning. |
+| `warning-foreground` | `--maz-warning-foreground` | - | |
+| `destructive` | `--maz-destructive` | `--maz-destructive-50..900` | Status - error / danger. |
+| `destructive-foreground` | `--maz-destructive-foreground` | - | |
 | `contrast` | `--maz-contrast` | `--maz-contrast-50..900` | High-contrast accent (light = near-black, dark = near-white). |
-| `contrast-foreground` | `--maz-contrast-foreground` | — | |
+| `contrast-foreground` | `--maz-contrast-foreground` | - | |
 | `divider` | `--maz-divider` | `--maz-divider-50..900` | Default border / separator color. |
 | `muted` | `--maz-muted` | `--maz-muted-50..900` | Muted / secondary text. |
 | `overlay` | `--maz-overlay` | `--maz-overlay-50..900` | Backdrop / dialog scrim. |
@@ -964,14 +868,14 @@ Multi-step scales under `scales.<key>`.
 
 | Preset key | CSS variables | Tailwind utility |
 | --- | --- | --- |
-| `rounded.xs..3xl` | `--maz-rounded-xs..3xl` | `maz:rounded-{key}` (bridged to `--radius-{key}`) |
-| `shadow.{sm, md, lg, xl, elevation}` | `--maz-shadow-style-{key}` | `maz:shadow-{key}` (bridged to `--shadow-{key}`) |
+| `rounded.xs..3xl` | `--maz-rounded-xs..3xl` | `rounded-{key}` (bridged to `--radius-{key}`) |
+| `shadow.{sm, md, lg, xl, elevation}` | `--maz-shadow-style-{key}` | `shadow-{key}` (bridged to `--shadow-{key}`) |
 
 > Same naming-collision avoidance as foundation: `rounded.*` (instead of `radius.*`) and `shadow-style-*` (instead of plain `shadow-*`) keep the bridge cycle-free under `prefix(maz)`.
 
 ### Components
 
-Per-component knobs under `components.<key>`. All optional — omit to fall back to the surface tokens.
+Per-component knobs under `components.<key>`. All optional - omit to fall back to the surface tokens.
 
 | Preset key | CSS variable | Notes |
 | --- | --- | --- |
@@ -989,13 +893,13 @@ Each base color is emitted as a `light-dark()` value; scales `--maz-X-50` throug
 :root {
   color-scheme: light dark;
 
-  /* Base colors — one declaration each, resolved by the browser */
+  /* Base colors - one declaration each, resolved by the browser */
   --maz-primary: light-dark(oklch(0.65 0.19 254), oklch(0.72 0.18 254));
   --maz-primary-foreground: light-dark(oklch(1 0 0), oklch(0.16 0.01 254));
   --maz-surface: light-dark(oklch(1 0 0), oklch(0.18 0.01 254));
   --maz-foreground: light-dark(oklch(0.26 0.01 254), oklch(0.96 0.005 254));
 
-  /* Auto-generated 50–950 scale — derived via relative color syntax */
+  /* Auto-generated 50-950 scale - derived via relative color syntax */
   --maz-primary-500: var(--maz-primary);
   --maz-primary-600: oklch(from var(--maz-primary) clamp(0, calc(l - 0.07), 1) c h);
   /* ... */
@@ -1012,24 +916,21 @@ Each base color is emitted as a `light-dark()` value; scales `--maz-X-50` throug
   --maz-shadow-style-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), …;
 }
 
-/* With darkModeStrategy: 'class' — explicit user choice overrides the system */
+/* With darkModeStrategy: 'class' - explicit user choice overrides the system */
 .dark  { color-scheme: only dark; }
 .light { color-scheme: only light; }
 ```
 
 For deeper detail on the generated CSS contract, see the [`@maz-ui/themes` README](https://github.com/LouisMazel/maz-ui/tree/master/packages/themes#generated-css-variables).
 
-
 ## Usage with Nuxt
 
-For Nuxt users, check the [dedicated Nuxt documentation](/ecosystem/nuxt) which covers installation and framework-specific configuration.
+For Nuxt users, check the [dedicated Nuxt documentation](./nuxt.md) which covers installation and framework-specific configuration.
 
 ## Migration from Legacy System
 
 If you're using the legacy theme system with CLI:
 
-::: code-group
-
 ```typescript [Before (CLI)]
 // maz-ui.config.ts
 export default defineConfig({
@@ -1062,68 +963,4 @@ const myTheme = definePreset({
 app.use(MazUiTheme, { preset: myTheme })
 ```
 
-:::
-
 The new system offers much more flexibility and performance!
-
-<script setup>
-import { useTheme } from '@maz-ui/themes/composables/useTheme'
-import { definePreset } from '@maz-ui/themes'
-import { ref } from 'vue'
-
-const {
-  isDark,
-  colorMode,
-  preset,
-  setColorMode,
-  updateTheme,
-  presetName
-} = useTheme()
-
-const originalPresetName = ref(null)
-
-const customPreset = await definePreset({
-  base: 'pristine',
-  overrides: {
-    name: 'custom-purple',
-    colors: {
-      light: {
-        'primary': 'oklch(0.62 0.24 305)',
-        'secondary': 'oklch(0.94 0.04 320)',
-        'accent': 'oklch(0.7 0.22 290)'
-      },
-      dark: {
-        'primary': 'oklch(0.72 0.22 305)',
-        'secondary': 'oklch(0.28 0.06 320)',
-        'accent': 'oklch(0.78 0.2 290)'
-      }
-    }
-  }
-})
-
-function applyCustomTheme() {
-  if (!originalPresetName.value) {
-    originalPresetName.value = presetName.value
-  }
-
-  updateTheme(customPreset)
-}
-
-function resetTheme() {
-  if (originalPresetName.value) {
-    updateTheme(originalPresetName.value)
-    originalPresetName.value = null
-  }
-}
-</script>
-
-<style scoped>
-@reference "../../.vitepress/theme/main.css";
-.demo-theme-controls {
-  @apply maz:w-full;
-}
-
-.theme-controls {
-  @apply maz:border-t maz:border-divider maz:pt-4;
-}
-</style>

package/docs/{src/ecosystem → ecosystem}/translations.md

@@ -1,13 +1,17 @@
 ---
-title: Translations (i18n)
-description: Internationalization for Maz-UI components.
+title: "Translations (i18n)"
+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"
 ---
 
-# {{ $frontmatter.title }}
+# Translations (i18n)
 
-{{ $frontmatter.description }}
+> Internationalization of the maz-ui components with @maz-ui/translations: built-in locales, custom messages, lazy loading and runtime locale switching with useTranslations
 
-<NpmBadge package="@maz-ui/translations"></NpmBadge>
+- Package: `@maz-ui/translations`
+- Import: `import { useTranslations } from '@maz-ui/translations'` or `import { fr } from '@maz-ui/translations'`
+- Web: https://maz-ui.com/ecosystem/translations
 
 ## ✨ Features
 
@@ -37,27 +41,25 @@ Maz-UI includes default translations for **8 languages** ready to use out of the
 
 All these languages include translations for:
 
-- 📱 **InputPhoneNumber** ([`MazInputPhoneNumber`](/components/maz-input-phone-number))
-- 📁 **Dropzone** ([`MazDropzone`](/components/maz-dropzone))
-- 📅 **DatePicker** ([`MazDatePicker`](/components/maz-date-picker))
-- 📋 **Checklist** ([`MazChecklist`](/components/maz-checklist))
-- 📤 **Dropdown** ([`MazDropdown`](/components/maz-dropdown))
-- 🔍 **Select** ([`MazSelect`](/components/maz-select))
-- 🗂️ **Table** ([`MazTable`](/components/maz-table))
-- 📄 **Pagination** ([`MazPagination`](/components/maz-pagination))
-- 🎠 **Carousel** ([`MazCarousel`](/components/maz-carousel))
-- 🌍 **SelectCountry** ([`MazSelectCountry`](/components/maz-select-country))
+- 📱 **InputPhoneNumber** ([`MazInputPhoneNumber`](../components/maz-input-phone-number.md))
+- 📁 **Dropzone** ([`MazDropzone`](../components/maz-dropzone.md))
+- 📅 **DatePicker** ([`MazDatePicker`](../components/maz-date-picker.md))
+- 📋 **Checklist** ([`MazChecklist`](../components/maz-checklist.md))
+- 📤 **Dropdown** ([`MazDropdown`](../components/maz-dropdown.md))
+- 🔍 **Select** ([`MazSelect`](../components/maz-select.md))
+- 🗂️ **Table** ([`MazTable`](../components/maz-table.md))
+- 📄 **Pagination** ([`MazPagination`](../components/maz-pagination.md))
+- 🎠 **Carousel** ([`MazCarousel`](../components/maz-carousel.md))
+- 🌍 **SelectCountry** ([`MazSelectCountry`](../components/maz-select-country.md))
 
 ### Basic Usage
 
-::: warning
+**Warning:**
 
 **By default Maz-UI will not load any translations to avoid unused code in your bundle.**
 
 So, to avoid loading hydration issues or any flashes, use the `messages` option to provide the translations for the language you want to use. Otherwise, the translations will be loaded asynchronously.
 
-:::
-
 ```typescript
 import { fr } from '@maz-ui/translations'
 
@@ -72,9 +74,9 @@ app.use(MazUi, {
 })
 ```
 
-::: tip Alternative: MazUiProvider
+**Tip: Alternative: MazUiProvider**
+
 You can also provide translations via the [`MazUiProvider`](../guide/maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped configurations.
-:::
 
 ## How it works
 
@@ -181,9 +183,9 @@ app.use(MazUi, {
 
 ## Enhanced Lazy Loading
 
-::: tip BUILT-IN FEATURE
+**Tip: BUILT-IN FEATURE**
+
 All supported languages (fr, es, de, it, pt, ja, zh-CN) are automatically loaded lazily. You don't need to configure anything to benefit from this.
-:::
 
 The Maz-UI translation system natively supports **lazy loading**, a powerful feature to optimize your application's performance.
 
@@ -296,7 +298,7 @@ app.use(MazUi, {
 
 ### Create your translation files
 
-Check the [all translations keys](#all-translations-keys) section to see all available keys.
+Check the all translations keys section to see all available keys.
 
 Create separate files for each language: