shadcn Migration
Agent Workflow (MANDATORY)
Before migration, spawn agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Inventory all affected components
- fuse-ai-pilot:research-expert - Verify migration patterns via Context7
After: Run fuse-ai-pilot:sniper for validation.
Overview
| Feature |
Description |
| Radix -> Base UI |
Optional: Base UI is the default for new projects since July 2026; Radix is NOT deprecated |
| Base UI -> Radix |
Migrate to the Radix base (still fully supported) |
| React Aria |
Third base (aria-*, July 2026); no documented migration path to or from it; "existing projects stay on their current base" |
| API mapping |
Complete transformation table |
| Validation |
Post-migration checklist |
Official migration tooling
| Need |
Command / tool |
Source |
| Radix -> Base UI, per component |
npx skills add shadcn/ui, then ask the agent "migrate accordion to base-ui" (progressive, one commit per component, report in .migration/<component>.md) |
changelog 2026-07-base-ui-default |
@radix-ui/react-* -> unified radix-ui |
{runner} shadcn@latest migrate radix [path] |
/docs/cli#migrate-radix |
clsx + tailwind-merge -> cn package |
{runner} shadcn@latest migrate cn [path] (merge engine targets Tailwind v4 like tailwind-merge v3; on Tailwind v3 keep tailwind-merge v2, a clsx-only migration is safe; no components.json needed) |
/docs/cli#migrate-cn |
| Physical -> logical classes (RTL) |
{runner} shadcn@latest migrate rtl [path] |
/docs/cli#migrate-rtl |
| Icon library swap |
{runner} shadcn@latest migrate icons --from lucide --to phosphor |
/docs/cli#migrate-icons |
| Base color swap |
{runner} shadcn@latest migrate base-color --to zinc |
/docs/cli#migrate-base-color |
| Keep Radix in non-interactive CI init |
{runner} shadcn@latest init -b radix (default base is now base) |
changelog 2026-07-base-ui-default |
{runner} shadcn@latest migrate --list prints the available migrations (CLI 4.21.0: cn, icons, base-color, radix, rtl).
Critical Rules
- ALWAYS run detection before starting migration
- ALWAYS create backup branch before migration
- MIGRATE one component type at a time
- UPDATE CSS selectors along with JSX changes
- RUN tests after each component migration
Architecture
Migration order (leaf components first):
1. Tooltip, Switch, Checkbox (simple)
2. Accordion, Tabs (medium)
3. Dialog, Select, Popover, Menu (complex)
-> See migration-dialog.md for complete example
Pre-Migration Checklist
[ ] Run shadcn-detection to confirm current primitive
[ ] Create backup branch (git checkout -b pre-migration)
[ ] Inventory all affected files (Grep for imports)
[ ] Review component-specific API changes
[ ] Plan migration order (leaf components first)
Migration Workflow
1. DETECT -> Run shadcn-detection skill
2. BACKUP -> Create git branch
3. INVENTORY -> List all affected components
4. TRANSFORM -> Apply API changes per component
5. VALIDATE -> Run tests + sniper check
Key API Changes
| Aspect |
Radix |
Base UI |
| Composition |
asChild |
render prop |
| Dialog content (primitive) |
Dialog.Content |
Dialog.Popup (shadcn wrapper keeps DialogContent) |
| Dialog overlay (primitive) |
Dialog.Overlay |
Dialog.Backdrop (wrapper keeps DialogOverlay) |
| Positioning |
Built-in |
Separate Positioner |
| Accordion body (primitive) |
Accordion.Content |
Accordion.Panel (wrapper keeps AccordionContent) |
| Accordion single/multi |
type="single" collapsible / type="multiple" |
defaultValue={[...]} / multiple |
| Raw data attrs |
data-state="open" |
data-open (Tailwind data-open: variant matches both) |
| Package |
radix-ui (or legacy @radix-ui/react-*) |
Single @base-ui/react |
| components.json style |
radix-* (legacy new-york) |
base-* |
Best Practices
DO
- Migrate one component type at a time
- Run tests after each component migration
- Update CSS selectors along with JSX
- Remove unused Radix packages after migration
DON'T
- Migrate all components at once
- Skip detection step
- Leave mixed APIs in production
- Forget to update data-attribute CSS selectors
Reference Guide
Concepts
Templates
