git:20251229.a45cbc5 to git:20251229.6bb0348

96 added, 19 removed. Audit B to B.

---

name: maz-ui

description: Maz-UI v4 - Modern Vue & Nuxt component library with 50+ standalone components, composables, directives, theming, i18n, and SSR support. Use when building Vue/Nuxt applications with forms, dialogs, tables, animations, or need responsive design system with dark mode.

---

# Maz-UI v4 - Vue & Nuxt Component Library

Maz-UI is a comprehensive, standalone component library for Vue 3 and Nuxt 3 applications, offering 50+ production-ready components, powerful theming, internationalization, and exceptional developer experience.

- **Latest Version**: 4.3.2 (as of 2025-12-14)

+ **Latest Version**: 4.3.3 (as of 2025-12-29)

**Package**: `maz-ui` | `@maz-ui/nuxt` | `@maz-ui/themes` | `@maz-ui/translations` | `@maz-ui/icons`

## Quick Start

### Vue 3 Installation

```bash

# Install core packages

pnpm add maz-ui @maz-ui/themes

# Or with npm

npm install maz-ui @maz-ui/themes

```

**Setup** in `main.ts`:

```typescript

import { createApp } from 'vue'

import { MazUi } from 'maz-ui/plugins/maz-ui'

import { mazUi } from '@maz-ui/themes'

import { en } from '@maz-ui/translations'

import 'maz-ui/styles'

import App from './App.vue'

const app = createApp(App)

app.use(MazUi, {

theme: { preset: mazUi },

translations: { messages: { en } }

})

app.mount('#app')

```

**Use Components**:

```vue

import MazBtn from 'maz-ui/components/MazBtn'

import MazInput from 'maz-ui/components/MazInput'

import { ref } from 'vue'

const inputValue = ref('')

</script>

<MazBtn color="primary">Submit</MazBtn>

</template>

```

### Nuxt 3 Installation

```bash

# Install Nuxt module

pnpm add @maz-ui/nuxt

```

**Setup** in `nuxt.config.ts`:

```typescript

export default defineNuxtConfig({

modules: ['@maz-ui/nuxt']

// That's it! Auto-imports enabled 🎉

})

```

**Use Components** (no imports needed):

```vue

// Auto-imported composables

const theme = useTheme()

const toast = useToast()

const inputValue = ref('')

</script>

Submit

</MazBtn>

</template>

```

## Core Capabilities

### 🎨 Components (50+)

**Forms & Inputs**:

- `MazInput` - Text input with validation states

- `MazSelect` - Dropdown select

- `MazTextarea` - Multi-line text input

- `MazCheckbox` - Checkbox with label

- `MazRadio` - Radio buttons

- `MazSwitch` - Toggle switch

- `MazSlider` - Range slider

- `MazInputPhoneNumber` - International phone input with validation

- `MazInputCode` - Code/PIN input

- `MazInputPrice` - Currency input with formatting

- `MazInputTags` - Tag/chip input

- `MazDatePicker` - Date picker

- `MazChecklist` - Searchable checklist

**UI Elements**:

- `MazBtn` - Button with variants

- `MazCard` - Container card

- `MazBadge` - Label badge

- `MazAvatar` - User avatar

- `MazIcon` - Icon display

- `MazSpinner` - Loading spinner

- `MazTable` - Data table with sorting/pagination

- `MazTabs` - Tab navigation

- `MazStepper` - Step indicator

- `MazPagination` - Pagination controls

**Overlays & Modals**:

- `MazDialog` - Modal dialog

- `MazDialogConfirm` - Confirmation dialog

- `MazDrawer` - Slide-out drawer

- `MazBottomSheet` - Mobile bottom sheet

- `MazBackdrop` - Overlay backdrop

- `MazPopover` - Floating popover

- `MazDropdown` - Dropdown menu

**Feedback & Animation**:

- `MazFullscreenLoader` - Loading overlay

- `MazLoadingBar` - Progress bar

- `MazCircularProgressBar` - Circular progress

- `MazReadingProgressBar` - Reading progress indicator

- `MazAnimatedText` - Text animations

- `MazAnimatedElement` - Element animations

- `MazAnimatedCounter` - Number counter animation

- `MazCardSpotlight` - Card with spotlight effect

