UI スタックアドバイザー
UI スタックの選択はプロジェクトにおける最も影響力の大きい UI 上の判断です。アクセシビリティの品質、テーマの柔軟性、バンドルサイズ、そして結果の「テンプレート感」を決定します。選択は慎重に、一度だけ行い、それを文書に残しましょう。
ナレッジスナップショット: 2026年11月。ライブラリの進化は速いため、インストール前に現在のメジャーバージョンと API を確認してください（鮮度チェックを参照）。ここにリストされているものよりも、プロジェクトですでに使用されているものを優先してください。
ステップ 1 — まずプロジェクトを読む
package.json / pubspec.yaml / Package.swift / build.gradle をチェックして、既存の UI ライブラリ、スタイリング（Tailwind のバージョン、CSS-in-JS）、フレームワークのバージョン、および components.json（shadcn）、DESIGN.md、トークンファイルの有無を確認します。既存のコンポーネントライブラリの隣に別のものを導入しないでください — 既存のものを拡張するか、ラップしてください。プロジェクトですでにここでの推奨事項と競合するライブラリを使用している場合は、それに言及しますが、頼まれてもいないのに依存関係を入れ替えることはしません。
ステップ 2 — 5 つの質問に答える
- プラットフォーム: Web のみ、モバイルのみ、それとも両方を単一のコードベースで？
- 所有権: コピーインして自由に再スタイルできるソース（shadcn モデル） vs. テーマ API を持つバージョン管理された依存関係（MUI/Mantine モデル）？コピーイン = 最大のデザイン自由度 + 自分でメンテナンス。依存関係 = 高速、一貫性、無料でアップグレード、差別化は困難。
- プロダクトタイプ: マーケティング/ランディング（表現豊か、モーション重視）、プロダクト UI/ダッシュボード（高密度、一貫性、キーボードフレンドリー）、コンテンツ（タイポグラフィ優先）、モバイル消費者アプリ（ネイティブな感触、ジェスチャー）。
- アクセシビリティの基準: 公共セクター/エンタープライズ/EU（欧州アクセシビリティ法）→ 実績のある a11y を持つプリミティブ（React Aria、Base UI、Radix）を選択し、インタラクティブウィジェットを手作りしない。
- スタイリングシステム: Tailwind v4（新しい Web プロジェクトのデフォルト）、CSS Modules/vanilla-extract、または CSS-in-JS；RN では NativeWind vs Unistyles vs Tamagui。
ステップ 3 — デフォルトの選択（他の制約がない場合）
| 状況 | デフォルト | 理由 |
|---|---|---|
| React/Next.js プロダクト UI | shadcn/ui（Base UI プリミティブ — 2026年7月以降のデフォルト；Radix と React Aria もサポート）+ Tailwind v4 | コードを所有、優れた a11y、巨大なレジストリエコシステム、AI ツールがよく理解している |
| React、アクセシビリティ重視/複雑なウィジェット（日付範囲、コンボボックス、ドラッグ＆ドロップ、i18n） | React Aria Components（またはそれを基にした shadcn の React Aria バリアント / HeroUI v3） | 最も厳格な a11y + i18n 動作 |
| React、バッテリー同梱、Tailwind なし | Mantine | 100+ コンポーネント + フック + フォーム + 日付、優れたドキュメント |
| React、エンタープライズ/Material ルック、または高機能データグリッド | MUI v9（+ MUI X Data Grid/Date Pickers/Charts） | 成熟、完全；差別化は困難 |
| エンタープライズ管理（特に中国/APAC チーム） | Ant Design | 巨大なコンポーネントセット、データ密度の高いパターン |
| Vue / Nuxt | Nuxt UI v4（無料、Reka UI + Tailwind v4 上に構築）または shadcn-vue | |
| Svelte / SvelteKit | shadcn-svelte（Bits UI 上） | |
| Solid | Kobalte / solid-ui（shadcn ポート） / Ark UI | |
| Angular | Spartan UI（shadcn 風）または Angular Material / PrimeNG | |
| フレームワークに依存しないプリミティブ | Ark UI（Zag.js ステートマシン；React/Vue/Solid/Svelte） | |
| マーケティング / ランディングページの華やかさ | shadcn + Motion + Magic UI / Aceternity / Animate UI / React Bits からの抜粋 | 1～3 個の特徴的なエフェクトを使用し、コラージュにしない |
| React Native / Expo（新規アプリ） | Expo + Expo Router + NativeWind v5 + React Native Reusables（RN 向け shadcn）または HeroUI Native；真にネイティブな SwiftUI/Compose コントロールには @expo/ui；モーションには Reanimated 4 + Gesture Handler | |
| React Native、StyleSheet スタイルのパフォーマンス重視 | Unistyles 3 + 独自コンポーネント | |
| React Native + Web を単一コードベースで | Tamagui（コンパイラ、ユニバーサル）または Expo + NativeWind + react-native-web | |
| Flutter | Material 3（ビルトイン）/ Cupertino；Material 以外のルックには forui または shadcn_ui | |
| iOS ネイティブ | SwiftUI システムコンポーネント（iOS 26 以降の Liquid Glass は標準コントロールに含まれます） | プラットフォームにできるだけ逆らわない |
| Android ネイティブ | Jetpack Compose Material 3（material3 1.5 ラインの Expressive APIs） |
各プラットフォームの詳細、代替案、トレードオフは参考文献にあります。該当するものを読んでください:
references/web-react.md— React プリミティブ、スタイル付きキット、shadcn エコシステムとレジストリ、Tailwind ツールreferences/web-other.md— Vue、Svelte、Solid、Angular、Astro、プレーン HTML/Web コンポーネントreferences/mobile.md— React Native/Expo、Flutter、SwiftUI、Compose、Kotlin Multiplatformreferences/motion.md— プラットフォーム別のアニメーションライブラリと CSS/ネイティブで十分な場合references/building-blocks.md— アイコン、フォント、チャート、テーブル、フォーム、トースト、日付、DnD、仮想化、エディタ、コマンドメニュー、カルーセル、マップ、3Dreferences/inspiration.md— 参考事例を探す場所（Mobbin、Refero など）と AI デザインツール
ステップ 4 — 決定を記録する
選択をプロジェクト（DESIGN.md または README の「UI スタック」セクション）に書き込みます：ライブラリ + バージョン、スタイリングアプローチ、アイコンセット、モーションライブラリ、フォント、そして理由。将来のセッション（および他のエージェント）が再決定する代わりにそれを読みます。
鮮度チェック（インストール前に行う）
npm view <pkg> version time.modified repository.url # 現在のバージョン + 最終公開日
npm view <pkg> deprecated # 非推奨通知（ある場合）
# Flutter: https://pub.dev/packages/<pkg>（いいね、pub ポイント、最終公開日）
# Swift: リポジトリの最新リリースタグを確認
ライブラリを避けるべきシグナル: 12 ヶ月以上リリースがなく、未解決の重大な Issue がある、README に「unmaintained/archived」と書かれている、ピア依存関係が古い React/RN に固定されている、TypeScript の型がない、a11y の問題が無視されている。既知の退役/リスクのある例: react-beautiful-dnd（非推奨 → @atlaskit/pragmatic-drag-and-drop または dnd kit を使用）、@base-ui-components/react（名称変更 → @base-ui/react）、Chakra v2 API（v3 は Ark UI/Panda 上での書き換え）、Reanimated 2/3 のジェスチャー API（useAnimatedGestureHandler は v4 で削除）。
ドキュメント MCP が利用可能な場合（例: Context7、shadcn MCP、デザインシステム検索用の Figma MCP）、記憶に頼らずそれらを使用して現在のドキュメントを読んでください。
アンチパターン
- 1 つのアプリに 2 つのコンポーネントライブラリ（MUI + shadcn）→ フォーカス、間隔、テーマの不整合。
- ダイアログ、メニュー、コンボボックス、日付ピッカー、トースト、ツールチップの手作り → アクセシビリティのバグ（フォーカストラップ、エスケープ、aria、スクロールロック、衝突）。プリミティブを使用してください。
- 「アニメーションコンポーネント」ライブラリを丸ごとインストール → 必要な 1～3 個の部品だけをコピーする。
- Web ビューを介して React Native 内で Web UI キットを使用する、または iOS ユーザーに Material コンポーネントを強制する。
- ライブラリのデフォルトテーマをそのまま残す → 「すべての shadcn アプリが同じに見える」問題。最低限、フォント、半径、アクセントカラー、ニュートラルな色温度、密度を変更してください（design-system-builder および color-theory スキルを参照）。