@maz-ui/mcp 5.0.0-beta.1 → 5.0.0-beta.11

package/docs/src/components/maz-timeline.md

@@ -9,6 +9,21 @@ description: MazTimeline is a step/progress timeline component for Vue 3 with su
 
 <!--@include: ./../../.vitepress/mixins/getting-started.md-->
 
+---
+
+Control the current step:
+
+<MazRadioButtons
+  :model-value="currentStep"
+  size="sm"
+  :options="[
+    { label: 'None', value: -1 },
+    ...steps.map((step, index) => ({ label: index, value: index })),
+    { label: 'All Completed', value: 99 },
+  ]"
+  @update:model-value="currentStep = $event"
+/>
+
 ## Basic usage
 
 <ComponentDemo>
@@ -292,6 +307,40 @@ Customize the indicator border radius with the `rounded-size` prop.
   </template>
 </ComponentDemo>
 
+## Custom Icons
+
+<ComponentDemo>
+  <MazTimeline :model-value="0" :steps="iconsSteps" direction="horizontal" size="lg" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazTimeline
+    v-model="currentStep"
+    :steps="steps"
+    size="lg"
+  />
+</template>
+
+<script lang="ts" setup>
+  import { MazCommandLine } from '@maz-ui/icons/MazCommandLine'
+  import { MazClipboardDocumentList } from '@maz-ui/icons/MazClipboardDocumentList'
+  import { MazClipboardDocumentCheck } from '@maz-ui/icons/MazClipboardDocumentCheck'
+  import { MazComputerDesktop } from '@maz-ui/icons/MazComputerDesktop'
+
+  const iconsSteps = [
+    { title: 'PO', subtitle: 'Writing PRD', icon: MazClipboardDocumentList },
+    { title: 'Dev', subtitle: 'Building Code', icon: MazCommandLine },
+    { title: 'Tech Lead', subtitle: 'Review Code', icon: MazComputerDesktop },
+    { title: 'QA', subtitle: 'Testing', icon: MazClipboardDocumentCheck },
+  ]
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
 ## Custom slots
 
 MazTimeline provides scoped slots for full customization.
@@ -378,6 +427,10 @@ MazTimeline provides scoped slots for full customization.
 
 <script lang="ts" setup>
   import { ref } from 'vue'
+  import { MazComputerDesktop } from '@maz-ui/icons/MazComputerDesktop'
+  import { MazCommandLine } from '@maz-ui/icons/MazCommandLine'
+  import { MazClipboardDocumentList } from '@maz-ui/icons/MazClipboardDocumentList'
+  import { MazClipboardDocumentCheck } from '@maz-ui/icons/MazClipboardDocumentCheck'
 
   const currentStep = ref(1)
   const clickableStep = ref(0)
@@ -410,6 +463,13 @@ MazTimeline provides scoped slots for full customization.
     { title: 'Complete', subtitle: 'All done!' },
   ]
 
+  const iconsSteps = [
+    { title: 'PO', subtitle: 'Writing PRD', icon: MazClipboardDocumentList },
+    { title: 'Dev', subtitle: 'Building Code', icon: MazCommandLine },
+    { title: 'Tech Lead', subtitle: 'Review Code', icon: MazComputerDesktop },
+    { title: 'QA', subtitle: 'Testing', icon: MazClipboardDocumentCheck },
+  ]
+
   const colors = ['primary', 'secondary', 'info', 'success', 'warning', 'destructive']
   const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
   const roundedSizes = ['full', 'lg', 'md', 'sm', 'none']

package/docs/src/components/maz-window-mockup.md