**Layout & Display**:

- `MazCarousel` - Image carousel

- `MazGallery` - Image gallery

- `MazAccordion` - Collapsible panels

- `MazExpandAnimation` - Expand/collapse animation

- `MazLazyImg` - Lazy-loaded image

- `MazPullToRefresh` - Pull-to-refresh gesture

- `MazChart` - Chart.js integration

### 🔧 Composables (14+)

**Theming**:

- `useTheme()` - Theme and dark mode management

**Translations**:

- `useTranslations()` - i18n management

**UI Interactions**:

- `useToast()` - Toast notifications

- `useDialog()` - Programmatic dialogs

- `useWait()` - Loading states

**Utilities**:

- `useBreakpoints()` - Responsive breakpoints

- `useWindowSize()` - Window dimensions

- `useTimer()` - Timer/countdown

- `useFormValidator()` - Form validation (Valibot)

- `useIdleTimeout()` - Idle detection

- `useUserVisibility()` - Page visibility

- `useSwipe()` - Swipe gestures

- `useReadingTime()` - Reading time calculation

- `useStringMatching()` - String utilities

- `useDisplayNames()` - Localized display names

### 📌 Directives (5)

- `v-tooltip` - Tooltips

- `v-click-outside` - Outside click detection

- `v-lazy-img` - Lazy loading

- `v-zoom-img` - Image zoom

- `v-fullscreen-img` - Fullscreen image viewer

### 🔌 Plugins (4)

- **AOS** - Animations on scroll

- **Dialog** - Template-free dialogs

- **Toast** - Notifications

- **Wait** - Global loading states

## Key Features

✅ **Standalone Components** - Import only what you need, zero bloat

✅ **SSR/SSG Ready** - Full Nuxt 3 support with auto-imports

✅ **TypeScript-First** - Complete type safety out of the box

✅ **Dark Mode** - Built-in dark/light theme switching

✅ **Tree-Shakable** - Optimized bundle sizes

✅ **Responsive** - Mobile-first design

✅ **Accessible** - ARIA-compliant components

✅ **Themeable** - 4 built-in presets + custom themes

✅ **i18n** - Multi-language support with @maz-ui/translations

✅ **840+ Icons** - Optimized SVG icon library (@maz-ui/icons)

+ ## Template Structure

+ Maz-UI provides **two sets of production-ready templates** organized by framework:

+ ### Vue 3 + Vite Templates (`templates/vue/`)

+ - ✅ Pure Vue 3 with Vite

+ - ✅ Uses standard `fetch()` API

+ - ✅ Explicit imports for all dependencies

+ - ✅ No framework-specific dependencies

+ - ✅ Optimized for SPA development

+ **Use when**: Building Vue 3 applications with Vite

+ **Available templates**:

+ - `setup/vite.config.ts` - Vite configuration with auto-imports

+ - `components/form-basic.vue` - Basic form validation

+ - `components/form-multi-step.vue` - Multi-step form with stepper

+ - `components/dialog-confirm.vue` - Dialog confirmation patterns

+ - `components/data-table.vue` - Data table with pagination, search, sort

+ ### Nuxt 3 Templates (`templates/nuxt/`)

+ - ✅ Nuxt 3 optimized

