base-ui-migrator — Claude Code skill: what it does, how to install
base-ui-migrator converts custom React overlays, native HTML dialogs, and libraries like Radix UI to Base UI (@base-ui/react). Preserves existing styles across components.
MIT 144 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill base-ui-migrator -a claude-codeWhat base-ui-migrator does
The skill automates migrating React components to unstyled @base-ui/react primitives. It targets custom overlays built with useState and click-outside listeners, native <dialog> and <select> tags, or packages like Radix UI and Headless UI. It includes an offline catalog of 37 Base UI components backed by documentation snapshots.
The process starts by scanning target directories with scripts/scan-candidates.sh. The agent presents candidates in JSON format, confirms scope with the developer, and swaps elements for Base UI parts while preserving Tailwind or CSS Modules classes. Once editing is done, scripts/verify-migration.sh executes project typechecks and builds to catch syntax errors or leftover patterns.
Candidate scanning relies on jq and ripgrep for speed. Without rg, the scan falls back to grep and takes noticeably longer. Because the workflow modifies source files in place, a clean git working tree is required before running it.
What it helps with
- migrate custom modals and dropdowns to Base UI
- replace Radix UI or Headless UI with
@base-ui/react - detect bespoke overlay components across React codebases
- verify TypeScript builds and remove obsolete primitives after refactoring
Example prompts for the agent
- Scan
src/componentsfor any components that can be migrated to Base UI - Replace the bespoke modal in
src/Dialog.tsxwith Base UI Dialog - Migrate Radix UI dropdown menus to Base UI while keeping existing Tailwind classes
How to install base-ui-migrator
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill base-ui-migrator -a claude-code2Manually: put the files in place
~/.claude/skills/base-ui-migrator/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/base-ui-migrator/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill base-ui-migrator -a codex2Manually: put the files in place
.agents/skills/base-ui-migrator/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill base-ui-migrator -a cursor2Manually: put the files in place
.cursor/skills/base-ui-migrator/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.experimental/base-ui-migrator2Manually: put the files in place
.github/skills/base-ui-migrator/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill base-ui-migrator -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/base-ui-migratorManually: put the files in place
.devin/skills/base-ui-migrator/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill base-ui-migrator -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about base-ui-migrator
How do I install base-ui-migrator in Claude Code?
Run npx skills add pproenca/dot-skills --skill base-ui-migrator -a claude-code. The skill specification will be placed in ~/.claude/skills/base-ui-migrator/SKILL.md.
What command-line dependencies does base-ui-migrator require?
The skill expects curl, jq, and rg (ripgrep) alongside Node.js. If rg is missing, scanning still runs via grep at a slower pace.
Does the migration break existing CSS and Tailwind classes?
No. The skill is designed to swap component architecture while retaining project styling, including Tailwind, CSS Modules, or Emotion.
Source text
SKILL.md · MIT
---
name: base-ui-migrator
description: Migrates React UI code to Base UI (`@base-ui/react`) — replacing bespoke modals, custom dropdowns, raw `<dialog>`/`<select>` elements, ad-hoc popovers/menus/tooltips, or other component libraries (Radix UI, Headless UI, Reach UI). Ships a 37-component catalog (snapshotted from base-ui.com/llms.txt) and scripts to refresh it, scan for migration candidates, and verify the migration compiles. Triggers on phrases like "migrate to base-ui", "use base-ui instead of X", "replace this dialog/popover/menu with base-ui", or when scanning a React codebase for components Base UI can replace. Trigger even if the user only mentions one component (e.g., "swap this modal for base-ui dialog") — the workflow scales from one file to a whole repo.
---
# Base UI Migrator
Automated workflow that converts bespoke React UI primitives and other component libraries to [Base UI](https://base-ui.com) (`@base-ui/react`).
Base UI is the unstyled successor to Radix UI, maintained by the Material UI team and Radix authors. It exposes the same composition model (`Root` + parts) but with a single canonical API, modern data attributes for state styling, and built-in transitions. This skill knows the full catalog (37 components, snapshotted) and how to map common bespoke patterns to it.
## When to Apply
Use this skill when:
- The user explicitly asks to migrate to Base UI, or to a specific Base UI component.
- You spot a React file with bespoke overlays — manual modals, dropdown menus built from `useState` + click-outside hooks, floating UI compositions — that have a Base UI equivalent.
- The codebase uses Radix UI, Headless UI, Reach UI, or react-aria components — these are 1:1 mappable to Base UI.
- The user wants to consolidate a fragmented set of UI primitives behind one library.
- The user wants to scan a directory for migration opportunities.
Do NOT trigger when:
- The user is starting a fresh project and asks for a UI library recommendation (suggest they install Base UI directly, no migration needed).
- The user is migrating *away from* Base UI (out of scope).
## Workflow Overview
```
┌─────────────────────────────────────────────────────────────┐
│ 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) │
└─────────────────────────────────────────────────────────────┘
```
**Risk level:** Write. The skill edits source files. It never force-pushes, deletes branches, or runs irreversible commands. Always commit (or stash) before starting so `git diff` shows the migration cleanly.
## Tool Requirements
| Tool | Purpose | Install |
|------|---------|---------|
| `curl` | Fetch llms.txt + component docs | preinstalled |
| `jq` | Parse JSON output | `brew install jq` |
| `rg` (ripgrep) | Fast candidate scanning | `brew install ripgrep` |
| Node.js + project's typecheck | Verification step | per project |
`scripts/scan-candidates.sh` falls back to `grep` if `rg` is missing, but is much slower.
## Quick Reference
### Scripts
| Script | When to run |
|--------|-------------|
| [`scripts/refresh-catalog.sh`](scripts/refresh-catalog.sh) | Catalog stale (>7 days) or before a large migration |
| [`scripts/scan-candidates.sh`](scripts/scan-candidates.sh) `<path>` | Find migration candidates in a file/dir |
| [`scripts/fetch-component-doc.sh`](scripts/fetch-component-doc.sh) `<name>` | Cache a single component's doc on demand |
| [`scripts/verify-migration.sh`](scripts/verify-migration.sh) | After editing — typecheck + build + leftover scan. Pass `--skip-build` for fast iteration during the migration. |
### References
| File | Read when |
|------|-----------|
| [`references/catalog.md`](references/catalog.md) | Mapping a bespoke pattern to a Base UI component |
| [`references/migration-patterns.md`](references/migration-patterns.md) | Migrating overlays/interactive components (full before/after) |
| [`references/migration-patterns-primitives.md`](references/migration-patterns-primitives.md) | Migrating primitives (Button, Input, etc.) — condensed recipes |
| [`references/workflow.md`](references/workflow.md) | Detailed step-by-step with error handling and rollback |
| [`references/styling-notes.md`](references/styling-notes.md) | Adapting unstyled Base UI to your project's styling |
### Cached Catalog Data
| Path | Description |
|------|-------------|
| `assets/data/llms.txt` | Snapshot of base-ui.com/llms.txt (refresh via script) |
| `assets/data/components/<name>.md` | Per-component docs, fetched on demand and cached |
## Setup
On first use, the skill reads `config.json` for project-specific settings. If empty, ask the user:
- `project_root` — where to scan and apply edits (default: current working directory)
- `package_manager` — `pnpm` / `npm` / `yarn` / `bun` (autodetect from lockfile, confirm)
- `styling` — `tailwind` / `css-modules` / `styled-components` / `emotion` / `vanilla-extract` / `other` (so migrations preserve the project's idiom)
- `target_paths` — directories to scan (default: `src/`)
Save responses back to `config.json` before proceeding.
## Triggers Worth Acting On (Even When Phrased Casually)
- "Swap this modal for Base UI" → run scan on one file
- "We're moving off Radix" → run scan on whole repo, expect 1:1 mappings
- "Replace `<dialog>` with something accessible" → migrate to `Dialog`
- "Build a popover" (in an existing codebase) → check catalog before scaffolding bespoke
## Gotchas
See [`gotchas.md`](gotchas.md). Highlights:
- **Package was renamed**: `@base-ui-components/react` → `@base-ui/react`. Old imports still resolve in some snapshots; always migrate to the new name.
- **Portals are required for overlays**: `Dialog`, `Popover`, `Menu`, `Select`, `Tooltip`, `AlertDialog` all need `<Component.Portal>` between `Root` and `Backdrop`/`Positioner`/`Popup`. Forgetting this is the #1 cause of "it renders but doesn't appear."
- **State is styled via data attributes**: `data-[state=open]`, `data-[starting-style]`, `data-[ending-style]`. Don't reach for JS-driven enter/exit animations — the data attributes drive CSS transitions.
- **Controlled vs uncontrolled**: every interactive component has both modes. Match the source code — if the bespoke version used `useState` for `open`, port to `<Dialog.Root open={...} onOpenChange={...}>`.
## Related Skills
- `react-19-component-scaffolder` — generate new Base UI components from templates after migration
- `tailwind-refactor` — clean up the styling once the structure is on Base UI
- `react-optimise` — re-check rendering performance after the migration
© pproenca · MIT · pproenca/dot-skills