@@ -0,0 +1,249 @@
+---
+title: MazWindowMockup
+description: MazWindowMockup renders a macOS-style window frame in three variants — browser, terminal, and editor — to showcase content, demos, or code examples in your documentation or UI.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+<!--@include: ./../../.vitepress/mixins/getting-started.md-->
+
+::: info Optional: shiki for code variants
+When you pass the `code` prop, `MazWindowMockup` mounts `MazCodeHighlight` internally for syntax highlighting. This requires the [`shiki`](https://shiki.style) optional peer dependency to be installed. See the [MazCodeHighlight installation note](/components/maz-code-highlight#installation-requirement).
+:::
+
+## Browser variant
+
+The default variant. Displays an address bar with the `url` prop and a copy-URL button on the right side of the bar.
+
+<ComponentDemo>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <div style="padding: 1rem; text-align: center;">Browser content goes here</div>
+  </MazWindowMockup>
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <div>Browser content goes here</div>
+  </MazWindowMockup>
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+### Hide the URL copy button
+
+Set `:hide-url-copy="true"` to remove the copy-URL button from the title bar.
+
+<ComponentDemo>
+  <MazWindowMockup url="https://maz-ui.com" min-height="80px" :hide-url-copy="true" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="80px" :hide-url-copy="true" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+### With screenshot
+
+Use this variant to display a screenshot of a website.
+
+<ComponentDemo>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <img :src="screenshot" alt="Maz UI Demo Dashboard" width="100%">
+  </MazWindowMockup>
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <img src="/img/screenshots/maz-ui-home-desktop.webp" alt="Maz UI Demo Dashboard" width="100%">
+  </MazWindowMockup>
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Terminal variant
+
+Displays a centered title and a `$` prompt prefix in front of the code (when `code` is provided). The prompt prefix is **not** copied to the clipboard — the copy button only writes the raw `code` value.
+
+<ComponentDemo>
+  <MazWindowMockup variant="terminal" title="zsh" code="pnpm add maz-ui" language="bash" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup variant="terminal" title="zsh" code="pnpm add maz-ui" language="bash" />
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+### Custom prompt
+
+Replace the default `$` with any character via the `prompt` prop.
+
+<ComponentDemo>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" prompt="❯" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" prompt="❯" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+### Without prompt
+
+Hide the default prompt by setting `hide-prompt` to `true`.
+
+<ComponentDemo>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" :hide-prompt="true" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" :hide-prompt="true" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Editor variant
+
+Shows a filename tab anchored to the bottom of the title bar — matching the look of real editors like VSCode.
+
+<ComponentDemo>
+  <MazWindowMockup variant="editor" filename="App.vue" :code="vueCode" language="vue" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup variant="editor" filename="App.vue" :code="vueCode" language="vue" />
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+
+  const vueCode = `<template>
+  <MazBtn>Click me</MazBtn>
+</template>`
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## With code and language props
+
+Pass `code` and `language` to display highlighted source code via `MazCodeHighlight`. The inner highlighter automatically renders with squared corners so it sits flush against the window's border.
+
+<ComponentDemo>
+  <MazWindowMockup code="import MazBtn from 'maz-ui/components/MazBtn'" language="ts" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup code="import MazBtn from 'maz-ui/components/MazBtn'" language="ts" />
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Empty-state placeholder
+
+When neither `code` nor a slot content is provided, the content area renders an empty placeholder. Pass the optional `label` prop to display a centered text inside it.
+
+<ComponentDemo>
+  <MazWindowMockup url="https://maz-ui.com" min-height="160px" label="Preview" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="160px" label="Preview" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Custom translations
+
+The URL copy button's aria-label and tooltip come from the `@maz-ui/translations` package (`windowMockup.copyUrlToClipboard` / `windowMockup.urlCopiedToClipboard`). Override per-instance with the `translations` prop:
+
+<ComponentDemo>
+  <MazWindowMockup
+    url="https://maz-ui.com"
+    min-height="80px"
+    :translations="{ copyUrlToClipboard: 'Copier l\'URL', urlCopiedToClipboard: 'URL copiée !' }"
+  />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup
+    url="https://maz-ui.com"
+    min-height="80px"
+    :translations="{
+      copyUrlToClipboard: 'Copier l\'URL',
+      urlCopiedToClipboard: 'URL copiée !',
+    }"
+  />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+For app-wide translations, set up the [maz-ui translations plugin](/translations) and the component will pick up your locale automatically.
+
+<script lang="ts" setup>
+  import screenshot from './../assets/interface-screenshot.png'
+
+  const vueCode = `<template>
+  <MazBtn>Click me</MazBtn>
+</template>`
+</script>
+
+<!--@include: ./../../.vitepress/generated-docs/maz-window-mockup.doc.md-->

package/docs/src/directives/click-outside.md

@@ -11,8 +11,7 @@ description: vClickOutside is a Vue directive to trigger a function when the use
 
 <ComponentDemo>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="clikedOutside">
       Click outside me
@@ -21,8 +20,7 @@ description: vClickOutside is a Vue directive to trigger a function when the use
 
   <div
     v-if="hasClikedOutside"
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-success); color: black;"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:bg-sucess maz:text-success-foreground maz:p-4 maz:mt-4"
   >
     You clicked outside
   </div>
