# Migrate Radix To Base

> Migra proyectos y componentes React de Radix UI a Base UI: wrappers shadcn, composiciones hechas a mano y su código consumidor, componente a componente o el proyecto completo.

Fuente: https://skillsagentes.com/skills/shadcn-ui/ui/migrate-radix-to-base
Markdown: https://skillsagentes.com/skills/shadcn-ui/ui/migrate-radix-to-base.md

Repositorio: https://github.com/shadcn-ui/ui
Autor: shadcn-ui
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 64 tok instalada, 2.3k tok al activarse, 44.2k tok con todos los archivos del bundle
Bundle: 10 archivos, 173 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add shadcn-ui/ui --skill migrate-radix-to-base --agent claude-code
# Cursor
npx -y skills add shadcn-ui/ui --skill migrate-radix-to-base --agent cursor
# Codex
npx -y skills add shadcn-ui/ui --skill migrate-radix-to-base --agent codex
# Gemini CLI
npx -y skills add shadcn-ui/ui --skill migrate-radix-to-base --agent gemini
# Windsurf
npx -y skills add shadcn-ui/ui --skill migrate-radix-to-base --agent windsurf
# Cline
npx -y skills add shadcn-ui/ui --skill migrate-radix-to-base --agent cline
```

## Qué hace

- Migra wrappers de shadcn y composiciones Radix hechas a mano hacia @base-ui/react, componente por componente o en el proyecto entero
- Detecta pares golden vía la CLI de shadcn o aplica un motor de transformación con tablas de props por familia cuando no hay par golden
- Repuntúa consumidores, elimina dependencias de radix al final y deja el proyecto compilando en cada paso
- Genera reportes en .migration/<componente>.md con lo cambiado, lo dejado igual, cambios de comportamiento y checklist de verificación manual

## Cuándo usarla

- Se pide migrar de radix, mover a base-ui, convertir primitivas radix o cambiar la librería base de un proyecto shadcn
- Migrar un solo componente (ej. "migrate accordion") o el proyecto completo

## Cuándo no

- Para librerías no-radix como cmdk, vaul, sonner, input-otp o react-day-picker, que deben quedar intencionalmente sin tocar

## Qué la activa

- "Migra el componente accordion de Radix a Base UI"
- "Convierte todo el proyecto shadcn de radix-nova a base-nova"
- "Pasa nuestras primitivas radix hechas a mano a @base-ui/react"
- "¿Qué componentes de la UI siguen usando Radix?"

## Antes de instalar

- Requiere un árbol git limpio, trabajar en una rama, y ejecutar `npx shadcn@latest info --json` antes de tocar dependencias.

## Archivos

- SKILL.md — 9 KB
- class-mapping.md — 3 KB
- consumer-props.md — 4 KB
- disclosure.md — 20 KB
- display-misc.md — 25 KB
- form-controls.md — 29 KB
- menus.md — 32 KB
- overlays.md — 31 KB
- universal-patterns.md — 14 KB
- wrapper-shapes.md — 5 KB

## SKILL.md

Reproducido tal cual desde shadcn-ui/ui bajo MIT. Esta sección es el documento original y está en inglés.

# Radix UI -> Base UI migration

You migrate shadcn wrappers, hand-rolled radix compositions, and their
consumers to `@base-ui/react`, keeping the project buildable at every step.
Be precise; never guess a mapping. When a prop or part is not in these
reference files, check `node_modules/@base-ui/react/**/*.d.ts` before
transforming, and record gaps in the report.

## Preflight (always)

1. `npx shadcn@latest info --json` (or the project's runner): gives the
   current base, STYLE (e.g. `radix-lyra`), tailwind version, aliases,
   installed components, and package manager. Trust it over inference.
2. Detect the package manager (packageManager field / lockfile:
   pnpm-lock.yaml, bun.lock, yarn.lock, package-lock.json) and use IT for
   every install. Never leave a stale lockfile.
3. Require a clean git tree; work on a branch; one commit per component.
4. Baseline check BEFORE touching dependencies: run the project's
   typecheck/build so pre-existing failures are never attributed to you.
5. Install `@base-ui/react` alongside radix. Radix packages are removed only
   after the LAST component is migrated (both coexist fine).

## Strategy: golden pair first, transformation engine second

- **Golden pair via the CLI (preferred).** If the project is shadcn with a
  known style (`radix-<style>`), the shadcn CLI itself is the golden-pair
  executor:
  1. Classify each ui wrapper FIRST: diff the user's file against its stock
     origin, using the components.json style VERBATIM in the URL
     (`https://ui.shadcn.com/r/styles/<style>/<component>.json`,
     files[0].content). This works for prefixed styles (radix-nova) AND
     legacy unprefixed ones (new-york, new-york-v4, default), which are all
     still served.
  2. WHOLE-PROJECT mode: flip `components.json` style `radix-<style>` ->
     `base-<style>` now. PROGRESSIVE mode: do NOT flip yet (the project is
     still mostly radix; the flip happens once, after the last component);
     fetch base variants directly by URL instead
     (`https://ui.shadcn.com/r/styles/base-<style>/<component>.json`).
  3. PRISTINE wrappers, whole-project mode: `shadcn add <component>
     --overwrite` delivers the base variant with the project's exact
     icon/font/preset resolution. Never bulk `--all --overwrite`; go
     component by component, or you drown in unrelated registry version
     drift. PROGRESSIVE mode: never use `--overwrite` (it destroys the
     original that consumers still import); write the fetched base variant
     content to `<component>-base.tsx` instead.
  4. CUSTOMIZED wrappers: fetch the base variant and replay the user's diff
     onto it (their customizations must SURVIVE; `--overwrite` would destroy
     them). Mechanical implementation that works at scale:
     `git merge-file user.tsx radix-golden.tsx base-golden.tsx` (three-way
     merge, radix golden as ancestor) auto-resolves most files; hand-resolve
     conflicts with the reference tables.
  5. MANDATORY leftover sweep on EVERY golden-pair file, including ones that
     merged "clean": `grep -n "radix-ui\|@radix-ui\|IconPlaceholder"` per
     file. The registry sometimes reorders functions between variants, which
     makes three-way merges report zero conflicts while leaving stale radix
     hunks in place. A clean merge is NOT proof of a clean file.
  This is more reliable than reconstructing transforms; use it whenever the
  pair exists. Consumer/app code has no CLI mechanism: always hand-migrate it
  against `consumer-props.md`.
