shadcn/ui

Un framework pour construire des IU, des composants et des systèmes de design. Les composants sont ajoutés sous forme de code source au projet de l'utilisateur via le CLI.

IMPORTANT : Exécutez toutes les commandes CLI en utilisant le lanceur de paquets du projet : npx shadcn@latest, pnpm dlx shadcn@latest, ou bunx --bun shadcn@latest — selon le packageManager du projet. Les exemples ci-dessous utilisent npx shadcn@latest mais substituez le lanceur correct pour le projet.

Contexte actuel du projet

!`npx shadcn@latest info --json`

Le JSON ci-dessus contient la configuration du projet et les composants installés. Utilisez npx shadcn@latest docs <composant> pour obtenir les URL de documentation et d'exemples pour tout composant.

Principes

Utilisez d'abord les composants existants. Utilisez npx shadcn@latest search pour vérifier les registres avant d'écrire de l'IU personnalisée. Vérifiez également les registres communautaires.
Composez, ne réinventez pas. Page de paramètres = Tabs + Card + contrôles de formulaire. Tableau de bord = Sidebar + Card + Chart + Table.
Utilisez les variantes intégrées avant les styles personnalisés. variant="outline", size="sm", etc.
Utilisez les couleurs sémantiques. bg-primary, text-muted-foreground — jamais de valeurs brutes comme bg-blue-500.

Règles critiques

Ces règles sont toujours appliquées. Chacune renvoie à un fichier avec des paires de code Incorrect/Correct.

Stylisme & Tailwind → styling.md

className pour la disposition, pas pour le stylisme. Ne remplacez jamais les couleurs ou la typographie des composants.
Pas de space-x-* ou space-y-*. Utilisez flex avec gap-*. Pour les piles verticales, flex flex-col gap-*.
Utilisez size-* lorsque la largeur et la hauteur sont égales. size-10 pas w-10 h-10.
Utilisez le raccourci truncate. Pas overflow-hidden text-ellipsis whitespace-nowrap.
Pas de remplacements manuels de couleur dark:. Utilisez des tokens sémantiques (bg-background, text-muted-foreground).
Utilisez cn() pour les classes conditionnelles. N'écrivez pas de ternaires manuels avec des littéraux de gabarit.
Pas de z-index manuel sur les composants de superposition. Dialog, Sheet, Popover, etc. gèrent leur propre empilement.

Formulaires & Entrées → forms.md

Les formulaires utilisent FieldGroup + Field. N'utilisez jamais de div brut avec space-y-* ou grid gap-* pour la disposition des formulaires.
InputGroup utilise InputGroupInput/InputGroupTextarea. Jamais de Input/Textarea brut à l'intérieur de InputGroup.
Les boutons dans les entrées utilisent InputGroup + InputGroupAddon.
Les ensembles d'options (2–7 choix) utilisent ToggleGroup. Ne bouclez pas sur Button avec un état actif manuel.
FieldSet + FieldLegend pour regrouper des cases à cocher/boutons radio associés. N'utilisez pas de div avec un titre.
La validation de champ utilise data-invalid + aria-invalid. data-invalid sur Field, aria-invalid sur le contrôle. Pour désactivé : data-disabled sur Field, disabled sur le contrôle.

Structure des composants → composition.md

Les éléments sont toujours dans leur Groupe. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
Utilisez asChild (radix) ou render (base) pour les déclencheurs personnalisés. Vérifiez le champ base de npx shadcn@latest info. → base-vs-radix.md
Dialog, Sheet et Drawer ont toujours besoin d'un Titre. DialogTitle, SheetTitle, DrawerTitle requis pour l'accessibilité. Utilisez className="sr-only" si masqué visuellement.
Utilisez la composition complète de Card. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Ne mettez pas tout dans CardContent.
Button n'a pas de isPending/isLoading. Composez avec Spinner + data-icon + disabled.
TabsTrigger doit être à l'intérieur de TabsList. Ne rendez jamais les déclencheurs directement dans Tabs.
Avatar a toujours besoin de AvatarFallback. Pour quand l'image ne charge pas.