@@ -44,8 +42,7 @@ function clikedOutside() {
 
 <template>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="flex flex-center rounded"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="clikedOutside">
       Click outside me
@@ -54,8 +51,7 @@ function clikedOutside() {
 
   <div
     v-if="hasClikedOutside"
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-success); color: black;"
-    class="flex flex-center rounded"
+    class="maz:flex maz:flex-center maz:rounded-md maz:bg-sucess maz:text-success-foreground maz:p-4 maz:mt-4"
   >
     You clicked outside
   </div>
@@ -71,8 +67,7 @@ The directive can accept an options object to customize its behavior:
 
 <ComponentDemo>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="{ callback: clickedOutsideWithIgnore, ignore: ['.ignore-me'] }">
       <div class="maz:p-4">
@@ -86,8 +81,7 @@ The directive can accept an options object to customize its behavior:
 
   <div
     v-if="hasClickedOutsideWithIgnore"
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-warning); color: black;"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:bg-sucess maz:text-success-foreground maz:p-4 maz:mt-4"
   >
     You clicked outside (button clicks are ignored)
   </div>
@@ -128,8 +122,7 @@ The directive can be configured to trigger only once:
 
 <ComponentDemo>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="{ callback: clickedOnce, once: true }">
       Click outside me (works only once)

package/docs/src/directives/lazy-img.md

@@ -10,7 +10,7 @@ description: vLazyImg is a Vue directive to lazy load images with many options.
 ## Basic usage
 
 <img
-  style="background-color: var(--maz-surface-300); width: 80%;"
+  style="background-color: var(--maz-color-surface-300); width: 80%;"
   class="flex flex-center rounded"
   v-lazy-img="'https://placedog.net/1500/1000'"
 />
@@ -23,7 +23,7 @@ import { vLazyImg } from 'maz-ui/directives'
 <template>
   <img
     v-lazy-img="'https://placedog.net/1500/1000'"
-    style="background-color: var(--maz-surface-300); width: 80%;"
+    style="background-color: var(--maz-color-surface-300); width: 80%;"
     class="flex flex-center rounded"
   >
 </template>
@@ -54,7 +54,7 @@ import { vLazyImg } from 'maz-ui/directives'
 > Open the developer console to show logs
 
 <img
-  style="background-color: var(--maz-surface-300); width: 80%;"
+  style="background-color: var(--maz-color-surface-300); width: 80%;"
   class="flex flex-center rounded"
   v-lazy-img="lazyBinding"
 />
