flux-ui

Flux UI（Vue 3）

Flux は Bas Milius による、独自の方針を持つ Vue 3 コンポーネントライブラリです。@flux-ui/components から名前付きエクスポート（SFC、<script lang="ts" setup>）を提供し、ドキュメントは flux-ui.dev で公開されています。正確な props／emits／slots については、こちらが一次情報です。実際のアプリでは、兄弟パッケージの @flux-ui/application（アプリシェル）や @flux-ui/statistics（KPI／チャート）も使用します。

このスキルはルーターです。 長く有効な判断基準（どのコンポーネントを選ぶか、どう組み合わせるか、命名で間違いやすい点）をまとめ、props の一覧はドキュメントに委ねます。以下から適切なリファレンスファイルを選び、props の正確な内容を記憶に頼って作業しないでください。

1. 取り違えを避ける（最初に読む）

「Flux UI」は複数のものを指します。このスキルが対象とするのは、basmilius/flux のみです。Vue 3、npm の @flux-ui/components、ドキュメントは flux-ui.dev です。次のものには適用せず、構文を混在させないでください。

• livewire/flux（fluxui.dev）：flux:button 形式のタグを使用する Laravel／Livewire／Blade キットです。別のプロジェクトです。
• Flux Web Components ライブラリ（j-flex、j-box など）。これも別のライブラリです。

Vue Flux のタスクで flux:button の Blade タグや j- 要素を出力するのは、ライブラリを混同しているということです。作業を中断し、Vue コンポーネントの Flux プレフィックスを使ってください。

2. セットアップ（ビルドを気づかないうちに壊す3つの要因）

インストール全般、Vite プリセット、FluxRoot、アイコン、トークンについては、references/conventions.md を参照してください。あらかじめ知っておくべき注意点は次のとおりです。

• Vue 3.6 のプレリリース版が peer dependency です。 Flux 3.x は vue@latest を受け付けません（3.5.x は peer dependency を満たしません）。許容範囲は 3.6 の安定版リリースが近づくにつれて変わるため、ここに記載されたビルドを信頼するのではなく、パッケージ自体から確認してください（npm view @flux-ui/components peerDependencies）。Flux と @basmilius/vite-preset は、推測した caret 範囲ではなく @latest の dist-tag を使ってインストールしてください。
• Flux パッケージごとに Vite プラグインが1つ必要です（flux()、fluxApplication()、fluxStatistics()）。プラグインがないと、そのパッケージはインポートされていない CSS を含む dist に解決され、スタイルが適用されていないシェル／チャートになります。
• FluxRoot は必須です。 アプリのラッパーとして1つマウントしてください。そうしないと、showAlert／showConfirm／showPrompt／showSnackbar、FluxOverlay、FluxTooltip が例外をスローします。

3. 命名規則（最もよくある落とし穴）

名前は Flux をプレフィックスとする PascalCase です。ほとんどの名前は、ドキュメントのパスを PascalCase にしたものです（form/field → FluxFormField）。ただし、いくつかのグループには例外があり、推測で名前を付けることが最もよくある間違いです。注意すべきパターンは3つあります。

• バリアントが先頭に移動する： button/primary → FluxPrimaryButton、pane/clickable → FluxClickablePane。
• パスの一部が省略される： layout/flex → FluxFlex、form/toggle → FluxToggle。
• 順序が入れ替わる／接尾辞が付け替えられる： form/slider/ranged → FluxFormRangeSlider、filter/async-option → FluxFilterOptionAsync。