- **Legacy styles (new-york, new-york-v4, default): classification only, no
  replay.** These have no base counterpart (there is no base-new-york), and
  retargeting onto a base-<style> variant would restyle the user's app. Use
  the radix golden ONLY to detect customizations, then run the transformation
  engine on the user's OWN file: rewire primitives, keep their exact classes,
  apply class-mapping renames. Their look stays theirs. At the end of a
  legacy whole-project migration, FLAG (do not fix): the style name still
  reads as radix to the CLI, so future `shadcn add` will deliver radix
  variants; the user decides whether to switch style or add manually.
- **Transformation engine (fallback).** Hand-rolled radix code, non-shadcn
  projects, unknown styles: transform using `universal-patterns.md` (imports
  in BOTH forms: `radix-ui` and `@radix-ui/react-*`; asChild->render with the
  worked example; Portal>Positioner>Popup; the positioner FORWARD rule; part
  renames), the per-family props tables (`overlays.md`, `menus.md`,
  `form-controls.md`, `disclosure.md`, `display-misc.md`), `class-mapping.md`
  for data-attribute/CSS-var rewrites, and `wrapper-shapes.md` for exact
  target shapes (tooltip arrow, SubContent defaults, select anatomy).

## Modes

**Progressive (default).** "Migrate accordion" = one component, strangler-fig:
1. Detect in-progress state first: an existing `<component>-base.tsx`,
   consumers split between old/new imports. The files ARE the state; resume,
   never restart.
2. If the component imports other ui wrappers still on radix (select ->
   button), STOP and recommend migrating those first, bottom-up.
3. Write the migrated version to `<component>-base.tsx` (original untouched;
   golden-pair content fetched by URL, or transformed by hand, per the
   strategy above); typecheck. Repoint consumers ONE AT A TIME (imports + the
   call-site props in `consumer-props.md`); typecheck each. When no consumer
   imports the original: delete it, rename `-base` -> original, flip imports
   back, final check, commit. When the LAST radix wrapper in the project is
   finalized, flip `components.json` to `base-<style>` and remove radix deps.

**Whole project** (only when explicitly asked): same per-component work in
dependency order (leaf/shared wrappers like button and label first). After
wrappers, sweep ALL app code against `consumer-props.md` — the call-site
break surface is much larger than asChild. Then remove radix deps, install,
full build.

## Hard rules

- NEVER touch non-radix libraries or their wrappers: cmdk (command), vaul
  (drawer), sonner, input-otp, react-day-picker (calendar), recharts (chart).
  Report them as intentionally untouched.
- No Base UI counterpart: AspectRatio -> CSS aspect-ratio div; Label ->
  native `<label>`; VisuallyHidden -> `sr-only`; Direction -> Direction
  Provider (`direction` prop, not `dir`). Popover Anchor and NavigationMenu
  Indicator have no equivalent: inert passthrough + flag.
