shadcn-migration

shadcn/ui の Radix UI と Base UI のプリミティブ間を移行する手順ガイドです（3 つ目の基盤である React Aria には、文書化された移行手順がありません）。CLI による移行（`migrate radix|cn|rtl|icons|base-color`）も扱います。移行前のチェックリスト（検出、バックアップブランチ、コンポーネントの一覧作成）、移行順序（最初にリーフコンポーネントの Tooltip／Switch／Checkbox、次に Accordion／Tabs、最後に Dialog／Select／Popover／Menu）、API 変換表（`asChild`→`render`、`DialogContent`→`Dialog.Popup`、`data-state`→`data-[open]` など）、移行後の検証チェックリストを含みます。

shadcn の移行

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

移行前に、name を指定して Agent を 1 回ずつ呼び出し、エージェントを並行して起動してください。

1. fuse-ai-pilot:explore-codebase - 影響を受けるすべてのコンポーネントを一覧化します
2. fuse-ai-pilot:research-expert - Context7 を通じて移行パターンを確認します

移行後は、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

機能	説明
Radix -> Base UI	任意：2026 年 7 月以降、新規プロジェクトでは Base UI がデフォルトです。Radix は非推奨ではありません
Base UI -> Radix	Radix 基盤に移行します（引き続き完全にサポートされています）
React Aria	3 つ目の基盤（aria-*、2026 年 7 月）。ここへの、またはここからの移行手順は文書化されていません。「既存のプロジェクトは現在の基盤を使い続けます」
API マッピング	完全な変換表
検証	移行後のチェックリスト

公式の移行ツール

必要な作業	コマンド／ツール	参照元
Radix -> Base UI、コンポーネント単位	npx skills add shadcn/ui を実行し、エージェントに「migrate accordion to base-ui」と依頼します（段階的に、コンポーネントごとに 1 つのコミットで進行し、.migration/<component>.md に報告します）	changelog 2026-07-base-ui-default
@radix-ui/react-* -> 統合された radix-ui	{runner} shadcn@latest migrate radix [path]	/docs/cli#migrate-radix
clsx + tailwind-merge -> cn パッケージ	{runner} shadcn@latest migrate cn [path]（マージエンジンの対象は tailwind-merge v3 と同様に Tailwind v4 です。Tailwind v3 では tailwind-merge v2 を維持してください。clsx のみの移行は安全で、components.json は不要です）	/docs/cli#migrate-cn
物理クラス -> 論理クラス（RTL）	{runner} shadcn@latest migrate rtl [path]	/docs/cli#migrate-rtl
アイコンライブラリの切り替え	{runner} shadcn@latest migrate icons --from lucide --to phosphor	/docs/cli#migrate-icons
ベースカラーの切り替え	{runner} shadcn@latest migrate base-color --to zinc	/docs/cli#migrate-base-color
非対話型 CI の初期化で Radix を維持	{runner} shadcn@latest init -b radix（現在のデフォルト基盤は base です）	changelog 2026-07-base-ui-default

{runner} shadcn@latest migrate --list を実行すると、利用可能な移行が表示されます（CLI 4.21.0：cn、icons、base-color、radix、rtl）。

重要なルール

1. 移行を開始する前に、必ず検出を実行してください
2. 移行前に、必ずバックアップブランチを作成してください
3. 一度に移行するコンポーネントタイプは 1 つにしてください
4. JSX の変更に合わせて、CSS セレクターも更新してください
5. 各コンポーネントの移行後に、テストを実行してください

アーキテクチャ

Migration order (leaf components first):
1. Tooltip, Switch, Checkbox (simple)
2. Accordion, Tabs (medium)
3. Dialog, Select, Popover, Menu (complex)

-> 完全な例については、migration-dialog.md を参照してください

---

移行前のチェックリスト

[ ] Run shadcn-detection to confirm current primitive
[ ] Create backup branch (git checkout -b pre-migration)
[ ] Inventory all affected files (Grep for imports)
[ ] Review component-specific API changes
[ ] Plan migration order (leaf components first)

---

移行ワークフロー

1. DETECT  -> Run shadcn-detection skill
2. BACKUP  -> Create git branch
3. INVENTORY -> List all affected components
4. TRANSFORM -> Apply API changes per component
5. VALIDATE -> Run tests + sniper check

---

主な API の変更点

項目	Radix	Base UI
コンポジション	asChild	render prop
ダイアログのコンテンツ（プリミティブ）	Dialog.Content	Dialog.Popup（shadcn のラッパーでは DialogContent を維持）
ダイアログのオーバーレイ（プリミティブ）	Dialog.Overlay	Dialog.Backdrop（ラッパーでは DialogOverlay を維持）
位置指定	組み込み	個別の Positioner
アコーディオンの本文（プリミティブ）	Accordion.Content	Accordion.Panel（ラッパーでは AccordionContent を維持）
アコーディオンの単一／複数選択	type="single" collapsible / type="multiple"	defaultValue={[...]} / multiple
生のデータ属性	data-state="open"	data-open（Tailwind の data-open: バリアントは両方に一致）
パッケージ	radix-ui（または旧式の @radix-ui/react-*）	単一の @base-ui/react
components.json のスタイル	radix-*（旧式の new-york）	base-*

---

ベストプラクティス

すること

• コンポーネントの種類ごとに順番に移行します
• 各コンポーネントの移行後にテストを実行します
• JSX とともに CSS セレクターも更新します
• 移行後、使用されていない Radix パッケージを削除します

しないこと

• すべてのコンポーネントを一度に移行しません
• 検出の手順を省略しません
• 本番環境で API が混在した状態を放置しません
• データ属性の CSS セレクターの更新を忘れません

リファレンスガイド

概念

トピック	リファレンス	参照するタイミング
Radix -> Base UI	radix-to-baseui.md	Radix から移行するとき
Base UI -> Radix	baseui-to-radix.md	Radix へ移行するとき

テンプレート

テンプレート	使用するタイミング
migration-dialog.md	移行の完全な例