niamkvn/shadcn-svelte

Que fait shadcn-svelte ?

Un cadre pour construire des interfaces utilisateur, des composants et des systèmes de design pour Svelte. Les composants sont ajoutés sous forme de code source dans le projet de l'utilisateur via la CLI.

IMPORTANT : Exécutez toutes les commandes CLI en utilisant le gestionnaire de paquets du projet : npx shadcn-svelte@latest, pnpm dlx shadcn-svelte@latest, ou bunx --bun shadcn-svelte@latest — selon le gestionnaire de paquets utilisé. Les exemples ci-dessous utilisent npx shadcn-svelte@latest mais remplacez par la bonne commande pour le projet.

Contexte actuel du projet

Lisez components.json à la racine du projet et, lorsque vous avez besoin de la structure des fichiers en direct, listez le répertoire donné par le chemin aliases.ui (résolu avec les mêmes règles que la CLI).

Imports (Svelte)

Chaque composant réside dans son propre dossier avec un fichier baril index.ts. Suivez la documentation d'installation :

• Composants multi-parties (dialog, select, card, field, tabs, …) : import * as Dialog from "$lib/components/ui/dialog" puis Dialog.Content, Dialog.Title, Card.Root, Card.Header, etc. — selon ce que le baril exporte (noms courts et/ou alias Root as …).
• Barils à composant unique (un seul composant significatif dans le dossier) : imports nommés — import { Button } from "$lib/components/ui/button" et <Button>, pas import * as Button + Button.Root. Même modèle pour { Input }, { Badge }, { Spinner }, { Checkbox }, { Separator }, { Skeleton }, etc.

import * as Dialog from "$lib/components/ui/dialog";
import { Button } from "$lib/components/ui/button";
import { Separator } from "$lib/components/ui/separator";

Utilisez les vrais alias de components.json (souvent $lib/components/ui/...), pas de chemins codés en dur.

Principes

1. Utilisez d'abord les composants existants. Exécutez npx shadcn-svelte@latest add sans arguments pour parcourir les composants disponibles, ou consultez Composants avant d'écrire une UI personnalisée.
2. Composez, ne réinventez pas. Page de paramètres = Tabs + Card + contrôles de formulaire. Tableau de bord = Sidebar + Card + Chart + Table.
3. Utilisez les variantes intégrées avant les styles personnalisés. variant="outline", size="sm", etc.
4. Utilisez des 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.

Style & Tailwind → styling.md

• class pour la mise en page, pas pour le style. Ne remplacez jamais les couleurs ou la typographie des composants.
• Pas de space-x-* ou space-y-*. Utilisez flex avec gap-*. Pour les empilements verticaux, 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 d'écrasements manuels de couleurs 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 template literals.
• Pas de z-index manuel sur les composants de superposition. Dialog, Sheet, Popover, etc. gèrent leur propre empilement.

Formulaires & Saisies → forms.md

• Les formulaires utilisent Field.FieldGroup + Field.Field. N'utilisez jamais de div brut avec space-y-* ou grid gap-* pour la mise en page du formulaire.
• InputGroup utilise InputGroup.Input/InputGroup.Textarea. Jamais de Input/Textarea brut à l'intérieur de InputGroup.Root.
• Les boutons dans les saisies utilisent InputGroup.Root + InputGroup.Addon.
• Les ensembles d'options (2–7 choix) utilisent ToggleGroup. Ne bouclez pas sur Button avec un état actif manuel.
• Field.FieldSet + Field.FieldLegend pour regrouper des cases à cocher/boutons radio associés. N'utilisez pas de div avec un titre.
• La validation des champs 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. Select.Item → Select.Group. DropdownMenu.Item → DropdownMenu.Group. Command.Item → Command.Group.
• Déclencheurs personnalisés. Enveloppez les contrôles dans Dialog.Trigger / AlertDialog.Trigger, ou contrôlez l'état ouvert avec bind:open sur la racine — consultez la documentation du composant.
• Dialog, Sheet et Drawer ont toujours besoin d'un Titre. Dialog.Title, Sheet.Title, Drawer.Title requis pour l'accessibilité. Utilisez class="sr-only" si caché visuellement.
• Utilisez la composition complète de Card. Card.Header/Card.Title/Card.Description/Card.Content/Card.Footer. Ne mettez pas tout dans Card.Content.
• Button n'a pas de isPending/isLoading. Composez avec Spinner à l'intérieur de Button + disabled ; utilisez data-icon="inline-start" / inline-end sur Spinner pour un espacement correct (import { Button }, import { Spinner }).
• Tabs.Trigger doit être à l'intérieur de Tabs.List. Ne rendez jamais les déclencheurs directement dans Tabs.
• Avatar a toujours besoin de Avatar.Fallback. Pour quand l'image ne se charge pas.

