Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill base-ui-migrator -a claude-code
Open on GitHub

What 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/components for any components that can be migrated to Base UI
  • Replace the bespoke modal in src/Dialog.tsx with 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-code

2Manually: put the files in place

~/.claude/skills/base-ui-migrator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/base-ui-migrator/

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

Similar skills

All skills for Frontend and UI →

From the same set139

The whole set →
code-map-visualization code-map-visualization tells the agent how to draw a codebase map that is already projected: which attribute goes on position, size or colour, and how to stay inside a 16 ms frame. CX Codex +1 145installs nuqs-scaffolder nuqs-scaffolder turns one JSON spec into four Next.js files for URL-backed filters: a parser map, a server loader, a client component and a Vitest test. CX Codex +1 145installs migrate-js-to-modern-typescript migrate-js-to-modern-typescript guides the file-by-file conversion of a JavaScript codebase to strict TypeScript. Helps configure tsconfig, turn on strict compiler flags, and eliminate any without breaking the build. CX Codex +1 145installs radical-simplification radical-simplification — a skill for untangling hard engineering and product problems by changing the frame, reducing scope, and testing assumptions. Use it when the current approach has stalled. CX Codex +1 144installs implementation-design-patterns-python implementation-design-patterns-python — a Python design-pattern guide for choosing an approach when conditionals, inheritance, or object relationships start to sprawl. It favors modern Python idioms over class-heavy templates. CX Codex +1 143installs better-auth-scaffold better-auth-scaffold scaffolds Better Auth in a Next.js App Router project on Drizzle: file templates, three plugin presets, schema generation and migrations. CX Codex +1 143installs expo-ui Guidance for building and reviewing React Native screens with @expo/ui on iOS. Useful when adopting SwiftUI views or working with iOS 26 interface features. CX Codex +1 142installs design-to-react-algorithms The design-to-react-algorithms skill provides a step-by-step pipeline to convert Sketch files into React and CSS while preventing layout regressions. CX Codex +1 142installs

Project sponsors

Companies that keep this analytics open