@@ -83,7 +83,7 @@ const lazyBinding: vLazyImgBindingValue = {
 <template>
   <img
     v-lazy-img="lazyBinding"
-    style="background-color: var(--maz-surface-300); width: 80%;"
+    style="background-color: var(--maz-color-surface-300); width: 80%;"
     class="flex flex-center rounded"
   >
 </template>

package/docs/src/ecosystem/eslint-config.md

@@ -114,6 +114,8 @@ defineConfig({
     detectComponentClasses: true,
     // Monorepo: directory used to resolve `tailwindcss` and the config file.
     cwd: 'apps/web',
+    // Custom `maz/tailwind-no-arbitrary-px` rule — see "Custom rules" below.
+    noArbitraryPx: true,
   },
 })
 ```
@@ -135,12 +137,98 @@ defineConfig({
 
 The plugin recognizes the most common class-name utilities out of the box (`clsx`, `cn`, `tw-merge`, `cva`, `tv`, …); see the [plugin docs](https://github.com/schoero/eslint-plugin-better-tailwindcss) for the full list and how to register your own.
 
+## Custom rules
+
+`@maz-ui/eslint-config` ships its own ESLint plugin under the **`maz/*`** namespace. Rules are grouped by category — `maz/tailwind-*` today, with room for `maz/js-*` and others as they get added.
+
+### `maz/tailwind-no-arbitrary-px`
+
+Forbids `px` units inside Tailwind arbitrary value classes (`w-[16px]`, `m-[-16px]`, `[gap:24px]`, …) and **autofixes** them to `rem` (or `em`) using your project's root font-size. Whitespace inside brackets (e.g. `[up to 100px]`) is left alone, so plain prose is never rewritten by accident.
+
+::: info Registered only when `tailwindcss` is enabled
+The `maz` plugin and the `maz/tailwind-*` rules are only added to the flat-config when `tailwindcss` is set to anything other than `false`. With `tailwindcss: false` *(default)*, neither the plugin nor the rule appear in the resolved config — keeping the preset zero-cost for non-Tailwind projects. To use the rule without opting into the full Tailwind preset, register `mazPlugin` manually (see [Use the plugin directly](#use-the-plugin-directly)).
+:::
+
+When `tailwindcss` is on, the rule is enabled with defaults. You can tune it two ways:
+
+**Standard ESLint override** *(idiomatic, max control)*
+
+```ts
+defineConfig({
+  tailwindcss: 'recommended',
+  rules: {
+    'maz/tailwind-no-arbitrary-px': ['error', { baseFontSize: 10, unit: 'em' }],
+  },
+})
+```
+
+User `rules` overrides are applied in a *trailing* flat-config block, so they win over the defaults wired in by `tailwindcssConfigs`.
+
+**Ergonomic shortcut** *(set defaults via `tailwindcss.noArbitraryPx`)*
+
+```ts
+defineConfig({
+  tailwindcss: {
+    preset: 'recommended',
+    noArbitraryPx: {
+      baseFontSize: 16, // default — divide px by this to get rem
+      unit: 'rem', // default — output unit ('rem' | 'em')
+      severity: 'error', // default — 'off' | 'warn' | 'error'
+    },
+  },
+})
+```
+
+| `noArbitraryPx` value              | Behavior                                            |
+| ---------------------------------- | --------------------------------------------------- |
+| `true` *(default)*                 | Enabled with defaults (`baseFontSize: 16`, `rem`).  |
+| `false`                            | Disabled.                                           |
+| `{ baseFontSize, unit, severity }` | Override any subset of the defaults.                |
+
+If both are set, the standard `rules` override wins (it's the last block applied).
+
+What the autofix does (with `baseFontSize: 16`):
+
+| Before                  | After                    |
+| ----------------------- | ------------------------ |
+| `w-[16px]`              | `w-[1rem]`               |
+| `m-[-16px]`             | `m-[-1rem]`              |
+| `tracking-[.5px]`       | `tracking-[0.03125rem]`  |
+| `p-[16px_8px]`          | `p-[1rem_0.5rem]`        |
+| `[gap:24px]`            | `[gap:1.5rem]`           |
+| `w-[calc(100%-16px)]`   | `w-[calc(100%-1rem)]`    |
+| `md:hover:w-[16px]`     | `md:hover:w-[1rem]`      |
+
+The rule fires on:
+
+- JSX `className` strings and template literals
+- Vue SFC static `class="…"` attributes (via `vue-eslint-parser`)
+- Vue dynamic `:class` bindings, including string literals inside arrays / objects
+- Function-call arguments and tagged template literals (`clsx`, `cn`, `cva`, `tw`, …)
+
+### Use the plugin directly
+
+If you don't want the full Tailwind preset (or just prefer wiring rules yourself), import `mazPlugin` and register it in your own flat-config block. This is also the way to use `maz/tailwind-*` rules **without** enabling `tailwindcss` in `defineConfig`:
+
+```ts
+import { mazPlugin } from '@maz-ui/eslint-config'
+
+export default [{
+  files: ['**/*.{ts,tsx,vue}'],
+  plugins: { maz: mazPlugin },
+  rules: {
+    'maz/tailwind-no-arbitrary-px': ['error', { baseFontSize: 16, unit: 'rem' }],
+  },
+}]
+```
+
 ## What it includes
 
 - **Antfu base** — TypeScript-aware rules, Stylistic formatting, modern import order.
 - **SonarJS** — code quality and complexity heuristics, with a relaxed set for `*.spec.ts` / `*.test.ts`.
 - **Vue rules** (when Vue/Nuxt is detected) — block-tag order, naming conventions, template a11y.
 - **Tailwind plugin** (opt-in) — class ordering, duplicate / deprecated / unknown / conflicting class detection — see [Tailwind support](#tailwind-support).
+- **`maz/*` custom rules** — namespaced ESLint plugin shipped with the preset; see [Custom rules](#custom-rules).
 - **Markdown** — prose linting baseline.
 - **vueAccessibility** (opt-in) — `eslint-plugin-vuejs-accessibility` rules with the AudioWorklet globals fix.
 
@@ -151,6 +239,7 @@ The plugin recognizes the most common class-name utilities out of the box (`clsx
 ```ts
 import {
   baseRules,
+  mazPlugin,
   sonarjsRules,
   tailwindcssConfigs,
   vueRules,
@@ -158,14 +247,19 @@ import {
 
 export default [
   {
+    plugins: { maz: mazPlugin },
     rules: {
       ...baseRules(true), // production = true → no-console: 'error'
       ...sonarjsRules,
       ...vueRules,
+      'maz/tailwind-no-arbitrary-px': 'error',
     },
   },
   // Drop in just the Tailwind block, with whatever preset and settings you want.
-  ...tailwindcssConfigs('stylistic', { entryPoint: 'src/main.css' }),
+  ...tailwindcssConfigs('stylistic', {
+    entryPoint: 'src/main.css',
+    noArbitraryPx: { unit: 'em' },
+  }),
 ]
 ```
 

package/docs/src/guide/getting-started.md

@@ -93,8 +93,9 @@ npm install @maz-ui/themes
 
 **Features:**
 
-- 🎨 OKLCh color system with perceptually uniform 11-step scales
-- 🌓 Smart dark mode detection and class/media/auto strategies
+- 🎨 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
@@ -163,15 +164,6 @@ npm install @maz-ui/icons
 Maz-UI v5 is built with tree-shaking in mind. Import only what you need for optimal bundle sizes:
 
 ```typescript
-/**
- * Utilities
- */
-
-// ❌ Avoid importing everything
-import { formatCurrency, debounce } from '@maz-ui/utils'
-// ✅ Import from @maz-ui/utils
-import { formatCurrency, debounce } from '@maz-ui/utils'
-
 /**
  * Components
  */