- `button.tsx` migrates to the REAL `@base-ui/react/button` primitive, never
  a hand-rolled useRender wrapper.
- Behavior deltas are FLAGGED, never silently patched (tabs manual
  activation, menu items not closing on click, nav-menu 50ms delay). The
  target is idiomatic Base UI matching the shadcn base registry.
- Honest reporting: skipped/reverted files are listed as flagged, never as
  migrated. Pre-existing failures are named as pre-existing.

## Verify and report

Typecheck per file, build per batch, full build at the end vs the baseline.

Reports live in a `.migration/` directory at the project root, ONE FILE PER
COMPONENT: `.migration/<component>.md` (e.g. `.migration/accordion.md`).
Rules:
- Each run writes (or fully overwrites) the file for each component it
  migrated. Re-running a component replaces its report; never touch other
  components' files.
- A multi-component run ("migrate alert-dialog and dropdown-menu") writes one
  file per component, each self-contained; shared consumer-sweep notes are
  repeated in every affected file.
- Whole-project mode writes the per-component files plus
  `.migration/project.md` (dependency swap, app-code sweep summary, final
  build result).
- There is NO index file. Migration status is derived from disk, not
  maintained: scan the project's ui directory (the `ui` alias from shadcn
  info, e.g. components/ui or src/components/ui) for remaining radix imports
  when asked "what's left". End every run's summary with that derived count
  ("N wrappers remain on Radix").

Each `.migration/<component>.md` uses EXACTLY this structure (it is
documented publicly; reports must match it):

```md
# <component>

<date, strategy used (golden pair via CLI / merge / engine), one-line verdict>

## Changed

<every file touched, with what changed and why; include file:line for
anything notable. Confirm the leftover scan is clean:
grep -n "radix-ui\|@radix-ui" on this component's files>

## Left alone

<files that look related but were intentionally not touched, with the reason
(cmdk/vaul/sonner are not radix; unrelated drift; etc.)>

## Behavior changes

<differences that compile fine but act differently; flagged, never patched
(tabs activation, menu close-on-click, delays...). Empty section if none>

## Verify by hand

<short manual QA checklist for this primitive family: focus return on
dialogs, keyboard nav + typeahead on menus/select, tooltip delay feel,
slider commit events. Concrete steps, one minute of clicking>
```

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [shadcn-ui](https://skillsagentes.com/creators/shadcn-ui.md) — 2 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Shadcn](https://skillsagentes.com/skills/shadcn/ui/shadcn.md): Gestiona componentes y proyectos shadcn: añadir, buscar, corregir, depurar, estilizar y componer UI, incluyendo interfaces de chat, con contexto del proyecto y documentación.
- [Shadcn](https://skillsagentes.com/skills/shadcn-ui/ui/shadcn.md): Gestiona componentes y proyectos shadcn: añadir, buscar, corregir, depurar, estilizar y componer UI, incluyendo interfaces de chat, con docs y ejemplos del proyecto.
- [Migrate Radix To Base](https://skillsagentes.com/skills/shadcn/ui/migrate-radix-to-base.md): Migra proyectos y componentes React de Radix UI a Base UI: componentes individuales ('migrate accordion') o proyectos completos, manteniendo el build funcional en cada paso.

## Skills relacionadas

- [Migrate Radix To Base](https://skillsagentes.com/skills/shadcn/ui/migrate-radix-to-base.md): Migra proyectos y componentes React de Radix UI a Base UI: componentes individuales ('migrate accordion') o proyectos completos, manteniendo el build funcional en cada paso.
- [Shadcn](https://skillsagentes.com/skills/shadcn-ui/ui/shadcn.md): Gestiona componentes y proyectos shadcn: añadir, buscar, corregir, depurar, estilizar y componer UI, incluyendo interfaces de chat, con docs y ejemplos del proyecto.
- [Shadcn](https://skillsagentes.com/skills/shadcn/ui/shadcn.md): Gestiona componentes y proyectos shadcn: añadir, buscar, corregir, depurar, estilizar y componer UI, incluyendo interfaces de chat, con contexto del proyecto y documentación.
- [Finishing A Development Branch](https://skillsagentes.com/skills/obra/superpowers/finishing-a-development-branch.md): Úsalo cuando la implementación esté completa, todos los tests pasen, y necesites decidir cómo integrar el trabajo.
- [Using Git Worktrees](https://skillsagentes.com/skills/obra/superpowers/using-git-worktrees.md): Úsalo al empezar trabajo de feature que necesita aislamiento del workspace actual, o antes de ejecutar planes de implementación: asegura un workspace aislado vía herramientas nativas o fallback a git worktree.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)