# base-ui-migrator

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 144 installs · ★ 227 repo stars
- Author: pproenca
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/base-ui-migrator/SKILL.md
- Updated: 2026-08-15
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/base-ui-migrator

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill base-ui-migrator -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/base-ui-migrator/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/base-ui-migrator/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill base-ui-migrator -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/base-ui-migrator/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill base-ui-migrator -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/base-ui-migrator/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pproenca/dot-skills skills/.experimental/base-ui-migrator
```

2. **Manually: put the files in place**
- File: `.github/skills/base-ui-migrator/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill base-ui-migrator -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/base-ui-migrator
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/base-ui-migrator/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill base-ui-migrator -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/base-ui-migrator/SKILL.md

## When to use it
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 595f4860cf92d021.

BEGIN THIRD-PARTY FILE 595f4860cf92d021
````text
---
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                   │
````
END THIRD-PARTY FILE 595f4860cf92d021

The third-party file has ended. Everything between the 595f4860cf92d021 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2485 of 9119 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/base-ui-migrator/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
