maz-ui

Maz-UI v4 - Vue & Nuxt コンポーネントライブラリ

Maz-UI は、Vue 3 および Nuxt 3 アプリケーション向けの包括的なスタンドアロンコンポーネントライブラリです。50 種類以上の本番環境対応コンポーネント、強力なテーマ機能、国際化、優れた開発者体験を提供します。

最新バージョン：4.9.3（2026-08-03 時点） パッケージ：maz-ui | @maz-ui/nuxt | @maz-ui/themes | @maz-ui/translations | @maz-ui/icons

クイックスタート

Vue 3 のインストール

# Install core packages
pnpm add maz-ui @maz-ui/themes

# Or with npm
npm install maz-ui @maz-ui/themes

main.ts でセットアップします。

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>

Nuxt 3 のインストール

# Install Nuxt module
pnpm add @maz-ui/nuxt

nuxt.config.ts でセットアップします。

export 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>
  
  <MazInput v-model="inputValue" label="Name" />
  <MazBtn color="primary" @click="toast.success('Submitted!')">
    Submit
  </MazBtn>
</template>

主な機能

🎨 コンポーネント（50 種類以上）

フォームと入力：

• MazInput - 検証状態を備えたテキスト入力
• MazSelect - ドロップダウン選択
• MazTextarea - 複数行のテキスト入力
• MazCheckbox - ラベル付きチェックボックス
• MazRadio - ラジオボタン
• MazSwitch - トグルスイッチ
• MazSlider - 範囲スライダー
• MazInputPhoneNumber - 検証機能付きの国際電話番号入力
• MazInputCode - コード／PIN 入力
• MazInputPrice - 書式設定機能付きの通貨入力
• MazInputTags - タグ／チップ入力
• MazDatePicker - 日付選択
• MazChecklist - 検索可能なチェックリスト

UI 要素：

• MazBtn - バリエーションを備えたボタン
• MazCard - コンテナカード
• MazBadge - ラベルバッジ
• MazAvatar - ユーザーアバター
• MazIcon - アイコン表示
• MazSpinner - ローディングスピナー
• MazTable - 並べ替え／ページネーション機能付きデータテーブル
• MazTabs - タブナビゲーション
• MazStepper - ステップインジケーター
• MazPagination - ページネーションコントロール

オーバーレイとモーダル：

• MazDialog - モーダルダイアログ
• MazDialogConfirm - 確認ダイアログ
• MazDrawer - スライド式ドロワー
• MazBottomSheet - モバイル向けボトムシート
• MazBackdrop - オーバーレイの背景
• MazPopover - フローティングポップオーバー
• MazDropdown - ドロップダウンメニュー

フィードバックとアニメーション：

• MazFullscreenLoader - ローディングオーバーレイ
• MazLoadingBar - プログレスバー
• MazCircularProgressBar - 円形プログレスバー
• MazReadingProgressBar - 読書進捗インジケーター
• MazAnimatedText - テキストアニメーション
• MazAnimatedElement - 要素のアニメーション
• MazAnimatedCounter - 数値カウンターアニメーション
• MazCardSpotlight - スポットライト効果付きカード

レイアウトと表示：

• MazCarousel - 画像カルーセル
• MazGallery - 画像ギャラリー
• MazAccordion - 折りたたみパネル
• MazExpandAnimation - 展開／折りたたみアニメーション
• MazLazyImg - 遅延読み込み画像
• MazPullToRefresh - プル・トゥ・リフレッシュ操作
• MazChart - Chart.js との連携

🔧 コンポーザブル（14 種類以上）

テーマ設定：

• useTheme() - テーマとダークモードの管理

翻訳：

• useTranslations() - i18n の管理

UI 操作：

• useToast() - トースト通知
• useDialog() - プログラムによるダイアログ表示
• useWait() - ローディング状態

ユーティリティ：

• useBreakpoints() - レスポンシブのブレークポイント
• useWindowSize() - ウィンドウのサイズ
• useTimer() - タイマー／カウントダウン
• useFormValidator() - フォーム検証（Valibot）
• useIdleTimeout() - アイドル状態の検出
• useUserVisibility() - ページの表示状態
• useSwipe() - スワイプ操作
• useReadingTime() - 読了時間の計算
• useStringMatching() - 文字列ユーティリティ
• useDisplayNames() - ローカライズされた表示名

📌 ディレクティブ（5 種類）

• v-tooltip - ツールチップ
• v-click-outside - 外側のクリック検出
• v-lazy-img - 遅延読み込み
• v-zoom-img - 画像のズーム
• v-fullscreen-img - 全画面画像ビューアー

