shadcn Migration

Agent Workflow (MANDATORY)

Before migration, use TeamCreate to spawn agents:

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

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 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

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