@maz-ui/mcp 5.0.0-beta.6 → 5.0.0-beta.9

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/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>
 

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

@@ -23,7 +23,7 @@ npx @maz-ui/upgrade ./ --dry-run
 npx @maz-ui/upgrade ./
 ```
 
-It rewrites: CSS subpath imports (`maz-ui/styles` → `maz-ui/style.css`), `left-icon`/`right-icon` → `start-icon`/`end-icon` (props, slots, `--has-*-icon` classes), `footer-align`/`variant` direction values, `color="background"` / `active-color="background"` → `surface`, `rounded-size="base"` → `md`, `--maz-background` / `--maz-border` CSS vars → `--maz-surface` / `--maz-divider`, `hsl(var(--maz-X))` collapse, Nuxt `injectMainCss` → `injectCss`, theme `strategy: 'hybrid'` → `'runtime'`, drops the removed theme options (`injectCriticalCSS`, `injectFullCSS`, `injectAllCSSOnServer`), and renames `colors.{light,dark}.background` → `surface` / `.border` → `divider` inside custom presets. It also bumps every `maz-ui` and `@maz-ui/*` entry in your `package.json` files to `^5.0.0` and runs the right `<pm> install` for you (detected from your lockfile — pnpm, yarn, bun, npm). Pass `--no-install` if you want to skip the install step.
+It handles the mechanical part of the migration (CSS subpath imports, prop renames, CSS var renames, Nuxt config keys, custom preset color keys, and `package.json` version bumps)
 
 What it can't decide for you: the `MazIcon` API simplification (section 4), `MazBadge` numeric size mapping (section 9), `foundation.radius` → `scales.rounded.md` reshape (section 11) and `MazChart` `update-mode` defaults (section 8). Those are best handled with the MCP server below.
 
@@ -557,7 +557,7 @@ rg "color\s*=\s*['\"]background['\"]" src/
 
 ### Theme colors are now emitted as OKLCh
 
-`@maz-ui/themes` now ships its bundled presets (`mazUi`, `ocean`, `pristine`, `obsidian`) in `oklch()` form, and the dynamic color scale generator (`generateColorScale`, `adjustColorLightness`, `getContrastColor`) steps in OKLCh space and emits `oklch(L C H)` strings. The runtime CSS variables (`--maz-primary`, `--maz-primary-100`, …) therefore hold OKLCh colors.
+`@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**:
 
@@ -568,16 +568,8 @@ This is **transparent for consumers**:
 
 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. Use `getComputedStyle(...).getPropertyValue(...)` and a CSS color parser if you need channels.
-- **Calling `adjustColorLightness`** directly — the `adjustment` parameter is now in OKLCh L units (`0..1`) instead of HSL L percentage (`0..100`). Divide your existing values by 100.
-
-```ts
-// v4: HSL L percentage
-adjustColorLightness('hsl(210 50% 40%)', 20)  // → 'hsl(210 50% 60%)'
-
-// v5: OKLCh L (0..1)
-adjustColorLightness('hsl(210 50% 40%)', 0.2) // → 'oklch(0.65 0.108 232.62)'
-```
+- **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.
 
 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.
 
@@ -615,6 +607,69 @@ Four bundled presets remain (`mazUi`, `pristine`, `ocean`, `obsidian`) plus a ne
 
 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)
+
+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.
+
+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'`)
+
+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, {
+  theme: {
+    preset: mazUi,
+    darkClass: 'dark',
+    lightClass: 'light', // new
+  },
+})
+```
+
+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.
+
+```ts
+const { setColorMode, toggleDarkMode } = useTheme()
+
+// Existing v4 call — still works, return value ignored
+setColorMode('dark')
+toggleDarkMode()
+
+// v5 — await to chain after the change is applied
+await setColorMode('dark')
+
+// 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.
+
+#### 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:
+
+| Removed export | Replacement |
+| --- | --- |
+| `generateColorScale(base, mode)` | The scale is now generated in CSS via `oklch(from var(--maz-X) clamp(0, calc(l ± offset), 1) calc(c * mult) h)`. Read the live value from `--maz-X-{50..950}`, or replicate the formula inline. |
+| `parseHSL(value)` | Use a CSS color parser or `parseColorAsOklch` from `@maz-ui/themes/utils/color-conversions`. |
+| `adjustColorLightness(color, amount)` | Inline with `oklch(from <color> calc(l + N) c h)` to shift lightness while preserving chroma and hue. |
+| `getContrastColor(color)` | Use the preset's `*-foreground` token, which is what components consume internally. |
+
+`colorToHex`, `parseColorAsOklch` and `formatAsOklch` are **preserved**, now exported from `@maz-ui/themes/utils/color-conversions`.
+
+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)
 
 `@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: