# mdui v2 Documentation

mdui is an front-end component library based on Material Design 3, using Web Components, supporting dynamic colors, dark mode, and lightweight efficiency.

## 開発ガイド

- [概要](https://www.mdui.org/ja/docs/2/index.md): mduiはWeb Componentsベースの高品質なコンポーネントライブラリで、50以上のMaterial Design 3コンポーネントを収録。ダークモード、多言語対応、TypeScriptをサポート。CDNやnpmで現代的なWebアプリを簡単に構築できます。
- [インストール](https://www.mdui.org/ja/docs/2/getting-started/installation.md): npm、pnpm、CDNでのインストールに対応。全量導入と、サイズを削減できる個別インポートを選択可能です。グローバルビルドやESモジュール版の使用法を詳述し、あらゆるプロジェクトへのスムーズな統合をサポートします。
- [クイックスタート](https://www.mdui.org/ja/docs/2/getting-started/usage.md): Web Components標準に基づき開発。属性、プロパティ、メソッド、イベント、Slot、CSS Part、CSS カスタムプロパティの使用法を詳述。更新メカニズムやスタイル管理を学び、効率的なWeb Components開発をサポート。
- [TypeScript サポート](https://www.mdui.org/ja/docs/2/getting-started/typescript-support.md): TypeScriptで開発され、完璧な型定義を提供。全てのコンポーネントと関数に型があり、自動補完や型チェックが利用可能です。個別パックやメインパッケージからの型導入が可能で、開発効率とコード品質を劇的に向上させます。
- [IDE サポート](https://www.mdui.org/ja/docs/2/getting-started/ide-support.md): VS CodeやWebStorm向けに最適化されています。npm設定や拡張機能により、自動補完、ホバー提示、属性値のヒントを提供。完全なHTML/CSSデータサポートによりドキュメント参照の負担を減らし、開発効率を劇的に向上させます。
- [ローカライズ](https://www.mdui.org/ja/docs/2/getting-started/localization.md): 50以上の言語パックを内蔵し、多言語対応をサポート。遅延読み込み、プリロード、静的インポートを選択でき、CDN経由のロードも可能です。ローカライズイベントを利用して、グローバルなアプリを簡単に構築するための機能を解説。
- [よくある質問](https://www.mdui.org/ja/docs/2/getting-started/faq.md): コミュニティでよくある質問を掲載。自己終了タグの使用や、コンポーネント読み込み前の非表示対策など、開発中の重要な課題への解決策を提示します。豊富なサンプルコードと共に、トラブルを迅速に解決するためのヒントを豊富に提供。

## AI 補助開発

- [LLMs.txt](https://www.mdui.org/ja/docs/2/ai/llms.md): llms.txtとllms-full.txtを提供し、大規模言語モデルに正確な文脈を提供します。各ドキュメントのMarkdown版は直接貼り付けやアップロードに対応。AIの回答精度を高め、AIを活用したモダンな開発プロセスを強力に支援します。
- [MCP サーバー](https://www.mdui.org/ja/docs/2/ai/mcp.md): @mdui/mcpにより、Cursor等のAIエージェントにMCP サーバーを統合。属性、アイコン、CSS カスタムプロパティ、ドキュメントをAIが直接参照可能です。AIによる自動プログラミング体験を深化させ、次世代の開発体験を提供します。

## スタイル

- [ダークモード](https://www.mdui.org/ja/docs/2/styles/dark-mode.md): 全コンポーネントでダークモードを標準サポート。システム設定への追従や手動設定に対応し、CSS クラスや関数で柔軟に制御可能です。グローバルおよび局部的なテーマ切り替えをサポートし、あらゆるシーンに最適な視覚体験を提供。
- [ダイナミックカラー](https://www.mdui.org/ja/docs/2/styles/dynamic-color.md): 指定色や画像から調和のとれた配色を自動生成。画像から主要な色を抽出してテーマに反映させるなど、ユーザーに合わせた配色を動的に構築可能です。一貫性を保ちつつ、アプリのパーソナライズ化を容易かつ高度に実現することを助けます。
- [文章のタイポグラフィ](https://www.mdui.org/ja/docs/2/styles/prose.md): mdui-proseやmdui-tableにより、記事や表のレイアウトを最適化。追加のCSSなしで美しいフォント、余白、行間、枠線を適用可能です。Markdownや動的コンテンツの可読性を高め、洗練されたタイポグラフィを簡単に実現。
- [デザイントークン](https://www.mdui.org/ja/docs/2/styles/design-tokens.md): CSS カスタムプロパティを活用したデザイントークンシステム。100以上のトークンを定義しており、これらをカスタマイズすることで独自のデザインを適用可能です。コンポーネント全体のスタイルを一括管理し、統一感を容易に維持。

## フレームワークとの統合

- [React との統合](https://www.mdui.org/ja/docs/2/frameworks/react.md): Web ComponentsベースのmduiはReact内で通常のHTMLタグとして使用可能です。TypeScriptの型定義、イベント処理、プロパティ同期をサポート。Reactにおけるベストプラクティスと連携方法を詳細にガイドします。
- [Vue との統合](https://www.mdui.org/ja/docs/2/frameworks/vue.md): Vueプロジェクトへの統合方法を解説. コンパイラの設定から、v-modelによる双方向バインディング、イベント監視までサポート. Vue 3との親和性が高く、型安全な開発環境とIDEによる支援を最大限に活用するための手順を詳述.
- [Angular との統合](https://www.mdui.org/ja/docs/2/frameworks/angular.md): AngularでWeb Componentsを使うための設定や統合手順を詳述. 依存性の注入、双方向バインディング、フォーム連携など、Angular特有の機能と組合せる方法を解説. 正確な型定義により、堅牢なアプリケーション構築を強力に支援.
- [他のフレームワークとの統合](https://www.mdui.org/ja/docs/2/frameworks/others.md): 標準的なWeb Componentsに準拠. Svelte、Next.js、Nuxt等、あらゆるモダンフレームワークに導入可能です. 各環境での一般的な初期設定や、コンポーネントをシームレスに動作させるための汎用的な統合ガイドラインを提供.

## コンポーネント

- [アバターコンポーネント Avatar](https://www.mdui.org/ja/docs/2/components/avatar.md): アバターはユーザーや事物、ブランドを視覚化。画像、マテリアルアイコン、文字の三種に対応。サイズや形状（丸・角）、フィット方法を設定可能。プロフィールやコメント、カードなどに多用されます。
- [バッジコンポーネント Badge](https://www.mdui.org/ja/docs/2/components/badge.md): 通知や状態を数値やドットで表示. アイコン等に付加し未読数等を告知. 重要事項へ注意を導き、緊急性を伝えるM3準拠の視覚要素. 省スペースで高い伝達効果を実現し、Material Design 3に基づいた円滑な操作を支援.
- [ボトムアプリバーコンポーネント BottomAppBar](https://www.mdui.org/ja/docs/2/components/bottom-app-bar.md): モバイル向け下部に主要操作を集約. FABや複数のボタンを機能的に配置します. スクロール非表示に対応し片手操作を最適化. 重要な機能を身近に保ち、Material Design 3に基づいた美しさと機能美、高い利便性を実現.
- [ボタンコンポーネント Button](https://www.mdui.org/ja/docs/2/components/button.md): 5種類のスタイルをサポート。ホバーやローディング等の状態を完備し、Material Design 3に準拠。アイコン統合やアクセシビリティも考慮されており、あらゆる操作の起点となる基本要素として洗練されたデザインを提供します。
- [アイコンボタンコンポーネント ButtonIcon](https://www.mdui.org/ja/docs/2/components/button-icon.md): 補助操作向けの軽量なボタン。4つのスタイルを選択でき、トグル動作やリンク、ローディングにも対応。ツールバーやカード内での操作など、UIを簡潔かつ機能的に保ちたい場面で、Material Design 3の優れた効果を発揮。
- [カードコンポーネント Card](https://www.mdui.org/ja/docs/2/components/card.md): 関連するコンテンツと操作をまとめる汎用コンテナ。M3の3つのスタイルを採用。画像やリンク、メディアを柔軟に配置可能です。情報の構造化を助け、洗練されたダッシュボードやニュースフィード等の構築を高品質にサポートします。
- [チェックボックスコンポーネント Checkbox](https://www.mdui.org/ja/docs/2/components/checkbox.md): 複数の選択肢からの任意選択や、オン/オフ의切り替えに使用。チェックや不確定状態をサポート。配色やアイコンのカスタマイズ、バリデーションに対応し、入力を的確かつ視覚的に管理。一貫性のある明確なフィードバックを提供。
- [チップコンポーネント Chip](https://www.mdui.org/ja/docs/2/components/chip.md): 入力、選択、フィルタ等をコンパクトに表現。4つのスタイルがあり、削除やチェックにも対応。タグ付けや情報の分類、検索条件の提示等に最適です。情報の整理と操作を同時に提供し、構造化された画面構成を高品質に実現します。
- [円形プログレスコンポーネント CircularProgress](https://www.mdui.org/ja/docs/2/components/circular-progress.md): 円環で進行状況を表現. サイズ、太さ、色の変更、確定値、無限回転に対応. ボタン内や画面中央等で、読み込み待ちを洗練されたステータス提示として最小限の負荷で実現します. 円滑な体験を支える便利なグラフィック要素.
- [折りたたみコンポーネント Collapse](https://www.mdui.org/ja/docs/2/components/collapse.md): 表示/非表示を切り替えて画面を整理。アコーディオン形式やカスタムトリガーに対応。FAQや補足情報のグループ化に便利で、必要な情報だけを効果的に提示します。空間を有効活用し情報を整理するための、洗練されたツールです。
- [ダイアログコンポーネント Dialog](https://www.mdui.org/ja/docs/2/components/dialog.md): 告知や決定を促すモーダル. タイトル、アイコン、操作ボタンを自在にカスタマイズ. 命令型APIにより、M3準拠の対話フローを最小限の記述で構成可能です. 美しさと機能性を兼ね備えた、意思決定を支援する強力な対話要素.
- [区切り線コンポーネント Divider](https://www.mdui.org/ja/docs/2/components/divider.md): コンテンツを整理し階層を明確化. 垂直・水平描画、インデント設定に対応します. リストの可読性を高め、情報の視覚的整理を強力に支援. 一貫性のあるレイアウトを構築するための、Material Design 3準拠の不可欠な要素.
- [ドロップダウンコンポーネント Dropdown](https://www.mdui.org/ja/docs/2/components/dropdown.md): クリックやホバーでメニュー等をポップアップ表示。位置調整、表示遅延、はみ出し防止を完備。あらゆる要素をトリガーにでき、操作を邪魔せず必要な機能へアクセス可能です。洗練されたUIにより、快適なユーザー体験を提供します。
- [フローティングアクションボタンコンポーネント Fab](https://www.mdui.org/ja/docs/2/components/fab.md): 最優先操作を強調するボタン。2つの形態、3つのサイズ、多彩な配色に対応。画面上に固定表示され、ユーザーが重要な機能へ素早くアクセス可能です。高い直感性と利便性により、Material Design 3準拠の開発を強力に支援。
- [アイコンコンポーネント Icon](https://www.mdui.org/ja/docs/2/components/icon.md): Material IconsやカスタムSVGをレンダリング. サイズや色の制御が容易です. 直感的なシンボルの提供で認知負荷を下げ、美しく一貫性のあるユーザーエクスペリエンスを最小限のコストで構築し、世界観を強化.
- [レイアウトコンポーネント Layout](https://www.mdui.org/ja/docs/2/components/layout.md): 複雑なアプリケーション構成を整理. トップバーやサイドバー、メインの関係性を定義し、応答性の高い構造を構築. グリッドや断点など、Material Design 3のレイアウトシステムを即座に導入するための土台.
- [線形プログレスコンポーネント LinearProgress](https://www.mdui.org/ja/docs/2/components/linear-progress.md): 水平バーで進行状況を視覚化. 確定値表示と不確定アニメーションをサポート. 色、高さのカスタマイズにより、あらゆる画面に適合します. 進捗を直感的に伝え、Material Design 3に基づいた一貫したフィードバックを提供.
- [リストコンポーネント List](https://www.mdui.org/ja/docs/2/components/list.md): 項目を垂直に並べる基本レイアウト。アバターや複数行テキストを自由に構成。リンクや無効状態をサポート。情報の提示とナビゲーションを、洗練されたMaterial Design 3スタイルで提供する中心的なUIコンポーネント。
- [メニューコンポーネント Menu](https://www.mdui.org/ja/docs/2/components/menu.md): 操作オプションをリスト化。単一/複数選択、サブメニュー、ショートカット、無効化をサポート. ドロップダウンと組み合わせて多層UIを構築可能です. 複雑なフローを整理し、使い勝手を向上させる、M3準拠の洗練された要素. 
- [ナビゲーションバーコンポーネント NavigationBar](https://www.mdui.org/ja/docs/2/components/navigation-bar.md): モバイル向けの主要ナビゲーション. 3〜5個の目的地間を素早く移動可能. バッジ、ラベル、カラー設定、スクロール非表示を搭載. Material Design 3に基づき、操作をシードレスに繋ぎ、高品質と美しさを両立.
- [ナビゲーションドロワーコンポーネント NavigationDrawer](https://www.mdui.org/ja/docs/2/components/navigation-drawer.md): ページ側面のナビゲーションパネル. 標準とモーダルの2種から選択可能です. メニュー等で階層構造を整理. 画面幅を有効活用し洗練されたMaterial Design 3スタイルを提供. 美しいナビゲーションの実現に不可欠.
- [ナビゲーションレールコンポーネント NavigationRail](https://www.mdui.org/ja/docs/2/components/navigation-rail.md): ワイド画面向けのコンパクトな垂直ナビゲーション. 迅速な画面切り替えを支援. 上部/下部配置が可能です. Material Design 3に基づき軽量で効率的. 負荷を抑えつつ、高頻度機能への迅速なアクセスを最高品質で実現.
- [ラジオボタンコンポーネント Radio](https://www.mdui.org/ja/docs/2/components/radio.md): 複数の選択肢から1つだけを選ぶ際に使用。視角的な情報を明確にし、フォーム内での一貫した挙動を保証。スタイルのカスタマイズや無効状態の制御に対応し、決定が必要な場面で、直感的かつミスのない操作体験を一貫して実現。
- [レンジスライダーコンポーネント RangeSlider](https://www.mdui.org/ja/docs/2/components/range-slider.md): 2つのハンドルで数値範囲を選択。価格帯や時間、各種パラメータのフィルタリングに最適。詳細なスタイル制御に対応し、複雑な範囲選択を視覚的に分かりやすく。情報を絞り込むための、Material Design 3準拠の強力なツール。
- [セレクトコンポーネント Select](https://www.mdui.org/ja/docs/2/components/select.md): 単一/複数選択、フィルタリング、バリデーションを完備したセレクター。2つのスタイル、グループ化、アイコンに対応. フォーム等での正確な入力を支援します. Material Design 3の美しさと利便性を高い次元で両立. 
- [セグメントボタンコンポーネント SegmentedButton](https://www.mdui.org/ja/docs/2/components/segmented-button.md): 複数の選択肢をグループ化し、単一/複数選択を可能にします。表示の切り替えやフィルタリングに最適。アイコン配置や全幅設定等の多彩な機能を備え、洗練された直感的なUIを、高い自由度と一貫したデザインで簡単に実現。
- [スライダーコンポーネント Slider](https://www.mdui.org/ja/docs/2/components/slider.md): スライド操作で数値を直感的に選択。最小/最大値、ステップ、目盛りの表示を柔軟に制御。数値ラベルやバリデーションにも対応し、音量や価格設定等、範囲指定が必要なあらゆる入力画面で、Material Design 3の優れた操作を実現. 
- [Snackbar コンポーネント](https://www.mdui.org/ja/docs/2/components/snackbar.md): 短い通知を画面端に一時表示. ボタンを含め直感的な操作を促します. 多彩な制御やJS呼び出しをサポート. 作業を邪魔せず、Material Design 3に基づいた軽量で洗練されたスタイルで、重要なフィードバックを提供.
- [Switch コンポーネント](https://www.mdui.org/ja/docs/2/components/switch.md): 機能の有効/無効を直感的に切り替えるトグル。即時の視覚フィードバック、ローディング表示、アイコン付きデザインに対応. 色やサイズの細かな調整も可能で、管理画面や設定メニューにおいてモダンで快適な操作体験を提供します.
- [Tabs コンポーネント](https://www.mdui.org/ja/docs/2/components/tabs.md): 同一領域内で複数のビューを切り替えるナビゲーション。2つのスタイル、アイコンやバッジの統合が可能。動的な更新に対応し、情報を整理して提示するための、Material Design 3準拠の効率的で高品質な標準UI要素。
- [TextField コンポーネント](https://www.mdui.org/ja/docs/2/components/text-field.md): 単一行・複数行入力に対応. パスワードやメール入力、ラベル、補助テキスト、エラー表示、自動高さ調整等を完備. バリデーションとアクセシビリティを備えたM3準拠の入力要素. あらゆる画面で正確かつ迅速な入力を支援します.
- [Tooltip コンポーネント](https://www.mdui.org/ja/docs/2/components/tooltip.md): 要素に短い説明を追加. 自動位置調整に対応. アイコンだけでは不足する情報の補足に最適です. ユーザー動作に応じ表示. Material Design 3に基づき洗練された理解を助け、UIの価値と品質を向上させる快適な要素.
- [TopAppBar コンポーネント](https://www.mdui.org/ja/docs/2/components/top-app-bar.md): ページ上部のメインヘッダー. タイトル、検索や設定等のアクションを一元管理. 4つのスタイルがあり、固定やスクロール縮放に対応. 核心的ナビゲーションとして、構造と機能をMaterial Design 3の品質で提供.

## 関数

- [jq ツールライブラリ](https://www.mdui.org/ja/docs/2/functions/jq.md): jQuery風APIを備えた超軽量JSライブラリ. DOM操作、イベント、アニメーション、連鎖呼び出しを完備. 単独で動作し機能をシンプルに. 機動力を劇的に向上させ、Material Design 3と最高の親和性を誇ります.
- [dialog 関数](https://www.mdui.org/ja/docs/2/functions/dialog.md): 命令型APIでmdui-dialogを制御. HTMLを書かずにスクリプトから直接生成可能です. タイトル、本文、操作を動的に設定し、結果をPromiseで取得. Material Design 3の品質で対話フローを迅速に実装.
- [alert 関数](https://www.mdui.org/ja/docs/2/functions/alert.md): window.alertに代わる美しい警告. 一行で呼び出し可能で、非同期での待機をサポート. カスタムも可能です. アプリに一貫した体験を付加し、情報の重要性を的確に伝える、洗練された高品質なツール.
- [confirm 関数](https://www.mdui.org/ja/docs/2/functions/confirm.md): window.confirmを洗練されたダイアログへ置換. 非同期処理で待機し、Promiseで結果を返却します. UIをブロックせず、意志確認プロセスをMaterial Design 3のスタイルとシンプルなコードで高い次元で実現.
- [prompt 関数](https://www.mdui.org/ja/docs/2/functions/prompt.md): 入力フィールドを備えたダイアログをプログラムから発行. 初期値、バリデーション、入力タイプの設定が可能です. デザインと調和したリッチで安全なユーザー入力体験を、Material Design 3の品質で簡単に提供.
- [snackbar 関数](https://www.mdui.org/ja/docs/2/functions/snackbar.md): 通知をスクリプトから即表示. メッセージ、位置、時間、ボタンを自在に設定可能です. 要素の配置は不要. フィードバックやステータス通知を、Material Design 3のスタイルでスマートに一括管理し、利便性を高めます.
- [getTheme 関数](https://www.mdui.org/ja/docs/2/functions/getTheme.md): 現在のテーマ（ライト、ダーク、OS追従）を指定要素から取得. ユーザー環境や状況に合わせ、スクリプト側で動的にロジックを調整可能です. Material Design 3の高度な配色管理を支える、実用的で重要な基盤関数.
- [setTheme 関数](https://www.mdui.org/ja/docs/2/functions/setTheme.md): テーマモードを瞬時に切り替え. ライト、ダーク、システム追従を選択可能です. 全ページまたは特定のコンテナ限定での制御にも対応. Material Design 3の高度な配色管理を提供し、UI最適化を強力に実現します.
- [getColorFromImage 関数](https://www.mdui.org/ja/docs/2/functions/getColorFromImage.md): 画像から主要な色情報を分析し、最適なカラー値を抽出. setColorSchemeと組み合わせて、画像に完全に溶け込む動的テーマ配色を提供します. Material Design 3の没入型デザインを強力にサポートするアルゴリズム.
- [setColorScheme 関数](https://www.mdui.org/ja/docs/2/functions/setColorScheme.md): ベースカラーからMaterial Design 3規格のフルカラースキームを生成. プライマリから各コンテナ色まで一貫した配色を、最小の労力で反映可能です. グローバルや特定要素に適用でき、高品質な配色システムを提供.
- [removeColorScheme 関数](https://www.mdui.org/ja/docs/2/functions/removeColorScheme.md): ダイナミックカラー設定をクリアし、デフォルト状態へ安全に復元します. ページ全体や個別の要素で実行でき、初期化やデザインリセットを確実に. Material Design 3本来のスタイルへ回帰するための重要な関数です.
- [loadLocale 関数](https://www.mdui.org/ja/docs/2/functions/loadLocale.md): 必要な言語パッケージをオンデマンドで読み込みます。サイズを最小化し、50以上の言語をサポート. グローバル展開に不可欠な多言語体験を、モダンで効率的なアプローチで支え、アプリのパフォーマンスを高い水準で維持.
- [setLocale 関数](https://www.mdui.org/ja/docs/2/functions/setLocale.md): 言語をグローバルに変更します。リロードなしで全要素が即座に翻訳され、インターフェースを一括管理. Material Design 3の多言語体験を、シームレス、一貫、そして美しく提供するための、強力で実用的な機能です.
- [getLocale 関数](https://www.mdui.org/ja/docs/2/functions/getLocale.md): 現在の言語コードを取得し、動作環境を判断します. 外部API連携など細やかな対応を可能にする運用関数. Material Design 3の多言語対応をプログラムから高度に制御し、正確なローカライズを強力に支援します.
- [throttle 関数](https://www.mdui.org/ja/docs/2/functions/throttle.md): 高頻度イベントの実行頻度を抑制し負荷を軽減. アニメーションの滑らかさを維持し、Material Design 3の性能を支えます. 心地よいユーザー体験を実現させるための不可欠なパフォーマンス最適化ユーティリティ.
- [observeResize 関数](https://www.mdui.org/ja/docs/2/functions/observeResize.md): 要素の寸法変化を高精度に追跡します. 動的なレイアウト変化を、メモリリークを防ぎつつ実現. Material Design 3開発において、レスポンスの良さと美しさ、一貫性を追求するための、実用的で堅牢なツールです.
- [breakpoint 関数](https://www.mdui.org/ja/docs/2/functions/breakpoint.md): 表示領域を判定し、閾値による論理チェックをサポート. 環境に応じたJSロジックの構築を支援します. Material Design 3に基づいたレスポンシブデザインを、あらゆる環境で最高の品質で正確に担保するための関数.

## 独立パッケージ

- [アイコンコンポーネントライブラリ @mdui/icons](https://www.mdui.org/ja/docs/2/libraries/icons.md): 全Google Material Iconsを独立コンポーネントとして提供. 1アイコン1ファイルの構成によりツリーシェイキングを活用でき、必要な分だけをバンドル可能です. 一貫したアイコン使用と軽量化を高度に両立.