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

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

@@ -0,0 +1,100 @@
+---
+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.
+---
+
+# {{ $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).
+
+## Installation
+
+```bash
+pnpm add -D @maz-ui/eslint-config eslint
+```
+
+## 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, // optional, requires eslint-plugin-tailwindcss
+  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'],
+  },
+})
+```
+
+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' },
+  },
+)
+```
+
+## 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.
+- **Markdown** — prose linting baseline.
+
+## Advanced
+
+You can import the individual rule sets if you want to compose your own config:
+
+```ts
+import { baseRules, sonarjsRules, tailwindcssRules, vueRules } from '@maz-ui/eslint-config'
+
+export default [
+  {
+    rules: {
+      ...baseRules(true),
+      ...sonarjsRules,
+      // ...
+    },
+  },
+]
+```
+
+## Compatibility
+
+| Tool | Required version |
+| --- | --- |
+| ESLint | `>=9.0.0 <11.0.0` |
+| Node.js | `>=20.19.0` |
+| TypeScript | `^5.0.0` |

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

@@ -0,0 +1,190 @@
+---
+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 at-rule whitelist, RTL-friendly logical properties, optional SCSS support, and Vue/HTML block parsing.
+
+## 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`, …) 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` 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`) |
+
+## 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,
+  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'  : Strict A→Z ordering
+  //   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 },
+    },
+  ],
+})
+```
+
+## 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: true`, 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.
+
+## 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.
+- **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.
+- **BEM-friendly class patterns** — disables `selector-class-pattern` and `no-descending-specificity` so `m-btn__icon`, `m-btn--ghost` and `:deep(...)` selectors flow naturally.
+
+## Advanced
+
+You can import the individual rule sets to compose your own:
+
+```js
+import {
+  baseRules,
+  GLOBAL_IGNORES,
+  logicalRules,
+  scssRules,
+  TAILWIND_AT_RULES,
+  tailwindAtRuleNoUnknown,
+  tailwindRules,
+} from '@maz-ui/stylelint-config'
+
+export default {
+  rules: {
+    ...baseRules,
+    ...tailwindRules,
+    ...tailwindAtRuleNoUnknown,
+  },
+}
+```
+
+## 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,
++  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 {

package/docs/src/guide/icon-set.md

@@ -13,21 +13,21 @@ All icons follow a consistent naming pattern:
 ## Find your icon
 
 <ComponentDemo>
-  <div class="maz-flex maz-flex-col maz-gap-4">
-    <div class="maz-flex maz-gap-2 maz-items-start">
-      <MazInput v-model="search" label="Search icon" @update:model-value="search = $event.trim()" :left-icon="SearchIcon" class="flex-1" :assistive-text="`${filteredIcons.length} icons found`" />
+  <div class="maz:flex maz:flex-col maz:gap-4">
+    <div class="maz:flex maz:gap-2 maz:items-start">
+      <MazInput v-model="search" label="Search icon" @update:model-value="search = $event.trim()" :start-icon="SearchIcon" class="flex-1" :assistive-text="`${filteredIcons.length} icons found`" />
     </div>
     <MazTabs v-model="currentTab">
       <MazTabsBar :items="tabs" />
     </MazTabs>
-    <div class="maz-grid maz-grid-cols-3 maz-gap-2">
-      <div v-for="icon in filteredIcons" :key="icon.name" class="maz-flex maz-flex-col maz-items-center maz-gap-3 maz-text-center maz-border maz-border-solid maz-border-divider maz-rounded maz-p-4 maz-truncate">
-        <component :is="icon.component" class="maz-size-8" />
-        <span class="maz-text-xs maz-text-muted maz-truncate">{{ icon.name }}</span>
-        <div class="maz-flex maz-flex-row maz-gap-2 maz-w-full">
-          <MazBtn v-tooltip="{ text: 'Copy Name', panelClass: 'maz-text-xs' }" class="maz-flex-1" size="xs" color="background" outlined @click="copyIcon(icon.name)" :icon="ClipboardDocumentIcon" />
-          <MazBtn v-tooltip="{ text: 'Copy Static Import', panelClass: 'maz-text-xs' }" class="maz-flex-1" size="xs" color="background" outlined @click="copyStaticImport(icon.name)" :icon="ClipboardDocumentListIcon" />
-          <MazBtn v-tooltip="{ text: 'Copy Lazy Import', panelClass: 'maz-text-xs' }" class="maz-flex-1" size="xs" color="background" outlined @click="copyLazyImport(icon.name)" :icon="ClipboardDocumentListIcon" />
+    <div class="maz:grid maz:grid-cols-3 maz:gap-2">
+      <div v-for="icon in filteredIcons" :key="icon.name" class="maz:flex maz:flex-col maz:items-center maz:gap-3 maz:text-center maz:border maz:border-solid maz:border-divider maz:rounded-md maz:p-4 maz:truncate">
+        <component :is="icon.component" class="maz:size-8" />
+        <span class="maz:text-xs maz:text-muted maz:truncate">{{ icon.name }}</span>
+        <div class="maz:flex maz:flex-row maz:gap-2 maz:w-full">
+          <MazBtn v-tooltip="{ text: 'Copy Name', panelClass: 'maz:text-xs' }" class="maz:flex-1" size="xs" color="surface" outlined @click="copyIcon(icon.name)" :icon="ClipboardDocumentIcon" />
+          <MazBtn v-tooltip="{ text: 'Copy Static Import', panelClass: 'maz:text-xs' }" class="maz:flex-1" size="xs" color="surface" outlined @click="copyStaticImport(icon.name)" :icon="ClipboardDocumentListIcon" />
+          <MazBtn v-tooltip="{ text: 'Copy Lazy Import', panelClass: 'maz:text-xs' }" class="maz:flex-1" size="xs" color="surface" outlined @click="copyLazyImport(icon.name)" :icon="ClipboardDocumentListIcon" />
         </div>
       </div>
     </div>

package/docs/src/guide/icons.md

@@ -5,8 +5,8 @@ A comprehensive collection of **860 beautiful SVG icons** ready for use in your
 ## Features
 
 - **860+ icons** - All icons are available [in the icon set page](./icon-set.md)
-- **Static & Lazy components** - Static (eagerly loaded) by default, lazy (async) when you need to optimize bundle size
-- **Multiple usage patterns** - Direct SVG files, Vue components, or auto-import
+- **Three component variants** - `static` (eager Vue component, default), `lazy` (async Vue component), and `raw` ✨ **(new in v5)** raw SVG strings for inlining without a Vue component or async chunk
+- **Multiple usage patterns** - Vue components, raw SVG strings, direct SVG files, or auto-import
 - **TypeScript support** - Full type definitions included
 - **Tree-shakeable** - Import only the icons you need
 - **Customizable** - Easy to style with CSS
@@ -101,15 +101,41 @@ import { MazUser } from '@maz-ui/icons/lazy/MazUser'
 You can also import individual icons directly for optimal tree-shaking:
 
 ```ts
-// Static icon (individual file)
-import { MazCheck } from '@maz-ui/icons/MazCheck'
+// Static Vue component (individual file)
+import { MazCheck } from '@maz-ui/icons/static/MazCheck'
 
-// Lazy icon (individual file)
+// Lazy Vue component (individual file)
 import { MazCheck } from '@maz-ui/icons/lazy/MazCheck'
+
+// Raw SVG string (individual file) — new in v5
+import { MazCheck } from '@maz-ui/icons/raw/MazCheck'
 ```
 
 :::
 
+#### Raw SVG strings (new in v5)
+
+Each icon is also exported as a **raw SVG string** under the `raw/` subpath. Pass it to `<MazIcon :icon="…" />` to inline the SVG without paying the cost of a Vue component or an async chunk — useful for icons rendered hundreds of times on a page (lists, tables) or for one-off `innerHTML` use.
+
+```vue
+<script setup lang="ts">
+import MazIcon from 'maz-ui/components/MazIcon'
+import { MazStar } from '@maz-ui/icons/raw/MazStar'
+</script>
+
+<template>
+  <MazIcon :icon="MazStar" />
+</template>
+```
+
+**When to use which variant:**
+
+| Variant | Bundle cost | Use case |
+| --- | --- | --- |
+| `static` | Vue component, eager | Default. Few icons per page, simplest path. |
+| `lazy` | Vue component, async chunk | Many icons but most off-screen at first paint. |
+| `raw` | Inline SVG string | Same icon repeated many times in a list/table; or you want zero component overhead. |
+
 **Benefits:**
 
 - ✅ Tree-shaking - Only bundled icons are included
@@ -167,6 +193,7 @@ export default defineConfig({
 </template>
 
 <style scoped>
+@reference "../../.vitepress/theme/main.css";
 .nav-icon {
   @apply w-6 h-6 text-gray-600 hover:text-blue-500 transition-colors cursor-pointer;
 }

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

@@ -26,12 +26,12 @@ The standard approach to initialize Maz-UI is the [`MazUi` plugin](./vue.md#inst
 import { MazUi } from 'maz-ui/plugins/maz-ui'
 import { mazUi } from '@maz-ui/themes/presets/mazUi'
 import { fr } from '@maz-ui/translations'
-import 'maz-ui/styles'
+import 'maz-ui/style.css'
 
 app.use(MazUi, {
   theme: {
     preset: mazUi,
-    strategy: 'hybrid',
+    strategy: 'runtime',
   },
   translations: {
     locale: 'fr',
@@ -74,7 +74,7 @@ import { fr } from '@maz-ui/translations'
 
 <template>
   <MazUiProvider
-    :theme="{ preset: mazUi, strategy: 'hybrid' }"
+    :theme="{ preset: mazUi, strategy: 'runtime' }"
     :translations="{ locale: 'fr', messages: { fr } }"
   >
     <!-- All Maz-UI components inside this subtree work as expected -->
@@ -99,7 +99,7 @@ The entire Maz-UI setup is now code-split into the Dashboard chunk.
 interface ThemeOptions {
   preset: ThemePreset              // Required - Theme preset (mazUi, ocean, pristine, obsidian, or custom)
   overrides?: ThemePresetOverrides // Partial overrides for colors, foundation, etc.
-  strategy?: 'runtime' | 'buildtime' | 'hybrid' // CSS generation strategy (default: 'hybrid')
+  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')
@@ -208,7 +208,7 @@ const locale = ref('fr')
   <MazUiProvider
     :theme="{
       preset: mazUi,
-      strategy: 'hybrid',
+      strategy: 'runtime',
       colorMode: 'auto',
     }"
     :translations="{
@@ -217,7 +217,7 @@ const locale = ref('fr')
       messages: { fr },
     }"
   >
-    <div class="maz-bg-background maz-text-foreground maz-p-4">
+    <div class="maz:bg-surface maz:text-foreground maz:p-4">
       <h1>My Dashboard</h1>
       <MazBtn color="primary">Action</MazBtn>
       <MazInput placeholder="Search..." />

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

@@ -105,7 +105,7 @@ npm uninstall dropzone
 ```typescript
 // main.ts
 import { createApp } from 'vue'
-import 'maz-ui/css/main.css'
+import 'maz-ui/style.css'
 import App from './App.vue'
 
 createApp(App).mount('#app')
@@ -121,7 +121,7 @@ import { mazUi } from '@maz-ui/themes/presets'
 import { fr } from '@maz-ui/translations'
 
 // Import styles before your CSS
-import 'maz-ui/styles'
+import 'maz-ui/style.css'
 import './style.css'
 
 import App from './App.vue'
@@ -173,7 +173,7 @@ export default defineNuxtConfig({
     // New configuration API
     theme: {
       preset: 'maz-ui',
-      strategy: 'hybrid',
+      strategy: 'runtime',
       darkModeStrategy: 'class',
     },
     translations: {