@maz-ui/mcp 5.0.0-canary.ef64a02.0 → 5.0.0

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

@@ -5,7 +5,7 @@ description: Stylelint preset for Vue/Nuxt/JS/TS projects, with first-class Tail
 
 # {{ $frontmatter.title }}
 
-`@maz-ui/stylelint-config` is the Stylelint counterpart to [`@maz-ui/eslint-config`](./eslint-config.md). It builds on Stylelint's official **standard** config and layers in the conventions used by maz-ui itself: BEM-friendly class patterns, Tailwind v4 at-rule whitelist, RTL-friendly logical properties, optional SCSS support, and Vue/HTML block parsing.
+`@maz-ui/stylelint-config` is the Stylelint counterpart to [`@maz-ui/eslint-config`](./eslint-config.md). It builds on Stylelint's official **standard** config and layers in the conventions used by maz-ui itself: BEM-friendly class patterns, Tailwind v4 support (at-rule whitelist + tunable plugin policy), RTL-friendly logical properties, optional SCSS support, Vue/HTML block parsing, and a single `extends` knob to compose extra shareable configs.
 
 ## Installation
 
@@ -13,7 +13,7 @@ description: Stylelint preset for Vue/Nuxt/JS/TS projects, with first-class Tail
 pnpm add -D @maz-ui/stylelint-config stylelint
 ```
 
-The peer dependencies the preset relies on (`stylelint-config-standard`, `stylelint-config-recommended-vue`, `stylelint-use-logical-spec`, …) are bundled as direct dependencies, so you don't need to install them yourself.
+The peer dependencies the preset relies on (`stylelint-config-standard`, `stylelint-config-recommended-vue`, `stylelint-use-logical-spec`, `stylelint-plugin-tailwindcss`, `stylelint-order`, …) are bundled as direct dependencies, so you don't need to install them yourself.
 
 ## Basic usage
 
@@ -30,8 +30,16 @@ Vue, Tailwind and SCSS are auto-detected from your `package.json`:
 | Detected when… | Enables… |
 | --- | --- |
 | `vue` or `nuxt` is in dependencies | Vue support (`stylelint-config-recommended-vue`, `<style>` block parsing) |
-| `tailwindcss` is in dependencies | Tailwind v4 at-rule whitelist (`@apply`, `@theme`, `@layer`, `@variant`, …) |
-| `sass`, `sass-embedded` or `node-sass` is in dependencies | SCSS support (`stylelint-config-recommended-scss`, `postcss-scss`) |
+| `tailwindcss` or `@tailwindcss/vite` is in dependencies | At-rule whitelist + Tailwind plugin with the `'minimal'` policy (see [Tailwind](#tailwind-css-v4) below) |
+| `sass`, `sass-embedded` or `node-sass` is in dependencies | SCSS support (`stylelint-config-standard-scss`, `postcss-scss`) |
+
+::: warning Monorepo caveat
+Detection only reads the `package.json` in the current working directory. In a monorepo where `tailwindcss`, `vue` or `sass` are hoisted to the root and **not declared** in a sub-package's `package.json`, detection silently fails when Stylelint runs from that sub-package. Set the relevant flags explicitly in those cases:
+
+```js
+defineConfig({ vue: true, tailwind: true, scss: false })
+```
+:::
 
 ## Configuration
 
@@ -42,6 +50,9 @@ export default defineConfig({
   // Each one is also auto-detected — set explicitly to opt in/out.
   vue: true,
   html: false,
+
+  // `true` → 'minimal' plugin policy. Pass 'recommended' or 'strict' to enforce
+  // utility-first authoring conventions. `false` disables Tailwind support.
   tailwind: true,
   scss: false,
 
@@ -52,7 +63,7 @@ export default defineConfig({
 
   // Property order strategy.
   //   'recess'        : Recess-based ordering via stylelint-config-recess-order (default)
-  //   'alphabetical'  : Strict A→Z ordering
+  //   'alphabetical'  : A→Z ordering via stylelint-order
   //   false           : Disable ordering rules
   order: 'recess',
 
@@ -72,9 +83,33 @@ export default defineConfig({
       rules: { 'no-descending-specificity': null },
     },
   ],
+
+  // Layer extra shareable configs. Appended after the built-ins so they
+  // win Stylelint's cascade.
+  extends: ['stylelint-config-clean-order'],
+
+  // Log verbosity — see "Logging" below.
+  logLevel: 'default',
 })
 ```
 
