# Shadcn Migration

> Use when migrating a shadcn/ui project between Radix UI and Base UI primitives, or validating a migration's API transformations.

- Skill: `fusengine/shadcn-migration` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add fusengine/shadcn-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fusengine/shadcn-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: fusengine (https://skillmd.com/u/fusengine)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/fusengine/shadcn-migration

---


<objective>
A 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.
</objective>

# shadcn Migration

## Agent Workflow (MANDATORY)

Before migration, spawn agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Inventory all affected components
2. **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

1. **ALWAYS run detection** before starting migration
2. **ALWAYS create backup** branch before migration
3. **MIGRATE one component** type at a time
4. **UPDATE CSS selectors** along with JSX changes
5. **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](references/templates/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](references/radix-to-baseui.md) | Migrating from Radix |
| **Base UI -> Radix** | [baseui-to-radix.md](references/baseui-to-radix.md) | Migrating to Radix |

### Templates

| Template | When to Use |
|----------|-------------|
| [migration-dialog.md](references/templates/migration-dialog.md) | Complete migration example |