shadcn Migration

Agent Workflow (MANDATORY)

Before migration, use TeamCreate to spawn agents:

• 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