button/*、form/*（コントロール）、layout/*、pane/*、filter/* 以下は、名前が例外になっている可能性があるため、必ず調べてください。基本のボタンは FluxButton です。グループ化するラッパーには、それぞれ独自の名前があります（FluxButtonStack、FluxFormRadioGroup など）。すべての例外を含む、ビルドで検証済みの完全な一覧は references/component-index.md にあります（まずこちらを確認してください）。

4. コンポーネントの選び方（選択マップ）

必要なものに合うコンポーネントを選び、正確な名前は references/component-index.md で確認してください。

• ボタン → FluxPrimaryButton / FluxSecondaryButton / FluxDestructiveButton、FluxSplitButton（アクション＋メニュー）、FluxButtonStack（横並び）。 FluxButton をそのまま使わないでください。通常のリンク → FluxLink。
• フォーム → 各コントロールを FluxForm 内の FluxFormField で囲みます。 名前を間違えやすいもの：トグルは FluxToggle、ステッパーは FluxQuantitySelector、範囲入力は FluxFormRangeSlider、 日付入力は FluxFormDateInput です。組み合わせ方：references/forms.md。
• ダイアログとフィードバック → プログラムから表示する場合は showConfirm / showPrompt / showAlert / showSnackbar、リッチな表示またはディープリンク可能な表示には FluxOverlay / FluxSlideOver、 インライン表示には FluxNotice / FluxBadge / FluxTooltip を使います。references/dialogs-and-feedback.md。
• レイアウト、テーブル、ナビゲーション → FluxFlex / FluxGrid / FluxContainer、 FluxPane（カードのサーフェス）、FluxSplitView、FluxDataTable / FluxTable、 FluxKanban、FluxTreeView、FluxCalendar、FluxMenu、FluxTabs、FluxStepper、 FluxCommandPalette、FluxSegmentedControl。references/components.md。
• ダッシュボード／複数ページのアプリ → レイアウトを独自実装せず、シェルに @flux-ui/application、 KPI／チャートに @flux-ui/statistics を使います。 references/patterns.md §6、references/ecosystem.md。
• タイポグラフィ／テキスト → 生の HTML とカスタム CSS ではなく、FluxText（Flux の文字スケール：サイズ／太さ／色、等幅数字、切り捨て）を使います。
• コンポーザブル → useBreakpoints（レスポンシブ対応）、useFluxStore（グローバルストア）、 use*Injection（カスタムコントロール）。references/conventions.md。

5. コンポジションと規約（必ず守るルール）

すぐにコピーして使えるひな形（アプリシェル、CRUD フォーム、データテーブル、ダッシュボード、ダイアログ）は references/patterns.md にあり、横断的なルールは references/conventions.md にあります。 ラッパーのネストを正しくすることは、props より重要です。ファイルを開く前に、以下を把握してください。

• フォーム： FluxForm › FluxPaneBody › FluxFormField（ラベル／ヒント／エラー）› コントロール。送信には FluxPrimaryButton is-submit を使います。Pane： FluxPane › FluxPaneHeader / FluxPaneBody / FluxPaneFooter。
• 分割ボタン： 両方の部分で同じバリアントを使う必要があります（ドロップダウン矢印は内部で FluxSecondaryButton なので、#button スロットにも FluxSecondaryButton を指定します）。references/patterns.md §5。
• オーバーレイ／スライドオーバーの v-if： サーフェス自体ではなく、その内側のペインに指定し（@close もそこに置きます）。そうしないとすぐにアンマウントされ、退出時のトランジションが実行されません。references/dialogs-and-feedback.md。
• アイコンは Font Awesome の登録済みアイコン名文字列です。各コンポーネントのドキュメントページにある「Required icons」も登録してください。注意： FluxIcon / FluxBoxedIcon では、アイコンは icon ではなく name で指定します。
• gap／間隔にはピクセル単位の数値を指定します。色には FluxColor トークン （gray | primary | danger | info | success | warning）を使います。ダークモードは組み込みです。
• 型（FluxIconName、FluxColor、FluxTo など）は @flux-ui/types からインポートしてください。 @flux-ui/components からではありません（そうすると型エラーになります）。
• **すべてのコンポーネントはインポートが必要です。**インポートしない場合、Vue は不明なタグを小文字にしてそのまま描画します（警告はなく、ビルドエラーにもなりません）。

これらの詳細については、references/conventions.md を参照してください。

6. props の正確な情報が必要な場合

prop が存在すると決めつけないでください。コンポーネントのドキュメントページ（すべての URL は references/component-index.md にあります）を開き、Props／Emits／Slots と正確なインポート方法を確認してください。

リファレンスファイル

• references/component-index.md - ビルドで検証済みの、すべてのコンポーネントとトランジションの完全な一覧です。ドキュメントの URL と、名前に関する注意点も記載しています。まずはこちらを確認してください。
• references/conventions.md - インストール、Vite プリセット、FluxRoot、Font Awesome の登録、ルーティング／Nuxt、デザイントークン、色、ダークモード、型、プロパティとスロットの使い分け、コンポーザブル／グローバル API について説明します。
• references/patterns.md - 本番アプリで使われる、慣用的なエンドツーエンドの基本構成です。アプリのシェル、CRUD フォーム、データテーブルとフィルター、確認→実行→スナックバーの流れ、ペインの構成、ダッシュボードを取り上げます。
• references/components.md - レイアウト、テーブル、ナビゲーションの各コンポーネントの選択と構成方法について説明します。どれを選ぶか、各パーツをどう組み合わせるかを解説します。
• references/forms.md - フォームグループ、Field の構成、コントロール、CRUD フォームのパターンについて説明します。
• references/dialogs-and-feedback.md - オーバーレイとプログラムによる表示の使い分け、show* 関数と実際の戻り値の型、通知、インラインフィードバックについて説明します。
• references/ecosystem.md - 関連パッケージの @flux-ui/application（アプリのシェル）と @flux-ui/statistics（KPI／グラフ）、およびそれらのエクスポート内容について説明します。

関連スキル

• vue-component-anatomy - 各コンポーネントの .vue ファイルの構成方法について説明します。ブロックの順序、マクロの順序、プロパティと emit の型指定を取り上げます。
• vue-build-feature - ビュー、コンポーネント、コンポーザブル、ルートにまたがる機能の分割方法について説明します。Flux は、組み合わせて使うコンポーネントを提供します。
• basmilius - Flux UI の背後でよく使われる、同じ作者による別スコープの @basmilius/* パッケージについて説明します。DTO サービス、ストア、useDataTable を取り上げます。