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

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

@@ -0,0 +1,187 @@
+---
+title: '@maz-ui/eslint-config'
+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 (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
+
+```bash
+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:
+
+```ts
+import { defineConfig } from '@maz-ui/eslint-config'
+
+export default defineConfig()
+```
+
+That's it. Vue is auto-detected from your `package.json` (presence of `vue` or `nuxt`).
+
+## Configuration
+
+```ts
+import { defineConfig } from '@maz-ui/eslint-config'
+
+export default defineConfig({
+  // Toggle features explicitly (each one is also auto-detected from your deps).
+  typescript: true, // default
+  vue: true, // auto-detected
+  sonarjs: true, // default
+  tailwindcss: false, // see "Tailwind support" below
+  vueAccessibility: false, // optional
+  formatters: true, // CSS/HTML/JSON/YAML/Markdown formatting via dprint
+
+  // 'production' downgrades console.log to error, 'development' keeps it warning.
+  env: 'production',
+
+  // Extra ignore globs (merged with sensible defaults).
+  ignores: ['**/*.generated.ts'],
+
+  // Direct rule overrides applied on top of the resolved config.
+  rules: {
+    '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
+export default defineConfig(
+  { typescript: true },
+  {
+    files: ['**/*.legacy.ts'],
+    rules: { 'ts/no-explicit-any': 'off' },
+  },
+)
+```
+
+## 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',
+  },
+})
+```
+
+::: 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.
+
+## 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).
+- **Markdown** — prose linting baseline.
+- **vueAccessibility** (opt-in) — `eslint-plugin-vuejs-accessibility` rules with the AudioWorklet globals fix.
+
+## Advanced
+
+### Compose your own config
+
+```ts
+import {
+  baseRules,
+  sonarjsRules,
+  tailwindcssConfigs,
+  vueRules,
+} from '@maz-ui/eslint-config'
+
+export default [
+  {
+    rules: {
+      ...baseRules(true), // production = true → no-console: 'error'
+      ...sonarjsRules,
+      ...vueRules,
+    },
+  },
+  // Drop in just the Tailwind block, with whatever preset and settings you want.
+  ...tailwindcssConfigs('stylistic', { entryPoint: 'src/main.css' }),
+]
+```
+
+### 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 |
+| --- | --- |
+| 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

@@ -0,0 +1,302 @@
+---
+title: '@maz-ui/stylelint-config'
+description: Stylelint preset for Vue/Nuxt/JS/TS projects, with first-class Tailwind CSS v4 support, RTL-friendly logical properties, and SCSS opt-in.
+---
+
+# {{ $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 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
+
+```bash
+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`, `stylelint-plugin-tailwindcss`, `stylelint-order`, …) are bundled as direct dependencies, so you don't need to install them yourself.
+
+## Basic usage
+
+Create `stylelint.config.mjs` at the root of your project:
+
+```js
+import { defineConfig } from '@maz-ui/stylelint-config'
+
+export default defineConfig()
+```
+
+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` 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
+
+```js
+import { defineConfig } from '@maz-ui/stylelint-config'
+
+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,
+
+  // Encourage logical CSS properties for RTL-friendly authoring:
+  // `inset-inline-start` instead of `left`, `margin-inline-start` instead
+  // of `margin-left`, etc. Highly recommended for design systems.
+  logical: true,
+
+  // Property order strategy.
+  //   'recess'        : Recess-based ordering via stylelint-config-recess-order (default)
+  //   'alphabetical'  : A→Z ordering via stylelint-order
+  //   false           : Disable ordering rules
+  order: 'recess',
+
+  // Extra ignore globs (merged with sensible defaults).
+  ignores: ['**/legacy/**'],
+
+  // Direct rule overrides applied on top of the resolved config.
+  rules: {
+    'no-descending-specificity': null,
+    'function-no-unknown': [true, { ignoreFunctions: ['v-bind', 'theme'] }],
+  },
+
+  // Per-file overrides appended last.
+  overrides: [
+    {
+      files: ['**/*.legacy.css'],
+      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:
+
+```css
+/* ❌ Physical — breaks in RTL languages */
+.toolbar {
+  margin-left: 1rem;
+  padding-right: 1rem;
+  text-align: left;
+  left: 0;
+}
+
+/* ✅ Logical — adapts to writing direction */
+.toolbar {
+  margin-inline-start: 1rem;
+  padding-inline-end: 1rem;
+  text-align: start;
+  inset-inline-start: 0;
+}
+```
+
+If you ship a design system that has to work in both LTR and RTL locales (Arabic, Hebrew, Persian, …), this rule is the cheapest way to keep your CSS direction-agnostic without auditing every property by hand.
+
+Disable it explicitly if your project doesn't need RTL support:
+
+```js
+defineConfig({ logical: false })
+```
+
+## Tailwind CSS v4
+
+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** — 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) — `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
+
+You can import the individual rule sets to compose your own:
+
+```js
+import {
+  baseRules,
+  GLOBAL_IGNORES,
+  logicalRules,
+  scssRules,
+  TAILWIND_AT_RULES,
+  tailwindAtRuleNoUnknown,
+  tailwindPluginMinimal,
+  tailwindPluginRecommended,
+  tailwindPluginStrict,
+  tailwindRules,
+} from '@maz-ui/stylelint-config'
+
+export default {
+  rules: {
+    ...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:
+
+```diff
+-/** @type {import('stylelint').Config} */
+-export default {
+-  plugins: ['stylelint-scss'],
+-  extends: [
+-    'stylelint-config-standard',
+-    'stylelint-config-standard-scss',
+-    'stylelint-config-recommended-vue',
+-  ],
+-  rules: {
+-    'at-rule-no-unknown': [true, { ignoreAtRules: ['theme', 'apply', 'layer', /* ... */] }],
+-    'scss/at-rule-no-unknown': [true, { ignoreAtRules: [/* same list */] }],
+-    'selector-pseudo-class-no-unknown': [true, { ignorePseudoClasses: ['deep'] }],
+-    'selector-class-pattern': null,
+-    'no-descending-specificity': null,
+-    'function-no-unknown': [true, { ignoreFunctions: ['v-bind'] }],
+-    'nesting-selector-no-missing-scoping-root': null,
+-  },
+-  overrides: [
+-    { files: ['**/*.vue', '**/*.html'], customSyntax: 'postcss-html' },
+-  ],
+-}
++import { defineConfig } from '@maz-ui/stylelint-config'
++
++export default defineConfig({
++  vue: true,
++  scss: true,
++  tailwind: true, // 'minimal' | 'recommended' | 'strict' | false also accepted
++  logical: true,
++})
+```
+
+## Compatibility
+
+| Tool | Required version |
+| --- | --- |
+| Stylelint | `>=16.0.0 <18.0.0` |
+| Node.js | `>=20.19.0` |

package/docs/src/guide/browser-support.md

@@ -0,0 +1,81 @@
+---
+title: Browser support
+description: Maz-UI v5 browser compatibility matrix and the native CSS features it depends on.
+---
+
+# {{ $frontmatter.title }}
+
+Maz-UI v5 is built on **Tailwind CSS v4**, which relies on modern native CSS features with no polyfill path. If your audience still uses older browsers, stay on Maz-UI v4.
+
+## Minimum versions
+
+| Browser            | Minimum |
+| ------------------ | ------- |
+| **Chromium** (Chrome, Edge, Opera, Brave, Arc, …) | **111** (March 2023) |
+| **Safari** (macOS, iOS, iPadOS) | **16.4** (March 2023) |
+| **Firefox** | **128** (July 2024) |
+| **Samsung Internet** | **22** (2023) |
+
+On the Android side: Chrome 111+ is bundled with Android 13+ devices and is available as an update on anything from Android 7. WebView apps built against API level 24+ get Chromium 111+ automatically.
+
+Anything older than the versions above will not render the design system correctly. The most common failure mode is colors looking wrong (because `color-mix()` doesn't resolve) or cascade layers being ignored.
+
+## Why these minimums
+
+Maz-UI v5 + Tailwind v4 uses the following native CSS features:
+
+### `color-mix()`
+
+Used for every alpha modifier (`bg-primary/50`, the custom `color-mix(in srgb, var(--X) 60%, transparent)` generated by the `@maz-ui/upgrade` package for `hsl(var(--X) / 60%)`, etc.).
+
+[Browser support · caniuse](https://caniuse.com/?search=color-mix) — supported everywhere since Chromium 111 / Safari 16.4 / Firefox 128.
+
+### `@property`
+
+Used internally by Tailwind v4 to declare typed custom properties with default values. Powers the `--tw-translate-x`, `--tw-rotate`, etc. that back transform utilities.
+
+[Browser support · caniuse](https://caniuse.com/?search=%40property) — supported everywhere since Chromium 111 / Safari 16.4 / Firefox 128.
+
+### Native CSS nesting
+
+Used by Tailwind v4 internally and by Maz-UI utilities like `cap-f` (`&::first-letter`). v4 does not run a CSS-nesting preprocessor; the output relies on the browser parsing nested rules directly.
+
+[Browser support · caniuse](https://caniuse.com/css-nesting) — supported everywhere since Chromium 112 / Safari 16.5 / Firefox 117.
+
+### `:has()` selector
+
+Used by a few Maz-UI utilities for parent-aware styling.
+
+[Browser support · caniuse](https://caniuse.com/css-has) — supported everywhere since Chromium 105 / Safari 15.4 / Firefox 121.
+
+## Testing on older browsers
+
+If you need to support a browser older than the matrix above:
+
+1. **Stay on Maz-UI v4** — it keeps Tailwind v3 and targets Chromium 90+, Safari 14+, Firefox 90+.
+2. **Check your real audience** using your analytics tool before bumping to v5. "Support everything" is often outdated advice in 2026 — most teams can comfortably drop anything older than Chromium 111.
+
+## Testing on the minimum versions
+
+Playwright can install exact minimum-version browsers for regression testing:
+
+```bash
+pnpm add -D @playwright/test
+npx playwright install chromium@111 firefox@128 webkit@16.4
+```
+
+Then run your visual tests against that matrix in CI.
+
+## What happens on unsupported browsers
+
+- **`color-mix` unsupported** — any utility that goes through an alpha modifier (`bg-primary/50`, the custom overlay colors in MazDialog / MazBackdrop) falls back to the base color with no transparency. Visual regression but not a crash.
+- **`@property` unsupported** — transform, translate, rotate, scale utilities don't animate smoothly because the custom properties aren't interpolatable without `@property`.
+- **Cascade layers unsupported** — the order of Maz-UI styles vs app styles becomes non-deterministic, so resets and utilities can override app styles (or vice versa) unpredictably.
+
+The safe recommendation is: detect at app boot and show an "unsupported browser" screen if you can't guarantee the minimum matrix.
+
+## See also
+
+- [Migration v4 → v5](./migration-v5.md) — the full upgrade guide
+- [Tailwind v4 browser support](https://tailwindcss.com/blog/tailwindcss-v4#browser-support) — upstream notes
+- [Tailwind CSS integration](./tailwind.md) — how the design system plugs into your own Tailwind

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

@@ -1,6 +1,6 @@
 ---
 title: Getting Started
-description: Build Vue and Nuxt applications faster with Maz-UI v4 - The modern, modular component library
+description: Build Vue and Nuxt applications faster with Maz-UI v5 - The modern, modular component library
 head:
   - - meta
     - name: keywords
@@ -16,24 +16,29 @@ head:
 - 🌱 **Tree-shaking** - Import only what you need
 - 🛠️ **TypeScript-first** - Full type safety out of the box
 - 🚀 **Performance** - Tree-shaking benefits and maximum optimization
-- 🎨 **Theming system** - Customizable themes and dark mode support (4 presets available) - [@maz-ui/themes](./themes.md)
+- 🎨 **Theming system** - Customizable themes and dark mode support (5 presets available) - [@maz-ui/themes](./themes.md)
+- 💨 **Optional Tailwind bridge** - Already have a Tailwind v4 setup? Expose your active maz-ui theme tokens (colors, radius, breakpoints, custom utilities) to your own Tailwind config - [Tailwind integration](./tailwind.md)
 - 🌐 **Internationalization** - Locale management and tree-shakable imports - [@maz-ui/translations](./translations.md)
-- 🎨 **Icon library** - Comprehensive collection of SVG icons designed for performance and flexibility (400+ icons) - [@maz-ui/icons](./icons.md)
+- 🎨 **Icon library** - Comprehensive collection of SVG icons designed for performance and flexibility (860+ icons) - [@maz-ui/icons](./icons.md)
 - 🧰 **Nuxt module** - Effortless Maz-UI integration with auto-imports - [@maz-ui/nuxt](./nuxt.md)
-- 🤖 **MCP** - Connect your IA agents to the documentation - [@maz-ui/mcp](./mcp.md)
+- 🤖 **MCP** - Connect your AI agents to the documentation - [@maz-ui/mcp](./mcp.md)
 
 :::
 
+::: tip Migrating from v4?
+Run `npx @maz-ui/upgrade ./` to handle 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). See the [v5 migration guide](./migration-v5.md) for the rest.
+:::
+
 ## Guides
 
 Start by choosing your framework:
 
-<div class="maz-flex maz-gap-4 maz-w-full maz-flex-col tab-m:maz-flex-row vp-raw">
+<div class="maz:flex maz:gap-4 maz:w-full maz:flex-col maz:tab-m:flex-row vp-raw">
   <MazCard
     href="/guide/vue"
-    class="maz-flex-1"
+    class="maz:flex-1"
     :gallery="{
-      images: ['https://positivethinking.tech/wp-content/uploads/2021/01/Logo-Vuejs.png'],
+      images: ['/vue.png'],
       height: 200,
       width: '100%',
     }"
@@ -51,10 +56,10 @@ Start by choosing your framework:
   </MazCard>
   <MazCard
     href="/guide/nuxt"
-    class="maz-flex-1"
+    class="maz:flex-1"
     content-title="Nuxt Users Guide"
     :gallery="{
-      images: ['https://media2.dev.to/dynamic/image/width=1000,height=420,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2F8mpeku6brwkfmrsumu3h.png'],
+      images: ['/nuxt.png'],
       height: 200,
       width: '100%',
     }"
@@ -80,7 +85,7 @@ Extend Maz-UI with our specialized companion packages:
 
 **Advanced Theming System**
 
-Modern theme system with HSL variables, dark mode support, and flexible strategies.
+Modern theme system with OKLCh color scales, runtime preset switching, and dark mode support.
 
 ```bash
 npm install @maz-ui/themes
@@ -88,9 +93,10 @@ npm install @maz-ui/themes
 
 **Features:**
 
-- 🎨 HSL CSS custom properties
-- 🌓 Smart dark mode detection
-- ⚡ Multiple rendering strategies
+- 🎨 OKLCh color system with perceptually uniform 11-step scales
+- 🌓 Smart dark mode detection and class/media/auto strategies
+- ⚡ `runtime` and `buildtime` rendering strategies
+- 🍪 Active preset persisted across reloads (opt-out)
 - 🛡️ Full TypeScript support
 
 [→ View Theme Documentation](./themes.md)
@@ -154,7 +160,7 @@ npm install @maz-ui/icons
 
 ### Tree-Shaking Benefits
 
-Maz-UI v4 is built with tree-shaking in mind. Import only what you need for optimal bundle sizes:
+Maz-UI v5 is built with tree-shaking in mind. Import only what you need for optimal bundle sizes:
 
 ```typescript
 /**
@@ -162,7 +168,7 @@ Maz-UI v4 is built with tree-shaking in mind. Import only what you need for opti
  */
 
 // ❌ Avoid importing everything
-import { formatCurrency, debounce } from 'maz-ui'
+import { formatCurrency, debounce } from '@maz-ui/utils'
 // ✅ Import from @maz-ui/utils
 import { formatCurrency, debounce } from '@maz-ui/utils'
 
@@ -242,8 +248,9 @@ Browse [GitHub discussions](https://github.com/LouisMazel/maz-ui/discussions) or
 </div>
 
 <style scoped>
+@reference "../../.vitepress/theme/main.css";
 .hero-section {
-  @apply maz-rounded maz-p-8 maz-my-12 maz-from-primary-400 maz-to-secondary-700 maz-bg-gradient-to-br;
+  @apply maz:rounded-md maz:p-8 maz:my-12 maz:from-primary-400 maz:to-secondary-700 maz:bg-linear-to-br;
 }
 
 .features-grid {