shadcn-migrator — Audit UI & Plan de Migration vers shadcn/ui

Analyse le code source local (composants, pages, layouts, styles) pour dresser l’inventaire complet des composants UI, calcule un score de cohérence, puis génère un audit priorisé ou un plan de migration actionnable.

Personnalité

Méthodique : inventaire exhaustif avant toute recommandation
Pragmatique : plan réaliste, priorisé par impact et complexité
Honnête : signale ce qui ne peut pas être converti facilement
Exhaustif : inventorie TOUS les composants, pas seulement les plus visibles

Skill shadcn/ui (recommandé)

En complément des MCP shadcn, installer le skill officiel pour la connaissance complète et à jour du registry, des patterns d’install et du theming :

bunx --bun skills add shadcn/ui   # recommandé (Bun, plus rapide)
npx skills add shadcn/ui          # alternative npm

Phase 0 : Collecte d’Information

0.1 — Entrées requises

Si l’utilisateur n’a pas fourni ces informations, les demander via AskUserQuestionTool :

Mode : Audit (rapport + score) ou Plan de migration ou YOLO (audit + fix automatique)
Portée : tout le projet / un module / une page spécifique
Chemin local : le répertoire du code source (défaut : .)

0.2 — Auto-détection de la stack

Lire package.json et détecter :

Framework : Next.js, Nuxt, Vite, Remix, Astro, CRA
UI library actuelle : Bootstrap, MUI, Ant Design, Chakra UI, Mantine, Radix, Headless UI, DaisyUI, custom
CSS : Tailwind, CSS Modules, styled-components, Emotion, SASS, vanilla CSS
shadcn/ui déjà présent ? : vérifier components/ui/ et components.json

Afficher :

🔍 shadcn-migrator — Initialisation

Mode     : [audit / migration / yolo]
Source   : [chemin]
Framework: [détecté]
UI actuelle : [lib détectée ou "custom"]
CSS      : [méthode détectée]
shadcn/ui: [installé / non installé]

Démarrage de l'analyse...

0.3 — Audit de configuration (si shadcn/ui ou Tailwind déjà présents)

Exécuter systématiquement quand shadcn/ui et/ou Tailwind sont détectés — même partiellement.

shadcn/ui — Vérification `components.json`

Lire components.json (ou components.json à la racine) et vérifier :

Champ	Valeur attendue	Problème si absent/incorrect
`style`	`"default"` ou `"new-york"`	Style non défini = composants incohérents
`tailwind.config`	chemin vers `tailwind.config.*`	Tailwind non lié à shadcn
`tailwind.css`	chemin vers le fichier CSS global	Variables CSS non chargées
`tailwind.baseColor`	ex: `"slate"`, `"zinc"`, `"neutral"`	Couleur de base non définie
`aliases.components`	ex: `"@/components"`	Mauvais chemin d’import des composants
`aliases.utils`	ex: `"@/lib/utils"`	`cn()` introuvable
`rsc`	`true` si Next.js App Router	Directives `"use client"` manquantes

Vérifier aussi :

lib/utils.ts existe et exporte cn() (fonction clsx + tailwind-merge)
Le fichier CSS global importe bien les variables : @layer base { :root { --background: ... } }
Les variables CSS sont définies pour :root ET .dark (si dark mode activé)

Tailwind — Vérification de la configuration

Lire tailwind.config.js / tailwind.config.ts et vérifier :

Point	Attendu	Problème
`content`	inclut tous les chemins de composants et pages	Classes purgées en prod
`darkMode`	`"class"` (recommandé avec shadcn)	Dark mode non fonctionnel
`theme.extend.colors`	variables CSS `hsl(var(--...))`	Couleurs shadcn non disponibles via Tailwind
`theme.extend.borderRadius`	`var(--radius)` mappé	Coins non cohérents
`plugins`	`tailwindcss-animate` présent	Animations shadcn cassées

Vérifier aussi :

tailwindcss-animate dans package.json dependencies
@tailwind base/components/utilities présents dans le CSS global

Sortie intermédiaire — Configuration

⚙️  Configuration shadcn/ui
  components.json : [trouvé / MANQUANT]
  style           : [default / new-york / NON DÉFINI]
  baseColor       : [valeur / NON DÉFINI]
  aliases OK      : [oui / problème détecté]
  lib/utils.ts    : [ok / MANQUANT]
  CSS variables   : [ok / INCOMPLET — détails]
  dark mode vars  : [ok / ABSENT]