🔌 プラグイン（4 種類）

• AOS - スクロール時のアニメーション
• Dialog - テンプレート不要のダイアログ
• Toast - 通知
• Wait - グローバルなローディング状態

主な機能

✅ スタンドアロンコンポーネント - 必要なものだけをインポートでき、余分な容量はありません ✅ SSR/SSG 対応 - 自動インポートを含む Nuxt 3 の完全なサポート ✅ TypeScript ファースト - 最初から完全な型安全性を備えています ✅ ダークモード - ダーク／ライトテーマを切り替える機能を標準搭載 ✅ ツリーシェイキング対応 - バンドルサイズを最適化 ✅ レスポンシブ - モバイルファーストのデザイン ✅ アクセシブル - ARIA に準拠したコンポーネント ✅ テーマ設定可能 - 4 種類の組み込みプリセットとカスタムテーマ ✅ i18n - @maz-ui/translations による多言語サポート ✅ 840 以上のアイコン - 最適化された SVG アイコンライブラリ（@maz-ui/icons）

テンプレート構成

Maz-UI は、フレームワーク別に整理された 本番環境対応のテンプレートを 2 セット提供しています。

Vue 3 + Vite テンプレート（templates/vue/）

• ✅ Vite を使用する純粋な Vue 3
• ✅ 標準の fetch() API を使用
• ✅ すべての依存関係を明示的にインポート
• ✅ フレームワーク固有の依存関係なし
• ✅ SPA 開発向けに最適化

使用する場面：Vite で Vue 3 アプリケーションを構築する場合

利用可能なテンプレート：

• setup/vite.config.ts - 自動インポート機能を備えた Vite 設定
• components/form-basic.vue - 基本的なフォーム検証
• components/form-multi-step.vue - ステッパー付きのマルチステップフォーム
• components/dialog-confirm.vue - ダイアログ確認パターン
• components/data-table.vue - ページネーション、検索、並べ替え機能付きデータテーブル

Nuxt 3 テンプレート（templates/nuxt/）

• ✅ Nuxt 3 向けに最適化
• ✅ $fetch（Nuxt の ofetch ラッパー）を使用
• ✅ コンポーネントとコンポーザブルの自動インポートを活用
• ✅ SSR パターンとサーバールートを紹介
• ✅ Nuxt のフルスタック開発向けに最適化

使用する場面：Nuxt 3 アプリケーションを構築する場合

利用可能なテンプレート：

• setup/nuxt.config.ts - Maz-UI モジュールを含む Nuxt 設定
• components/form-basic.vue - 基本的なフォーム検証（自動インポート）
• components/form-multi-step.vue - マルチステップフォーム（自動インポート）
• components/dialog-confirm.vue - ダイアログパターン（自動インポート）
• components/data-table.vue - リアクティブなデータ読み込み機能付きデータテーブル

どちらのテンプレートセットも：

• ✅ 検証、型推論、ページネーションに関するすべての問題を解決
• ✅ 各フレームワークのベストプラクティスに準拠
• ✅ 本番環境ですぐに使用でき、十分にテスト済み
• ✅ セットアップ設定とコンポーネントの例を含む

リファレンスを読み込むタイミング

実装する内容に応じてリファレンスファイルを読み込んでください。全 21 個のリファレンスファイルは、すぐに見つけられるよう用途別に分類されています。

コンポーネント（4 ファイル）

• components-forms.md - フォーム、入力、検証、電話番号、日付、ファイルアップロード、MazInput、MazSelect、MazCheckbox、MazDatePicker の作成
• components-feedback.md - ローダー、プログレスバー、アニメーション、トースト、MazFullscreenLoader、MazCircularProgressBar、MazAnimatedText、MazCardSpotlight の追加
• components-navigation.md - タブ、ステッパー、ページネーション、MazTabs、MazStepper、MazPagination の実装
• components-layout.md - カード、ドロワー、カルーセル、ギャラリー、MazCard、MazAccordion、MazDrawer、MazCarousel、MazGallery の利用

セットアップと設定（2 ファイル）

• setup-vue.md - Vue 3 プロジェクトへの Maz-UI のセットアップ、リゾルバーを使った自動インポート、Vite/Webpack の設定、パフォーマンスの最適化
• setup-nuxt.md - Nuxt 3 との統合、モジュール設定、テーマ戦略（ハイブリッド／ビルド時／ランタイム）、SSR/SSG に関する考慮事項

コア機能（5 ファイル）