Utilisez des composants, pas du balisage personnalisé → composition.md

Utilisez des composants existants avant le balisage personnalisé. Vérifiez si un composant existe avant d'écrire un div stylisé.
Les encadrés utilisent Alert. Ne construisez pas de divs stylisés personnalisés.
Les états vides utilisent Empty. Ne construisez pas de balisage d'état vide personnalisé.
Toast suit la base du projet. Utilisez toast du composant toast pour les projets Base UI. Utilisez toast() de sonner pour les projets Radix et React Aria.
Utilisez Separator au lieu de <hr> ou <div className="border-t">.
Utilisez Skeleton pour les espaces réservés de chargement. Pas de divs animate-pulse personnalisés.
Utilisez Badge au lieu de spans stylisés personnalisés.

Icônes → icons.md

Les icônes dans Button utilisent data-icon. data-icon="inline-start" ou data-icon="inline-end" sur l'icône.
Pas de classes de dimensionnement sur les icônes dans les composants. Les composants gèrent le dimensionnement des icônes via CSS. Pas de size-4 ou w-4 h-4.
Passez les icônes sous forme d'objets, pas de clés de chaîne. icon={CheckIcon}, pas une recherche de chaîne.

Chat & Messagerie → chat.md

L'IU de chat compose les primitives de chat. Les conversations utilisent MessageScroller, les lignes utilisent Message, les surfaces utilisent Bubble. Jamais de div de bulle fait main ou de conteneur de défilement brut.
MessageScroller possède le comportement de défilement. Le suivi de diffusion, l'ancrage et le saut-vers-la-fin (MessageScrollerButton) sont intégrés. N'écrivez pas de hook useStickToBottom/ResizeObserver.
Les pièces jointes utilisent Attachment ; les notes système et les séparateurs utilisent Marker. Pas de cartes Item ou de Separator + une étiquette.

CLI

Ne décodez jamais les codes de préréglage et ne construisez pas d'URL de préréglage manuellement. Utilisez npx shadcn@latest preset decode <code>, preset url <code>, ou preset open <code>. Pour la détection de préréglage tenant compte du projet, utilisez npx shadcn@latest preset resolve.
Appliquez les codes de préréglage directement avec le CLI. Utilisez npx shadcn@latest apply <code> pour les projets existants, ou npx shadcn@latest init --preset <code> lors de l'initialisation.

Modèles clés

Ce sont les modèles les plus courants qui différencient le code shadcn/ui correct. Pour les cas particuliers, consultez les fichiers de règles liés ci-dessus.

// Disposition de formulaire : FieldGroup + Field, pas div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validation : data-invalid sur Field, aria-invalid sur le contrôle.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Email invalide.</FieldDescription>
</Field>

// Icônes dans les boutons : data-icon, pas de classes de dimensionnement.
<Button>
  <SearchIcon data-icon="inline-start" />
  Rechercher
</Button>

// Espacement : gap-*, pas space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // faux

// Dimensions égales : size-*, pas w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // faux

// Couleurs de statut : variantes Badge ou tokens sémantiques, pas de couleurs brutes.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // faux

Sélection de composants

Besoin	Utiliser
Bouton/action	`Button` avec la variante appropriée
Entrées de formulaire	`Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider`
Basculer entre 2–5 options	`ToggleGroup` + `ToggleGroupItem`
Affichage de données	`Table`, `Card`, `Badge`, `Avatar`
Navigation	`Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`
Superpositions	`Dialog` (modal), `Sheet` (panneau latéral), `Drawer` (feuille du bas), `AlertDialog` (confirmation)
Retour d'information	`toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner`
Palette de commandes	`Command` à l'intérieur de `Dialog`
Graphiques	`Chart` (encapsule Recharts)
Disposition	`Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`
États vides	`Empty`
Menus	`DropdownMenu`, `ContextMenu`, `Menubar`
Infobulles/informations	`Tooltip`, `HoverCard`, `Popover`
IU de chat / conversation	`MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker`

