inkeep/agents

shadcn/ui

Ein Framework zum Erstellen von UI-Komponenten und Designsystemen. Komponenten werden als Quellcode über die CLI in das Projekt des Benutzers eingefügt.

WICHTIG: Führen Sie alle CLI-Befehle mit dem Paket-Manager des Projekts aus: npx shadcn@latest, pnpm dlx shadcn@latest oder bunx --bun shadcn@latest – basierend auf dem packageManager des Projekts. Die folgenden Beispiele verwenden npx shadcn@latest, aber ersetzen Sie den korrekten Runner für das Projekt.

Aktueller Projektkontext

!`npx shadcn@latest info --json`

Das obige JSON enthält die Projektkonfiguration und installierte Komponenten. Verwenden Sie npx shadcn@latest docs <component>, um Dokumentations- und Beispiel-URLs für jede Komponente zu erhalten.

Prinzipien

1. Verwenden Sie zuerst vorhandene Komponenten. Überprüfen Sie mit npx shadcn@latest search die Registries, bevor Sie benutzerdefiniertes UI schreiben. Überprüfen Sie auch Community-Registries.
2. Kombinieren, nicht neu erfinden. Einstellungsseite = Tabs + Card + Formularelemente. Dashboard = Sidebar + Card + Chart + Table.
3. Verwenden Sie eingebaute Varianten vor benutzerdefinierten Styles. variant="outline", size="sm" usw.
4. Verwenden Sie semantische Farben. bg-primary, text-muted-foreground – niemals rohe Werte wie bg-blue-500.

Kritische Regeln

Diese Regeln werden immer durchgesetzt. Jede enthält einen Link zu einer Datei mit inkorrekten/korrekten Code-Paaren.

Styling & Tailwind → styling.md

• className 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.
• Kein manuelles dark:-Farb-Override. 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 usw. kümmern sich selbst um ihre Stapelung.

Formulare & Eingaben → forms.md

• Formulare verwenden FieldGroup + Field. Verwenden Sie niemals rohes div mit space-y-* oder grid gap-* für das Formular-Layout.
• InputGroup verwendet InputGroupInput/InputGroupTextarea. Niemals rohes Input/Textarea innerhalb von InputGroup.
• Schaltflächen innerhalb von Eingaben verwenden InputGroup + InputGroupAddon.
• Optionssätze (2–7 Auswahlmöglichkeiten) verwenden ToggleGroup. Verwenden Sie keine Schleife von Button mit manuellem aktivem Zustand.
• FieldSet + FieldLegend zum Gruppieren verwandter Checkboxen/Radios. Verwenden Sie kein div mit einer Ü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

• Items befinden sich immer innerhalb ihrer Gruppe. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
• Verwenden Sie asChild (radix) oder render (base) für benutzerdefinierte Trigger. Überprüfen Sie das base-Feld aus npx shadcn@latest info. → base-vs-radix.md
• Dialog, Sheet und Drawer benötigen immer einen Titel. DialogTitle, SheetTitle, DrawerTitle sind für die Barrierefreiheit erforderlich. Verwenden Sie className="sr-only", wenn visuell versteckt.
• Verwenden Sie die vollständige Card-Komposition. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Werfen Sie nicht alles in CardContent.
• Button hat kein isPending/isLoading. Kombinieren Sie mit Spinner + data-icon + disabled.
• TabsTrigger muss innerhalb von TabsList sein. Rendern Sie Trigger niemals direkt in Tabs.
• Avatar benötigt immer AvatarFallback. Für den Fall, dass das Bild nicht geladen werden kann.

Komponenten verwenden, kein benutzerdefiniertes Markup → composition.md

• Verwenden Sie vorhandene Komponenten vor benutzerdefiniertem Markup. Überprüfen Sie, ob eine Komponente existiert, bevor Sie ein gestyltes div schreiben.
• Hinweise verwenden Alert. Bauen Sie keine benutzerdefinierten gestylten Divs.
• Leere Zustände verwenden Empty. Bauen Sie kein benutzerdefiniertes Leerzustands-Markup.
• Toast via sonner. Verwenden Sie toast() aus sonner.
• Verwenden Sie Separator anstelle von <hr> oder <div className="border-t">.
• Verwenden Sie Skeleton für Ladeplatzhalter. Keine benutzerdefinierten animate-pulse-Divs.
• Verwenden Sie Badge anstelle von benutzerdefinierten gestylten Spans.

Icons → icons.md

• Icons in Button verwenden data-icon. data-icon="inline-start" oder data-icon="inline-end" auf dem Icon.
• Keine Größenklassen für Icons innerhalb von Komponenten. Komponenten kümmern sich um die Icon-Größe über CSS. Kein size-4 oder w-4 h-4.
• Icons als Objekte übergeben, nicht als String-Schlüssel. icon={CheckIcon}, keine String-Nachschlage.

CLI

• Dekodieren oder holen Sie Preset-Codes niemals manuell. Übergeben Sie sie direkt an npx shadcn@latest init --preset <code>.