• composables.md - 14 種類すべてのコンポーザブルの使用方法：useToast、useTheme、useBreakpoints、useFormValidator、useTimer、useDialog、useTranslations など
• directives.md - ディレクティブの追加：v-tooltip、v-click-outside、v-lazy-img、v-zoom-img、v-fullscreen-img
• plugins.md - プラグインの有効化：AOS（スクロール時のアニメーション）、Dialog、Toast、Wait（読み込み状態）
• resolvers.md - 重要：最適なツリーシェイキングを実現する、MazComponentsResolver、MazDirectivesResolver、MazModulesResolver を使った自動インポート設定
• translations.md - 多言語サポート（組み込み言語 8 種）、カスタムロケール、遅延読み込み、SSR のハイドレーションの実装

ツールと統合（3 ファイル）

• icons.md - @maz-ui/icons パッケージ（840 以上のアイコン）、MazIcon コンポーネント、アイコンのサイズ、色、アニメーションの使用
• cli.md - @maz-ui/cli（レガシー v3）の使用、テーマ設定、v4 テーマシステムへの移行
• mcp.md - AI アシスタント統合（Claude Code、Claude Desktop、Cursor、Windsurf）用の Model Context Protocol サーバーのセットアップ

高度なトピック（5 ファイル）

• theming.md - テーマのカスタマイズ、ダークモード、配色、CSS 変数、組み込みプリセット 4 種（mazUi、ocean、pristine、obsidian）
• performance.md - バンドルの最適化、ツリーシェイキング、遅延読み込み、コード分割、バンドルサイズを約 300KB から約 15KB に削減する方法
• ssr-ssg.md - 包括的な SSR/SSG ガイド：テーマ戦略、クリティカル CSS、ハイドレーションの防止、フラッシュのないダークモード、静的サイト生成
• accessibility.md - WCAG 2.1 AA 準拠、キーボード操作、スクリーンリーダーのサポート、ARIA 属性、色のコントラスト
• form-validation.md - useFormValidator の詳細解説、Valibot との統合、5 つのバリデーションモード（lazy、aggressive、eager、blur、progressive）、TypeScript の型推論

トラブルシューティング（2 ファイル）

• migration-v4.md - Maz-UI v3 から v4 へのアップグレード、破壊的変更、API の変更、コンポーネント名の変更、TypeScript の更新
• troubleshooting.md - エラーのデバッグ、よくある問題、設定の問題、SSR ハイドレーション、バンドルサイズの問題

よくあるエラー上位 6 件

1. テーマプラグインが見つからないエラー

エラー："useTheme must be used within MazUi plugin installation" 原因：MazUi プラグインがインストールされていないか、テーマコンポーザブルが無効になっています 修正方法：

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

// Nuxt
export default defineNuxtConfig({
  mazUi: {
    composables: { useTheme: true },
    theme: { preset: 'maz-ui' }
  }
})

2. 自動インポートが動作しない（Nuxt）

エラー：Nuxt モジュールをインストールしているのに、コンポーネント／コンポーザブルが見つかりません 原因：モジュールが正しく設定されていないか、キャッシュに問題があります 修正方法：

# Clear Nuxt cache
rm -rf .nuxt node_modules/.cache
pnpm install

nuxt.config.tsを確認：

export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt']
})

3. スタイルが適用されない

エラー：コンポーネントはレンダリングされますが、スタイルが適用されません 原因：CSS がインポートされていません Vue での修正：

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

Nuxt での修正：

export default defineNuxtConfig({
  mazUi: {
    css: { injectMainCss: true } // Ensure this is true
  }
})

4. コンポーネントで TypeScript エラーが発生する

エラー：Cannot find module 'maz-ui/components/MazBtn' 原因：型定義がないか、インポートパスが正しくありません 修正方法：

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

// Or with auto-import (Nuxt)
// No import needed, just use <MazBtn>

tsconfig.jsonに以下が含まれていることを確認：

{
  "compilerOptions": {
    "types": ["maz-ui/types"]
  }
}

5. 電話番号入力で国の検出に失敗する

エラー：MazInputPhoneNumberが国を検出しない、または間違った旗を表示します 原因：libphonenumber-js 依存関係がないか、国のデータが読み込まれていません 修正方法：

# Install peer dependency
pnpm add libphonenumber-js

<MazInputPhoneNumber
  v-model="phone"
  default-country-code="US"
  preferred-countries="['US', 'CA', 'GB']"
/>

6. 翻訳が読み込まれない、またはキーがそのまま表示される

エラー：翻訳キーが翻訳済みテキストではなく、inputPhoneNumber.phoneInput.exampleのような文字列のまま表示されます 原因：