Champs clés

Le contexte de projet injecté contient ces champs clés :

aliases → utilisez le préfixe d'alias réel pour les importations (par exemple @/, ~/), ne codez jamais en dur.
isRSC → quand true, les composants utilisant useState, useEffect, les gestionnaires d'événements ou les API du navigateur ont besoin de "use client" en haut du fichier. Référencez toujours ce champ lorsque vous conseillez sur la directive.
tailwindVersion → "v4" utilise les blocs @theme inline ; "v3" utilise tailwind.config.js.
tailwindCssFile → le fichier CSS global où les variables CSS personnalisées sont définies. Modifiez toujours ce fichier, n'en créez jamais un nouveau.
style → traitement visuel des composants (par exemple nova, vega).
base → bibliothèque primitive (radix ou base). Affecte les API des composants et les props disponibles.
iconLibrary → détermine les importations d'icônes. Utilisez lucide-react pour lucide, @tabler/icons-react pour tabler, etc. Ne supposez jamais lucide-react.
resolvedPaths → destinations exactes du système de fichiers pour les composants, utilitaires, hooks, etc.
framework → conventions de routage et de fichiers (par exemple Next.js App Router vs Vite SPA).
packageManager → utilisez-le pour toute installation de dépendances non shadcn (par exemple pnpm add date-fns vs npm install date-fns).
preset → code de préréglage et valeurs résolus pour le projet actuel. Utilisez npx shadcn@latest preset resolve --json lorsque vous avez seulement besoin d'informations sur le préréglage.

Consultez cli.md — commande info pour la référence complète des champs.

Documentation, exemples et utilisation des composants

Exécutez npx shadcn@latest docs <composant> pour obtenir les URL de la documentation, des exemples et de la référence API d'un composant. Récupérez ces URL pour obtenir le contenu réel.

npx shadcn@latest docs button dialog select

Lors de la création, de la correction, du débogage ou de l'utilisation d'un composant, exécutez toujours npx shadcn@latest docs et récupérez d'abord les URL. Cela garantit que vous travaillez avec l'API et les modèles d'utilisation corrects plutôt que de deviner.

Flux de travail

