UI Migration Skill

Track component provenance (shadcn, custom, wrapper) during UI library migrations. Optionally integrates with the todo-workflow skill for multi-step migration tracking.

When to use

Use this skill when migrating between UI component libraries (e.g., custom design system → shadcn/ui, or upgrading shadcn versions). It provides conventions for documenting component ancestry so future developers know what each component is built on.

Dependencies

This skill optionally depends on todo-workflow:

• If todo-workflow is loaded, migration tasks are tracked in TODOS.md and errors in ERRORS.md.
• If todo-workflow is not loaded, this skill operates on a standalone COMPONENT_CATALOG.md with no task tracking.

Component Provenance Categories

Every component in the project falls into one of these categories:

Component Catalog

Create or maintain COMPONENT_CATALOG.md at the project root with this format:

# Component Catalog

## UI Components (src/components/ui/)

| Component | Provenance | Depends On | Notes |
|---|---|---|---|
| Button | shadcn | @base-ui/react/button, cva | Added during Tailwind v4 migration |
| Card | shadcn | — | Pure Tailwind + cn() |
| Input | shadcn | @base-ui/react/input | |

## Custom Components (src/components/)

| Component | Provenance | Imports | Notes |
|---|---|---|---|
| AppIcon | custom | lucide-react (dynamic) | Dynamic icon lookup |
| Header | custom | AppIcon, lucide-react, react-router-dom | |
| Sidebar | custom | AppIcon, react-router-dom | Collapsible nav |

Sections

• src/components/ui/ — shadcn-generated components, one row per file.
• src/components/ — custom components, one row per file.
• Legacy / Removed — components from the old design system that were deleted, with their migration path.
• Patterns (unimplemented) — documented component patterns from AGENTS.md that don't yet have files. Only include these if they are part of the current migration scope.

Migration Workflow

1. Discover current state

Run a survey to catalog every component file:

src/components/ui/   → shadcn originals
src/components/      → custom components
src/features/*/      → consumers

For each component, record:

• File path
• Imports (to determine dependencies)
• Which category it falls into

2. Plan the migration

For each component being migrated, decide:

3. Execute with todo-workflow (if loaded)

If todo-workflow is active:

1. Break the migration into per-component tasks in TODOS.md.
2. Process one task at a time: install/rewrite → update callers → verify.
3. Delete old files only after all callers are updated.
4. Commit after each completed task (see Commit discipline in todo-workflow).

4. Update the catalog

After each component migration:

1. Move the row to its new section in COMPONENT_CATALOG.md.
2. Update provenance, dependencies, and notes.
3. If the old component was deleted, add a row to Legacy / Removed.

5. Clean up stale references

After deleting a legacy directory or alias, search for stale references:

rg '@design-system' --include '*.{js,jsx,ts,tsx}' src/

Also check:

• vite.config.js — alias definitions
• tsconfig.json / jsconfig.json — path aliases
• README.md, AGENTS.md — documentation references

Component Survey Commands

# List all components by location
ls src/components/ui/*.{jsx,tsx} 2>/dev/null
ls src/components/*.jsx 2>/dev/null

# Find all feature imports to a component
rg "from '@/components/" src/features/ --include '*.jsx'
rg "from '@components/" src/features/ --include '*.jsx'

# Check for stale legacy imports
rg '@design-system' src/ --include '*.{js,jsx,ts,tsx}'

Example: shadcn Migration

When migrating a legacy Select to shadcn:

1. pnpm dlx shadcn@latest add select
2. Create a SelectWrapper.jsx if backward compat is needed, or update callers directly.
3. Update COMPONENT_CATALOG.md:

   - | Select | legacy-ds | @design-system/ui/Select | Replaced by shadcn |
   + | Select | shadcn     | @base-ui/react/select, lucide-react | Installed during v4 migration |

4. If using todo-workflow, mark task complete, log errors to ERRORS.md, and commit.