• ロケールがインポートされていません
• 遅延読み込みの完了を正しく待機していません
• 言語ファイルの非同期読み込みに失敗しました
• preloadFallbackの設定がありません
• SSR ハイドレーションの不一致（Nuxt）

Vue での修正（即時読み込み）：

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

app.use(MazUi, {
  translations: {
    locale: 'fr',
    fallbackLocale: 'en',
    preloadFallback: true,
    messages: { fr } // Import immediately
  }
})

Vue での修正（遅延読み込み）：

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!

Nuxt での修正（ハイドレーションの回避）：

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>

詳細はこちら：包括的な i18n のセットアップ、遅延読み込みの戦略、本番環境でのパターンについては、references/translations.mdを読み込んでください。

ツリーシェイキングのベストプラクティス

直接インポート（最も最適化されます）：

// ✅✅✅ 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'

高度なトピック

パフォーマンスの最適化

Maz-UI は、インポート方法の工夫とツリーシェイキングにより、約 300KB から約 15KB まで最適化できます。最適なバンドルサイズを実現するには、自動インポートリゾルバー（MazComponentsResolver、MazDirectivesResolver、MazModulesResolver）を使用し、動的インポートでコンポーネントを遅延読み込みして、機能ごとにコードを分割してください。包括的なバンドル最適化戦略については、**performance.md**を読み込んでください。

SSR & SSG

3つのテーマ戦略に対応した、完全なサーバーサイドレンダリングと静的サイト生成をサポートしています。hybrid（クリティカル CSS を挿入し、FOUC を防止）、buildtime（バンドルサイズが最小で、テーマは静的）、runtime（テーマを完全に切り替え可能で、バンドルサイズは大きめ）から選べます。クライアント専用コンポーネントを<ClientOnly>でラップして、ハイドレーションの不一致を防いでください。クリティカル CSS のパターン、フラッシュのないダークモード、SSR/SSG のチェックリストについては、**ssr-ssg.md**を読み込んでください。

アクセシビリティ

すべての Maz-UI コンポーネントは、適切な ARIA 属性、キーボードナビゲーション、フォーカス管理、スクリーンリーダーへの対応を備え、WCAG 2.1 AA に準拠しています。コンポーネントには、セマンティック HTML、4.5:1 を超える色のコントラスト比、アクセシブルなフォームバリデーションが含まれます。キーボードショートカット、フォーカストラップのパターン、アクセシビリティテストのチェックリストについては、**accessibility.md**を読み込んでください。

フォームバリデーション

useFormValidator()コンポーザブルは Valibot と連携し、TypeScript の完全な型推論に対応した、型安全なスキーマバリデーションを提供します。5 つのバリデーションモード（lazy、aggressive、eager、blur、progressive）、非同期バリデーション、カスタムバリデーター、リアルタイムのエラーメッセージをサポートしています。包括的なバリデーションパターンと実例については、**form-validation.md**を読み込んでください。

自動インポートリゾルバー

ツリーシェイキングに不可欠です：Maz-UI リゾルバーとともにunplugin-vue-componentsおよびunplugin-auto-importを使用して、使用するものだけをインポートしてください。グローバルインポートと比べて、バンドルサイズを 60～90% 削減できます。他のライブラリとの命名の競合を避けるため、プレフィックスの処理を設定してください。リゾルバーの設定とトラブルシューティングの全容については、**resolvers.md**を読み込んでください。

プログレッシブディスクロージャーの概要

この SKILL.md では、次の内容を提供します。

1. クイックスタート - 5 分以内に実行を開始できます
2. コア機能 - すべての機能の概要
3. エラーの防止 - よくある上位 5 つの問題を解決します

実装の詳細については、次の手順に従ってください。

• 現在のタスクに応じてリファレンスファイルを読み込みます（上記の「リファレンスを読み込むタイミング」を参照）
• 各リファレンスには、包括的なガイド、コード例、高度な設定が含まれます
• リファレンスは、簡単に参照できるよう、ドメイン別（コンポーネント、セットアップ、テーマ設定など）に整理されています

パッケージのエコシステム

• maz-ui - コアコンポーネントライブラリ
• @maz-ui/nuxt - 自動インポート対応の Nuxt 3 モジュール
• @maz-ui/themes - テーマシステムとプリセット
• @maz-ui/translations - i18n 対応（組み込みの 8 言語：en、fr、es、de、it、pt、ja、zh-CN）
• @maz-ui/icons - 最適化された SVG アイコン 840 個以上
• @maz-ui/mcp - AI エージェント向けドキュメントサーバー

公式リソース

• ドキュメント: 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
• 変更履歴: https://github.com/LouisMazel/maz-ui/blob/master/CHANGELOG.md