base-ui-migrator

Base UI マイグレーター

独自の React UI プリミティブやその他のコンポーネントライブラリを Base UI（@base-ui/react）に変換する自動ワークフローです。

Base UI は Radix UI のスタイルなし版の後継で、Material UI チームと Radix の作者がメンテナンスしています。同じコンポジションモデル（Root + パーツ）を公開しながら、単一の正規 API、状態のスタイリングに使える最新のデータ属性、組み込みのトランジションを備えています。このスキルはコンポーネントの全カタログ（37 コンポーネントのスナップショット）を把握し、よくある独自パターンを Base UI に対応付ける方法を理解しています。

適用するタイミング

次の場合にこのスキルを使用します。

• ユーザーが Base UI、または特定の Base UI コンポーネントへの移行を明示的に依頼した場合。
• useState とクリック領域外を検知するフックで作られた手動モーダルやドロップダウンメニュー、Floating UI のコンポジションなど、独自のオーバーレイを含む React ファイルを見つけた場合。
• コードベースで Radix UI、Headless UI、Reach UI、または react-aria のコンポーネントが使われている場合。これらは Base UI に 1 対 1 で対応付けられます。
• ユーザーが、分散した UI プリミティブを単一のライブラリに統合したい場合。
• ユーザーが、移行候補を見つけるためにディレクトリをスキャンしたい場合。

次の場合は実行しないでください。

• ユーザーが新規プロジェクトを始めるにあたって UI ライブラリの推奨を求めている場合（移行は不要なので、Base UI を直接インストールするよう提案してください）。
• ユーザーが Base UI からの移行を希望している場合（対象外です）。

ワークフローの概要

┌─────────────────────────────────────────────────────────────┐
│ 0. Stale check — is assets/data/llms.txt > 7 days old?      │
│    └─ if yes → scripts/refresh-catalog.sh                   │
├─────────────────────────────────────────────────────────────┤
│ 1. Scan target — scripts/scan-candidates.sh <path>          │
│    Output: JSON {file, line, pattern, suggested_component}  │
├─────────────────────────────────────────────────────────────┤
│ 2. Triage — present candidates to the user, confirm scope   │
│    (write-risk gate: never migrate silently)                │
├─────────────────────────────────────────────────────────────┤
│ 3. Install @base-ui/react if missing                        │
│    └─ Use the project's package manager (autodetected)      │
├─────────────────────────────────────────────────────────────┤
│ 4. Per candidate:                                           │
│    a. Look up references/catalog.md → get component name    │
│    b. Read references/migration-patterns.md (top tier) OR   │
│       fetch-component-doc.sh <component> (cached on disk)   │
│    c. Edit source — replace bespoke with Base UI parts      │
│    d. Preserve existing styling (Tailwind / CSS Modules)    │
├─────────────────────────────────────────────────────────────┤
│ 5. Verify — scripts/verify-migration.sh                     │
│    Runs typecheck + build + flags leftover bespoke patterns │
├─────────────────────────────────────────────────────────────┤
│ 6. Cleanup — uninstall replaced libraries (optional)        │
└─────────────────────────────────────────────────────────────┘

リスクレベル： 書き込み。このスキルはソースファイルを編集します。強制プッシュ、ブランチの削除、取り消し不能なコマンドの実行は行いません。git diff で移行内容を明確に確認できるよう、開始前に必ずコミット（またはスタッシュ）してください。

ツールの要件

ツール	用途	インストール
curl	llms.txt とコンポーネントのドキュメントを取得	プリインストール済み
jq	JSON 出力を解析	brew install jq
rg（ripgrep）	候補をすばやくスキャン	brew install ripgrep
Node.js + プロジェクトの型チェック	検証ステップ	プロジェクトによる

scripts/scan-candidates.sh は rg がない場合に grep にフォールバックしますが、処理がかなり遅くなります。

クイックリファレンス

スクリプト

スクリプト	実行するタイミング
scripts/refresh-catalog.sh	カタログが古い場合（7 日超）、または大規模な移行の前
scripts/scan-candidates.sh <path>	ファイル／ディレクトリ内の移行候補を検索
scripts/fetch-component-doc.sh <name>	必要に応じて、単一コンポーネントのドキュメントをキャッシュ
scripts/verify-migration.sh	編集後に実行 — 型チェック + ビルド + 残存箇所のスキャン。移行中の素早い反復では --skip-build を指定します。

参考資料

ファイル	読むタイミング
references/catalog.md	独自パターンを Base UI コンポーネントに対応付けるとき
references/migration-patterns.md	オーバーレイ／インタラクティブコンポーネントを移行するとき（移行前／移行後の例をすべて掲載）
references/migration-patterns-primitives.md	プリミティブ（Button、Input など）を移行するとき — 要点をまとめたレシピ
references/workflow.md	エラー処理とロールバックを含む詳細な手順
references/styling-notes.md	スタイルなしの Base UI をプロジェクトのスタイリングに適合させるとき

キャッシュ済みカタログデータ

パス	説明
assets/data/llms.txt	base-ui.com/llms.txt のスナップショット（スクリプトで更新）
assets/data/components/<name>.md	コンポーネントごとのドキュメント。必要に応じて取得し、キャッシュします

セットアップ

初回使用時、このスキルはプロジェクト固有の設定を config.json から読み込みます。空の場合は、ユーザーに次の項目を確認します。

• project_root — スキャンして編集を適用する場所（デフォルト：現在の作業ディレクトリ）
• package_manager — pnpm ／ npm ／ yarn ／ bun（ロックファイルから自動検出し、確認します）
• styling — tailwind ／ css-modules ／ styled-components ／ emotion ／ vanilla-extract ／ other（移行後もプロジェクトの慣習を保つため）
• target_paths — スキャンするディレクトリ（デフォルト：src/）

作業を進める前に、回答を config.json に保存します。

気軽な言い方でも対応すべきトリガー

• 「このモーダルを Base UI に置き換えて」→ 1 つのファイルをスキャンします
• 「Radix から移行します」→ リポジトリ全体をスキャンし、1 対 1 の対応付けを想定します
• 「<dialog> をアクセシブルなものに置き換えて」→ Dialog に移行します
• 「ポップオーバーを作って」（既存のコードベースで）→ 独自実装を作る前にカタログを確認します

注意点

gotchas.md を参照してください。主な注意点：

• パッケージ名が変更されています：@base-ui-components/react → @base-ui/react。古いインポートも一部のスナップショットでは引き続き解決されますが、必ず新しい名前に移行してください。
• オーバーレイにはポータルが必要です：Dialog、Popover、Menu、Select、Tooltip、AlertDialog では、Root と Backdrop ／ Positioner ／ Popup の間に <Component.Portal> が必要です。これを忘れると、「レンダリングされるのに表示されない」という問題の最大の原因になります。
• 状態のスタイル設定にはデータ属性を使います：data-[state=open]、data-[starting-style]、data-[ending-style]。JavaScript による入場／退場アニメーションに頼らないでください。データ属性によって CSS トランジションを制御できます。
• 制御コンポーネントと非制御コンポーネント：すべてのインタラクティブなコンポーネントに、どちらのモードもあります。元のコードに合わせてください。独自実装で open に useState を使用していた場合は、<Dialog.Root open={...} onOpenChange={...}> に移行します。

関連スキル

• react-19-component-scaffolder — 移行後、テンプレートから新しい Base UI コンポーネントを生成します
• tailwind-refactor — 構造を Base UI にした後、スタイルを整理します
• react-optimise — 移行後、レンダリングパフォーマンスを再確認します