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 组件。
• 你发现某个 React 文件使用了定制的浮层——手动实现的模态框、使用 useState + 点击外部钩子构建的下拉菜单、浮动 UI 组合——而 Base UI 有对应组件。
• 代码库使用 Radix UI、Headless UI、Reach UI 或 react-aria 组件——这些都可以一对一映射到 Base UI。
• 用户希望将零散的 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 + 项目的类型检查	验证步骤	按项目而定

如果缺少 rg，scripts/scan-candidates.sh 会回退到 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” → 对一个文件运行扫描
• “我们要弃用 Radix” → 对整个仓库运行扫描，预计存在一对一映射
• “把 <dialog> 换成无障碍的实现” → 迁移到 Dialog
• “构建一个弹出框”（在现有代码库中）→ 在搭建定制实现之前先检查目录

注意事项

请参阅 gotchas.md。重点如下：

• 包已重命名：@base-ui-components/react → @base-ui/react。旧导入在某些快照中仍可解析；请始终迁移到新名称。
• 叠层必须使用 Portal：Dialog、Popover、Menu、Select、Tooltip、AlertDialog 都需要在 Root 和 Backdrop/Positioner/Popup 之间放置 <Component.Portal>。忘记添加它是“已渲染但未显示”问题的头号原因。
• 状态通过数据属性设置样式：data-[state=open]、data-[starting-style]、data-[ending-style]。不要使用由 JS 驱动的进入/退出动画——数据属性会驱动 CSS 过渡效果。
• 受控与非受控：每个交互式组件都支持这两种模式。请匹配源代码——如果定制实现使用 useState 管理 open，则迁移为 <Dialog.Root open={...} onOpenChange={...}>。

相关技能

• react-19-component-scaffolder — 迁移后，根据模板生成新的 Base UI 组件
• tailwind-refactor — 结构基于 Base UI 后，整理样式
• react-optimise — 迁移后重新检查渲染性能