---
name: design-system-migration
description: "Migrate React applications from @strongtie/design-system to shadcn/ui with Tailwind. Use when: (1) User mentions 'migrate', 'convert', or 'upgrade' with design-system, (2) User wants to move from @strongtie/design-system to shadcn, (3) User asks about design-system to tailwind conversion, (4) Codebase has @strongtie/design-system imports that need updating."
---

# Design System to Shadcn Migration Skill

Automates migration from `@strongtie/design-system` to local shadcn/ui components with Tailwind CSS.

## Context7 Integration

**Always use Context7 MCP** to fetch the latest shadcn/ui documentation before performing migrations:

```
Library ID: /shadcn-ui/ui
```

Query Context7 for:
- Component API changes and new props
- Installation commands and dependencies
- Theming and CSS variable patterns
- Breaking changes between versions

This ensures migrations use current shadcn patterns rather than potentially outdated training data.

## When to Use

- Migrating a project from @strongtie/design-system to shadcn/ui
- Converting design-system imports to local component imports
- Updating component usage patterns for shadcn compatibility

## Detection

Check for `@strongtie/design-system` in:
- `package.json` dependencies
- Import statements in `.tsx`/`.ts` files

```bash
# Find all files with design-system imports
grep -r "@strongtie/design-system" src/ --include="*.tsx" --include="*.ts"
```

## Migration Workflow

### Step 1: Pre-Migration Analysis

Scan the codebase to understand scope:

```bash
# Count files needing migration
grep -rl "@strongtie/design-system" src/ --include="*.tsx" --include="*.ts" | wc -l

# List unique components in use
grep -roh "from ['\"]@strongtie/design-system/[^'\"]*" src/ --include="*.tsx" | sort -u
```

### Step 2: Install shadcn/ui

```bash
npx shadcn@latest init
```

When prompted, choose:
- **Style:** New York
- **Base color:** Neutral
- **CSS variables:** Yes

### Step 3: Add Required Components

Based on analysis, add the components you need:

```bash
# Common components
npx shadcn@latest add button card dialog input select tabs alert badge checkbox label

# Additional as needed
npx shadcn@latest add accordion avatar breadcrumb calendar carousel checkbox collapsible command context-menu date-picker drawer dropdown-menu form hover-card menubar navigation-menu pagination popover progress radio-group resizable scroll-area separator sheet sidebar skeleton slider sonner switch table textarea toast toggle toggle-group tooltip
```

### Step 4: Add Strongtie Design Tokens

Add these CSS variables to your `globals.css` to maintain Strongtie branding:

```css
:root {
  /* Base radius */
  --radius: 0.625rem;
  
  /* Semantic colors (oklch format) */
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  
  /* Strongtie Brand Colors */
  --sst-orange: #ff5308;
  --sst-orange-hover: #d64405;
  --sst-orange-active: #ac3503;
  
  /* Feedback Colors */
  --success: oklch(0.55 0.15 145);
  --warning: oklch(0.75 0.15 85);
  --info: oklch(0.55 0.15 250);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.556 0 0);
}
```

### Step 5: Transform Imports

Use find-and-replace to update import paths:

**Find:** `@strongtie/design-system/`
**Replace:** `@/components/ui/`

Or use command line:

```bash
# macOS/Linux
find src -type f \( -name "*.tsx" -o -name "*.ts" \) -exec sed -i '' \
  's/@strongtie\/design-system\//@\/components\/ui\//g' {} +

# Linux (GNU sed)
find src -type f \( -name "*.tsx" -o -name "*.ts" \) -exec sed -i \
  's/@strongtie\/design-system\//@\/components\/ui\//g' {} +
```

### Step 6: Handle Breaking Changes

See [references/breaking-changes.md](references/breaking-changes.md) for components that need manual updates:

- **CardAction** - Replace with flex layout in CardHeader
- **AlertTitle** - Replace with styled `<h5>` element
- **Spinner** - Replace with `Loader2` icon from lucide-react
- **ButtonGroup** - Replace with flex container
- **InputGroup** - Replace with flex container

### Step 7: Remove Old Package

```bash
npm uninstall @strongtie/design-system
```

### Step 8: Remove Style Imports

Remove any imports of design-system styles:

```typescript
// Remove these lines
import "@strongtie/design-system/styles"
```

### Step 9: Verify Migration

```bash
# Type check
npm run typecheck

# Build
npm run build

# Run tests
npm test
```

## Quick Reference

### Import Path Mapping

| Design System | Shadcn |
|---------------|--------|
| `@strongtie/design-system/button` | `@/components/ui/button` |
| `@strongtie/design-system/card` | `@/components/ui/card` |
| `@strongtie/design-system/input` | `@/components/ui/input` |
| `@strongtie/design-system/dialog` | `@/components/ui/dialog` |
| `@strongtie/design-system/select` | `@/components/ui/select` |
| `@strongtie/design-system/tabs` | `@/components/ui/tabs` |

### Component Compatibility

**Identical APIs (import change only):**
- Button, Input, Checkbox, Switch, Tabs, Dialog, Select, Tooltip, Badge, Separator, ScrollArea, Skeleton, Progress, Label, Textarea, RadioGroup, Popover, DropdownMenu, ContextMenu, Menubar, NavigationMenu, Accordion, Collapsible, HoverCard, Sheet, Drawer, Command, Calendar, Carousel, Pagination, Resizable, Slider, Toggle, ToggleGroup, Table, Form, Avatar, Breadcrumb

**Modified APIs (need manual updates):**
- Card (CardAction removed)
- Alert (AlertTitle removed)

**Not in Shadcn (need replacement):**
- Spinner → Loader2 icon
- ButtonGroup → flex container
- InputGroup → flex container
- Empty → custom component
- Tree → custom or third-party

## Detailed References

- [Component Mapping](references/component-mapping.md) - Full API comparison
- [Token Mapping](references/token-mapping.md) - CSS variable mappings
- [Import Transforms](references/import-transforms.md) - Detailed import patterns
- [Breaking Changes](references/breaking-changes.md) - Components needing manual updates
- [Tailwind v4 Syntax](references/tailwind-v4-syntax.md) - CSS variable arbitrary value patterns
- [Examples](transforms/examples.md) - Before/after code examples

## Troubleshooting

### "Module not found" after migration

1. Ensure shadcn components are installed: `npx shadcn@latest add <component>`
2. Check path alias in `tsconfig.json`: `"@/*": ["./src/*"]`
3. Clear build cache: `rm -rf node_modules/.cache dist`

### TypeScript errors

1. Restart TS server: VS Code → Cmd/Ctrl+Shift+P → "Restart TS Server"
2. Check for removed exports (CardAction, AlertTitle)
3. Verify component props match shadcn API

### Styles not applying

1. Ensure globals.css has CSS variables defined
2. Check Tailwind config includes component paths
3. Verify `@import "tailwindcss"` in CSS entry point