shadcn-components

shadcn/ui のコンポーネントパターンを、3 つのベース（Base UI（2026 年 7 月以降のデフォルト）、Radix、React Aria）ごとに説明します。API の違い、プリミティブ間の対応関係（Dialog/Select/Tooltip/Accordion/Popover/Menu/Combobox）、ベースごとのコンポーネントの利用可否、および 3 つのコンポジションパターン（Base UI の `render`、Radix の `asChild`、React Aria のトリガーラッパーの子要素）を取り上げます。

まずプロジェクトのプリミティブを検出し（shadcn-detection）、コンポーネントの内部実装を手書きするのではなく、shadcn MCP にレジストリソースを確認する必要があります。

shadcn コンポーネント

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

コンポーネントの作業に入る前に、エージェントを並行して起動します。それぞれ name を指定して、Agent を 1 回ずつ呼び出してください。

1. fuse-ai-pilot:explore-codebase - 既存のコンポーネントを探します
2. fuse-ai-pilot:research-expert - Context7 でコンポーネントの API を確認します
3. mcp__shadcn__search_items_in_registries - 利用可能なコンポーネントを検索します

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

---

概要

機能	説明
Base UI プリミティブ	2026-07-02 以降、新規プロジェクトのデフォルトベースです（base-* スタイル、@base-ui/react）。init --defaults = Next.js テンプレート + base ベースの nova プリセット = base-nova
Radix プリミティブ	元のベース（2023 年）で、引き続き完全にサポートされています（radix-* スタイル、統合された radix-ui パッケージ）。init -b radix
React Aria プリミティブ	2026-07-17 以降の第 3 のベースです（aria-* スタイル、react-aria-components）。init -b aria
コンポーネントの対応関係	Base UI と Radix では同じ shadcn ラッパー名を使用します。React Aria のラッパーは異なります（以下を参照）
API の違い	render と asChild とトリガーラッパー、パーツの命名、データ属性
cn のインポート	コンポーネントは cn パッケージから cn をインポートします（2026 年 9 月）。lib/utils.ts は export { cn } from "cn" です

CLI からベース固有のドキュメント、例、API リンクを取得します。{runner} shadcn@latest docs dialog --base aria（--base base|radix|aria。デフォルトはプロジェクトのベースです）。コンポーネントページ：/docs/components/{base|radix|aria}/<name>。各ページに Composition ツリーがあります。

---

重要なルール

1. コンポーネントの作業前に、必ずプリミティブを検出します（shadcn-detection）
2. コンポーネントを追加する前に、必ず MCP を参照します
3. 同じコンポーネント内で Base UI、Radix、React Aria の API を決して混在させません
4. 検出されたプリミティブに応じたコンポジションパターンを使用します
5. 手書きのコードではなく、レジストリソースを正として扱います

---

アーキテクチャ

components/ui/
├── dialog.tsx          # Adapted to detected primitive
├── select.tsx
├── accordion.tsx
└── ...

-> 完全なコンポーネントについては、dialog-example.md を参照してください

---

MCP の使用（必須）

コンポーネントを追加する前に、必ず shadcn MCP を参照してください。

mcp__shadcn__search_items_in_registries -> find component
mcp__shadcn__view_items_in_registries   -> view source
mcp__shadcn__get_add_command_for_items  -> get install command

---

コンポーネント対応表