Wichtige Muster

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

// Formular-Layout: FieldGroup + Field, nicht div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">E-Mail</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validierung: data-invalid auf Field, aria-invalid auf dem Steuerelement.
<Field data-invalid>
  <FieldLabel>E-Mail</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Ungültige E-Mail.</FieldDescription>
</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 className="flex flex-col gap-4">  // korrekt
<div className="space-y-4">           // falsch

// Gleiche Abmessungen: size-*, nicht w-* h-*.
<Avatar className="size-10">   // korrekt
<Avatar className="w-10 h-10"> // falsch

// Statusfarben: Badge-Varianten oder semantische Tokens, keine Rohfarben.
<Badge variant="secondary">+20.1%</Badge>    // korrekt
<span className="text-emerald-600">+20.1%</span> // falsch

Komponentenauswahl

Bedarf	Verwenden
Schaltfläche/Aktion	Button mit geeigneter Variant
Formulareingaben	Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider
Umschalten zwischen 2–5 Optionen	ToggleGroup + ToggleGroupItem
Datenanzeige	Table, Card, Badge, Avatar
Navigation	Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination
Overlays	Dialog (Modal), Sheet (Seitenpanel), Drawer (unteres Panel), AlertDialog (Bestätigung)
Feedback	sonner (Toast), Alert, Progress, Skeleton, Spinner
Befehlspalette	Command innerhalb von Dialog
Diagramme	Chart (umhüllt Recharts)
Layout	Card, Separator, Resizable, ScrollArea, Accordion, Collapsible
Leere Zustände	Empty
Menüs	DropdownMenu, ContextMenu, Menubar
Tooltips/Info	Tooltip, HoverCard, Popover

Wichtige Felder

Der eingefügte Projektkontext enthält diese wichtigen Felder:

• aliases → verwenden Sie das tatsächliche Alias-Präfix für Imports (z. B. @/, ~/), niemals hartcodieren.
• isRSC → wenn true, benötigen Komponenten, die useState, useEffect, Event-Handler oder Browser-APIs verwenden, "use client" am Anfang der Datei. Beachten Sie dieses Feld immer, wenn Sie die Direktive empfehlen.
• tailwindVersion → "v4" verwendet @theme inline-Blöcke; "v3" verwendet tailwind.config.js.
• tailwindCssFile → die globale CSS-Datei, in der benutzerdefinierte CSS-Variablen definiert sind. Bearbeiten Sie immer diese Datei, erstellen Sie keine neue.
• style → visuelle Behandlung der Komponente (z. B. nova, vega).
• base → primitive Bibliothek (radix oder base). Beeinflusst die Komponenten-APIs und verfügbaren Props.
• iconLibrary → bestimmt die Icon-Imports. Verwenden Sie lucide-react für lucide, @tabler/icons-react für tabler usw. Gehen Sie niemals von lucide-react aus.
• resolvedPaths → genaue Dateisystem-Ziele für Komponenten, Utilities, Hooks usw.
• framework → Routing- und Dateikonventionen (z. B. Next.js App Router vs. Vite SPA).
• packageManager → verwenden Sie dies für alle nicht-shadcn-Abhängigkeitsinstallationen (z. B. pnpm add date-fns vs. npm install date-fns).

Siehe cli.md — info-Befehl für die vollständige Feldreferenz.

Komponentendokumentation, Beispiele und Verwendung

Führen Sie npx shadcn@latest docs <component> aus, um die URLs für die Dokumentation, Beispiele und API-Referenz einer Komponente zu erhalten. Holen Sie diese URLs ab, um den tatsächlichen Inhalt zu erhalten.

npx shadcn@latest docs button dialog select

Führen Sie beim Erstellen, Reparieren, Debuggen oder Verwenden einer Komponente immer npx shadcn@latest docs aus und holen Sie die URLs ab. Dies stellt sicher, dass Sie mit der korrekten API und den richtigen Verwendungsmustern arbeiten, anstatt zu raten.

Arbeitsablauf

