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

package/docs/src/guide/nuxt.md

@@ -20,7 +20,7 @@ Check out the documentation of [@maz-ui/mcp](./mcp.md)
 - **Zero Configuration** - Works out of the box with sensible defaults
 - **Advanced Theming** - Built-in dark mode, custom themes, and CSS variables
 - **Auto-Import Everything** - Components, composables, and directives automatically available
-- **Performance Optimized** - Tree-shaking, lazy loading, and hybrid CSS strategies
+- **Performance Optimized** - Tree-shaking, lazy loading, and SSR-friendly CSS injection
 - **Developer Experience** - TypeScript support, DevTools integration, and IntelliSense
 - **Production Ready** - SSR/SSG support with client-side hydration
 
@@ -75,7 +75,7 @@ const { toggleDarkMode, isDark } = useTheme()
 </script>
 
 <template>
-  <div class="maz-bg-background p-8 maz-text-foreground">
+  <div class="maz:bg-surface p-8 maz:text-foreground">
     <!-- Components are auto-imported -->
     <MazBtn color="primary" @click="start">
       Start timer ({{ remainingTime }}ms)
@@ -119,13 +119,13 @@ export default defineNuxtConfig({
 
     // CSS & Styling
     css: {
-      injectMainCss: true, // Auto-inject Maz-UI styles
+      injectCss: true, // Auto-inject Maz-UI styles
     },
 
     // Theming System
     theme: {
-      preset: 'maz-ui', // 'maz-ui' | 'dark' | 'ocean' | custom object
-      strategy: 'hybrid', // 'runtime' | 'buildtime' | 'hybrid'
+      preset: 'maz-ui', // 'maz-ui' | 'pristine' | 'ocean' | 'obsidian' | 'nova' | custom object
+      strategy: 'runtime', // 'runtime' | 'buildtime'
       darkModeStrategy: 'class', // 'class' | 'media' | 'auto'
       overrides: {
         colors: {
@@ -190,7 +190,7 @@ const general = {
   // Add prefix to all auto-imported composables
   autoImportPrefix: 'Maz', // only for composables, generates useMazToast, useMazTheme, etc.
 
-  // Default icon path for <MazIcon name="..." />
+  // Default icon path for <MazIcon icon="..." />
   defaultMazIconPath: '/icons',
 
   // Enable Nuxt DevTools integration
@@ -203,7 +203,7 @@ const general = {
 ```ts
 const css = {
   // Auto-inject Maz-UI base styles
-  injectMainCss: true,
+  injectCss: true,
 }
 ```
 
@@ -222,13 +222,13 @@ const theme = {
       light: {
         primary: '220 100% 50%',
         secondary: '220 14% 96%',
-        background: '0 0% 100%',
+        surface: '0 0% 100%',
         foreground: '222 84% 5%',
       },
       dark: {
         primary: '220 100% 70%',
         secondary: '220 14% 4%',
-        background: '222 84% 5%',
+        surface: '222 84% 5%',
         foreground: '210 40% 98%',
       }
     },
@@ -242,46 +242,32 @@ const theme = {
   colorMode: 'auto', // 'light' | 'dark' | 'auto'
 
   // CSS generation strategy
-  strategy: 'hybrid', // 'runtime' | 'buildtime' | 'hybrid' (recommended)
+  strategy: 'runtime', // 'runtime' (recommended) | 'buildtime'
 
   // Dark mode handling
   darkModeStrategy: 'class', // 'class' | 'media' | 'auto'
+
+  // Persist the active preset name in the `maz-preset` cookie so the
+  // user's last-used theme is restored on reload. Default: true.
+  persistPreset: true,
 }
 ```
 
 ## Theme Strategies Explained
 
-### Hybrid (Recommended)
-
-The hybrid strategy combines optimal performance with zero FOUC (Flash of Unstyled Content):
-
-- **Critical CSS injected immediately** - Essential theme variables are inlined on server side to prevent visual flash (on client side if SSR is not enabled)
-- **Full CSS loaded asynchronously** - Complete theme CSS is injected on client side using `requestIdleCallback` with 100ms timeout, avoiding main thread blocking
-- **SSR-optimized** - When SSR is enabled, critical CSS is inlined during server rendering for instant theming
-
-```ts
-export default defineNuxtConfig({
-  mazUi: {
-    theme: {
-      strategy: 'hybrid' // Recommended for most use cases
-    }
-  }
-})
-```
-
-### Runtime
+### Runtime (Recommended)
 
-Immediate CSS injection strategy:
+The full theme CSS is generated and injected synchronously on first paint:
 
-- **Critical CSS on server side** - Essential theme variables are injected during SSR
-- **Full CSS on client side** - Complete theme CSS is injected immediately on client-side hydration
-- **⚠️ Performance impact** - Immediate injection can block the main thread during hydration
+- **No FOUC** - The full stylesheet is rendered in the document head before the first paint
+- **SSR-friendly** - On Nuxt SSR, the CSS is inlined via `useHead` during server rendering and re-used on the client
+- **Dynamic** - `useTheme().updateTheme(...)` re-injects the new CSS on the fly
 
 ```ts
 export default defineNuxtConfig({
   mazUi: {
     theme: {
-      strategy: 'runtime' // Use when you need immediate full styling
+      strategy: 'runtime' // Recommended for most use cases
     }
   }
 })
@@ -306,12 +292,6 @@ export default defineNuxtConfig({
 })
 ```
 
-::: info SSR Behavior
-The behavior of `hybrid` and `runtime` strategies depends on your Nuxt SSR configuration:
-- **With SSR**: Critical CSS is injected during server rendering, full CSS handled on client
-- **SPA mode**: All CSS injection happens on client-side as described in the [themes documentation](/guide/themes#rendering-strategies)
-:::
-
 ### Components
 
 ```ts
@@ -403,14 +383,17 @@ export const customTheme = definePreset({
   foundation: {
     'base-font-size': '14px',
     'font-family': `Manrope, sans-serif, system-ui, -apple-system`,
-    'radius': '0.7rem',
+    'space': '0.25rem',
     'border-width': '0.0625rem',
   },
+  scales: {
+    rounded: { md: '0.7rem' },
+  },
   colors: {
     light: {
       primary: '350 100% 50%', // Custom pink
       secondary: '350 14% 96%',
-      background: '0 0% 100%',
+      surface: '0 0% 100%',
       foreground: '222 84% 5%',
       muted: '210 40% 96%',
       accent: '210 40% 90%',
@@ -422,7 +405,7 @@ export const customTheme = definePreset({
     dark: {
       primary: '350 100% 70%',
       secondary: '350 14% 4%',
-      background: '222 84% 5%',
+      surface: '222 84% 5%',
       foreground: '210 40% 98%',
       muted: '217 33% 17%',
       accent: '217 33% 17%',
@@ -439,7 +422,7 @@ export default defineNuxtConfig({
   mazUi: {
     theme: {
       preset: customTheme,
-      strategy: 'hybrid',
+      strategy: 'runtime',
     }
   }
 })

package/docs/src/guide/resolvers.md

@@ -450,7 +450,7 @@ function saveUser() {
             size="sm"
             @click="refreshData"
           >
-            <MazIcon name="refresh" />
+            <MazIcon icon="/refresh.svg" />
           </MazBtn>
         </div>
       </template>
@@ -626,7 +626,7 @@ MazComponentsResolver({
 
 ```vue
 <script setup lang="ts">
-import { formatCurrency, debounce } from 'maz-ui'
+import { formatCurrency, debounce } from '@maz-ui/utils'
 import { MazBtn, MazCard, MazInput } from 'maz-ui/components'
 import { useTheme, useToast } from 'maz-ui/composables'
 import { vTooltip } from 'maz-ui/directives'

package/docs/src/guide/tailwind.md

@@ -0,0 +1,154 @@
+---
+title: Tailwind CSS integration (optional)
+description: Expose your active maz-ui theme tokens to your own Tailwind v4 setup
+---
+
+# {{ $frontmatter.title }}
+
+::: tip This page is optional
+Maz-UI works without Tailwind. You install the package, import `maz-ui/style.css`, and components render with the preset you chose — nothing else is required.
+
+This page is for consumers who **already have a Tailwind v4 setup of their own** and want their own utilities (`bg-primary`, `rounded-md`, `tab-m:flex`, …) to pull from the active maz-ui theme.
+:::
+
+## Setup
+
+In your Tailwind entry, add **one import** under `@import "tailwindcss"`:
+
+```css
+/* src/tailwind.css (or wherever your Tailwind entry lives) */
+@import "tailwindcss";
+@import "maz-ui/tailwindcss/theme.css";
+```
+
+That's it. Your Tailwind utilities now resolve to the currently-active maz-ui theme. Switch presets at runtime via `useTheme().updateTheme()` and every utility reflows automatically — no rebuild.
+
+**Prerequisites:** `tailwindcss@^4.2`, `@tailwindcss/vite` or `@tailwindcss/postcss`, and `@maz-ui/themes` initialized in your app.
+
+## What you get
+
+### Brand & state colors
+
+Each one comes with `bg-X`, `text-X`, `border-X`, an 11-step scale (`bg-X-50` → `bg-X-950`), and a paired foreground (`text-X-foreground`) suitable for text on top of that color.
+
+| Color | Use case |
+| --- | --- |
+| `primary` | brand primary |
+| `secondary` | brand secondary |
+| `accent` | brand accent |
+| `success` | success state |
+| `warning` | warning state |
+| `destructive` | error / danger state |
+| `info` | informational state |
+| `contrast` | neutral high-contrast surface (text/dark UI) |
+
+```html
+<div class="bg-primary text-primary-foreground p-4">Hello</div>
+<div class="bg-success-100 text-success-700">Saved!</div>
+```
+
+### Neutral & surface colors
+
+These don't have a foreground variant — they're typically used for backgrounds, text, borders or overlays directly. Each one still ships an 11-step scale.
+
+| Color | Use case |
+| --- | --- |
+| `surface` | page / container backgrounds |
+| `foreground` | body text |
+| `divider` | borders, separators |
+| `muted` | secondary text, placeholders |
+| `overlay` | modal backdrops, scrims |
+| `shadow` | shadow tint (used by `shadow-*` utilities) |
+
+```html
+<p class="text-foreground">Body text</p>
+<p class="text-muted">Secondary text</p>
+<hr class="border-divider" />
+```
+
+### Per-component surfaces
+
+Two extra background tokens that follow the active preset's `components` block — useful when your custom components want to match the look of `MazContainer` / `MazInput`:
+
+- `bg-container` — same as `MazContainer`'s background
+- `bg-input` — same as `MazInput`'s background (different in dark mode by default)
+
+### Spacing
+
+`--spacing` is sourced from the preset's `foundation.space` (default `0.25rem`), so every Tailwind spacing utility (`p-1`, `gap-2`, `w-4`, …) rescales when the preset changes.
+
+### Radius
+
+The whole `rounded-*` scale is preset-controlled via `scales.rounded`:
+
+| Class | Source |
+| --- | --- |
+| `rounded-xs` … `rounded-3xl` | `var(--maz-rounded-{xs..3xl})` |
+
+### Shadows
+
+| Class | Use case |
+| --- | --- |
+| `shadow-sm`, `shadow-md`, `shadow-lg`, `shadow-xl` | standard scale (preset-controlled) |
+| `shadow-elevation` | elevated surfaces — cards, popovers |
+
+### Breakpoints
+
+Added **on top of** Tailwind's defaults (`sm`/`md`/`lg`/`xl`/`2xl` still work):
+
+| Variant | Min-width |
+| --- | --- |
+| `mob-s:` | 320px |
+| `mob-m:` | 425px |
+| `mob-l:` | 576px |
+| `tab-s:` | 640px |
+| `tab-m:` | 768px |
+| `tab-l:` | 992px |
+| `lap-s:` | 1024px |
+| `lap-m:` | 1280px |
+| `lap-l:` | 1366px |
+| `lap-xl:` | 1440px |
+| `lap-2xl:` | 1680px |
+| `lap-3xl:` | 1920px |
+
+### Typography
+
+| Class | Source |
+| --- | --- |
+| `font-sans` | `var(--maz-font-family)` |
+| `font-mono` | `var(--maz-font-mono-stack)` |
+| `font-display` | `var(--maz-font-display-stack)` |
+
+Default border width and the default transition duration also follow the preset (`var(--maz-border-width)`, `var(--maz-motion-normal)`).
+
+## Using `@apply` inside Vue SFC `<style>` blocks
+
+Tailwind v4's Vite plugin processes each SFC `<style>` block in isolation. If your SFCs use `@apply`, the block must start with a `@reference` directive pointing at your Tailwind entry:
+
+```vue
+<style scoped>
+@reference "../tailwind.css";
+
+.card {
+  @apply flex gap-4 rounded-md bg-surface p-4 shadow-elevation;
+}
+</style>
+```
+
+One line per SFC. Maz-ui components already ship this internally.
+
+## Migrating from Tailwind v3
+
+If your app was on Tailwind v3, run the official Tailwind upgrade tool first — it handles 95% of the v3 → v4 transition (utility renames, `@apply !important` syntax, `tailwind.config.js` → CSS-first):
+
+```bash
+npx @tailwindcss/upgrade
+```
+
+Then apply the maz-ui-specific changes from the [v4 → v5 migration guide](./migration-v5.md#advanced-you-had-your-own-tailwind-setup).
+
+## See also
+
+- [Theming](./themes.md) — create a custom preset, switch themes at runtime
+- [Migration v4 → v5](./migration-v5.md) — library-level changes
+- [Browser Support](./browser-support.md) — exact minimum versions required by Tailwind v4