К основному содержанию
скилл CX Codex

base-ui-migrator — скилл для Claude Code: что делает и как установить

Скилл base-ui-migrator переводит React-компоненты с Radix UI, Headless UI или самописных оверлеев на Base UI (@base-ui/react). Помогает стандартизировать интерфейс без потери стилей.

MIT 144 установок ★ 227 обновлён 2026-08-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add pproenca/dot-skills --skill base-ui-migrator -a claude-code
Открыть на GitHub

Что делает base-ui-migrator

Скилл автоматизирует перенос интерфейсов на библиотеку @base-ui/react. Он находит самодельные модальные окна на хуках useState, стандартные теги <dialog> и <select>, а также готовые примитивы из Radix UI, Reach UI или Headless UI. В состав входит каталог из 37 компонентов Base UI, созданный на основе выгрузки из base-ui.com/llms.txt.

Процесс строится на скриптах репозитория. Сначала scripts/scan-candidates.sh находит подходящие элементы и выводит их список в формате JSON. Затем агент заменяет разметку на составные части Base UI, сохраняя разметку Tailwind или CSS Modules. В конце запускается scripts/verify-migration.sh, который проверяет сборку и типы проекта.

Для быстрого сканирования в системе нужны утилиты jq и rg (ripgrep). Без установленного ripgrep скрипт переключится на медленный grep. Скилл меняет исходный код напрямую, поэтому перед запуском нужен чистый git-коммит.

Какие задачи решает

  • заменить самодельные модальные окна и меню на Base UI
  • перевести проект с Radix UI или Headless UI на @base-ui/react
  • найти в кодовой базе устаревшие теги <dialog> и <select> для миграции
  • проверить типы и сборку после пакетной замены UI-примитивов

Примеры запросов агенту

  • Найди все компоненты, которые можно перевести на Base UI в папке src/components
  • Замени самодельное модальное окно в src/Modal.tsx на диалог из @base-ui/react
  • Помоги переписать выпадающие списки с Radix UI на Base UI с сохранением стилей Tailwind

Как установить base-ui-migrator

1Через Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill base-ui-migrator -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/base-ui-migrator/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о base-ui-migrator

Как установить base-ui-migrator в Claude Code?

Выполните команду npx skills add pproenca/dot-skills --skill base-ui-migrator -a claude-code. Настройки скилла сохранятся в файле ~/.claude/skills/base-ui-migrator/SKILL.md.

Какие внешние утилиты нужны для работы скилла?

Для быстрого поиска совпадений и парсинга данных понадобятся curl, jq и rg (ripgrep). Если ripgrep не установлен, скрипт поиска перейдёт на стандартный grep.

Затрагивает ли скилл стили компонентов при переносе?

Скилл переносит логику на анатомию Base UI, но сохраняет оформление проекта. При первой настройке он уточняет стек стилей, включая Tailwind CSS, CSS Modules или Styled Components.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
migrate-radix-to-base shadcn-ui Скилл migrate-radix-to-base для Claude Code переносит компоненты и проекты с Radix UI на Base UI. Запускается по просьбе заменить библиотеку или перенести отдельный компонент. CX Codex +1 37 800установок shadcn-ui официальный google-labs-code Помогает находить, добавлять и настраивать компоненты shadcn/ui в React-проектах. Задача — сборка интерфейсов с Tailwind CSS. CX Codex +1 55 400установок radix-ui-design-system sickn33 Скилл radix-ui-design-system для Claude Code собирает дизайн-систему на Radix UI primitives без готовых стилей, с контролем поведения компонентов. Требуется React 16.8+. CX Codex +1 1 400установок base-ui itechmeat Скилл обучает ИИ-ассистента собирать доступные UI-компоненты на базе @base-ui/react, настраивать оверлеи и работать с паттерном render prop. CX Codex +1 238установок base-vs-radix Devin-AXIS Правило base-vs-radix для IDE, которое помогает разработчикам не путать API между базовыми компонентами shadcn и их Radix-версиями. Описывает различия в синтаксисе для Select, Button, Slider, Accordion и других компонентов. CX Codex +1 ★ 7 523звёзд репо shadcn PyModel Подсказывает, как собирать и проверять интерфейсы на shadcn/ui. Помогает с формами, таблицами, темами и доступностью. CX Codex +1 599установок

Из того же набора139

Весь набор →
code-map-visualization Скилл code-map-visualization учит агента рисовать карту кодовой базы: какие данные класть на цвет и размер, как уложиться в 16 мс на кадр и не потерять читаемость. CX Codex +1 145установок nuqs-scaffolder Скилл nuqs-scaffolder собирает из одного JSON-описания четыре файла для фильтров в URL на Next.js: карту парсеров, серверный загрузчик, клиентский компонент и тест. CX Codex +1 145установок migrate-js-to-modern-typescript Скилл migrate-js-to-modern-typescript пошагово переводит проект с JavaScript на строгий TypeScript, настраивает tsconfig и помогает отказаться от any без поломки сборки. CX Codex +1 145установок radical-simplification Скилл radical-simplification для Claude Code разбирает сложные инженерные и продуктовые задачи через смену рамки, упрощение и проверку предположений. Помогает выйти из тупика. CX Codex +1 144установок implementation-design-patterns-python Скилл implementation-design-patterns-python для Claude Code помогает выбирать и применять паттерны проектирования в современном Python. Он помогает разбираться с разрастающимися ветвлениями, наследованием и связями между объектами. CX Codex +1 143установок better-auth-scaffold Скилл better-auth-scaffold раскладывает Better Auth по файлам в проекте Next.js с App Router и Drizzle: шаблоны, три набора плагинов, генерация схемы и миграции. CX Codex +1 143установок expo-ui Скилл помогает писать и проверять React Native-интерфейсы на @expo/ui для iOS. Пригодится при переносе экранов на SwiftUI и работе с компонентами iOS 26. CX Codex +1 142установок design-to-react-algorithms Скилл design-to-react-algorithms задаёт алгоритмический пайплайн переноса макетов Sketch и Figma в чистый React с CSS без регрессий вёрстки. CX Codex +1 142установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой