Geruyang/agent-skills-library

shadcn/ui

Vous êtes un expert de shadcn/ui — une collection de composants React magnifiquement conçus, accessibles et personnalisables, construits sur les primitives Radix UI et Tailwind CSS. Les composants sont ajoutés directement à votre code source, et non installés comme une dépendance.

Concept clé

shadcn/ui n'est pas une bibliothèque de composants au sens traditionnel. Vous ne l'installez pas en tant que package. Au lieu de cela, la CLI copie le code source des composants dans votre projet, vous donnant ainsi la pleine propriété et la possibilité de les personnaliser.

Commandes CLI

Initialisation (non interactive — TOUJOURS utiliser celle-ci)

IMPORTANT : shadcn init est interactif par défaut. Utilisez toujours -d (valeurs par défaut) pour une initialisation non interactive :

# Initialisation non interactive avec les valeurs par défaut — À UTILISER
npx shadcn@latest init -d

# Initialisation non interactive avec une présélection (recommandé pour des systèmes de design cohérents)
npx shadcn@latest init --preset <code> -f

# Initialisation non interactive avec un choix explicite de bibliothèque de base
npx shadcn@latest init -d --base radix
npx shadcn@latest init -d --base base-ui

# Générer un modèle de projet complet (CLI v4)

Compatibilité avec AI Elements : Utilisez toujours --base radix (la valeur par défaut) lorsque le projet utilise ou peut utiliser AI Elements. Les composants AI Elements reposent sur les API Radix et présentent des erreurs de type avec Base UI.

npx shadcn@latest init --template next -d
npx shadcn@latest init --template vite -d

Options :

• -d, --defaults — Utiliser la configuration par défaut, ignorer toutes les invites interactives (OBLIGATOIRE pour CI/agent)
• -y, --yes — Ignorer les invites de confirmation (n'ignore PAS la sélection de bibliothèque — utilisez -d à la place)
• -f, --force — Forcer l'écrasement de la configuration existante
• -t, --template — Générer un modèle de projet complet (next, vite, react-router, astro, laravel, tanstack-start)
• --preset — Appliquer une présélection de système de design (couleurs, thème, icônes, polices, rayon) sous la forme d'un code unique et partageable
• --base — Choisir la bibliothèque primitive : radix (par défaut) ou base-ui
• --monorepo — Configurer une structure de monorepo

ATTENTION : -y/--yes seul ne rend PAS init complètement non interactif — il invite toujours à sélectionner la bibliothèque de composants. Utilisez toujours -d pour ignorer TOUTES les invites.

Obsolète dans CLI v4 : Les drapeaux --style, --base-color, --src-dir, --no-base-style et --css-variables sont supprimés et généreront une erreur. Les types de registre registry:build et registry:mcp sont également obsolètes. Utilisez registry:base et registry:font à la place.

La commande init :

1. Détecte votre framework (Next.js, Vite, React Router, Astro, Laravel, TanStack Start)
2. Installe les dépendances requises (Radix UI, tailwind-merge, class-variance-authority)
3. Crée la configuration components.json
4. Configure la fonction utilitaire cn()
5. Configure les variables CSS pour le theming

Ajouter des composants

# Ajouter des composants spécifiques
npx shadcn@latest add button dialog card

# Ajouter tous les composants disponibles
npx shadcn@latest add --all

# Ajouter à partir d'un registre personnalisé
npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @acme/custom-button

# Ajouter à partir du registre AI Elements
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

Options :

• -o, --overwrite — Écraser les fichiers existants
• -p, --path — Chemin d'installation personnalisé
• -a, --all — Installer tous les composants
• --dry-run — Prévisualiser ce qui sera ajouté sans écrire de fichiers
• --diff — Afficher le diff des modifications lors de la mise à jour de composants existants
• --view — Afficher le code source d'un élément de registre en ligne

Recherche et liste

npx shadcn@latest search button
npx shadcn@latest list @v0

Construire (Registre personnalisé)

npx shadcn@latest build
npx shadcn@latest build ./registry.json -o ./public/r

Voir, Informations et Documentation (CLI v4)

# Voir la source d'un élément de registre avant de l'installer
npx shadcn@latest view button

# Afficher les diagnostics du projet — configuration, composants installés, dépendances
npx shadcn@latest info

# Obtenir la documentation, le code et des exemples pour n'importe quel composant (sortie adaptée aux agents)
npx shadcn@latest docs button
npx shadcn@latest docs dialog

shadcn docs donne aux agents de codage le contexte nécessaire pour utiliser correctement les primitives — renvoie des exemples de code, une référence API et des modèles d'utilisation en ligne.

Migrer

npx shadcn@latest migrate rtl    # Migration de support RTL
npx shadcn@latest migrate radix  # Migration vers le package unifié radix-ui
npx shadcn@latest migrate icons  # Changements de bibliothèque d'icônes

# Migrer les composants en dehors du répertoire ui par défaut
npx shadcn@latest migrate radix src/components/custom

shadcn/skills (CLI v4)

shadcn/skills donne aux agents de codage le contexte nécessaire pour travailler correctement avec les composants et les registres. Il couvre à la fois les primitives Radix et Base UI, les API mises à jour, les modèles de composants et les flux de travail de registre. La compétence sait comment utiliser la CLI, quand l'invoquer et quels drapeaux passer — afin que les agents produisent un code qui correspond à votre système de design.

Installation : pnpm dlx skills add shadcn/ui

Package unifié Radix UI (Février 2026)

Le style new-york utilise désormais un seul package radix-ui au lieu de packages individuels @radix-ui/react-* :

// ANCIEN — packages individuels
import * as DialogPrimitive from "@radix-ui/react-dialog"

// NOUVEAU — package unifié
import { Dialog as DialogPrimitive } from "radix-ui"

Pour migrer les projets existants : npx shadcn@latest migrate radix. Après la migration, supprimez les packages @radix-ui/react-* inutilisés de package.json.

Prise en charge de Base UI (Janvier 2026)

shadcn/ui prend désormais en charge Base UI comme alternative à Radix UI pour la bibliothèque primitive sous-jacente. Les composants ont la même apparence et le même comportement, quel que soit la bibliothèque que vous choisissez — seule l'implémentation sous-jacente change.

Choisissez lors de l'init : npx shadcn@latest init --base base-ui

La CLI extrait automatiquement la variante de composant correcte en fonction de la configuration de votre projet.

Configuration (components.json)

Le fichier components.json configure le fonctionnement de shadcn/ui dans votre projet :

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "zinc",  // Options : gray, neutral, slate, stone, zinc, mauve, olive, mist, taupe
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "v0": {
      "url": "https://v0.dev/chat/api/registry"
    },
    "ai-elements": {
      "url": "https://elements.ai-sdk.dev/api/registry"
    }
  }
}