Utilisez les composants, pas le balisage personnalisé → composition.md

• Utilisez les 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 div stylisés personnalisés.
• Les états vides utilisent Empty. Ne construisez pas de balisage d'état vide personnalisé.
• Toast via svelte-sonner. Utilisez toast() de svelte-sonner avec le composant Sonner de votre dossier UI.
• Utilisez Separator au lieu de <hr> ou d'un div avec des classes de bordure uniquement.
• Utilisez Skeleton pour les espaces réservés de chargement. Pas de div animate-pulse personnalisé.
• Utilisez Badge au lieu de span 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 la taille des icônes via CSS. Pas de size-4 ou w-4 h-4.
• Passez les icônes en tant que composants. Importez depuis la iconLibrary configurée (par ex. @lucide/svelte), pas de clés de chaîne.

CLI

• Préréglages — copiez la chaîne encodée du générateur de système de design sur shadcn-svelte.com et passez-la à npx shadcn-svelte@latest init --preset <code>.

Modèles clés

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

<script lang="ts">
  import * as Field from "$lib/components/ui/field";
  import { Input } from "$lib/components/ui/input";
  import { Button } from "$lib/components/ui/button";
  import SearchIcon from "@lucide/svelte/icons/search";
  import { Badge } from "$lib/components/ui/badge";
  import * as Avatar from "$lib/components/ui/avatar";
</script>

<!-- Mise en page du formulaire : Field.FieldGroup + Field.Field, pas div + Label. -->
<Field.FieldGroup>
  <Field.Field>
    <Field.FieldLabel for="email">Email</Field.FieldLabel>
    <Input id="email" />
  </Field.Field>
</Field.FieldGroup>

<!-- Validation : data-invalid sur Field, aria-invalid sur le contrôle. -->
<Field.Field data-invalid>
  <Field.FieldLabel for="email">Email</Field.FieldLabel>
  <Input id="email" aria-invalid />
  <Field.FieldDescription>Email invalide.</Field.FieldDescription>
</Field.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 class="flex flex-col gap-4"></div>

<!-- Dimensions égales : size-*, pas w-* h-*. -->
<Avatar.Root class="size-10">
  <Avatar.Image src="/u.png" alt="Utilisateur" />
  <Avatar.Fallback>U</Avatar.Fallback>
</Avatar.Root>

<!-- Couleurs d'état : variantes Badge ou tokens sémantiques, pas de couleurs brutes. -->
<Badge variant="secondary">+20,1%</Badge>

Sélection des composants

Besoin	Utilisation
Bouton/action	Button avec la variante appropriée (import { Button })
Saisies de formulaire	Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider
Basculer entre 2–5 options	ToggleGroup.Root + ToggleGroup.Item
Affichage de données	Table, Card, Badge, Avatar
Navigation	Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination
Superpositions	Dialog (modal), Sheet (panneau latéral), Drawer (feuille inférieure), AlertDialog (confirmation)
Feedback	svelte-sonner (toast), Alert, Progress, Skeleton, Spinner
Palette de commandes	Command dans Dialog
Graphiques	Chart (LayerChart)
Mise en page	Card, Separator, Resizable, ScrollArea, Accordion, Collapsible
États vides	Empty
Menus	DropdownMenu, ContextMenu, Menubar
Info-bulles/info	Tooltip, HoverCard, Popover

Champs clés

Utilisez components.json et le système de fichiers — pas une commande info séparée :

• aliases → utilisez le préfixe d'alias réel de la configuration (par ex. $lib/), ne codez jamais en dur des projets non liés.
• tailwind.css → le fichier CSS global où résident les variables de thème. Modifiez ce fichier pour les réglages de thème ; n'ajoutez pas de second fichier global sauf si l'utilisateur en utilise déjà un.
• style → le traitement visuel (par ex. nova, vega, …) et le chemin du style du registre.
• iconLibrary → détermine les paquets d'icônes (@lucide/svelte, @tabler/icons-svelte, etc.). Ne supposez jamais @lucide/svelte.
• registry → où la CLI récupère les composants ; registre officiel par défaut sur shadcn-svelte.com.
• resolvedPaths (conceptuel) → la CLI résout aliases en chemins absolus ; listez aliases.ui sur le disque pour voir les composants installés.