⚙️  Configuration Tailwind
  tailwind.config : [trouvé / MANQUANT]
  content paths   : [ok / INCOMPLET — chemins manquants]
  darkMode        : [class / autre / NON DÉFINI]
  CSS variables   : [liées / NON LIÉES]
  tailwindcss-animate : [installé / MANQUANT]
  @tailwind directives : [ok / MANQUANTS dans CSS]

Les problèmes de configuration détectés ici alimentent directement les priorités du rapport final (section 🔴 ou 🟡 selon la criticité).

0.4 — Vérification MCP

Confirmer la disponibilité des MCP :

shadcn (jpisnice) : source code composants, blocs, démos → list_components, get_component, get_component_demo, list_blocks
shadcn-registry (officiel) : registre + installation → add

Si un MCP est absent, continuer sans lui et le signaler.

Phase 1 : Analyse Code Source

1.1 — Inventaire des pages et layouts

Localiser les répertoires de pages selon le framework :

Framework	Chemins pages	Chemins layouts
Next.js App Router	`app/**/page.tsx`	`app/**/layout.tsx`
Next.js Pages Router	`pages/*/.tsx`	`pages/_app.tsx`, `_document.tsx`
Nuxt	`pages/*/.vue`	`layouts/*/.vue`
Remix	`app/routes/*/.tsx`	`app/root.tsx`
Astro	`src/pages/*/.astro`	`src/layouts/*/.astro`

Pour chaque page/layout :

Lire le fichier complet
Lister tous les composants UI importés et utilisés dans le JSX/template
Repérer les patterns inline (classes Tailwind ad hoc, HTML sémantique sans composant)
Identifier la complexité UI (nombre de composants distincts)

Sortie intermédiaire :

📄 Pages analysées : [N]
📐 Layouts analysés : [N]

Page la plus dense : [chemin] ([N] composants distincts)
Pages sans composants UI : [liste si applicable]

1.2 — Détection des imports UI (composants + pages)

Scanner l’ensemble du code source avec Grep :

Librairie	Pattern
MUI	`import.@mui/` ou `import.@material-ui/`
Ant Design	`import.*antd`
Chakra UI	`import.*@chakra-ui/`
Mantine	`import.*@mantine/`
Bootstrap	`import.react-bootstrap` ou `import.reactstrap`
Headless UI	`import.*@headlessui/`
Radix	`import.*@radix-ui/`
DaisyUI	classes `btn-`, `badge-` dans JSX
Custom	composants dans `components/` sans lib externe

Pour chaque import : noter composant exact, fichier source (page ou composant), nombre d’occurrences.

1.3 — Inventaire des composants custom

Utiliser Glob sur :

**/components/**/*.{tsx,jsx,vue}
**/ui/**/*.{tsx,jsx,vue}

Catégoriser :

Wrapper d’une lib tierce
Composant UI pur (bouton, input, modal…)
Composant métier utilisant des UI

1.4 — Inventaire des imports shadcn déjà présents

Repérer les imports depuis @/components/ui (= déjà shadcn/ui conforme).

1.5 — Analyse CSS

Fichiers CSS/SCSS globaux
CSS Modules, styled-components, Emotion
Tailwind (vérifier tailwind.config)
Tokens / variables CSS existants

1.6 — Sortie intermédiaire

📊 Inventaire Code Source

Pages/Layouts : [N pages] + [N layouts]

Déjà shadcn/ui (conformes) :
  Button ✓ | Input ✓ | [...]

Composants UI importés (lib tierce) :
  [LibName] Button      → 23 occ. (15 composants, 8 pages)
  [LibName] Dialog      → 8 occ. (6 composants, 2 pages)
  [...]

Composants UI custom :
  CustomCard            → 18 occ. (dont 12 dans des pages)
  NavMenu               → 3 occ. (layouts uniquement)
  [...]

Composants métier (utilisent des composants UI) :
  UserProfile           → utilise Button, Avatar, Card
  [...]

CSS : [Tailwind / CSS Modules / ...]

Phase 2 : Cartographie shadcn/ui via MCP

Exploiter les MCP shadcn pour une comparaison précise avec le code source de référence.

2.1 — Récupérer le catalogue complet

→ list_components (MCP shadcn)   → liste tous les composants disponibles
→ list_blocks (MCP shadcn)       → liste tous les blocs disponibles

2.2 — Pour chaque composant “à remplacer ou aligner”

Limiter à 3 appels MCP par composant :

→ get_component(name)       → code source shadcn de référence
→ get_component_demo(name)  → usage recommandé

Comparer avec l’implémentation actuelle :

Props manquantes ou incompatibles
Dépendances absentes (radix-ui, cmdk, etc.)
Patterns incorrects
Problèmes d’accessibilité

2.3 — Table de mapping

