react-shadcn

shadcn/ui（CLI 4.21.0）と Tailwind CSS v4 を使い、プロジェクトで採用しているコンポーネントのベースに応じて、React SPA（Vite）向けの UI コンポーネントを構築します。対応するベースは Base UI（2026 年 7 月以降の新規プロジェクトのデフォルト）、Radix UI（統合された `radix-ui` パッケージで完全サポート）、React Aria（2026 年 7 月に追加）です。フォーム（TanStack Form を使った Field/FieldLabel/FieldError パターン。React Hook Form は使用しません）、オーバーレイ（Dialog、Sheet、Drawer、Popover、Tooltip）、フィードバック（Base UI では Alert、Toast、Radix と Aria では Sonner、Progress、Skeleton）、データ表示（Table、Badge、Calendar、Chart）、ナビゲーション（Sidebar、Command、DropdownMenu）を扱います。

コンポーネントのコードを書く前に、components.json からベースを検出する必要があります。コンポーネントは bunx --bun shadcn@latest add を使って @/modules/cores/shadcn/components/ui/ にインストールしてください（手書きは禁止）。実装前にコンポーネントを探すための MCP レジストリツール（mcp__shadcn__*）も扱います。これは shadcn/ui のプレーンな React 版です。Next.js App Router 版については nextjs-shadcn を参照してください。

React 向け shadcn/ui

Tailwind CSS v4 でスタイルを設定した、Base UI、Radix UI、React Aria のプリミティブをベースにした、アクセシブルでコピーして使えるコンポーネントです。

エージェントのワークフロー（必須）

実装を始める前に、必ず name を指定して Agent を 1 回ずつ呼び出し、3 つのエージェントを並行して起動します。

1. fuse-ai-pilot:explore-codebase - 既存のコンポーネントとパターンを分析します
2. fuse-ai-pilot:research-expert - Context7/Exa を使って最新の shadcn/ui ドキュメントを確認します
3. mcp__shadcn__* - コンポーネントが利用可能かレジストリを検索します

実装後、検証のために fuse-ai-pilot:sniper を実行します。

---

概要

使用する場面

• React アプリケーション（Vite）向けの UI コンポーネントを構築する場合
• アクセシブルでカスタマイズ可能なフォームコンポーネント（入力、セレクト、チェックボックス）が必要な場合
• Dialog、Sheet、Drawer、オーバーレイのパターンを実装する場合
• 並べ替え、フィルタリング、ページネーションに対応したデータテーブルを作成する場合
• ナビゲーションメニュー、サイドバー、コマンドパレットを構築する場合
• トースト通知やアラートのフィードバックコンポーネントが必要な場合

shadcn/ui を選ぶ理由

特長	メリット
コピー＆ペースト方式	コンポーネントをプロジェクトにコピーするため、完全に所有できます
ベースを選択可能	Base UI（デフォルト）、Radix UI、React Aria — コンポーネント名は共通です
Tailwind CSS v4 によるスタイル設定	CSS ファーストのテーマ（@theme inline、OKLCH トークン）
TanStack Form に対応	Field と FieldError は Standard Schema の問題を受け取れます
Lucide アイコン（デフォルト）	components.json の iconLibrary で、migrate icons を使って切り替え可能です

---

重要なルール

1. 最初にベースを検出する - components.json の style を確認します。base-* は Base UI、radix-* / new-york は Radix、aria-* は React Aria です。1 つのコンポーネント内でベースを混在させないでください
2. 新規プロジェクトのデフォルトは Base UI - -b radix / -b aria を指定しない限り、init は Base UI を選択します
3. ベースに沿ってコンポジションする - Base UI は render={<Button />}、Radix は asChild を使います。Radix と記載された参考例は、Base UI のプロジェクトでは適切な形に読み替えてください
4. コンポーネントを手動で作成しない - 必ず bunx --bun shadcn@latest add でインストールしてください（レジストリからプロジェクトのベースに対応するバリアントが提供されます）
5. TanStack Form のみを使う - React Hook Form は使用しません。Field に data-invalid を、コントロールに aria-invalid を設定してエラーを連携してください
6. SOLID パス - コンポーネントの配置先は @/modules/cores/shadcn/components/ui/ です

---

コードに影響するベースの違い