Voir cli.md pour les commandes et les drapeaux.

Documentation, exemples et utilisation des composants

Ouvrez https://shadcn-svelte.com/docs/components/<name>.md pour la documentation et les exemples. Lors de la création, correction, débogage ou utilisation d'un composant, lisez d'abord la page officielle afin de suivre les API documentées.

Flux de travail

1. Obtenez le contexte du projet — lisez components.json et listez le répertoire des composants UI lorsque nécessaire.
2. Vérifiez d'abord les composants installés — avant d'exécuter add, listez les fichiers sous le chemin ui résolu. N'importez pas de composants qui n'ont pas été ajoutés, et ne ré-ajoutez pas ceux déjà présents sauf pour une mise à jour.
3. Découvrez les composants — npx shadcn-svelte@latest add sans arguments (liste interactive), ou le site de documentation.
4. Installez ou mettez à jour — npx shadcn-svelte@latest add <name> ou une URL de registre. Pour rafraîchir les fichiers existants depuis le registre, utilisez npx shadcn-svelte@latest update (voir cli.md).
5. Corrigez les imports dans les éléments ajoutés par des tiers/URL — Après avoir ajouté depuis une URL de registre personnalisée, vérifiez les chemins codés en dur qui ne correspondent pas aux aliases du projet. Réécrivez les imports pour utiliser les alias ui / lib du projet depuis components.json.
6. Passez en revue les composants ajoutés — Après l'ajout, lisez les fichiers ajoutés et vérifiez la composition (groupes, titres, attributs de validation). Alignez les imports d'icônes avec iconLibrary.
7. Éléments de registre distant — L'ajout par URL est explicite ; si l'utilisateur souhaite un composant d'une source inconnue, confirmez l'URL du registre ou l'élément avant d'exécuter add.

Systèmes de design à partir de DESIGN.md

Lorsque l'utilisateur demande un système de design à partir d'un DESIGN.md (ou d'un cahier des charges de marque), avec ou sans préréglage, suivez design-system.md de bout en bout :

1. Pour une nouvelle application, créez SvelteKit avec npx sv create <app> (ou Svelte + Vite si demandé), puis initialisez avec npx shadcn-svelte@latest init --preset <code>. Sans code, choisissez un style qui correspond au DESIGN.md et passez son nom, par ex. init --preset luma ; les codes de préréglage React et les drapeaux de création ne s'appliquent pas. Dans une application existante, préservez les personnalisations locales.
2. Installez tous les composants avec add --all --yes dans une nouvelle application ; ajoutez uniquement les composants manquants dans une application existante.
3. Lisez le frontmatter du DESIGN.md, les À faire et À ne pas faire, et les Lacunes connues avant d'éditer.
4. Mappez ses tokens sur les variables dans tailwind.css de components.json. Fixez l'échelle de rayon, les ombres, les polices et les utilitaires type-*.
5. Restylez les variantes installées de tailwind-variants et le CSS de style associé. Modifiez les hauteurs des contrôles ensemble.
6. Construisez la page selon design-system-page.md : rôles de couleur vérifiés pour le contraste, spécimens typographiques, matrices d'état épinglées, cas particuliers, paires faire/ne pas faire, recettes. Vérifiez les imports avec scripts/showcase-coverage.mjs, puis vérifiez que chaque composant s'affiche.
7. Vérifiez dans un navigateur : svelte-check, build de production incluant SSR, aucune erreur dans la console, chargement en haut de page, pas de débordement horizontal, mode sombre.

Mise à jour des composants

Utilisez la commande update pour récupérer les dernières versions du registre des composants déjà présents dans le projet. Examinez les modifications avec git diff après update.

1. Validez ou mettez de côté le travail local.
2. Exécutez npx shadcn-svelte@latest update [component] ou --all.
3. Résolvez les conflits de fusion si vous avez personnalisé des fichiers.
4. N'utilisez jamais --overwrite sur add sans l'approbation explicite de l'utilisateur lorsque cela détruirait des modifications intentionnelles.

Référence rapide

# Initialiser shadcn-svelte dans un projet
npx shadcn-svelte@latest init

# Initialiser avec un préréglage
npx shadcn-svelte@latest init --preset <code>

# Ajouter des composants
npx shadcn-svelte@latest add
npx shadcn-svelte@latest add button
npx shadcn-svelte@latest add https://exemple.com/registre/button.json

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

# Mettre à jour les composants
npx shadcn-svelte@latest update
npx shadcn-svelte@latest update button
npx shadcn-svelte@latest update --all