<objective> A step-by-step migration guide between Radix UI and Base UI primitives for shadcn/ui (React Aria, the third base, has no documented migration path), plus the CLI migrations (`migrate radix|cn|rtl|icons|base-color`): pre-migration checklist (detection, backup branch, component inventory), migration order (leaf components first — Tooltip/Switch/Checkbox, then Accordion/Tabs, then Dialog/Select/Popover/Menu), the API transformation table (`asChild`→`render`, `DialogContent`→`Dialog.Popup`, `data-state`→`data-[open]`, etc.), and a post-migration validation checklist. </objective>

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

| Topic | Reference | When to Consult | |-------|-----------|-----------------| | Radix -> Base UI | radix-to-baseui.md | Migrating from Radix | | Base UI -> Radix | baseui-to-radix.md | Migrating to Radix |

Templates

| Template | When to Use | |----------|-------------| | migration-dialog.md | Complete migration example |