niamkvn/shadcn-svelte

Was macht shadcn-svelte?

Ein Framework zum Erstellen von UI, Komponenten und Designsystemen für Svelte. Komponenten werden über die CLI als Quellcode zum Benutzerprojekt hinzugefügt.

WICHTIG: Führen Sie alle CLI-Befehle mit dem Paket-Runner des Projekts aus: npx shadcn-svelte@latest, pnpm dlx shadcn-svelte@latest oder bunx --bun shadcn-svelte@latest – je nach Paketmanager des Projekts. Die Beispiele unten verwenden npx shadcn-svelte@latest, aber ersetzen Sie den korrekten Runner für das jeweilige Projekt.

Aktueller Projektkontext

Lesen Sie components.json im Projektstammverzeichnis und listen Sie, wenn Sie das aktuelle Dateilayout benötigen, das durch den aliases.ui-Pfad angegebene Verzeichnis auf (aufgelöst mit denselben Regeln wie die CLI).

Importe (Svelte)

Jede Komponente lebt in einem eigenen Ordner mit einer index.ts-Barrel-Datei. Entsprechen Sie der Installationsdokumentation:

• Mehrteilige Komponenten (Dialog, Select, Card, Field, Tabs, …): import * as Dialog from "$lib/components/ui/dialog" dann Dialog.Content, Dialog.Title, Card.Root, Card.Header, etc. – je nachdem, was die Barrel-Datei exportiert (Kurznamen und/oder Root as …-Aliase).
• Einzelkomponenten-Barrels (nur eine sinnvolle Komponente im Ordner): benannte Importe – import { Button } from "$lib/components/ui/button" und <Button>, nicht import * as Button + Button.Root. Gleiches Muster für { 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";

Verwenden Sie die tatsächlichen Aliasnamen aus components.json (oft $lib/components/ui/...), keine hartcodierten Pfade.

Grundsätze

1. Vorhandene Komponenten zuerst verwenden. Führen Sie npx shadcn-svelte@latest add ohne Argumente aus, um verfügbare Komponenten zu durchsuchen, oder prüfen Sie die Komponenten, bevor Sie eigene UI schreiben.
2. Komponieren, nicht neu erfinden. Einstellungsseite = Tabs + Card + Formular-Steuerelemente. Dashboard = Sidebar + Card + Chart + Table.
3. Eingebaute Varianten vor benutzerdefinierten Stilen verwenden. variant="outline", size="sm", etc.
4. Semantische Farben verwenden. bg-primary, text-muted-foreground – niemals rohe Werte wie bg-blue-500.

Kritische Regeln

Diese Regeln werden immer durchgesetzt. Jede verlinkt auf eine Datei mit korrekten/inkorrekten Code-Paaren.

Styling & Tailwind → styling.md

• class für Layout, nicht für Styling. Überschreiben Sie niemals Komponentenfarben oder Typografie.
• Kein space-x-* oder space-y-*. Verwenden Sie flex mit gap-*. Für vertikale Stapel: flex flex-col gap-*.
• Verwenden Sie size-*, wenn Breite und Höhe gleich sind. size-10 nicht w-10 h-10.
• Verwenden Sie die Kurzform truncate. Nicht overflow-hidden text-ellipsis whitespace-nowrap.
• Keine manuellen dark:-Farbüberschreibungen. Verwenden Sie semantische Tokens (bg-background, text-muted-foreground).
• Verwenden Sie cn() für bedingte Klassen. Schreiben Sie keine manuellen Template-Literal-Ternäre.
• Kein manuelles z-index auf Overlay-Komponenten. Dialog, Sheet, Popover, etc. verwalten ihren eigenen Stack.

Formulare & Eingaben → forms.md

• Formulare verwenden Field.FieldGroup + Field.Field. Verwenden Sie niemals rohe div mit space-y-* oder grid gap-* für das Formularlayout.
• InputGroup verwendet InputGroup.Input/InputGroup.Textarea. Niemals rohes Input/Textarea innerhalb von InputGroup.Root.
• Schaltflächen innerhalb von Eingaben verwenden InputGroup.Root + InputGroup.Addon.
• Optionssätze (2–7 Auswahlmöglichkeiten) verwenden ToggleGroup. Keine Schleife über Button mit manuellem Aktivstatus.
• Field.FieldSet + Field.FieldLegend für die Gruppierung verwandter Checkboxen/Radios. Kein div mit Überschrift.
• Feldvalidierung verwendet data-invalid + aria-invalid. data-invalid auf Field, aria-invalid auf dem Steuerelement. Für deaktiviert: data-disabled auf Field, disabled auf dem Steuerelement.

Komponentenstruktur → composition.md

• Elemente immer innerhalb ihrer Gruppe. Select.Item → Select.Group. DropdownMenu.Item → DropdownMenu.Group. Command.Item → Command.Group.
• Benutzerdefinierte Auslöser. Steuerelemente in Dialog.Trigger / AlertDialog.Trigger einschließen, oder den offenen Status mit bind:open auf dem Root-Element steuern – siehe Komponentendokumentation.
• Dialog, Sheet und Drawer benötigen immer einen Titel. Dialog.Title, Sheet.Title, Drawer.Title für Barrierefreiheit erforderlich. Verwenden Sie class="sr-only", wenn visuell versteckt.
• Vollständige Card-Komposition verwenden. Card.Header/Card.Title/Card.Description/Card.Content/Card.Footer. Nicht alles in Card.Content einfügen.
• Button hat kein isPending/isLoading. Mit Spinner innerhalb von Button + disabled komponieren; data-icon="inline-start" / inline-end auf Spinner für korrekte Abstände verwenden (import { Button }, import { Spinner }).
• Tabs.Trigger muss innerhalb von Tabs.List sein. Auslöser niemals direkt in Tabs rendern.
• Avatar benötigt immer Avatar.Fallback. Für den Fall, dass das Bild nicht geladen werden kann.

Komponenten verwenden, kein benutzerdefiniertes Markup → composition.md

• Vorhandene Komponenten vor benutzerdefiniertem Markup verwenden. Prüfen, ob eine Komponente existiert, bevor ein gestylter div geschrieben wird.
• Hinweise verwenden Alert. Keine benutzerdefinierten gestylten Divs bauen.
• Leere Zustände verwenden Empty. Kein benutzerdefiniertes Leerzustands-Markup bauen.
• Toast über svelte-sonner. toast() aus svelte-sonner mit der Sonner-Komponente aus Ihrem UI-Ordner verwenden.
• Separator anstelle von <hr> oder einem div mit randbasierten Klassen verwenden.
• Skeleton für Lade-Platzhalter verwenden. Keine benutzerdefinierten animate-pulse-Divs.
• Badge anstelle benutzerdefinierter gestylter Spans verwenden.

Icons → icons.md

• Icons in <Button> verwenden data-icon. data-icon="inline-start" oder data-icon="inline-end" auf dem Icon.
• Keine Größenklassen auf Icons innerhalb von Komponenten. Komponenten handhaben die Icon-Größe über CSS. Kein size-4 oder w-4 h-4.
• Icons als Komponenten übergeben. Aus der konfigurierten iconLibrary importieren (z. B. @lucide/svelte), nicht als String-Schlüssel.

CLI

• Presets – kopieren Sie die codierte Zeichenkette vom Design-System-Builder auf shadcn-svelte.com und übergeben Sie sie an npx shadcn-svelte@latest init --preset <code>.

Schlüsselmuster

Dies sind die häufigsten Muster, die korrekten shadcn-svelte-Code auszeichnen. Für Randfälle siehe die verlinkten Regeldateien oben.

<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>

<!-- Formularlayout: Field.FieldGroup + Field.Field, nicht div + Label. -->
<Field.FieldGroup>
  <Field.Field>
    <Field.FieldLabel for="email">E-Mail</Field.FieldLabel>
    <Input id="email" />
  </Field.Field>
</Field.FieldGroup>

<!-- Validierung: data-invalid auf Field, aria-invalid auf dem Steuerelement. -->
<Field.Field data-invalid>
  <Field.FieldLabel for="email">E-Mail</Field.FieldLabel>
  <Input id="email" aria-invalid />
  <Field.FieldDescription>Ungültige E-Mail.</Field.FieldDescription>
</Field.Field>

<!-- Icons in Schaltflächen: data-icon, keine Größenklassen. -->
<Button>
  <SearchIcon data-icon="inline-start" />
  Suchen
</Button>

<!-- Abstände: gap-*, nicht space-y-*. -->
<div class="flex flex-col gap-4"></div>

<!-- Gleiche Abmessungen: size-*, nicht w-* h-*. -->
<Avatar.Root class="size-10">
  <Avatar.Image src="/u.png" alt="Benutzer" />
  <Avatar.Fallback>B</Avatar.Fallback>
</Avatar.Root>

<!-- Statusfarben: Badge-Varianten oder semantische Tokens, nicht rohe Farben. -->
<Badge variant="secondary">+20,1%</Badge>

Komponentenauswahl

Bedarf	Verwendung
Schaltfläche/Aktion	Button mit passender Variante (import { Button })
Formulareingaben	Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider
Umschalten zwischen 2–5 Optionen	ToggleGroup.Root + ToggleGroup.Item
Datenanzeige	Table, Card, Badge, Avatar
Navigation	Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination
Overlays	Dialog (Modal), Sheet (Seitenleiste), Drawer (unteres Blatt), AlertDialog (Bestätigung)
Feedback	svelte-sonner (Toast), Alert, Progress, Skeleton, Spinner
Befehlspalette	Command innerhalb von Dialog
Diagramme	Chart (LayerChart)
Layout	Card, Separator, Resizable, ScrollArea, Accordion, Collapsible
Leere Zustände	Empty
Menüs	DropdownMenu, ContextMenu, Menubar
Tooltips/Info	Tooltip, HoverCard, Popover

Schlüsselfelder

Verwenden Sie components.json und das Dateisystem – nicht einen separaten info-Befehl:

• aliases → verwenden Sie das tatsächliche Alias-Präfix aus der Konfiguration (z. B. $lib/), niemals für fremde Projekte hartcodieren.
• tailwind.css → die globale CSS-Datei, in der Theme-Variablen leben. Bearbeiten Sie diese Datei für Theme-Anpassungen; fügen Sie keine zweite Globals-Datei hinzu, es sei denn, der Benutzer verwendet bereits eine.
• style → visuelle Behandlung (z. B. nova, vega, …) und Registry-Stil-Pfad.
• iconLibrary → bestimmt Icon-Pakete (@lucide/svelte, @tabler/icons-svelte, etc.). Gehen Sie niemals von @lucide/svelte aus.
• registry → wo die CLI Komponenten abruft; Standard-Registry unter shadcn-svelte.com.
• resolvedPaths (konzeptionell) → die CLI löst aliases zu absoluten Pfaden auf; listen Sie aliases.ui auf der Festplatte auf, um installierte Komponenten zu sehen.

Siehe cli.md für Befehle und Flags.

Komponentendokumentation, Beispiele und Verwendung

Öffnen Sie https://shadcn-svelte.com/docs/components/<name>.md für Dokumentation und Beispiele. Lesen Sie beim Erstellen, Reparieren, Debuggen oder Verwenden einer Komponente zuerst die offizielle Seite, damit Sie die dokumentierten APIs befolgen.

Arbeitsablauf

1. Projektkontext abrufen – components.json lesen und bei Bedarf das UI-Komponentenverzeichnis auflisten.
2. Installierte Komponenten zuerst prüfen – vor dem Ausführen von add die Dateien unter dem aufgelösten ui-Pfad auflisten. Keine Komponenten importieren, die nicht hinzugefügt wurden, und keine bereits vorhandenen erneut hinzufügen, es sei denn, es wird aktualisiert.
3. Komponenten entdecken – npx shadcn-svelte@latest add ohne Argumente (interaktive Liste) oder die Dokumentationsseite.
4. Installieren oder aktualisieren – npx shadcn-svelte@latest add <name> oder eine Registry-URL. Verwenden Sie npx shadcn-svelte@latest update (siehe cli.md), um vorhandene Dateien aus der Registry zu aktualisieren.
5. Importe in Drittanbieter-/URL-hinzugefügten Elementen reparieren – nach dem Hinzufügen von einer benutzerdefinierten Registry-URL auf hartcodierte Pfade prüfen, die nicht zu den aliases des Projekts passen. Importe so umschreiben, dass sie die ui- / lib-Aliase des Projekts aus components.json verwenden.
6. Hinzugefügte Komponenten überprüfen – nach dem Hinzufügen die hinzugefügten Dateien lesen und die Komposition verifizieren (Gruppen, Titel, Validierungsattribute). Icon-Importe mit iconLibrary abgleichen.
7. Remote-Registry-Elemente – das Hinzufügen per URL ist explizit; wenn der Benutzer eine Komponente aus einer unbekannten Quelle möchte, bestätigen Sie die Registry-URL oder das Element, bevor Sie add ausführen.

Designsysteme aus DESIGN.md

Wenn der Benutzer ein Designsystem aus einer DESIGN.md (oder einer Markenspezifikation) anfordert, mit oder ohne Preset, folgen Sie design-system.md Schritt für Schritt:

1. Für eine neue App SvelteKit mit npx sv create <app> (oder Svelte + Vite, wenn gewünscht) gerüsten, dann mit npx shadcn-svelte@latest init --preset <code> initialisieren. Ohne Code einen Stil auswählen, der zur DESIGN.md passt, und seinen Namen übergeben, z. B. init --preset luma; React-Preset-Codes und Scaffolding-Flags gelten nicht. In einer bestehenden App lokale Anpassungen beibehalten.
2. Jede Komponente mit add --all --yes in einer neuen App installieren; in einer bestehenden App nur fehlende Komponenten hinzufügen.
3. Die DESIGN.md-Frontmatter, Do's und Don'ts sowie bekannte Lücken lesen, bevor Änderungen vorgenommen werden.
4. Die Tokens auf die Variablen in components.json's tailwind.css abbilden. Die Radius-Skala, Schatten, Schriftarten und type-*-Hilfsklassen festlegen.
5. Installierte tailwind-variants-Varianten und zugehörige Stil-CSS neu gestalten. Steuerelementhöhen gemeinsam ändern.
6. Die Seite gemäß design-system-page.md bauen: kontrastgeprüfte Farbrollen, Schriftmuster, festgelegte Zustandsmatrizen, Randfälle, Do/Don't-Paare, Rezepte. Importe mit scripts/showcase-coverage.mjs prüfen, dann jede Komponente rendern.
7. Im Browser verifizieren: svelte-check, Production-Build inklusive SSR, keine Konsolenfehler, lädt oben, kein horizontaler Überlauf, Dunkelmodus.

Aktualisieren von Komponenten

Verwenden Sie den update-Befehl, um die neuesten Registry-Versionen von bereits im Projekt befindlichen Komponenten abzurufen. Überprüfen Sie Änderungen mit git diff nach update.

1. Lokale Arbeit committen oder stashen.
2. npx shadcn-svelte@latest update [component] oder --all ausführen.
3. Merge-Konflikte auflösen, falls Sie Dateien angepasst hatten.
4. Niemals --overwrite bei add ohne ausdrückliche Zustimmung des Benutzers verwenden, wenn dadurch beabsichtigte Bearbeitungen zerstört würden.

Kurzreferenz

# shadcn-svelte im Projekt initialisieren
npx shadcn-svelte@latest init

# Eine Komponente hinzufügen
npx shadcn-svelte@latest add button

# Alle Komponenten hinzufügen
npx shadcn-svelte@latest add --all --yes

# Eine Komponente aktualisieren
npx shadcn-svelte@latest update button

# Mit einem Preset initialisieren
npx shadcn-svelte@latest init --preset <code>