components/ui/*.tsx で使用されるプリミティブパーツ（レジストリの *-nova ソース、ui.shadcn.com/r/styles/<style>/<name>.json）：

コンポーネント	Radix パーツ	Base UI パーツ	React Aria パーツ
ダイアログのコンテンツ	Dialog.Content	Dialog.Popup	Modal > Dialog
ダイアログのオーバーレイ	Dialog.Overlay	Dialog.Backdrop	ModalOverlay
セレクト	Select.Content	Select.Positioner + Select.Popup (+ Select.List)	Select + Popover > ListBox
ツールチップ	Tooltip.Content	Tooltip.Positioner + Tooltip.Popup	TooltipTrigger > Tooltip
アコーディオン	Accordion.Content	Accordion.Panel	DisclosureGroup > Disclosure > DisclosurePanel
ポップオーバー	Popover.Content	Popover.Positioner + Popover.Popup	DialogTrigger > Popover
メニュー	DropdownMenu.Content	Menu.Positioner + Menu.Popup	MenuTrigger > Popover > Menu
コンボボックス	なし（@base-ui/react の Combobox を使用）	Combobox.*	ComboBox + Popover > ListBox

呼び出し側のラッパー API（@/components/ui/*）：

ラッパーの使用方法	Base UI	Radix	React Aria
Dialog	Dialog > DialogTrigger + DialogContent	Base UI と同じ	DialogTrigger > Button + Dialog（DialogContent なし）
Popover / Tooltip / DropdownMenu	X > XTrigger + XContent	同じ	XTrigger > Button + X（例：DropdownMenuTrigger > Button + DropdownMenu）
Accordion	defaultValue={["a"]}、multiple	type="single" collapsible defaultValue="a"、type="multiple"	defaultExpandedKeys={["a"]}、allowsMultipleExpanded、項目には id を使用
Select	Select の items プロパティ、SelectItem value	SelectItem value	Select の placeholder、SelectItem id
Combobox	items + ComboboxList のレンダー関数	Base UI と同じ	ComboboxList の子要素、renderEmptyState、ComboboxItem id
イベント／状態	onClick、disabled、open/onOpenChange	同じ	onPress、isDisabled、isOpen/onOpenChange
生のデータ属性	data-open、data-starting-style、data-side	data-state="open"、data-side	data-entering/data-exiting、data-placement、data-focused、data-pressed

共通の data-open: / data-closed: / data-checked: Tailwind バリアント（shadcn/tailwind.css 由来）は、[data-state=...] と [data-open] の両方に一致します。

ベース別のコンポーネント提供状況

コンポーネント	Base UI	Radix	React Aria
Toast（@base-ui/react/toast、toast.add()）	はい（2026 年 7 月）	いいえ：Sonner を使用	いいえ：Sonner を使用
Sonner	レジストリアイテムあり。ドキュメントは Toast に誘導	はい	はい
Menubar、Navigation Menu	はい	はい	いいえ（r/styles/aria-nova/{menubar,navigation-menu}.json → 404）
Questionnaire（@shadcn/react/questionnaire をスタイル設定）	はい	はい	はい
MessageScroller、Message、Bubble、Attachment、Marker（チャット、2026 年 6 月）	はい	はい	はい（ドキュメントページあり）
Blocks（login-01、サイドバー、ダッシュボードなど）	はい	はい	はい（例：r/styles/aria-nova/login-01.json）。add はプロジェクトのベースを選択

フォーム（/docs/forms）：すべてのガイドは Field、FieldLabel、FieldDescription、FieldError、FieldGroup を基盤として構築されており、Field に data-invalid、コントロールに aria-invalid を設定します — React Hook Form（Controller + Zod zodResolver）、TanStack Form（form.Field のレンダープロップ + Zod）、Formisch（Form + Field、Valibot スキーマ）、Next.js（Server Action + useActionState、サーバー側の Zod）。

@shadcn/react = スタイルなしのヘッドレスプリミティブ（@shadcn/react/questionnaire、@shadcn/react/message-scroller）；@shadcn/helpers（/ai-sdk、/tanstack-ai）= デモ／テスト用のスクリプト化された useChat の会話であり、UI ではありません。レンダリングされた Markdown のタイポグラフィ：shadcn/typeset（単一の typeset.css、className="typeset"）。

---

コンポジションパターン

Radix：asChild

<Dialog.Trigger asChild>
  <Button variant="outline">Open</Button>
</Dialog.Trigger>

Base UI：render

<Dialog.Trigger render={<Button variant="outline" />}>
  Open
</Dialog.Trigger>

React Aria：トリガーのラッパー（asChild なし、render なし）

<DialogTrigger>
  <Button variant="outline">Open</Button>
  <Dialog>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
    </DialogHeader>
  </Dialog>
</DialogTrigger>

---

リファレンスガイド

概念

トピック	リファレンス	確認するタイミング
Radix API	radix-components.md	Radix プリミティブを使用して構築する場合
Base UI API	baseui-components.md	Base UI プリミティブを使用して構築する場合
React Aria API	上の表 + dialog-example.md	React Aria プリミティブを使用して構築する場合

テンプレート

テンプレート	使用するタイミング
dialog-example.md	Dialog コンポーネントを作成する場合

---

ベストプラクティス

推奨事項

• 最初にプリミティブを検出します（shadcn-detection を使用）
• 編集前に、コンポーネントのソースを MCP で確認します
• プロジェクト内の既存の命名規則に従います
• 検出したプリミティブに適したコンポジションパターンを使用します

禁止事項

• 同じコンポーネントで asChild、render、React Aria のトリガーラッパーを混在させないでください
• 検出せずに Radix（または新しい Base UI のデフォルト）だと決めつけないでください
• コンポーネントの内部を手書きしないでください（MCP を使用します）
• 新しいコンポーネントを追加する前にレジストリを確認する手順を省略しないでください