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

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

@@ -1,11 +1,11 @@
 ---
 title: '@maz-ui/eslint-config'
-description: ESLint flat-config preset for Vue/Nuxt/JS/TS projects, layered on @antfu/eslint-config with SonarJS, Tailwind and a11y add-ons.
+description: ESLint flat-config preset for Vue/Nuxt/JS/TS projects, layered on @antfu/eslint-config with SonarJS, Tailwind v3+v4 and a11y add-ons.
 ---
 
 # {{ $frontmatter.title }}
 
-`@maz-ui/eslint-config` ships an opinionated ESLint **flat config** for the kind of stack maz-ui itself uses: TypeScript, Vue 3 / Nuxt 3, optional Tailwind CSS, and tests. It is built on top of [`@antfu/eslint-config`](https://github.com/antfu/eslint-config) so you get a battle-tested baseline, then layered with quality rules from [SonarJS](https://github.com/SonarSource/eslint-plugin-sonarjs) and accessibility rules from [`eslint-plugin-vuejs-accessibility`](https://github.com/vue-a11y/eslint-plugin-vuejs-accessibility).
+`@maz-ui/eslint-config` ships an opinionated ESLint **flat config** for the kind of stack maz-ui itself uses: TypeScript, Vue 3 / Nuxt 3, optional Tailwind CSS (v3 or v4), and tests. It is built on top of [`@antfu/eslint-config`](https://github.com/antfu/eslint-config) so you get a battle-tested baseline, then layered with quality rules from [SonarJS](https://github.com/SonarSource/eslint-plugin-sonarjs), Tailwind rules from [`eslint-plugin-better-tailwindcss`](https://github.com/schoero/eslint-plugin-better-tailwindcss), and accessibility rules from [`eslint-plugin-vuejs-accessibility`](https://github.com/vue-a11y/eslint-plugin-vuejs-accessibility).
 
 ## Installation
 
@@ -13,6 +13,8 @@ description: ESLint flat-config preset for Vue/Nuxt/JS/TS projects, layered on @
 pnpm add -D @maz-ui/eslint-config eslint
 ```
 
+The Tailwind plugin and other peer/transitive dependencies are bundled as direct dependencies, so you don't need to install them yourself.
+
 ## Basic usage
 
 Create `eslint.config.ts` (or `.mjs`/`.js`) at the root of your project:
@@ -35,7 +37,7 @@ export default defineConfig({
   typescript: true, // default
   vue: true, // auto-detected
   sonarjs: true, // default
-  tailwindcss: false, // optional, requires eslint-plugin-tailwindcss
+  tailwindcss: false, // see "Tailwind support" below
   vueAccessibility: false, // optional
   formatters: true, // CSS/HTML/JSON/YAML/Markdown formatting via dprint
 
@@ -50,9 +52,29 @@ export default defineConfig({
     'no-console': 'error',
     'vue/custom-event-name-casing': ['error', 'kebab-case'],
   },
+
+  // Log verbosity — see "Logging" below.
+  logLevel: 'default',
 })
 ```
 
+## Logging
+
+The preset prints a titled box summarizing what it resolved (typescript, vue, tailwindcss preset, sonarjs, …) when ESLint loads. Powered by [`@maz-ui/node`](https://www.npmjs.com/package/@maz-ui/node)'s consola-based logger.
+
+| `logLevel` | What you see |
+| --- | --- |
+| `'silent'` | Nothing. |
+| `'default'` *(TTY default)* | A titled box summarizing the resolved feature toggles, with `(auto-detected)` / `(default)` annotations next to each value. |
+| `'debug'` | Adds one line per major block applied (Vue rules, SonarJS preset, vue-a11y, Tailwind plugin, test relaxations, user overrides). |
+| `'verbose'` | Adds the final shape: total block count and ignore-glob count. |
+
+```ts
+defineConfig({ logLevel: 'debug' })
+```
+
+The default is **`'default'` in interactive terminals (TTY) and `'silent'` otherwise** — CI, lint-staged, pipes, and JSON / SARIF formatters all write to stdout, where the box would corrupt machine-readable output. `logLevel` always wins when set explicitly.
+
 You can also append raw flat-config items as additional arguments — they merge after the built-in configs:
 
 ```ts
@@ -65,32 +87,190 @@ export default defineConfig(
 )
 ```
 
+## Tailwind support
+
+Powered by [`eslint-plugin-better-tailwindcss`](https://github.com/schoero/eslint-plugin-better-tailwindcss) — supports both **Tailwind v3 and v4**, and ESLint 7→10.
+
+The `tailwindcss` option accepts several shapes:
+
+| Value | Behavior |
+| --- | --- |
+| `false` *(default)* | Disabled. |
+| `true` | Same as `'recommended'` with default settings. |
+| `'recommended'` | Stylistic + correctness rules. |
+| `'stylistic'` | Formatting rules only — class order, line wrapping, no duplicate classes, etc. |
+| `'correctness'` | Validation rules only — `no-unknown-classes`, `no-conflicting-classes`. |
+| `MazTailwindcssOptions` | Pick a preset and pass plugin settings (Tailwind config path, prefix entry point, …). |
+
+```ts
+defineConfig({
+  tailwindcss: {
+    preset: 'recommended',
+    // Tailwind v4 — path to the CSS that does `@import "tailwindcss" prefix(maz)`.
+    entryPoint: 'src/main.css',
+    // Tailwind v3 instead — path to your config file.
+    // tailwindConfig: 'tailwind.config.ts',
+    // Tailwind v4: detect custom @layer components classes (cards, btns, …).
+    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,
+  },
+})
+```
+
+::: warning Plugin needs to know your Tailwind setup
+The plugin's correctness rules (`no-unknown-classes`, `no-conflicting-classes`) auto-resolve your Tailwind installation. Without `entryPoint` (v4) or `tailwindConfig` (v3), the plugin falls back to the **default Tailwind config** and won't know about your prefix, custom utilities, or theme tokens — which produces a flood of false positives in non-vanilla setups.
+
+If you customize Tailwind in any meaningful way (prefix, extend theme, custom utilities), set `entryPoint` or `tailwindConfig` explicitly. If you hit false positives anyway, downgrade to `'stylistic'` (formatting only) or disable individual rules:
+
+```ts
+defineConfig({
+  tailwindcss: 'recommended',
+  rules: {
+    'better-tailwindcss/no-unknown-classes': 'off',
+  },
+})
+```
+:::
+
+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, no-contradicting classes, valid Tailwind syntax.
+- **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.
 
 ## Advanced
 
-You can import the individual rule sets if you want to compose your own config:
+### Compose your own config
 
 ```ts
-import { baseRules, sonarjsRules, tailwindcssRules, vueRules } from '@maz-ui/eslint-config'
+import {
+  baseRules,
+  mazPlugin,
+  sonarjsRules,
+  tailwindcssConfigs,
+  vueRules,
+} from '@maz-ui/eslint-config'
 
 export default [
   {
+    plugins: { maz: mazPlugin },
     rules: {
-      ...baseRules(true),
+      ...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',
+    noArbitraryPx: { unit: 'em' },
+  }),
 ]
 ```
 
+### Auto-detection caveat (monorepos)
+
+Auto-detection of Vue / Nuxt reads the `package.json` in `process.cwd()` only. In a monorepo where `vue` is hoisted to the root and missing from a sub-package's `package.json`, detection silently fails. Set `vue: true` explicitly in those cases:
+
+```ts
+defineConfig({ vue: true, tailwindcss: { preset: 'recommended', cwd: 'apps/web' } })
+```
+
 ## Compatibility
 
 | Tool | Required version |
@@ -98,3 +278,4 @@ export default [
 | ESLint | `>=9.0.0 <11.0.0` |
 | Node.js | `>=20.19.0` |
 | TypeScript | `^5.0.0` |
+| Tailwind CSS | `^3.3.0 \|\| ^4.0.0` *(when `tailwindcss` is on)* |

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