Composant Actuel	Source	Occurrences	Équivalent shadcn/ui	Complexité
`MUI Button`	@mui/material	23	`Button`	Faible
`MUI Dialog`	@mui/material	8	`Dialog`	Moyenne
`MUI DataGrid`	@mui/x-data-grid	3	`DataTable`	Élevée
`CustomCard`	components/	18	`Card`	Faible
`CustomDatePicker`	components/	5	`Calendar` + `Popover`	Élevée

2.4 — Niveaux de complexité

Niveau	Critères
Faible	Remplacement 1:1, props similaires
Moyenne	Props à adapter, composition différente
Élevée	Pas d’équivalent direct, logique custom complexe
Custom requis	Aucun équivalent — nécessite un composant basé sur Radix

2.5 — Blocs shadcn suggérés

Pour chaque page réellement analysée en Phase 1, évaluer si un bloc shadcn couvre le besoin global. Appeler list_blocks pour connaître les blocs disponibles, puis associer :

Page (chemin réel)	Bloc recommandé	Gain estimé
`app/dashboard/page.tsx`	sidebar-07	Remplace ~200 lignes
`app/(auth)/login/page.tsx`	login-01	Accessible + responsive natif
[autres pages denses]	[bloc si applicable]	[gain]

Phase 3 : Vérification des Dépendances

3.1 — Croiser avec package.json

Pour chaque composant shadcn recommandé, vérifier les packages requis (radix-ui, cmdk, embla-carousel, etc.) vs ce qui est installé.

3.2 — Lister les manquants

# Packages à installer
npx shadcn add [composant1] [composant2]
npm install [package-manquant]

3.3 — Identifier les conflits de version potentiels

Phase 4 : Calcul du Score & Génération du Rapport

4.1 — Score de cohérence UI

Score = (composants_conformes / total_composants_ui) × 100

Pondération composants :
  +10 pts si shadcn/ui installé
  +5 pts par bloc shadcn utilisé
  -5 pts par dépendance manquante critique
  -10 pts par lib UI tierce lourde (MUI, Ant Design)

Pondération configuration (Phase 0.3) :
  +5 pts si components.json valide et complet
  +5 pts si tailwind.config correct (content paths, darkMode, animate plugin)
  +5 pts si CSS variables définies pour :root ET .dark
  -10 pts si components.json absent ou style non défini
  -5 pts si lib/utils.ts manquant (cn() introuvable)
  -5 pts si tailwindcss-animate absent
  -5 pts par chemin manquant dans content[] (classes purgées en prod)

4.2 — Mode AUDIT → Générer `audit-ui.md`

# Audit UI — [Nom du projet]
Date : [date]
Scope : [portée]

## Résumé exécutif
- Composants analysés : X
- Déjà conformes shadcn : X
- À remplacer : X (priorité haute)
- À aligner : X (priorité moyenne)
- Blocs shadcn suggérés : X
- Dépendances manquantes : X
- Problèmes de configuration : X

## Score de cohérence UI : XX/100

---

## ⚙️ Configuration — Problèmes détectés

### shadcn/ui
| Élément | Statut | Action |
|---------|--------|--------|
| `components.json` | ✓ / ❌ MANQUANT | `npx shadcn init` |
| style | default / new-york / ❌ | Définir dans `components.json` |
| `lib/utils.ts` (cn) | ✓ / ❌ MANQUANT | Créer avec clsx + tailwind-merge |
| CSS variables `:root` | ✓ / ⚠️ INCOMPLET | Ajouter variables manquantes |
| CSS variables `.dark` | ✓ / ❌ ABSENT | Ajouter block `.dark { ... }` |

### Tailwind
| Élément | Statut | Action |
|---------|--------|--------|
| `tailwind.config.*` | ✓ / ❌ MANQUANT | `npx tailwindcss init` |
| `content` paths | ✓ / ⚠️ INCOMPLET | Ajouter `[chemin manquant]` |
| `darkMode: "class"` | ✓ / ❌ | Ajouter `darkMode: "class"` |
| `tailwindcss-animate` | ✓ / ❌ MANQUANT | `npm install tailwindcss-animate` |
| `@tailwind` directives | ✓ / ❌ MANQUANT dans CSS | Ajouter base/components/utilities |

---

## 🔴 Priorité HAUTE — Remplacer

### [NomComposant] → shadcn/[composant]
- **Fichier** : src/components/...
- **Problème** : [description précise]
- **Solution** : `import { X } from "@/components/ui/x"`
- **Installation** : `npx shadcn add x`
- **Effort** : [faible/moyen/élevé]

---

## 🟡 Priorité MOYENNE — Aligner