@@ -215,6 +207,16 @@ import { vClickOutside } from 'maz-ui/directives/vClickOutside'
 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

package/docs/src/guide/maz-ui-provider.md

@@ -97,12 +97,15 @@ The entire Maz-UI setup is now code-split into the Dashboard chunk.
 
 ```typescript
 interface ThemeOptions {
-  preset: ThemePreset              // Required - Theme preset (mazUi, ocean, pristine, obsidian, or custom)
-  overrides?: ThemePresetOverrides // Partial overrides for colors, foundation, etc.
-  strategy?: 'runtime' | 'buildtime' // CSS generation strategy (default: 'runtime')
+  preset: ThemePreset                            // Required - Theme preset (mazUi, ocean, pristine, obsidian, nova, or custom)
+  overrides?: ThemePresetOverrides               // Partial overrides for colors, foundation, etc.
+  strategy?: 'runtime' | 'buildtime'             // CSS generation strategy (default: 'runtime')
   darkModeStrategy?: 'class' | 'media'           // Dark mode handling (default: 'class')
   colorMode?: 'light' | 'dark' | 'auto'          // Initial color mode (default: 'auto')
   mode?: 'light' | 'dark' | 'both'               // Supported color modes (default: 'both')
+  darkClass?: string                             // Class on <html> when colorMode === 'dark' (default: 'dark')
+  lightClass?: string                            // Class on <html> when colorMode === 'light' (default: 'light')
+  persistPreset?: boolean                        // Persist active preset in cookie (default: true)
 }
 ```
 

package/docs/src/guide/migration-v4.md

@@ -41,6 +41,10 @@ v4.0.0 isn't just an update, it's a **complete rebuild** that transforms Maz-UI
 - **Dynamic CSS Variables**: Automatic CSS variable generation
 - **Intelligent dark mode**: Configurable strategies for dark mode based on system preferences and user choice stored in cookies
 
+::: tip Theming further evolved in v5
+The theme system has been rewritten on top of native `light-dark()` + `color-scheme` + `color-mix(in oklch)` in v5. If you are upgrading past v4, see the dedicated [v5 migration guide](./migration-v5.md#theming-native-css-rewrite-new-non-breaking-by-default) for the full theming changes (new `lightClass`, `Promise<void>` returns, removed JS helpers).
+:::
+
 #### Complete Internationalization
 
 - **9 supported languages by default**: EN, FR, DE, ES, IT, PT, JA, ZH-CN
@@ -688,12 +692,12 @@ app.use(MazUi, {
 <script setup>
 import { useTheme } from 'maz-ui/composables'
 
-const { isDark, toggleDarkMode, setTheme } = useTheme()
+const { isDark, toggleDarkMode, updateTheme } = useTheme()
 
 // Change theme
-setTheme('ocean')
+updateTheme('ocean')
 
-// Toggle dark mode
+// Toggle dark mode (v5: returns Promise<void>, optional { animate } param)
 toggleDarkMode()
 </script>