OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add secondsky/claude-skills --skill maz-ui
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.
npx skills add secondsky/claude-skills --skill maz-ui
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.9.3 (as of 2026-08-03)
Package: maz-ui | @maz-ui/nuxt | @maz-ui/themes | @maz-ui/translations | @maz-ui/icons
Setup in main.ts:
Use Components:
Setup in nuxt.config.ts:
Use Components (no imports needed):
Forms & Inputs:
MazInput - Text input with validation statesMazSelect - Dropdown selectMazTextarea - Multi-line text inputMazCheckbox - Checkbox with labelMazRadio - Radio buttonsMazSwitch - Toggle switchMazSlider - Range sliderMazInputPhoneNumber - International phone input with validationMazInputCode - Code/PIN inputMazInputPrice - Currency input with formattingMazInputTags - Tag/chip inputMazDatePicker - Date pickerMazChecklist - Searchable checklistUI Elements:
MazBtn - Button with variantsMazCard - Container cardMazBadge - Label badgeMazAvatar - User avatarMazIcon - Icon displayMazSpinner - Loading spinnerMazTable - Data table with sorting/paginationMazTabs - Tab navigationMazStepper - Step indicatorMazPagination - Pagination controlsOverlays & Modals:
MazDialog - Modal dialogMazDialogConfirm - Confirmation dialogMazDrawer - Slide-out drawerMazBottomSheet - Mobile bottom sheetMazBackdrop - Overlay backdropMazPopover - Floating popoverMazDropdown - Dropdown menuFeedback & Animation:
MazFullscreenLoader - Loading overlayMazLoadingBar - Progress barMazCircularProgressBar - Circular progressMazReadingProgressBar - Reading progress indicatorMazAnimatedText - Text animationsMazAnimatedElement - Element animationsMazAnimatedCounter - Number counter animationMazCardSpotlight - Card with spotlight effectLayout & Display:
MazCarousel - Image carouselMazGallery - Image galleryMazAccordion - Collapsible panelsMazExpandAnimation - Expand/collapse animationMazLazyImg - Lazy-loaded imageMazPullToRefresh - Pull-to-refresh gestureMazChart - Chart.js integrationTheming:
useTheme() - Theme and dark mode managementTranslations:
useTranslations() - i18n managementUI Interactions:
useToast() - Toast notificationsuseDialog() - Programmatic dialogsuseWait() - Loading statesUtilities:
useBreakpoints() - Responsive breakpointsuseWindowSize() - Window dimensionsuseTimer() - Timer/countdownuseFormValidator() - Form validation (Valibot)useIdleTimeout() - Idle detectionuseUserVisibility() - Page visibilityuseSwipe() - Swipe gesturesuseReadingTime() - Reading time calculationuseStringMatching() - String utilitiesuseDisplayNames() - Localized display namesv-tooltip - Tooltipsv-click-outside - Outside click detectionv-lazy-img - Lazy loadingv-zoom-img - Image zoomv-fullscreen-img - Fullscreen image viewer✅ 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)
Maz-UI provides two sets of production-ready templates organized by framework:
templates/vue/)fetch() APIUse when: Building Vue 3 applications with Vite
Available templates:
setup/vite.config.ts - Vite configuration with auto-importscomponents/form-basic.vue - Basic form validationcomponents/form-multi-step.vue - Multi-step form with steppercomponents/dialog-confirm.vue - Dialog confirmation patternscomponents/data-table.vue - Data table with pagination, search, sorttemplates/nuxt/)$fetch (Nuxt's ofetch wrapper)Use when: Building Nuxt 3 applications
Available templates:
setup/nuxt.config.ts - Nuxt configuration with Maz-UI modulecomponents/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 loadingBoth template sets:
Load reference files based on what you're implementing. All 21 reference files are grouped by purpose for quick discovery:
components-forms.md - Building forms, inputs, validation, phone numbers, dates, file uploads, MazInput, MazSelect, MazCheckbox, MazDatePickercomponents-feedback.md - Adding loaders, progress bars, animations, toasts, MazFullscreenLoader, MazCircularProgressBar, MazAnimatedText, MazCardSpotlightcomponents-navigation.md - Implementing tabs, steppers, pagination, MazTabs, MazStepper, MazPaginationcomponents-layout.md - Working with cards, drawers, carousels, galleries, MazCard, MazAccordion, MazDrawer, MazCarousel, MazGallerysetup-vue.md - Setting up Maz-UI in Vue 3 project, auto-imports with resolvers, Vite/Webpack configuration, performance optimizationsetup-nuxt.md - Integrating with Nuxt 3, module configuration, theme strategies (hybrid/buildtime/runtime), SSR/SSG considerationscomposables.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-imgplugins.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-shakingtranslations.md - Implementing multi-language support (8 built-in languages), custom locales, lazy loading, SSR hydrationicons.md - Using @maz-ui/icons package (840+ icons), MazIcon component, icon sizing, colors, animationscli.md - Using @maz-ui/cli (legacy v3), theme configuration, migration to v4 themes systemmcp.md - Setting up Model Context Protocol server for AI assistant integration (Claude Code, Claude Desktop, Cursor, Windsurf)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 ~15KBssr-ssg.md - Comprehensive SSR/SSG guide: theme strategies, critical CSS, hydration prevention, dark mode without flash, static site generationaccessibility.md - WCAG 2.1 AA compliance, keyboard navigation, screen reader support, ARIA attributes, color contrastform-validation.md - useFormValidator deep dive, Valibot integration, 5 validation modes (lazy, aggressive, eager, blur, progressive), TypeScript type inferencemigration-v4.md - Upgrading from Maz-UI v3 to v4, breaking changes, API changes, component renames, TypeScript updatestroubleshooting.md - Debugging errors, common issues, configuration problems, SSR hydration, bundle size issuesError: "useTheme must be used within MazUi plugin installation"
Cause: MazUi plugin not installed or theme composable disabled
Fix:
Error: Components/composables not found despite Nuxt module installed Cause: Module not properly configured or cache issue Fix:
Verify nuxt.config.ts:
Error: Components render but have no styling Cause: CSS not imported Fix Vue:
Fix Nuxt:
Error: Cannot find module 'maz-ui/components/MazBtn'
Cause: Missing type definitions or incorrect import path
Fix:
Ensure tsconfig.json includes:
Error: MazInputPhoneNumber doesn't detect country or shows wrong flag
Cause: Missing libphonenumber-js dependency or country data not loaded
Fix:
Error: Translation keys showing as raw strings like inputPhoneNumber.phoneInput.example instead of translated text
Causes:
preloadFallback configurationFix Vue (Immediate Loading):
Fix Vue (Lazy Loading):
Fix Nuxt (Avoid Hydration):
Error Handling:
Learn More: Load references/translations.md for comprehensive i18n setup, lazy loading strategies, and production patterns.
Direct Imports (Most Optimized):
Index Imports (Good):
Avoid (Not Tree-Shakable):
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.
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.
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.
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.
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.
This SKILL.md provides:
For detailed implementation:
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')<script setup>
import MazBtn from 'maz-ui/components/MazBtn'
import MazInput from 'maz-ui/components/MazInput'
import { ref } from 'vue'
const inputValue = ref('')
</script>
<template>
<MazInput v-model="inputValue" label="Name" />
<MazBtn color="primary">Submit</MazBtn>
</template># Install Nuxt module
pnpm add @maz-ui/nuxtexport default defineNuxtConfig({
modules: ['@maz-ui/nuxt']
// That's it! Auto-imports enabled 🎉
})<script setup>
// Auto-imported composables
const theme = useTheme()
const toast = useToast()
const inputValue = ref('')
</script>
<template>
<!-- Auto-imported components -->
<MazInput v-model="inputValue" label="Name" />
<MazBtn color="primary" @click="toast.success('Submitted!')">
Submit
</MazBtn>
</template>// Vue
app.use(MazUi, { theme: { preset: mazUi } })
// Nuxt
export default defineNuxtConfig({
mazUi: {
composables: { useTheme: true },
theme: { preset: 'maz-ui' }
}
})# Clear Nuxt cache
rm -rf .nuxt node_modules/.cache
pnpm installexport default defineNuxtConfig({
modules: ['@maz-ui/nuxt']
})import 'maz-ui/styles' // Add this lineexport default defineNuxtConfig({
mazUi: {
css: { injectMainCss: true } // Ensure this is true
}
})// Correct import
import MazBtn from 'maz-ui/components/MazBtn'
// Or with auto-import (Nuxt)
// No import needed, just use <MazBtn>{
"compilerOptions": {
"types": ["maz-ui/types"]
}
}# Install peer dependency
pnpm add libphonenumber-js<MazInputPhoneNumber
v-model="phone"
default-country-code="US"
preferred-countries="['US', 'CA', 'GB']"
/>import { fr } from '@maz-ui/translations'
app.use(MazUi, {
translations: {
locale: 'fr',
fallbackLocale: 'en',
preloadFallback: true,
messages: { fr } // Import immediately
}
})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!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')
}
}
}
})<script setup>
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>// ✅✅✅ Best - smallest bundle
import MazBtn from 'maz-ui/components/MazBtn'
import { useToast } from 'maz-ui/composables/useToast'
import { vClickOutside } from 'maz-ui/directives/vClickOutside'// ✅ Good - tree-shakable
import { MazBtn, MazInput } from 'maz-ui/components'
import { useToast, useTheme } from 'maz-ui/composables'// ❌ Imports everything
import * as MazUI from 'maz-ui'