Migrer une UI vers shadcn/ui avec shadcn-migrator

Contexte

Votre UI utilise Bootstrap, Ant Design, ou du CSS custom, et vous voulez migrer vers shadcn/ui (Radix UI + Tailwind). shadcn-migrator inventorie tous vos composants, évalue la complexité et génère un plan priorisé : les simples d’abord, les complexes ensuite. Mode YOLO disponible pour audit + migration automatique.

Prérequis

Projet React/Vue avec package.json
Source UI existante : Bootstrap, MUI, Chakra, custom CSS ou Tailwind
Tailwind CSS configuré (obligatoire pour shadcn/ui)
shadcn/ui partiellement ou non installé : components.json optionnel
Skill shadcn/ui recommandé : npx skills add shadcn/ui

Étapes

1. Invoquer shadcn-migrator

/ulk:frontend:shadcn-migrator
# ou
audit ui
# ou
migration shadcn

2. Phase 0 : Collecte d’information

L’agent demande (via AskUserQuestionTool) :

🔍 shadcn-migrator — Initialisation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Mode? (audit / migration / yolo)
   → audit : rapport + score, pas d'action
   → migration : plan d'action priorisé, pas d'action
   → yolo : audit + migration automatique (risqué, utiliser sur branche test)

2. Portée? (tout le projet / module spécifique / page spécifique)
   → exemple: "tout le projet"
   → exemple: "src/components/Button et src/components/Card seulement"

3. Chemin local? (défaut: .)
   → exemple: "./src"

3. Phase 0.2 : Auto-détection

L’agent détecte automatiquement :

Framework       : Next.js 15 (App Router)
UI library      : Bootstrap 5.3 (détectée via imports)
CSS             : Tailwind CSS (✅ prêt pour shadcn/ui)
shadcn/ui       : Non installé

=== Composants détectés ===

Bootstrap components utilisés:
  ✅ Button (simples)         : 12 occurrences
  ✅ Card (simples)           : 8 occurrences
  ✅ Modal (complexe)         : 3 occurrences
  ✅ Dropdown (complexe)      : 5 occurrences
  ⚠️  Alert (moyennement complexe) : 2 occurrences
  ✅ Badge (trivial)          : 15 occurrences

Custom CSS :
  ⚠️  .sidebar (custom layout) : migrer vs utiliser shadcn Layout
  ⚠️  .theme-switcher (custom) : intégrer avec Radix Theme

Score de cohérence: 4.2/10 (incohérences détectées)

4. Phase 1 : Audit complet

L’agent scanne :

Composants : Button, Card, Modal, Table, Form, etc.
Patterns : Layout, responsive, dark mode
Dépendances : Conflits potentiels
Complexité : Décomposition en tâches

Affichage :

╔════════════════════════════════════════════════════════════╗
║ AUDIT UI — Migration vers shadcn/ui                       ║
╠════════════════════════════════════════════════════════════╣
║                                                            ║
║ Composants simples (Button, Badge, Alert)  : 29           ║
║ Composants moyens (Modal, Dropdown, Table) : 10           ║
║ Composants complexes (Form, Custom)        : 5            ║
║ Custom layouts/patterns                    : 3            ║
║                                                            ║
║ Effort total estimé: 6-8 heures            ║
║ Priorisation recommandée: 3 phases          ║
║                                                            ║
╠════════════════════════════════════════════════════════════╣
║ Score de cohérence ACTUEL   : 4.2/10                     ║
║ Score de cohérence POST      : 9.2/10 (estimé)           ║
╚════════════════════════════════════════════════════════════╝

5. Phase 2-3 : Plan d’action priorisé

Generation d’un fichier audit-ui.md :

# Plan de Migration UI → shadcn/ui

## Phase 1 : Fondations (Rapide, ~2h)

### 1.1 Button → shadcn/ui Button
- Fichiers: src/components/Button.tsx, 12 usages
- Complexité: Trivial
- Migration: Copier composant shadcn, remplacer imports
- Effort: 30 min

### 1.2 Badge → shadcn/ui Badge
- Fichiers: src/components/Badge.tsx, 15 usages
- Complexité: Trivial
- Effort: 20 min

### 1.3 Alert → shadcn/ui Alert
- Fichiers: src/components/Alert.tsx, 2 usages
- Complexité: Simple
- Migration: Adapter les icons (lucide-react au lieu de Bootstrap icons)
- Effort: 30 min

**Subtotal Phase 1: 1h 20 min**

## Phase 2 : Moyenne Complexité (~3h)

### 2.1 Modal → shadcn/ui Dialog
- Fichiers: src/components/Modal.tsx, 3 usages
- Complexité: Moyenne (refactor ouverture/fermeture)
- Migration: Utiliser Dialog + Radix internals
- Effort: 45 min

### 2.2 Dropdown → shadcn/ui DropdownMenu
- Fichiers: src/components/Dropdown.tsx, 5 usages
- Complexité: Moyenne
- Effort: 45 min

