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 |
Migrate from legacy to new primitives |
| Base UI -> Radix |
Migrate to established primitives |
| API mapping |
Complete transformation table |
| Validation |
Post-migration checklist |
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 |
DialogContent |
Dialog.Popup |
| Dialog overlay |
DialogOverlay |
Dialog.Backdrop |
| Positioning |
Built-in |
Separate Positioner |
| Accordion body |
AccordionContent |
Accordion.Panel |
| Data attrs |
data-state="open" |
data-[open] |
| Package |
Multiple @radix-ui/* |
Single @base-ui/react |
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 |
1---2name: shadcn-migration3description: "Use when migrating a shadcn/ui project between Radix UI and Base UI primitives, or validating a migration's API transformations."4versions:5 shadcn-ui: "2.x"6 radix-ui: "1.x"7 base-ui: "1.x"8user-invocable: true9allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task10references: references/radix-to-baseui.md, references/baseui-to-radix.md, references/templates/migration-dialog.md11related-skills: shadcn-detection, shadcn-components12metadata:13 source: https://skillmd.com/skills/fusengine/shadcn-migration14---1516<objective>17A step-by-step migration guide between Radix UI and Base UI primitives for shadcn/ui: 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.18</objective>1920# shadcn Migration2122## Agent Workflow (MANDATORY)2324Before migration, spawn agents in parallel, one `Agent` call each with a `name`:25261. **fuse-ai-pilot:explore-codebase** - Inventory all affected components272. **fuse-ai-pilot:research-expert** - Verify migration patterns via Context72829After: Run **fuse-ai-pilot:sniper** for validation.3031---3233## Overview3435| Feature | Description |36|---------|-------------|37| **Radix -> Base UI** | Migrate from legacy to new primitives |38| **Base UI -> Radix** | Migrate to established primitives |39| **API mapping** | Complete transformation table |40| **Validation** | Post-migration checklist |4142## Critical Rules43441. **ALWAYS run detection** before starting migration452. **ALWAYS create backup** branch before migration463. **MIGRATE one component** type at a time474. **UPDATE CSS selectors** along with JSX changes485. **RUN tests** after each component migration4950## Architecture5152```53Migration order (leaf components first):541. Tooltip, Switch, Checkbox (simple)552. Accordion, Tabs (medium)563. Dialog, Select, Popover, Menu (complex)57```5859-> See [migration-dialog.md](references/templates/migration-dialog.md) for complete example6061---6263## Pre-Migration Checklist6465```66[ ] Run shadcn-detection to confirm current primitive67[ ] Create backup branch (git checkout -b pre-migration)68[ ] Inventory all affected files (Grep for imports)69[ ] Review component-specific API changes70[ ] Plan migration order (leaf components first)71```7273---7475## Migration Workflow7677```781. DETECT -> Run shadcn-detection skill792. BACKUP -> Create git branch803. INVENTORY -> List all affected components814. TRANSFORM -> Apply API changes per component825. VALIDATE -> Run tests + sniper check83```8485---8687## Key API Changes8889| Aspect | Radix | Base UI |90|--------|-------|---------|91| Composition | `asChild` | `render` prop |92| Dialog content | `DialogContent` | `Dialog.Popup` |93| Dialog overlay | `DialogOverlay` | `Dialog.Backdrop` |94| Positioning | Built-in | Separate `Positioner` |95| Accordion body | `AccordionContent` | `Accordion.Panel` |96| Data attrs | `data-state="open"` | `data-[open]` |97| Package | Multiple `@radix-ui/*` | Single `@base-ui/react` |9899---100101## Best Practices102103### DO104- Migrate one component type at a time105- Run tests after each component migration106- Update CSS selectors along with JSX107- Remove unused Radix packages after migration108109### DON'T110- Migrate all components at once111- Skip detection step112- Leave mixed APIs in production113- Forget to update data-attribute CSS selectors114115## Reference Guide116117### Concepts118119| Topic | Reference | When to Consult |120|-------|-----------|-----------------|121| **Radix -> Base UI** | [radix-to-baseui.md](references/radix-to-baseui.md) | Migrating from Radix |122| **Base UI -> Radix** | [baseui-to-radix.md](references/baseui-to-radix.md) | Migrating to Radix |123124### Templates125126| Template | When to Use |127|----------|-------------|128| [migration-dialog.md](references/templates/migration-dialog.md) | Complete migration example |