What is the migrate-radix-to-base skill?
The migrate-radix-to-base skill is a SKILL.md in the shadcn-ui/ui repository. It migrates React components from Radix UI to @base-ui/react, using the shadcn CLI's own base variants where they exist and mapping tables where they do not. It works progressively, one component per run, or across a whole project.
It is a skill in the skills folder of the shadcn-ui/ui repository, next to the main shadcn skill. It migrates shadcn wrappers, hand-rolled Radix compositions and their consumers to @base-ui/react while keeping the project buildable at every step.
The skill's rule is to never guess a mapping. When a prop or part is missing from its reference files, the agent checks the Base UI type definitions in node_modules before it transforms anything and records the gap in a report.
What changes in your agent's output
- The agent starts from
npx shadcn@latest info --json, so it knows your current base, style, Tailwind version, aliases and installed components. - It works on a branch with a clean git tree, one commit per component, and runs a baseline typecheck first so old failures are not blamed on the migration.
- For shadcn styles, it uses the CLI's own base variants as the reference, and replays your customizations onto them with a three-way merge.
- asChild becomes render, overlays become Portal, Positioner and Popup, and call sites are swept against a consumer props table.
- Each component gets a report in a .migration folder listing what changed, what was left alone, behavior changes and a manual QA checklist.
Progressive or whole project
The default mode is progressive. Asking to migrate accordion migrates only that component, as a base copy next to the original, and repoints consumers one at a time. The whole-project mode runs only when you ask for it.
- Progressive mode flips components.json to the base style only after the last Radix wrapper is finalized.
- Whole-project mode flips the style first, then migrates in dependency order, leaf wrappers such as button and label first.
- Both modes end by removing Radix packages and running a full build against the baseline.
Who the skill is for
Best for
- shadcn projects on a radix style that want to move to a base style without hand-rewriting every wrapper.
- Apps with their own Radix compositions that need a careful, reviewable move to Base UI.
- Teams that want a written trail per component, so reviewers see exactly what changed.
Not for
- Projects that do not use Radix. The skill's whole job is the Radix to Base UI change.
- Day-to-day shadcn work such as forms and composition rules. Use the shadcn skill for that, and the shadcn MCP server to search and add registry items.
- Choosing a different component library. For that decision, see pick-ui-library.
How to install Migrate Radix to Base UI Skill for shadcn Projects
git clone https://github.com/shadcn-ui/ui.gitClone the repository
Run
git clone https://github.com/shadcn-ui/ui.git. The skill is the skills/migrate-radix-to-base folder.Copy the skill folder
Copy skills/migrate-radix-to-base into your agent's skills folder, with its mapping files. SKILL.md refers to them by name, for example consumer-props.md and overlays.md.
Prepare the project
Commit or stash your work and create a branch. The skill requires a clean git tree.
Ask for one component
Try: migrate accordion to Base UI. Ask for the whole project only when you want every wrapper moved in one pass.
Check that it loaded
After a run, check for a .migration folder with one markdown file per component, and confirm your typecheck matches the baseline taken before the first change.
Key features
- Preflight checksThe agent reads the shadcn info output, detects the package manager from the lockfile, requires a clean git tree and runs a baseline typecheck or build before touching dependencies.
- Golden pair via the CLIFor shadcn styles, stock Radix and base variants are fetched by URL. Pristine wrappers are replaced with
shadcn add --overwrite, one component at a time, never with all at once. - Customizations surviveA customized wrapper is diffed against its stock origin, and the diff is replayed onto the base variant with a three-way merge instead of an overwrite.
- Leftover sweepEvery migrated file is grepped for radix-ui, @radix-ui and IconPlaceholder, because a clean merge is not proof of a clean file.
- Transformation engineFor hand-rolled code, the skill ships mapping files for universal patterns, overlays, menus, form controls, disclosure, display parts, class mapping and wrapper shapes.
- asChild to renderBoth import forms, radix-ui and @radix-ui/react-*, are handled, asChild becomes render with a worked example, and overlays follow the Portal, Positioner, Popup shape.
- Protected librariescmdk, vaul, sonner, input-otp, react-day-picker and recharts are never touched. They are reported as intentionally untouched.
- Behavior deltas flaggedDifferences that compile but act differently, such as tabs activation or menu items closing on click, are flagged in the report and never silently patched.
- Honest reportingSkipped or reverted files are listed as flagged, not as migrated, and every run ends with a count of wrappers still on Radix.
Frequently asked questions
What is the migrate-radix-to-base skill?
It is a skill in the shadcn-ui/ui repository that migrates React projects and components from Radix UI to Base UI. It handles single components such as accordion and whole projects, and it is built around the shadcn CLI, a set of mapping files and a per-component report.
How do I install the migrate-radix-to-base skill?
Clone shadcn-ui/ui and copy the skills/migrate-radix-to-base folder, including its mapping markdown files, into your agent's skills folder. Then start from a clean branch and ask your agent to migrate one component. The skill itself describes no other install route.
Will it overwrite my customized shadcn components?
Not by default. The skill classifies each wrapper against its stock origin first. Pristine files can be replaced, but customized ones get the base variant with your changes replayed through a three-way merge. In progressive mode it never uses overwrite, so the original stays until consumers move.
What happens to cmdk, vaul and sonner?
Nothing. The skill's hard rules say never to touch non-Radix libraries or their wrappers, and name cmdk for command, vaul for drawer, sonner, input-otp, react-day-picker for calendar and recharts for chart. They are reported as intentionally untouched.
Does it work with projects that are not shadcn?
Yes, through its transformation engine, which covers hand-rolled Radix code and unknown styles using mapping tables for imports, asChild, overlays, props and classes. The golden pair route through the CLI applies only when a project has a known shadcn style.
How do I run it in smaller steps?
Use the default progressive mode. Ask for one component, review the report and continue. If a component imports other wrappers still on Radix, the skill stops and recommends migrating those first, working bottom-up through the dependency order.
How is it different from the shadcn skill?
The shadcn skill teaches your agent to use shadcn/ui correctly day to day. This skill performs one specific project change, Radix to Base UI. Run it while moving bases, and return to the shadcn skill for ordinary component work afterward.