1. Projektkontext abrufen — bereits oben eingefügt. Führen Sie npx shadcn@latest info erneut aus, wenn Sie die Daten aktualisieren müssen.
2. Installierte Komponenten zuerst prüfen — bevor Sie add ausführen, überprüfen Sie immer die components-Liste aus dem Projektkontext oder listen Sie das resolvedPaths.ui-Verzeichnis auf. Importieren Sie keine Komponenten, die nicht hinzugefügt wurden, und fügen Sie keine bereits installierten erneut hinzu.
3. Komponenten finden — npx shadcn@latest search.
4. Dokumentation und Beispiele abrufen — führen Sie npx shadcn@latest docs <component> aus, um URLs zu erhalten, und holen Sie diese dann ab. Verwenden Sie npx shadcn@latest view, um Registry-Elemente zu durchsuchen, die Sie nicht installiert haben. Verwenden Sie npx shadcn@latest add --diff, um Änderungen an installierten Komponenten in der Vorschau anzuzeigen.
5. Installieren oder aktualisieren — npx shadcn@latest add. Verwenden Sie beim Aktualisieren vorhandener Komponenten --dry-run und --diff, um Änderungen zuerst in der Vorschau anzuzeigen (siehe Komponenten aktualisieren unten).
6. Imports in Drittanbieter-Komponenten korrigieren — Nach dem Hinzufügen von Komponenten aus Community-Registries (z. B. @bundui, @magicui) überprüfen Sie die hinzugefügten Nicht-UI-Dateien auf hartcodierte Importpfade wie @/components/ui/.... Diese stimmen möglicherweise nicht mit den tatsächlichen Aliasen des Projekts überein. Verwenden Sie npx shadcn@latest info, um den korrekten ui-Alias zu erhalten (z. B. @workspace/ui/components) und schreiben Sie die Imports entsprechend um. Die CLI schreibt Imports für ihre eigenen UI-Dateien um, aber Drittanbieter-Registry-Komponenten können Standardpfade verwenden, die nicht zum Projekt passen.
7. Hinzugefügte Komponenten überprüfen — Nachdem Sie eine Komponente oder einen Block aus einer beliebigen Registry hinzugefügt haben, lesen Sie immer die hinzugefügten Dateien und überprüfen Sie, ob sie korrekt sind. Überprüfen Sie auf fehlende Unterkomponenten (z. B. SelectItem ohne SelectGroup), fehlende Imports, falsche Komposition oder Verstöße gegen die kritischen Regeln. Ersetzen Sie auch alle Icon-Imports durch die iconLibrary des Projekts aus dem Projektkontext (z. B. wenn das Registry-Element lucide-react verwendet, aber das Projekt hugeicons verwendet, tauschen Sie die Imports und Icon-Namen entsprechend aus). Beheben Sie alle Probleme, bevor Sie fortfahren.
8. Registry muss explizit sein — Wenn der Benutzer darum bittet, einen Block oder eine Komponente hinzuzufügen, raten Sie nicht die Registry. Wenn keine Registry angegeben ist (z. B. sagt der Benutzer "Füge einen Login-Block hinzu" ohne @shadcn, @tailark usw. anzugeben), fragen Sie, welche Registry verwendet werden soll. Verwenden Sie niemals standardmäßig eine Registry im Namen des Benutzers.
9. Presets wechseln — Fragen Sie zuerst den Benutzer: Neu installieren, Zusammenführen oder Überspringen?
   • Neu installieren: npx shadcn@latest init --preset <code> --force --reinstall. Überschreibt alle Komponenten.
   • Zusammenführen: npx shadcn@latest init --preset <code> --force --no-reinstall, führen Sie dann npx shadcn@latest info aus, um installierte Komponenten aufzulisten, und führen Sie dann für jede installierte Komponente --dry-run und --diff aus, um sie einzeln intelligent zusammenzuführen.
   • Überspringen: npx shadcn@latest init --preset <code> --force --no-reinstall. Aktualisiert nur Konfiguration und CSS, lässt Komponenten unverändert.
   • Wichtig: Führen Sie Preset-Befehle immer innerhalb des Projektverzeichnisses des Benutzers aus. Die CLI behält automatisch die aktuelle Basis (base vs. radix) aus components.json bei. Wenn Sie ein temporäres Verzeichnis verwenden müssen (z. B. für --dry-run-Vergleiche), übergeben Sie explizit --base <aktuelle-basis> – Preset-Codes kodieren die Basis nicht.

Komponenten aktualisieren

Wenn der Benutzer darum bittet, eine Komponente aus dem Upstream zu aktualisieren, während seine lokalen Änderungen beibehalten werden, verwenden Sie --dry-run und --diff, um intelligent zusammenzuführen. HOLEN SIE NIEMALS rohe Dateien manuell von GitHub – verwenden Sie immer die CLI.

1. Führen Sie npx shadcn@latest add <component> --dry-run aus, um alle Dateien zu sehen, die betroffen wären.
2. Führen Sie für jede Datei npx shadcn@latest add <component> --diff <file> aus, um zu sehen, was sich im Upstream gegenüber lokal geändert hat.
3. Entscheiden Sie pro Datei basierend auf dem Diff:
   • Keine lokalen Änderungen → sicher zu überschreiben.
   • Hat lokale Änderungen → lesen Sie die lokale Datei, analysieren Sie das Diff und wenden Sie Upstream-Änderungen an, während lokale Modifikationen beibehalten werden.
   • Der Benutzer sagt "Aktualisiere einfach alles" → verwenden Sie --overwrite, aber bestätigen Sie zuerst.
4. Verwenden Sie NIEMALS --overwrite ohne die ausdrückliche Zustimmung des Benutzers.

Kurzreferenz

# Ein neues Projekt erstellen.
npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite

# Ein Monorepo-Projekt erstellen.
npx shadcn@latest init --name my-app --preset base-nova --monorepo
npx shadcn@latest init --name my-app --preset base-

…

[gekürzt für Übersetzung]