Obtenez le contexte du projet — déjà injecté ci-dessus. Exécutez npx shadcn@latest info à nouveau si vous avez besoin d'actualiser.
Vérifiez d'abord les composants installés — avant d'exécuter add, vérifiez toujours la liste components du contexte du projet ou listez le répertoire resolvedPaths.ui. N'importez pas de composants qui n'ont pas été ajoutés et ne ré-ajoutez pas ceux déjà installés.
Trouvez des composants — npx shadcn@latest search.
Obtenez la documentation et les exemples — exécutez npx shadcn@latest docs <composant> pour obtenir les URL, puis récupérez-les. Utilisez npx shadcn@latest view pour parcourir les éléments du registre que vous n'avez pas installés. Pour prévisualiser les modifications des composants installés, utilisez npx shadcn@latest add --diff.
Installez ou mettez à jour — npx shadcn@latest add. Lors de la mise à jour de composants existants, utilisez --dry-run et --diff pour prévisualiser d'abord les modifications (voir Mise à jour des composants ci-dessous).
Corrigez les importations dans les composants tiers — Après avoir ajouté des composants à partir de registres communautaires (par exemple @bundui, @magicui), vérifiez les fichiers non IU ajoutés pour les chemins d'importation codés en dur comme @/components/ui/.... Ceux-ci ne correspondront pas aux alias réels du projet. Utilisez npx shadcn@latest info pour obtenir l'alias ui correct (par exemple @workspace/ui/components) et réécrivez les importations en conséquence. Le CLI réécrit les importations pour ses propres fichiers IU, mais les composants de registre tiers peuvent utiliser des chemins par défaut qui ne correspondent pas au projet.
Examinez les composants ajoutés — Après avoir ajouté un composant ou un bloc à partir de n'importe quel registre, lisez toujours les fichiers ajoutés et vérifiez qu'ils sont corrects. Vérifiez les sous-composants manquants (par exemple SelectItem sans SelectGroup), les importations manquantes, la composition incorrecte ou les violations des Règles critiques. Remplacez également toutes les importations d'icônes par iconLibrary du projet à partir du contexte du projet (par exemple si l'élément du registre utilise lucide-react mais que le projet utilise hugeicons, échangez les importations et les noms d'icônes en conséquence). Corrigez tous les problèmes avant de continuer.
Le registre doit être explicite — Lorsque l'utilisateur demande d'ajouter un bloc ou un composant, ne devinez pas le registre. Si aucun registre n'est spécifié (par exemple l'utilisateur dit "ajouter un bloc de connexion" sans spécifier @shadcn, @tailark, owner/repo, etc.), demandez quel registre utiliser. Ne choisissez jamais de registre par défaut pour l'utilisateur.
Changement de préréglages — Demandez d'abord à l'utilisateur : écraser, partiel, fusionner ou ignorer ?
- Inspectez le préréglage actuel : npx shadcn@latest preset resolve. Utilisez --json lorsque vous avez besoin de valeurs structurées.
- Inspectez le préréglage entrant : npx shadcn@latest preset decode <code>. Utilisez preset url <code> ou preset open <code> pour partager ou ouvrir le générateur de préréglages.
- Écraser : npx shadcn@latest apply <code>. Écrase les composants, polices et variables CSS détectés.
- Partiel : npx shadcn@latest apply <code> --only theme,font. Met à jour uniquement les parties de préréglage sélectionnées sans réinstaller les composants IU. Les valeurs prises en charge sont theme et font ; les combinaisons séparées par des virgules sont autorisées. icon n'est intentionnellement pas pris en charge, car les modifications d'icônes peuvent nécessiter une réinstallation complète des composants.
- Fusionner : applique un ensemble de modifications mixtes. Cela peut impliquer la réécriture manuelle de parties de la configuration du projet, des polices, des icônes ou des valeurs CSS. Faites preuve de jugement pour déterminer ce qui relève de la fusion par rapport à l'écrasement ou à l'application partielle. Comme la fusion n'est pas prise en charge nativement par le CLI, soyez explicite sur ce que vous faites changez et pourquoi.
- Ignorer : ne pas changer le préréglage. Gardez le préréglage et la configuration actuelle du projet. Évaluez les changements de code ultérieurs dans le contexte actuel.

Mise à jour des composants

Avant de mettre à jour un composant, lisez toujours ses fichiers source actuels.

Lisez les fichiers source actuels du composant. Cela vous permet de comparer ce qui va changer.
Exécutez npx shadcn@latest add <composant> --dry-run pour voir quels changements de fichiers sont proposés.
Exécutez npx shadcn@latest add <composant> --dry-run --diff pour voir les changements de différence réels par fichier.
Exécutez npx shadcn@latest add <composant> pour appliquer les mises à jour.
Exécutez npx shadcn@latest info pour mettre à jour le contexte du projet avec les versions de composants mises à jour.
Vérifiez les changements dans les fichiers mis à jour. Assurez-vous qu'ils suivent toujours les Règles critiques ci-dessus. Vérifiez que les composants qui utilisent le composant mis à jour fonctionnent toujours correctement.

Ajout ou mise à jour de blocs depuis un registre

Les blocs sont des sections d'IU plus grandes qui encapsulent plusieurs composants, l'état, les données, etc.

npx shadcn@latest add --registry <registre> <nom-du-bloc>
# Ou, pour un registre initié :
npx shadcn@latest add @shadcn/blocks/login-01