+## Logging
+
+The preset can explain what it resolved and which plugins / extends it added — useful when you can't figure out why a rule is on or off. Logging is powered by [`@maz-ui/node`](https://www.npmjs.com/package/@maz-ui/node)'s consola-based logger.
+
+| `logLevel` | What you see |
+| --- | --- |
+| `'silent'` | Nothing. |
+| `'default'` *(default)* | A titled box summarizing the resolved support (vue, tailwind, scss, html, logical, order), with `(auto-detected)` / `(default)` annotations next to each value. |
+| `'debug'` | Adds one line per plugin / extends / overrides addition (`Vue: extended stylelint-config-recommended-vue`, `Tailwind: loaded 2 plugin(s) for "minimal" policy`, `User: extended stylelint-config-clean-order`, …). |
+| `'verbose'` | Adds the final shape: complete `extends` list, plugin / rule / override / ignore counts. |
+
+```js
+defineConfig({ logLevel: 'debug' })
+```
+
+The `logLevel` type comes from `@maz-ui/node` and accepts the full set of consola levels (`'silent'`, `'error'`, `'warning'`, `'normal'`, `'default'`, `'debug'`, `'trace'`, `'verbose'`). The four values above are the ones the preset actually produces output for.
+
 ## Logical properties (RTL-friendly)
 
 When `logical: true` (default), the preset enables [`stylelint-use-logical-spec`](https://github.com/Jordan-Hall/stylelint-use-logical-spec) which warns whenever you use a physical CSS property that has a logical equivalent:
@@ -107,20 +142,91 @@ defineConfig({ logical: false })
 
 ## Tailwind CSS v4
 
-When `tailwind: true`, the preset:
+When `tailwind` is enabled (truthy or auto-detected), the preset:
 
 - Whitelists every Tailwind v4 at-rule via `at-rule-no-unknown` (and `scss/at-rule-no-unknown` when SCSS is also on): `@apply`, `@theme`, `@layer`, `@variant`, `@custom-variant`, `@reference`, `@utility`, `@source`, `@screen`, `@starting-style`, `@tailwind`.
 - Sets `at-rule-no-deprecated` to allow `@apply` (Tailwind v4 still ships it as the canonical authoring directive).
 - Forces `import-notation: 'string'` — Tailwind v4 only parses the `prefix(...)` modifier on bare-string `@import` forms, never on `url()`-wrapped imports.
+- Loads [`stylelint-plugin-tailwindcss`](https://github.com/sonofmagic/dev-configs/tree/main/packages/stylelint-plugin-tailwindcss) and applies a curated rule set based on the chosen policy level.
+
+### Policy levels
+
+The `tailwind` option accepts a strictness level. Pure `true` (or auto-detection) maps to `'minimal'`.
+
+| Value | Plugin loaded | What runs |
+| --- | --- | --- |
+| `true` *(or auto-detected)* | ❌ | Same as `'minimal'`. |
+| `'minimal'` | ❌ | At-rule whitelist + `import-notation: 'string'` + `at-rule-no-deprecated`. **No plugin rules.** |
+| `'recommended'` | ✅ | `'minimal'` + `stylelint-plugin-tailwindcss`'s `recommended` preset (`no-invalid-apply`, `no-invalid-theme-function`, `no-atomic-class`, `no-apply`, `no-arbitrary-value`). |
+| `'strict'` | ✅ | `'recommended'` + architecture-level rules (`no-theme-function`, `no-screen-directive`, `no-tailwind-directive`, `no-import-directive`, `no-css-layer`). |
+| `false` | ❌ | Tailwind support disabled entirely (no at-rule whitelist, no plugin). |
+
+```js
+defineConfig({ tailwind: 'recommended' })
+```
+
+::: warning Plugin rules need to find your Tailwind runtime
+Both `'recommended'` and `'strict'` enable rules from `stylelint-plugin-tailwindcss` that resolve your project's Tailwind installation from each linted file's path. Projects with a Tailwind v4 prefix (`maz:`, `tw:`, …), a non-standard entry CSS, or a monorepo layout where the plugin can't locate Tailwind will produce a flood of false positives (every `@apply maz:flex` flagged as invalid).
+
+`'minimal'` is the safe default — it only enables the at-rule whitelist and a couple of CSS-level rules, no runtime Tailwind validation.
+
+If you want validation but hit false positives, drop the offending rule:
+
+```js
+defineConfig({
+  tailwind: 'recommended',
+  rules: {
+    'tailwindcss/no-invalid-apply': null,
+    'tailwindcss/no-invalid-theme-function': null,
+  },
+})
+```
+:::
+
+The plugin supports both Tailwind v3 and v4.
+
+## Property ordering
+
+| Value | Behavior |
+| --- | --- |
+| `'recess'` *(default)* | Extends `stylelint-config-recess-order`. Pragmatic, widely adopted, groups related properties. |
+| `'alphabetical'` | Loads `stylelint-order` and enables `order/properties-alphabetical-order`. Strict A→Z. |
+| `false` | No ordering rules. |
+
+To swap recess for another shareable order config (e.g. `stylelint-config-clean-order`), disable the built-in strategy and extend yours via the [`extends`](#layering-shareable-configs) option:
+
+```js
+defineConfig({
+  order: false,
+  extends: ['stylelint-config-clean-order'],
+})
+```
+
+## Layering shareable configs
+
+The `extends` option appends entries **after** the built-ins, so user configs win Stylelint's cascade:
+
+```js
+defineConfig({
+  extends: [
+    'stylelint-config-clean-order', // alternative property order
+    '@stylistic/stylelint-config', // restore stylistic rules retired from Stylelint core
+  ],
+})
+```
+
+Use this to layer additional shareable configs without rewriting the whole `defineConfig` output.
 
 ## What it includes
 
 - **Stylelint Standard** — Idiomatic CSS rules from the official Stylelint config.
-- **Property ordering** (`stylelint-config-recess-order`) — Recess-based, the most widely adopted convention for non-alphabetical ordering.
+- **Property ordering** — Recess-based by default (`stylelint-config-recess-order`), alphabetical via `stylelint-order`, or off — see [Property ordering](#property-ordering).
+- **Tailwind v4 support** (opt-in / auto-detected) — at-rule whitelist + `stylelint-plugin-tailwindcss` with three policy levels — see [Tailwind CSS v4](#tailwind-css-v4).
 - **Vue / HTML support** (opt-in / auto-detected) — `<style>` and `<style scoped>` block parsing via `postcss-html`.
-- **SCSS support** (opt-in / auto-detected) — full `stylelint-config-recommended-scss` + native SCSS at-rule whitelist.
-- **Logical properties** — RTL-friendly authoring.
+- **SCSS support** (opt-in / auto-detected) — `stylelint-config-standard-scss` + native SCSS at-rule whitelist.
+- **Logical properties** — RTL-friendly authoring via `stylelint-use-logical-spec`.
 - **BEM-friendly class patterns** — disables `selector-class-pattern` and `no-descending-specificity` so `m-btn__icon`, `m-btn--ghost` and `:deep(...)` selectors flow naturally.
+- **Layering** — `extends` option to compose additional shareable configs on top of the resolved output.
 
 ## Advanced
 
@@ -134,6 +240,9 @@ import {
   scssRules,
   TAILWIND_AT_RULES,
   tailwindAtRuleNoUnknown,
+  tailwindPluginMinimal,
+  tailwindPluginRecommended,
+  tailwindPluginStrict,
   tailwindRules,
 } from '@maz-ui/stylelint-config'
 
@@ -142,10 +251,13 @@ export default {
     ...baseRules,
     ...tailwindRules,
     ...tailwindAtRuleNoUnknown,
+    ...tailwindPluginMinimal,
   },
 }
 ```
 
+Each `tailwindPlugin*` constant is the rule object for the corresponding policy level — useful when you compose Stylelint configs by hand instead of going through `defineConfig`.
+
 ## Migrating from a hand-written `.stylelintrc`
 
 If you used the historical maz-ui Stylelint setup, the migration boils down to:
@@ -177,7 +289,7 @@ If you used the historical maz-ui Stylelint setup, the migration boils down to:
 +export default defineConfig({
 +  vue: true,
 +  scss: true,
-+  tailwind: true,
++  tailwind: true, // 'minimal' | 'recommended' | 'strict' | false also accepted
 +  logical: true,
 +})
 ```

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

@@ -1,19 +1,21 @@
 ---
 title: Theming
-description: Modern and performant theme system for Maz-UI with TypeScript, HSL CSS variables and flexible strategies.
+description: Modern and performant theme system for Maz-UI built on native CSS features (light-dark(), color-scheme, color-mix(in oklch)) for v5.
 ---
 
 # {{ $frontmatter.title }}
 
-{{ $frontmatter.description }}
+Modern and performant theme system for Maz-UI built on native CSS features (`light-dark()`, `color-scheme`, `color-mix(in oklch)`) for v5.
 
 <NpmBadge package="@maz-ui/themes"></NpmBadge>
 
 ## Features
 
-- **Modern HSL CSS Variables** - Maximum flexibility with colors
-- **Smart Dark Mode** - Automatic support with `prefers-color-scheme`
-- **Automatic Generation** - Color scales (50-950) created automatically
+- **Native `light-dark()` + `color-scheme`** - Modern CSS theming with zero JS overhead for the light/dark switch
+- **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
 - **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
@@ -44,13 +46,17 @@ app.use(MazUi, {
     darkModeStrategy: 'class', // 'class' | 'media' (only if mode is `both`)
     mode: 'both', // 'light' | 'dark' | 'both' (supported color modes)
     colorMode: 'auto', // 'auto' | 'light' | 'dark' (initial color mode, only if mode is 'both')
+    // Class added to <html> when dark mode is forced (default: 'dark')
+    darkClass: 'dark',
+    // Class added to <html> when light mode is forced (default: 'light')
+    lightClass: 'light',
     persistPreset: true, // remember the active preset name across reloads
   }
 })
 ```
 
 ::: tip Alternative: MazUiProvider
-You can also initialize the theme via the [`MazUiProvider`](./maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped themes.
+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
@@ -89,10 +95,12 @@ const { toggleDarkMode, isDark, updateTheme } = useTheme()
 
 - `preset`: The theme preset to use
 - `overrides` (optional): Override specific parts of the theme
-- `strategy` (optional): The rendering strategy to use
-- `darkModeStrategy` (optional): The dark mode strategy to use, only if you use mode `both`
-- `mode` (optional): The supported color modes to use (light, dark, both)
-- `colorMode` (optional): The initial color mode to use (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`
 - `persistPreset` (optional, default `true`): Persist the active preset name in the `maz-preset` cookie so it is restored on reload.
 
 ### Preset persistence
@@ -118,6 +126,48 @@ Useful when:
 - You want zero theme-related cookies (privacy / regulatory).
 - The active preset is fully driven by the consumer app and no end-user switching is exposed.
 
+## Color modes and class toggling
+
+`darkClass` and `lightClass` interact with `darkModeStrategy` to control how `<html>` is decorated when the user picks an explicit mode.
+
+### `darkModeStrategy: 'class'` (default)
+
+- `setColorMode('dark')` adds `darkClass` (default `.dark`) to `<html>` → `color-scheme: only dark`.
+- `setColorMode('light')` adds `lightClass` (default `.light`) to `<html>` → `color-scheme: only light`.
+- `setColorMode('auto')` removes both classes → `color-scheme: light dark` lets the browser follow the system `prefers-color-scheme`.
+
+Forcing both classes on the root ensures native widgets (scrollbars, native `<select>`, date pickers, autofill backgrounds, …) match the explicit user choice rather than the OS preference.
+
+### `darkModeStrategy: 'media'`
+
+- No class is ever added to `<html>`.
+- The browser always follows `prefers-color-scheme` via `color-scheme: light dark`.
+- `setColorMode()` still updates the persisted cookie but does **not** force a visual override.
+
+## Animated theme switch
+
+For a full-page animated swap (rather than per-variable color tweens), pass `{ animate: true }` to `setColorMode` or `toggleDarkMode`:
+
+```vue
+<script setup>
+import { useTheme } from '@maz-ui/themes'
+
+const { toggleDarkMode, setColorMode } = useTheme()
+
+async function onToggle() {
+  await toggleDarkMode({ animate: true })
+}
+
+async function forceDark() {
+  await setColorMode('dark', { animate: true })
+}
+</script>
+```
+
+- 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.
+- **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">
@@ -395,14 +445,14 @@ const customTheme = await definePreset({
     },
     colors: {
       light: {
-        primary: '280 100% 60%',
-        secondary: '300 50% 90%',
-        accent: '260 100% 70%'
+        primary: 'oklch(0.62 0.24 305)',
+        secondary: 'oklch(0.94 0.04 320)',
+        accent: 'oklch(0.7 0.22 290)'
       },
       dark: {
-        primary: '280 100% 70%',
-        secondary: '300 30% 20%',
-        accent: '260 100% 80%'
+        primary: 'oklch(0.72 0.22 305)',
+        secondary: 'oklch(0.28 0.06 320)',
+        accent: 'oklch(0.78 0.2 290)'
       }
     }
   },
@@ -449,16 +499,16 @@ const brandTheme = await definePreset({
     },
     colors: {
       light: {
-        primary: '210 100% 50%',
-        secondary: '210 40% 96%',
-        surface: '210 20% 98%',
-        accent: '280 100% 70%'
+        primary: 'oklch(0.6 0.18 254)',
+        secondary: 'oklch(0.96 0.01 254)',
+        surface: 'oklch(0.99 0.005 254)',
+        accent: 'oklch(0.7 0.22 305)'
       },
       dark: {
-        primary: '210 100% 60%',
-        secondary: '210 40% 15%',
-        surface: '210 20% 8%',
-        accent: '280 100% 80%'
+        primary: 'oklch(0.7 0.18 254)',
+        secondary: 'oklch(0.22 0.03 254)',
+        surface: 'oklch(0.18 0.02 254)',
+        accent: 'oklch(0.78 0.2 305)'
       }
     }
   }
@@ -543,23 +593,58 @@ 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.
 
+### 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)`:
+
+```typescript
+const wideDialogTheme = definePreset({
+  base: 'maz-ui',
+  overrides: {
+    name: 'wide-dialogs',
+    components: {
+      dialog: {
+        'max-width': '48rem',
+        'min-width': '36rem',
+      },
+    },
+  },
+})
+```
+
+Both values are in `rem`, so they scale with the preset's `base-font-size`. Bundled presets anchored on `14px` use `38rem` / `32rem`; `ocean` (`16px`) ships scaled rem values (`33.25rem` / `28rem`) to keep the same rendered pixel width. The `max-width` / `min-width` props on `MazDialog` still override the preset per instance.
+
 ## useTheme Composable API
 
 ```typescript
 const {
   // Reactive state
+  preset, // ComputedRef<ThemePreset>
   presetName, // ComputedRef<string>
-  colorMode, // ComputedRef<'light' | 'dark' | 'auto'>
+  colorMode, // Ref<'light' | 'dark' | 'auto'> — also accepts assignment (computed setter)
   isDark, // ComputedRef<boolean>
   strategy, // ComputedRef<'runtime' | 'buildtime'>
+  mode, // ComputedRef<'light' | 'dark' | 'both'>
+  darkModeStrategy, // ComputedRef<'class' | 'media'>
 
   // Actions
-  updateTheme, // (preset: ThemePreset | ThemePresetOverrides) => void
-  setColorMode, // (mode: 'light' | 'dark' | 'auto') => void
-  toggleDarkMode // () => void
+  updateTheme, // (preset: ThemePreset | ThemePresetName | ThemePresetOverrides) => Promise<void>
+  setColorMode, // (mode: 'light' | 'dark' | 'auto', options?: { animate?: boolean }) => Promise<void>
+  toggleDarkMode, // (options?: { animate?: boolean }) => Promise<void>
 } = useTheme()
+
+// Set the color mode imperatively
+await setColorMode('dark')
+
+// 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.
+
 ### Advanced Usage Examples
 
 ```vue
@@ -623,8 +708,8 @@ const customPreset = definePreset({
   overrides: {
     name: 'custom',
     colors: {
-      light: { primary: '221.2 83.2% 53.3%' },
-      dark: { primary: '217.2 91.2% 59.8%' },
+      light: { primary: 'oklch(0.6 0.18 254)' },
+      dark: { primary: 'oklch(0.7 0.18 254)' },
     },
   },
 })
@@ -687,8 +772,8 @@ const customPreset = definePreset({
   overrides: {
     name: 'custom',
     colors: {
-      light: { primary: '221.2 83.2% 53.3%' },
-      dark: { primary: '217.2 91.2% 59.8%' },
+      light: { primary: 'oklch(0.6 0.18 254)' },
+      dark: { primary: 'oklch(0.7 0.18 254)' },
     },
   },
 })
@@ -729,8 +814,8 @@ const customPreset = definePreset({
   overrides: {
     name: 'custom',
     colors: {
-      light: { primary: '221.2 83.2% 53.3%' },
-      dark: { primary: '217.2 91.2% 59.8%' },
+      light: { primary: 'oklch(0.6 0.18 254)' },
+      dark: { primary: 'oklch(0.7 0.18 254)' },
     },
   },
 })
@@ -819,7 +904,7 @@ const styleTag = createThemeStylesheet(css, {
 
 ## Token Reference
 
-Every preset emits the same set of CSS variables on `:root` (and a `.dark` block when `mode: 'both'`). 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
 
@@ -893,16 +978,27 @@ Per-component knobs under `components.<key>`. All optional — omit to fall back
 | `btn.font-weight` | `--maz-btn-font-weight` | Font-weight on `.m-btn`. Defaults to `'500'`. |
 | `container.bg.light` / `.dark` | `--maz-container-bg` (per mode) | Background of `Card`, `Container`, `Dialog`, `Popover`, `Drawer`, … Defaults to `var(--maz-surface)`. Bridged to `--color-container`. |
 | `input.bg.light` / `.dark` | `--maz-input-bg` (per mode) | Background of `Input`, `Textarea`, `Select`, `Checkbox`, … Defaults to `var(--maz-surface)` light, `var(--maz-surface-400)` dark. Bridged to `--color-input`. |
+| `dialog.max-width` | `--maz-dialog-max-width` | Max-width of `MazDialog` on tablet and up. Defaults to `38rem` (`33.25rem` on `ocean`). Overridable via the `max-width` prop. |
+| `dialog.min-width` | `--maz-dialog-min-width` | Min-width of `MazDialog` on tablet and up. Defaults to `32rem` (`28rem` on `ocean`). Overridable via the `min-width` prop. |
 
 ### Sample output
 
+Each base color is emitted as a `light-dark()` value; scales `--maz-X-50` through `--maz-X-950` are derived via OKLCh relative color syntax so they automatically follow base color overrides at runtime, preserving chroma at every step.
+
 ```css
 :root {
-  /* Main colors */
-  --maz-primary: oklch(0.6495 0.1913 253.63);
-  --maz-primary-foreground: oklch(1 0 0);
-  --maz-surface: oklch(1 0 0);
-  --maz-foreground: oklch(0.2573 0.0068 248.09);
+  color-scheme: light dark;
+
+  /* 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 */
+  --maz-primary-500: var(--maz-primary);
+  --maz-primary-600: oklch(from var(--maz-primary) clamp(0, calc(l - 0.07), 1) c h);
+  /* ... */
 
   /* Foundation */
   --maz-base-font-size: 14px;
@@ -914,35 +1010,19 @@ Per-component knobs under `components.<key>`. All optional — omit to fall back
   /* Scales */
   --maz-rounded-md: 0.7rem;
   --maz-shadow-style-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), …;
-
-  /* Auto-generated 50–950 scale */
-  --maz-primary-500: oklch(…);
-  /* ... */
 }
-```
-
-### Dark Mode
 
-```css
-.dark {
-  --maz-surface: 235 16% 15%;
-  --maz-foreground: 0 0% 85%;
-  /* Variables automatically adapted */
-}
-
-/* Or with media query */
-@media (prefers-color-scheme: dark) {
-  :root {
-    --maz-surface: 235 16% 15%;
-    --maz-foreground: 0 0% 85%;
-  }
-}
+/* 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](/guide/nuxt) which covers installation and framework-specific configuration.
+For Nuxt users, check the [dedicated Nuxt documentation](/ecosystem/nuxt) which covers installation and framework-specific configuration.
 
 ## Migration from Legacy System
 
@@ -965,20 +1045,21 @@ export default defineConfig({
 ```typescript [After (@maz-ui/themes)]
 // main.ts
 import { definePreset, mazUi } from '@maz-ui/themes'
+import { MazUiTheme } from '@maz-ui/themes/plugin'
 
 const myTheme = definePreset({
   base: mazUi,
   overrides: {
     colors: {
       light: {
-        primary: '210 100% 56%',
-        secondary: '164 76% 46%'
+        primary: 'oklch(0.65 0.19 254)',
+        secondary: 'oklch(0.72 0.16 168)'
       }
     }
   }
 })
 
-app.use(MazThemePlugin, { preset: myTheme })
+app.use(MazUiTheme, { preset: myTheme })
 ```
 
 :::
@@ -1007,14 +1088,14 @@ const customPreset = await definePreset({
     name: 'custom-purple',
     colors: {
       light: {
-        'primary': '280 100% 60%',
-        'secondary': '300 50% 90%',
-        'accent': '260 100% 70%'
+        'primary': 'oklch(0.62 0.24 305)',
+        'secondary': 'oklch(0.94 0.04 320)',
+        'accent': 'oklch(0.7 0.22 290)'
       },
       dark: {
-        'primary': '280 100% 70%',
-        'secondary': '300 30% 20%',
-        'accent': '260 100% 80%'
+        'primary': 'oklch(0.72 0.22 305)',
+        'secondary': 'oklch(0.28 0.06 320)',
+        'accent': 'oklch(0.78 0.2 290)'
       }
     }
   }

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

@@ -73,7 +73,7 @@ app.use(MazUi, {
 ```
 
 ::: tip Alternative: MazUiProvider
-You can also provide translations via the [`MazUiProvider`](./maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped configurations.
+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

package/docs/src/ecosystem/utils/camel-case.md

@@ -0,0 +1,31 @@
+---
+title: camelCase
+description: Convert a kebab-case string to camelCase by stripping dashes and uppercasing the following letter.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { camelCase } from '@maz-ui/utils'
+
+camelCase('my-component-name') // → 'myComponentName'
+camelCase('hello-world') // → 'helloWorld'
+```
+
+## API
+
+```ts
+function camelCase(str: string): string
+```
+
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `str`     | `string` | The string to convert |
+
+## Notes
+
+`camelCase` is intentionally minimal — it only handles `kebab-case` input. For more general normalization (snake_case, spaces, PascalCase), use [`normalizeString`](./normalize-string) with the `case: 'camelCase'` option.

package/docs/src/{helpers → ecosystem/utils}/capitalize.md

@@ -10,8 +10,7 @@ description: The module capitalize is a function that adds a capital letter to a
 <MazInput v-model="stringValue" />
 
 <div
-  style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
-  class="flex flex-center rounded gap-05"
+  class="maz:flex maz:flex-center maz:rounded-md maz:gap-0.5 maz:p-4 maz:mt-16 maz:bg-surface-300"
 >
   formatted value: <strong>{{ stringFormatted }}</strong>
 </div>
@@ -32,7 +31,7 @@ const stringFormatted = computed(() =>
   <MazInput v-model="stringValue" />
 
   <div
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
+    class="flex flex-center rounded-md gap-0.5 p-4 mt-16 bg-surface-300"
   >
     {{ stringFormatted }}
   </div>