+ - ✅ Uses `$fetch` (Nuxt's ofetch wrapper)

+ - ✅ Leverages auto-imports for components and composables

+ - ✅ Showcases SSR patterns and server routes

+ - ✅ Optimized for full-stack Nuxt development

+ **Use when**: Building Nuxt 3 applications

+ **Available templates**:

+ - `setup/nuxt.config.ts` - Nuxt configuration with Maz-UI module

+ - `components/form-basic.vue` - Basic form validation (auto-imports)

+ - `components/form-multi-step.vue` - Multi-step form (auto-imports)

+ - `components/dialog-confirm.vue` - Dialog patterns (auto-imports)

+ - `components/data-table.vue` - Data table with reactive data loading

+ Both template sets:

+ - ✅ Fix all validation, type inference, and pagination issues

+ - ✅ Follow framework best practices

+ - ✅ Are production-ready and fully tested

+ - ✅ Include setup configs and component examples

## When to Load References

- Load reference files based on what you're implementing:

+ Load reference files based on what you're implementing. All 21 reference files are grouped by purpose for quick discovery:

- ### Components

- - **`references/components-forms.md`** - When building forms, inputs, validation, phone numbers, dates, file uploads

- - **`references/components-feedback.md`** - When adding toasts, dialogs, loading states, progress indicators

- - **`references/components-navigation.md`** - When implementing tabs, steppers, pagination, breadcrumbs

- - **`references/components-layout.md`** - When working with cards, grids, containers, spacing

+ ### Components (4 files)

+ - **`components-forms.md`** - Building forms, inputs, validation, phone numbers, dates, file uploads, MazInput, MazSelect, MazCheckbox, MazDatePicker

+ - **`components-feedback.md`** - Adding loaders, progress bars, animations, toasts, MazFullscreenLoader, MazCircularProgressBar, MazAnimatedText, MazCardSpotlight

+ - **`components-navigation.md`** - Implementing tabs, steppers, pagination, MazTabs, MazStepper, MazPagination

+ - **`components-layout.md`** - Working with cards, drawers, carousels, galleries, MazCard, MazAccordion, MazDrawer, MazCarousel, MazGallery

- ### Setup & Configuration

- - **`references/setup-vue.md`** - When setting up Maz-UI in Vue 3 project (with/without auto-imports)

- - **`references/setup-nuxt.md`** - When integrating with Nuxt 3, configuring module options

- - **`references/theming.md`** - When customizing themes, dark mode, color schemes, CSS variables

- - **`references/translations.md`** - When implementing multi-language support, custom locales

+ ### Setup & Configuration (2 files)

+ - **`setup-vue.md`** - Setting up Maz-UI in Vue 3 project, auto-imports with resolvers, Vite/Webpack configuration, performance optimization

+ - **`setup-nuxt.md`** - Integrating with Nuxt 3, module configuration, theme strategies (hybrid/buildtime/runtime), SSR/SSG considerations

- ### Advanced Features

- - **`references/composables.md`** - When using composable APIs (useToast, useTheme, useBreakpoints, etc.)

- - **`references/directives.md`** - When adding directives (tooltip, click-outside, lazy-img)

- - **`references/plugins.md`** - When enabling plugins (AOS, dialog, toast, wait)

- - **`references/icons.md`** - When using @maz-ui/icons package

- - **`references/migration-v4.md`** - When upgrading from Maz-UI v3 to v4

- - **`references/troubleshooting.md`** - When encountering errors, debugging issues

+ ### Core Features (5 files)

+ - **`composables.md`** - Using all 14 composables: useToast, useTheme, useBreakpoints, useFormValidator, useTimer, useDialog, useTranslations, etc.

+ - **`directives.md`** - Adding directives: v-tooltip, v-click-outside, v-lazy-img, v-zoom-img, v-fullscreen-img

+ - **`plugins.md`** - Enabling plugins: AOS (animations on scroll), Dialog, Toast, Wait (loading states)

+ - **`resolvers.md`** - **CRITICAL**: Auto-import configuration with MazComponentsResolver, MazDirectivesResolver, MazModulesResolver for optimal tree-shaking

+ - **`translations.md`** - Implementing multi-language support (8 built-in languages), custom locales, lazy loading, SSR hydration

+ ### Tools & Integrations (3 files)

+ - **`icons.md`** - Using @maz-ui/icons package (840+ icons), MazIcon component, icon sizing, colors, animations

+ - **`cli.md`** - Using @maz-ui/cli (legacy v3), theme configuration, migration to v4 themes system

+ - **`mcp.md`** - Setting up Model Context Protocol server for AI assistant integration (Claude Code, Claude Desktop, Cursor, Windsurf)

+ ### Advanced Topics (5 files)

+ - **`theming.md`** - Customizing themes, dark mode, color schemes, CSS variables, 4 built-in presets (mazUi, ocean, pristine, obsidian)

+ - **`performance.md`** - Bundle optimization, tree-shaking, lazy loading, code splitting, reducing bundle size from ~300KB to ~15KB

+ - **`ssr-ssg.md`** - **Comprehensive SSR/SSG guide**: theme strategies, critical CSS, hydration prevention, dark mode without flash, static site generation

+ - **`accessibility.md`** - WCAG 2.1 AA compliance, keyboard navigation, screen reader support, ARIA attributes, color contrast

+ - **`form-validation.md`** - useFormValidator deep dive, Valibot integration, 5 validation modes (lazy, aggressive, eager, blur, progressive), TypeScript type inference

+ ### Troubleshooting (2 files)

+ - **`migration-v4.md`** - Upgrading from Maz-UI v3 to v4, breaking changes, API changes, component renames, TypeScript updates

+ - **`troubleshooting.md`** - Debugging errors, common issues, configuration problems, SSR hydration, bundle size issues

## Top 6 Common Errors

### 1. Missing Theme Plugin Error

**Error**: `"useTheme must be used within MazUi plugin installation"`

**Cause**: MazUi plugin not installed or theme composable disabled

**Fix**:

```typescript

// Vue

app.use(MazUi, { theme: { preset: mazUi } })

// Nuxt

export default defineNuxtConfig({

mazUi: {

composables: { useTheme: true },

theme: { preset: 'maz-ui' }

}

})

```

### 2. Auto-Import Not Working (Nuxt)

**Error**: Components/composables not found despite Nuxt module installed

**Cause**: Module not properly configured or cache issue

**Fix**:

```bash

# Clear Nuxt cache

rm -rf .nuxt node_modules/.cache

pnpm install

```

**Verify** `nuxt.config.ts`:

```typescript

export default defineNuxtConfig({

modules: ['@maz-ui/nuxt']

})

```

### 3. Styles Not Applied

**Error**: Components render but have no styling

**Cause**: CSS not imported

**Fix Vue**:

```typescript

import 'maz-ui/styles' // Add this line

```

**Fix Nuxt**:

```typescript

export default defineNuxtConfig({

mazUi: {

css: { injectMainCss: true } // Ensure this is true

}

})

```

### 4. TypeScript Errors with Components

**Error**: `Cannot find module 'maz-ui/components/MazBtn'`

**Cause**: Missing type definitions or incorrect import path

**Fix**:

```typescript

// Correct import

import MazBtn from 'maz-ui/components/MazBtn'

// Or with auto-import (Nuxt)

// No import needed, just use <MazBtn>

```

**Ensure** `tsconfig.json` includes:

```json

{

"compilerOptions": {

"types": ["maz-ui/types"]

}

```

### 5. Phone Input Country Detection Fails

**Error**: `MazInputPhoneNumber` doesn't detect country or shows wrong flag

**Cause**: Missing libphonenumber-js dependency or country data not loaded

**Fix**:

```bash

# Install peer dependency

pnpm add libphonenumber-js

```

```vue

<MazInputPhoneNumber

v-model="phone"

default-country-code="US"

preferred-countries="['US', 'CA', 'GB']"

```

### 6. Translations Not Loading or Showing Raw Keys

**Error**: Translation keys showing as raw strings like `inputPhoneNumber.phoneInput.example` instead of translated text

**Causes**:

- Missing locale import

- Lazy loading not awaited properly

- Language file failed to load asynchronously

- Missing `preloadFallback` configuration

- SSR hydration mismatch (Nuxt)

**Fix Vue** (Immediate Loading):

```typescript

import { fr } from '@maz-ui/translations'

app.use(MazUi, {

translations: {

locale: 'fr',

fallbackLocale: 'en',

preloadFallback: true,

messages: { fr } // Import immediately

}

})

```

**Fix Vue** (Lazy Loading):

```typescript

app.use(MazUi, {

translations: {

locale: 'fr',

preloadFallback: true, // Ensure fallback is preloaded

messages: {

fr: () => import('@maz-ui/translations/locales/fr')

}

})

// In component: ALWAYS use await

const { setLocale } = useTranslations()

await setLocale('fr') // Don't forget await!

```

**Fix Nuxt** (Avoid Hydration):

```typescript

import { fr } from '@maz-ui/translations'

export default defineNuxtConfig({

mazUi: {

translations: {

locale: 'fr',

preloadFallback: true,

messages: {

// CRITICAL: Provide initial locale immediately (not as function)

fr, // SSR requires immediate load

// Other languages can be lazy

es: () => import('@maz-ui/translations/locales/es')

}

})

```

**Error Handling**:

```vue

const { setLocale } = useTranslations()

const toast = useToast()

async function switchLanguage(locale) {

try {

await setLocale(locale)

toast.success(`Language changed to ${locale}`)

} catch (error) {

console.error('Translation loading error:', error)

toast.error('Failed to load translations')

}

</script>

```

**Learn More**: Load `references/translations.md` for comprehensive i18n setup, lazy loading strategies, and production patterns.

## Tree-Shaking Best Practices

**Direct Imports** (Most Optimized):

```typescript

// ✅✅✅ Best - smallest bundle

import MazBtn from 'maz-ui/components/MazBtn'

import { useToast } from 'maz-ui/composables/useToast'

import { vClickOutside } from 'maz-ui/directives/vClickOutside'

```

**Index Imports** (Good):

```typescript

// ✅ Good - tree-shakable

import { MazBtn, MazInput } from 'maz-ui/components'

import { useToast, useTheme } from 'maz-ui/composables'

```

**Avoid** (Not Tree-Shakable):

```typescript

// ❌ Imports everything

import * as MazUI from 'maz-ui'

```

+ ## Advanced Topics

+ ### Performance Optimization

+ Maz-UI can be optimized from ~300KB to ~15KB through strategic imports and tree-shaking. Use auto-import resolvers (`MazComponentsResolver`, `MazDirectivesResolver`, `MazModulesResolver`) for optimal bundle size, lazy load components with dynamic imports, and split code by feature. Load **`performance.md`** for comprehensive bundle optimization strategies.

+ ### SSR & SSG

+ Full server-side rendering and static site generation support with three theme strategies: **hybrid** (critical CSS injection, no FOUC), **buildtime** (smallest bundle, static themes), and **runtime** (full theme switching, larger bundle). Prevent hydration mismatches by wrapping client-only components in `<ClientOnly>`. Load **`ssr-ssg.md`** for critical CSS patterns, dark mode without flash, and SSR/SSG checklist.

+ ### Accessibility

+ All Maz-UI components are WCAG 2.1 AA compliant with proper ARIA attributes, keyboard navigation, focus management, and screen reader support. Components include semantic HTML, color contrast ratios >4.5:1, and accessible form validation. Load **`accessibility.md`** for keyboard shortcuts, focus trap patterns, and accessibility testing checklist.

+ ### Form Validation

+ The `useFormValidator()` composable integrates with Valibot for type-safe schema validation with full TypeScript inference. Supports 5 validation modes (lazy, aggressive, eager, blur, progressive), async validation, custom validators, and real-time error messages. Load **`form-validation.md`** for comprehensive validation patterns and real-world examples.

+ ### Auto-Import Resolvers

+ **Critical for tree-shaking**: Use `unplugin-vue-components` and `unplugin-auto-import` with Maz-UI resolvers to import only what you use. Reduces bundle size by 60-90% compared to global imports. Configure prefix handling to avoid naming conflicts with other libraries. Load **`resolvers.md`** for complete resolver configuration and troubleshooting.

## Progressive Disclosure Summary

This SKILL.md provides:

1. **Quick Start** - Get running in <5 minutes

2. **Core Capabilities** - Overview of all features

3. **Error Prevention** - Top 5 common issues solved

For detailed implementation:

- Load **reference files** based on your current task (see "When to Load References" above)

- Each reference contains comprehensive guides, code examples, and advanced configurations

- References are organized by domain (components, setup, theming, etc.) for easy navigation

## Package Ecosystem

- **maz-ui** - Core component library

- **@maz-ui/nuxt** - Nuxt 3 module with auto-imports

- **@maz-ui/themes** - Theming system and presets

- **@maz-ui/translations** - i18n support (8 built-in languages: en, fr, es, de, it, pt, ja, zh-CN)

- **@maz-ui/icons** - 840+ optimized SVG icons

- **@maz-ui/mcp** - AI agent documentation server

## Official Resources

- **Documentation**: https://maz-ui.com

- **GitHub**: https://github.com/LouisMazel/maz-ui

- **NPM**: https://www.npmjs.com/package/maz-ui

- **Discord**: https://discord.gg/maz-ui

- **Changelog**: https://github.com/LouisMazel/maz-ui/blob/master/CHANGELOG.md