### 2.3 Table → shadcn/ui Table + TanStack Table
- Fichiers: src/components/Table.tsx, 1 usage
- Complexité: Moyenne-Haute
- Effort: 1h 30 min (config TanStack Table)

**Subtotal Phase 2: 3h**

## Phase 3 : Complexe / Custom (~2h)

### 3.1 Form Components (Input, Select, Textarea)
- Fichiers: src/components/FormField.tsx + 4 subcomponents
- Complexité: Haute (intégrer React Hook Form + Zod)
- Effort: 2h

**Subtotal Phase 3: 2h**

## Custom Patterns

### Sidebar Layout
- Current: CSS custom `.sidebar`
- Recommended: Utiliser shadcn/ui Layout primitive ou garder custom
- Effort: Évaluer après Phases 1-2

---

## Résumé d'effort

| Phase | Durée | Modules | Status |
|-------|-------|---------|--------|
| 1 | 1h 20 min | Button, Badge, Alert | Simple |
| 2 | 3h | Modal, Dropdown, Table | Moyenne |
| 3 | 2h | Form, Select, Textarea | Complexe |
| Bonus | 30 min | Sidebar, custom patterns | Optionnel |

**Total: 6h 50 min d'effort**

6. Mode YOLO (Optionnel)

Si utilisateur choisit mode=yolo :

shadcn-migrator mode=yolo

L’agent :

Génère le plan (comme ci-dessus)
Lance la migration automatique pour Phase 1
Demande confirmation avant chaque Phase 2/3
Crée des branches Git temporaires

Sortie YOLO :

🚀 Mode YOLO — Migration automatique
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 1 — En cours...
  ✅ Button migré
  ✅ Badge migré
  ✅ Alert migré

Phase 1 complétée en 47 min (prédiction: 1h 20 min)

→ Branche créée: feature/shadcn-migration-phase1
→ Commits: 3
→ npm install: 0 (dépendances OK)

Prêt pour Phase 2 (Modal, Dropdown, Table)?
  1. Oui, continuer
  2. Non, arrêter et valider manuellement

Exemple de sortie

Fichier généré : docs/audit-ui.md

# Audit UI — Migration vers shadcn/ui

## État actuel

Framework : Next.js 15
UI Library: Bootstrap 5.3
CSS       : Tailwind CSS
Status    : READY (Tailwind configuré, shadcn/ui non installé)

## Composants inventoriés

### Simples (29)
- Button (12 usages)
- Badge (15 usages)
- Alert (2 usages)

### Moyens (10)
- Modal (3 usages)
- Dropdown (5 usages)
- Table (2 usages)

### Complexes (5)
- Form (1 usage, 5 subcomponents)
- Sidebar (1 custom, refactor?)
- ThemeSwitcher (1 custom)

## Score de cohérence

Avant migration : 4.2/10 (Bootstrap + custom CSS)
Après migration : 9.2/10 (shadcn/ui unifié)

## Plan recommandé

Phase 1: 1h 20 min (Button, Badge, Alert)
Phase 2: 3h (Modal, Dropdown, Table)
Phase 3: 2h (Form, Select, Textarea)
Bonus:  30 min (Sidebar, custom patterns)

Total: 6h 50 min

Variantes

Variante A : Audit seul — mode=audit pour rapport sans action
Variante B : Module spécifique — --scope src/components/forms pour auditer une partie seulement
Variante C : Conversion progressive — Lancer Phases 1/2/3 séparément en sessions différentes pour ne pas surcharger

Agents enchaînés

Flux typique :

shadcn-migrator (frontend/07)
  ├─ Phase 0.2 : Auto-détection (5 min)
  ├─ Phase 1 : Audit (10 min)
  ├─ Phase 2-3 : Plan d'action (5 min)
  └─ [optionnel] Mode YOLO : migration automatique (variables par phase)

Post-migration optionnel :

vision (05) ─→ Audit visuel vs designs
brique (01) ─→ Si design Figma disponible, implémenter

Troubleshooting

Symptôme	Cause probable	Résolution
”Tailwind not configured”	Tailwind absent	Installer : `npm install -D tailwindcss` + setup `tailwind.config.js`
”shadcn/ui not ready”	components.json manquant	`npx shadcn-ui@latest init` pour initialiser
Mode YOLO échoue sur Phase 2	Dépendance manquante (React Hook Form, TanStack Table)	shadcn-migrator propose installation automatique, sinon installer manuellement
Wikilinks cassées après migration	Refactoring de chemins d’import	Relancer audit pour re-mapper ou utiliser `find/replace` global

Voir aussi

./04-brique-figma-to-code.md — Implémenter des designs Figma après migration UI
./07-shadcn-migration.md — Cette fiche (migration vers shadcn/ui)
./08-backoffice-auditor.md — Audit de back-office (utilise shadcn/ui)
agents/frontend/07-shadcn-migrator.md — Documentation complète
MCP shadcn : npx shadcn-ui@latest — CLI officiel shadcn/ui
Skill shadcn/ui : npx skills add shadcn/ui — Connaissance design system complète