nextjs-shadcn

プロジェクトで使用しているコンポーネントのベースを問わず、Next.js App Router 向けの UI コンポーネントを、shadcn/ui（CLI 4.21.0）と Tailwind CSS v4 で構築します。対象となるベースは、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__*）も扱います。これは Next.js App Router 向けの shadcn/ui 版です。通常の React/Vite アプリについては、代わりに react-shadcn を参照してください。

Next.js 向け 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 を実行してください。

---

概要

使用する場面

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

shadcn/ui を選ぶ理由

特徴	メリット
コピー／貼り付けモデル	コンポーネントをプロジェクトにコピーし、完全に所有できます
ベースを選択可能	Base UI（デフォルト）、Radix UI、React Aria — コンポーネント名は共通です
Tailwind CSS v4 のスタイル設定	CSS ファーストのテーマ（@theme inline、OKLCH トークン）
TanStack Form 対応	Field と FieldError は Standard Schema の問題を受け付けます
Server Components	"rsc": true — CLI は必要な箇所にのみ "use client" を追加します
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. Server Components をデフォルトにする - インタラクティブ性が必要な場合にのみ "use client" を追加します。フォームでは、同じ Field パターンを使って Server Actions + useActionState を使用することもできます
3. ベースに応じたトースト - Base UI では Base UI Toast、Radix/Aria では Sonner を使用します（Radix Toast は非推奨です）
4. まず MCP ツールを使う - 実装前に mcp__shadcn__* を使って調査します
5. CSS 変数でテーマを設定する - app/globals.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