Toujours :

Utilisez --dry-run en premier.
Examinez le nombre de composants et de fichiers ajoutés (rapport npx shadcn@latest add).
Lors de l'ajout de blocs à partir de registres communautaires, lisez toujours TOUS les fichiers ajoutés et vérifiez leur exactitude.

Fichier de composants de registre

Le fichier de composants de registre (npx shadcn@latest docs <composant> → doc field) contient la documentation du registre, les exemples et les liens de référence API. Utilisez ce fichier comme source d'informations pour le stylisme, les variantes d'API, les noms de propriétés et les modèles d'utilisation.

Erreurs courantes

Couleurs brutes

// FAUX :
<div className="bg-blue-500 p-4 text-white">
  Contenu
</div>

// CORRECT :
<div className="bg-primary p-4 text-primary-foreground">
  Contenu
</div>

Styles de formulaire manuels

// FAUX :
<div className="space-y-4">
  <div>
    <Label>Email</Label>
    <Input />
  </div>
</div>

// CORRECT :
<FieldGroup>
  <Field>
    <FieldLabel>Email</FieldLabel>
    <FieldControl>
      <Input />
    </FieldControl>
  </Field>
</FieldGroup>

Composition incorrecte

// FAUX :
<Select>
  <SelectItem value="1">Option 1</SelectItem>
  <SelectItem value="2">Option 2</SelectItem>
</Select>

// CORRECT :
<Select>
  <SelectGroup>
    <SelectLabel>Options</SelectLabel>
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2">Option 2</SelectItem>
  </SelectGroup>
</Select>

Bibliothèque d'icônes incorrecte

// FAUX (en supposant que lucide-react est utilisé) :
import { Search, Settings } from "lucide-react"

// CORRECT (vérifiez iconLibrary dans le contexte du projet) :
import { Search, Settings } from "@tabler/icons-react"
// ou toute bibliothèque spécifiée par iconLibrary

Chemins d'importation codés en dur dans les composants de registres tiers

Lors de l'ajout de composants à partir de registres communautaires, vérifiez toujours les chemins d'importation. Par exemple, un composant de @bundui pourrait avoir :

// FAUX (chemin codé en dur supposant @/) :
import { Button } from "@/components/ui/button"

// CORRECT (utilisez l'alias ui réel du projet) :
import { Button } from "@workspace/ui/components/button"

Utilisation d'icônes incorrecte dans les boutons

// FAUX :
<Button>
  <SearchIcon className="size-4" />
  Rechercher
</Button>

// CORRECT :
<Button>
  <SearchIcon data-icon="inline-start" />
  Rechercher
</Button>

Dépannage

Problème	Cause	Solution
Une classe Tailwind ne fonctionne pas	Tokens sémantiques non disponibles	Vérifiez que les variables CSS sont définies dans `tailwindCssFile`
Les composants ne correspondent pas au thème	Preset manquant ou appliqué de manière incorrecte	Utilisez `npx shadcn@latest preset resolve` pour vérifier l'état actuel
Le composant rend sans style	Le CSS du composant n'a pas été importé	Vérifiez les importations et que le `tailwindCssFile` est correctement chargé
Les importations d'un registre tiers échouent	Chemins d'importation codés en dur dans les fichiers ajoutés	Remplacez les chemins par les alias corrects du projet (voir champ `aliases`)
Le préréglage n'est pas appliqué	Code de préréglage invalide ou registre manquant	Utilisez `npx shadcn@latest preset decode <code>` pour vérifier le code et l'URL du registre

Variables d'environnement

Aucune variable d'environnement n'est requise pour l'utilisation de base. Les configurations avancées peuvent utiliser SHADCN_REGISTRY_URL pour les registres personnalisés, bien que cela ne soit pas courant.

ga-arnez/claude-skills

Qu'est-ce que claude-skills ?

Demander à votre IA préférée

Documentation