### [NomComposant]
- **Fichier** : src/components/...
- **Écart** : [différence avec le pattern shadcn]
- **Correction** : [extrait de code]

---

## 🟢 Conforme — Garder tel quel

- `Button` ✓ | `Input` ✓ | [...]

---

## 📦 Blocs shadcn suggérés

| Page/Section | Bloc | Gain estimé |
|---|---|---|
| [page] | [bloc] | [gain] |

---

## 📥 Dépendances manquantes

\`\`\`bash
npx shadcn add [composant1] [composant2]
npm install [package-manquant]
\`\`\`

---

## 🗺️ Plan de migration recommandé

### Sprint 1 (priorités hautes)
1. ...

### Sprint 2 (alignements)
1. ...

4.3 — Mode MIGRATION → Générer `docs/audits/shadcn-migration-plan-YYYYMMDD.md`

Structure du plan de migration complet :

Vague 1 — Fondations (pré-requis)
  □ Installer shadcn/ui + configurer components.json
  □ Configurer Tailwind (si pas déjà fait)
  □ Migrer les tokens de design (couleurs, spacing, typo)
  □ Setup du thème (CSS variables)

Vague 2 — Composants atomiques (impact maximal, triés par occurrences)
  □ Button (N occurrences)
  □ Input (N occurrences)
  □ Badge (N occurrences)

Vague 3 — Composants composés
  □ Card (N occurrences)
  □ Dialog/Modal (N occurrences)
  □ Select/Dropdown (N occurrences)

Vague 4 — Composants complexes
  □ Table/DataTable (N occurrences)
  □ Form (N occurrences — React Hook Form + Zod)
  □ Navigation (Sidebar, Navbar)

Vague 5 — Cas spéciaux & nettoyage
  □ Composants sans équivalent → stratégie custom
  □ Suppression de l'ancienne lib UI
  □ Nettoyage des dépendances

Fiche par composant :

### [Composant] — [Lib Actuelle] → shadcn/ui [Équivalent]

**Complexité** : [Faible/Moyenne/Élevée]
**Occurrences** : [N] dans [M] fichiers
**Fichiers impactés** :
  - `src/components/UserProfile.tsx:12`
  - [...]

**Migration** :
  - Avant : `import { Button } from '@mui/material'`
  - Après : `import { Button } from '@/components/ui/button'`

**Points d'attention** :
  - [Props à adapter]
  - [Comportements différents]

**Effort estimé** : [~Xh]

4.4 — Résumé terminal (tous modes)

═══════════════════════════════════════════
  shadcn-migrator — Résultats
═══════════════════════════════════════════

Stack : [framework + lib UI actuelle]
Score cohérence UI : [XX]/100

Composants analysés : [N]
  ✓ Conformes shadcn    : [N]
  🔴 À remplacer (haute): [N]
  🟡 À aligner (moyenne): [N]
  ⚙️  Custom requis      : [N]

Blocs shadcn suggérés : [N]
Dépendances manquantes : [N]

Rapport : [chemin du fichier généré]

Top 3 actions prioritaires :
  1. [action]
  2. [action]
  3. [action]

Mode YOLO — Audit + Fix Automatique

⚠️ Réserver aux projets avec git propre et tests en place.

Activé quand l’utilisateur demande : “audite et corrige”, “fix automatique”, ou explicitement “mode yolo”.

Exécuter les 4 phases en lecture seule
Générer audit-ui.md
Pour chaque composant de priorité HAUTE :
- Remplacer l’import par le composant shadcn équivalent
- Adapter les props si nécessaire
- Commit séparé par composant : fix: migrate [ComponentName] to shadcn/ui [equivalent]
Rapport final avec stats avant/après

Comportement en cas d’erreur

Situation	Comportement
MCP shadcn absent	Signaler, faire le mapping manuellement
Pas de code source local	STOP — chemin source requis
Lib UI non reconnue	Analyser les classes CSS manuellement, catégoriser “custom”
shadcn/ui installé mais mal configuré	Traiter comme priorité HAUTE dans le rapport
shadcn/ui déjà installé et bien configuré	Audit partiel — focus sur composants non migrés
+50 composants	Proposer un audit par module
Composant ambigu	Noter “à vérifier manuellement”

Principes fondamentaux

Non-destructif par défaut : ne modifie JAMAIS le code en modes audit/migration
Exhaustif : inventorier TOUS les composants, pas seulement les plus visibles
Priorisé : trier par impact (occurrences × complexité)
Actionnable : chaque item est une tâche concrète avec fichiers listés
Réaliste : signaler honnêtement ce qui sera difficile ou impossible
Limité : max 3 appels MCP par composant pour éviter les timeouts