項目	Base UI（デフォルト）	Radix UI
パッケージ	@base-ui/react	radix-ui（統合版。@radix-ui/react-* からは migrate radix）
カスタム要素としてのトリガー	<DialogTrigger render={<Button />}>開く</DialogTrigger>	<DialogTrigger asChild><Button>開く</Button></DialogTrigger>
Select	<Select items={items}>、SelectContent alignItemWithTrigger	<SelectContent position="item-aligned" | "popper">
Accordion	multiple、defaultValue={["item-1"]}	type="single" collapsible / type="multiple"
Toggle group の値	配列（defaultValue={["bold"]}）、multiple	type="single" | "multiple"
Checkbox の不確定状態	indeterminate プロパティ	checked="indeterminate"
Drawer	Base UI Drawer（swipeDirection）	Vaul（direction）
Toast	add toast → toast.add({ title })	add sonner → sonner の toast("…")
開閉状態のスタイル設定	data-open / data-closed	data-state="open"（どちらも shadcn/tailwind.css の data-open: バリアントで対応）

両方のベースで共通：コンポーネント名、DialogContent / SheetContent の showCloseButton、 Field ファミリー、テーマトークン。

---

アーキテクチャ

コンポーネントの基盤

• プリミティブ - Base UI / Radix UI / React Aria（components.json による）
• Tailwind CSS v4 - CSS ファーストの設定：@import "tailwindcss"、@import "shadcn/tailwind.css"、@custom-variant dark、@theme inline
• class-variance-authority - コンポーネントスタイルのバリアント管理
• cn パッケージ - レジストリコンポーネントでは import { cn } from "cn" を使用（2026年9月、twMerge(clsx(...)) のドロップイン置き換え）；lib/utils.ts が再エクスポート；既存プロジェクトは shadcn migrate cn で移行

プロジェクト構成

SOLID アーキテクチャに従い、コンポーネントを @/modules/cores/shadcn/components/ui/ にインストールします。ユーティリティは @/modules/cores/lib/utils.ts（export { cn } from "cn"）にあります。

---

MCP サーバー統合

bunx --bun shadcn@latest mcp init --client claude を実行するか、.mcp.json を作成して、shadcn レジストリと Claude Code を統合します。

利用可能な MCP ツール

• mcp__shadcn__search_items_in_registries - 利用可能なコンポーネントを検索
• mcp__shadcn__view_items_in_registries - コンポーネントのソースコードを表示
• mcp__shadcn__get_item_examples_from_registries - 使用例を取得
• mcp__shadcn__get_add_command_for_items - インストールコマンドを取得

エージェント向けの CLI ヘルパー：shadcn info（フレームワーク、ベース、インストール済みコンポーネント）および shadcn docs <component> -b <base|radix|aria>。

セットアップの全手順については、installation.md を参照してください。

---

コンポーネントのカテゴリー

カテゴリー	コンポーネント	主なリファレンス
セットアップ	初期化、設定、テーマ設定、アイコン	installation.md
フォーム	Button、Input、Field、Select、Checkbox、Switch、Slider	field-patterns.md
オーバーレイ	Dialog、Sheet、Drawer、Popover、Tooltip、HoverCard	dialog.md
フィードバック	Alert、Toast（Base UI）/ Sonner（Radix、Aria）、Progress、Skeleton、Spinner	toast.md
データ表示	Table、Badge、Avatar、Calendar、Chart、Carousel	table.md
ナビゲーション	Breadcrumb、DropdownMenu、Command、Sidebar、Tabs	sidebar.md
レイアウト	Card、Accordion、Separator、ScrollArea、Resizable	card.md

特に記載がない限り、コンポーネントのリファレンスには Radix API が記載されています。各リファレンスの先頭には Base UI との違いが記載されています。

---

ベストプラクティス

1. Field コンポーネント - Field + FieldLabel + FieldError errors={field.state.meta.errors}
2. クライアントコンポーネント - React アプリはデフォルトでクライアントサイドです（"rsc": false）
3. ベースごとのトースト - Base UI では Base UI Toast、Radix／Aria では Sonner を使用します（Radix Toast は非推奨です）
4. まず MCP ツールを使用 - 実装前に mcp__shadcn__* を使って調べます
5. CSS 変数によるテーマ設定 - src/index.css の :root／.dark に OKLCH トークンを定義し、@theme inline で公開します
6. アクセシビリティ - プリミティブのキーボードナビゲーションと ARIA を活用し、無効なコントロールでは aria-invalid を維持します

---

リファレンスガイド

必要な内容	リファレンス
初期設定	installation.md, configuration.md
フォームのパターン	field-patterns.md, form-examples.md
テーマのカスタマイズ	theming.md
データテーブル	table.md
モーダルダイアログ	dialog.md, alert-dialog.md
ナビゲーション	sidebar.md, navigation-menu.md