Registres avec espace de noms

Configurez plusieurs registres pour votre projet :

{
  "registries": {
    "acme": {
      "url": "https://acme.com/registry/{name}.json"
    },
    "private": {
      "url": "https://internal.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Installez en utilisant la syntaxe d'espace de noms :

npx shadcn@latest add @acme/header @private/auth-form

Thèmes

Variables CSS

shadcn/ui utilise des propriétés personnalisées CSS pour le theming, définies dans globals.css :

@theme inline {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-card: oklch(0.205 0 0);
  --color-card-foreground: oklch(0.985 0 0);
  --color-primary: oklch(0.488 0.243 264.376);
  --color-primary-foreground: oklch(0.985 0 0);
  --color-secondary: oklch(0.269 0 0);
  --color-secondary-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.269 0 0);
  --color-muted-foreground: oklch(0.708 0 0);
  --color-accent: oklch(0.269 0 0);
  --color-accent-foreground: oklch(0.985 0 0);
  --color-destructive: oklch(0.396 0.141 25.723);
  --color-border: oklch(0.269 0 0);
  --color-input: oklch(0.269 0 0);
  --color-ring: oklch(0.488 0.243 264.376);
  --radius: 0.625rem;
  /* CLI v4 : les tokens de rayon utilisent un calcul multiplicatif au lieu d'additif */
  --radius-xs: calc(var(--radius) * 0.5);
  --radius-sm: calc(var(--radius) * 0.75);
  --radius-md: calc(var(--radius) * 0.875);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.5);
}

Mode sombre

Pour le mode sombre, utilisez la classe dark sur <html> :

// app/layout.tsx
<html lang="en" className="dark">

Ou utilisez next-themes pour la commutation :

import { ThemeProvider } from 'next-themes'

<ThemeProvider attribute="class" defaultTheme="dark">
  {children}
</ThemeProvider>

Couleurs personnalisées

Ajoutez des couleurs spécifiques à l'application aux côtés des valeurs par défaut de shadcn :

@theme inline {
  /* valeurs par défaut de shadcn ci-dessus... */

  /* Couleurs d'application personnalisées */
  --color-priority-urgent: oklch(0.637 0.237 15.163);
  --color-priority-high: oklch(0.705 0.213 47.604);
  --color-status-done: oklch(0.723 0.219 149.579);
}

Utilisation dans les composants :

<span className="text-[var(--color-priority-urgent)]">Urgent</span>
// Ou avec Tailwind v4 theme() :
<span className="text-priority-urgent">Urgent</span>

Composants les plus courants

Composant	Cas d'utilisation
button	Actions, soumission de formulaire
card	Conteneurs de contenu
dialog	Modales, invites de confirmation
input / textarea	Champs de formulaire
select	Listes déroulantes
table	Affichage de données
tabs	Changement de vue
command	Palette de commandes (Cmd+K)
dropdown-menu	Menus contextuels
popover	Contenu flottant
tooltip	Info-bulles au survol
badge	Indicateurs d'état
avatar	Images de profil utilisateur
scroll-area	Conteneurs défilants
separator	Séparateurs visuels
label	Étiquettes de formulaire
sheet	Panneaux coulissants
skeleton	Espaces réservés de chargement

Direction du design pour shadcn sur Vercel

shadcn/ui n'est pas seulement un générateur de code source de composants. Dans la pile Vercel, c'est le langage d'interface par défaut. Ne vous arrêtez pas à « le composant fonctionne ». Composez des pages qui semblent délibérées, à fort signal et cohérentes.

Esthétique par défaut pour l'interface produit

• Préférez le style : new-york pour les surfaces produit, tableau de bord, IA et administration.
• Par défaut, utilisez le mode sombre pour les tableaux de bord, les applications IA, les outils internes, les paramètres et les produits destinés aux développeurs. Utilisez le mode clair uniquement lorsque le produit est clairement axé sur le contenu ou éditorial.
• Utilisez Geist Sans pour le texte de l'interface et Geist Mono pour le code, les métriques, les IDs, les horodatages et les commandes.
• Préférez zinc, neutral ou slate comme palette de base. Utilisez une couleur d'accent via --color-primary.
• Construisez les surfaces de base à partir de tokens : bg-background, bg-card, text-foreground, text-muted-foreground, border-border, ring-ring. Évitez les valeurs hexadécimales ad-hoc.
• Gardez un rayon cohérent. Le --radius: 0.625rem par défaut est une bonne base de référence.
• Utilisez un système de densité par page : confortable (gap-6 / p-6 / text-sm) ou compact (gap-4 / p-4 / text-sm).
• Gardez les icônes discrètes et cohérentes. Icônes Lucide à h-4 w-4 ou h-5 w-5.

Utilisez d'abord ceux-ci

Cas d'utilisation	Utilisez d'abord ceci	Pourquoi
Page de paramètres	Tabs + Card + Form	Regroupement clair des informations avec des flux de sauvegarde prévisibles
Tableau de bord de données	Card + Badge + Table + DropdownMenu	Couvre le résumé, le statut, les données denses et les actions de ligne sans shells personnalisés
Tableau CRUD	Table + DropdownMenu + Sheet + AlertDialog	Prend en charge la navigation, l'action, l'édition et la confirmation destructive dans un modèle standard
Écran d'authentification	Card + Label + Input + Button + Alert	Maintient les flux de connexion ciblés et donne aux erreurs un traitement approprié
Recherche globale	Command + Dialog	Découverte rapide axée sur le clavier avec un modèle d'interaction établi
Navigation mobile	Sheet + Button + Separator	Fournit un shell de navigation compact qui s'adapte proprement aux petits écrans
Page de détail	en-tête + Badge + Separator + Card	Équilibre la hiérarchie, les métadonnées et le contenu de support sans imbrication excessive
Filtres	Barre latérale Card + Sheet + Select	Fonctionne pour les filtres de bureau persistants et les commandes mobiles repliables
États vides/chargement/erreur	Card + Skeleton + Alert	Donne aux chemins non heureux une surface conçue au lieu d'un texte d'espace réservé

Recettes de composition

• Page de paramètres : Tabs + Card par groupe + Separator + action de sauvegarde
• Tableau de bord admin : Cards de résumé + barre de filtre + Table
• Détail d'entité : en-tête + Badge de statut + Card principal + Card latéral + AlertDialog pour les actions destructrices
• Interface de recherche : Command pour la recherche rapide, Popover pour les sélecteurs, Sheet pour les filtres mobiles
• Auth/onboarding : Card centré + Separator social + Alert en ligne pour les erreurs
• Flux destructeurs : AlertDialog (pas Dialog) pour la confirmation

Anti-patrons à éviter

• button / input / select / div bruts lorsque des primitives shadcn existent
• div rounded-xl border p-6 répété au lieu de Tabs / Table / Sheet / Dialog
• Plusieurs couleurs d'accent qui se concurrencent
• Des cartes imbriquées dans des cartes elles-mêmes imbriquées dans des cartes
• De grands fonds dégradés et du glassmorphisme sur chaque surface
• Mélange de valeurs d'espacement et de rayon arbitraires
• Utilisation de Dialog pour la confirmation destructive au lieu de AlertDialog
• Livraison d'états vides/chargement/erreur sans traitement de conception
• Utilisation de classes de palette Tailwind ad-hoc pour les surfaces fondamentales au lieu de tokens de thème

Construire un registre personnalisé

Créez votre propre registre de composants à partager entre les projets :

Types de registre (CLI v4)

Type	Objectif
registry:ui	Composants d'interface individuels
registry:base	Payload de système de design complet — composants, dépendances, variables CSS, polices, configuration
registry:font	Configuration de police en tant qu'élément de registre de première classe

1. Définir registry.json

[
  {
    "name": "custom-header",
    "type": "registry:ui",
    "dependencies": ["@radix-ui/react-navigation-menu"],
    "files": [
      {
        "path": "custom-header.tsx",
        "type": "registry:ui"
      }
    ]
  }
]

2. Construire le registre

npx shadcn@latest build ./registry.json -o ./public/r

3. Installer depuis le registre

npx shadcn@latest add @my-org/custom-header

shadcn/v0 (v4)

v0 est un registre officiel de composants shadcn. Il vous permet d'installer des composants et des blocs générés par v0 :

npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @v0/login-card

Important pour les agents : Lorsque vous utilisez le registre v0, vérifiez toujours les dépendances répertoriées dans le registre. L'installation peut échouer si les dépendances ne sont pas incluses dans votre projet.

Dépannage de v0

Si npx shadcn@latest add @v0/dashboard échoue :

1. Vérifiez que le registre v0 est configuré dans components.json
2. Exécutez npx shadcn@latest list @v0 pour voir les composants disponibles
3. Si un composant semble manquant, il peut s'agir d'un bloc nécessitant des dépendances supplémentaires — consultez la documentation

Installation AI Elements

Pour utiliser des composants AI Elements dans votre projet shadcn/ui :

1. Ajoutez le registre AI Elements à components.json :

{
  "registries": {
    "ai-elements": {
      "url": "https://elements.ai-sdk.dev/api/registry"
    }
  }
}

2. Installez des composants individuels :

npx shadcn@latest add @ai-elements/source @ai-elements/file-preview

Ou installez tous les composants :

npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

En résumé

En tant qu'expert shadcn/ui :

• Utilisez shadcn init -d pour l'initialisation non interactive — TOUJOURS avec -d
• Préférez le style new-york pour les applications modernes
• Utilisez le package unifié radix-ui pour les nouveaux projets
• Ajoutez des composants avec shadcn add <name>
• Créez des registres personnalisés avec registry:ui, registry:base, registry:font
• Utilisez des tokens de thème (--color-*, --radius-*) pour des designs cohérents
• Utilisez AlertDialog pour les actions destructrices, Dialog pour les modales habituelles
• Composez les UIs en utilisant des modèles établis (paramètres, tableaux de bord, authentification, recherche) plutôt que de construire à partir de zéro