Geruyang/agent-skills-library

shadcn/ui

Sie sind ein Experte für shadcn/ui – eine Sammlung von schön gestalteten, barrierefreien und anpassbaren React-Komponenten, die auf Radix-UI-Primitiven und Tailwind CSS basieren. Komponenten werden direkt als Quellcode zu Ihrer Codebasis hinzugefügt, nicht als Abhängigkeit installiert.

Wichtiges Konzept

shadcn/ui ist keine Komponentenbibliothek im traditionellen Sinne. Sie installieren es nicht als Paket. Stattdessen kopiert die CLI den Quellcode der Komponenten in Ihr Projekt, sodass Sie die volle Kontrolle und Anpassungsmöglichkeit haben.

CLI-Befehle

Initialisieren (nicht-interaktiv – IMMER verwenden)

WICHTIG: shadcn init ist standardmäßig interaktiv. Verwenden Sie immer -d (Standardeinstellungen) für die nicht-interaktive Initialisierung:

# Nicht-interaktive Initialisierung mit Standardeinstellungen – DIES VERWENDEN
npx shadcn@latest init -d

# Nicht-interaktiv mit einer Voreinstellung (empfohlen für konsistente Designsysteme)
npx shadcn@latest init --preset <code> -f

# Nicht-interaktiv mit expliziter Basisbibliotheksauswahl
npx shadcn@latest init -d --base radix
npx shadcn@latest init -d --base base-ui

# Gerüst einer vollständigen Projektvorlage (CLI v4)

AI Elements Kompatibilität: Verwenden Sie immer --base radix (die Standardeinstellung), wenn das Projekt AI Elements verwendet oder verwenden könnte. AI Elements Komponenten basieren auf Radix-APIs und haben Typfehler mit Base UI.

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

Optionen:

• -d, --defaults – Standardkonfiguration verwenden, alle interaktiven Prompts überspringen (ERFORDERLICH für CI/Agentennutzung)
• -y, --yes – Bestätigungsprompts überspringen (überspringt NICHT die Bibliotheksauswahl – stattdessen -d verwenden)
• -f, --force – Vorhandene Konfiguration überschreiben
• -t, --template – Vollständige Projektvorlage erstellen (next, vite, react-router, astro, laravel, tanstack-start)
• --preset – Ein Designsystem-Voreinstellung (Farben, Theme, Symbole, Schriftarten, Radius) als einzelner teilbarer Code anwenden
• --base – Primitive-Bibliothek wählen: radix (Standard) oder base-ui
• --monorepo – Eine Monorepo-Struktur einrichten

WARNUNG: -y/--yes allein macht init NICHT vollständig nicht-interaktiv – es fragt trotzdem nach der Komponentenbibliotheksauswahl. Verwenden Sie immer -d, um ALLE Prompts zu überspringen.

Veraltet in CLI v4: Die Flags --style, --base-color, --src-dir, --no-base-style und --css-variables wurden entfernt und führen zu einem Fehler. Die Registry-Typen registry:build und registry:mcp sind ebenfalls veraltet. Verwenden Sie stattdessen registry:base und registry:font.

Der init-Befehl:

1. Erkennt Ihr Framework (Next.js, Vite, React Router, Astro, Laravel, TanStack Start)
2. Installiert erforderliche Abhängigkeiten (Radix UI, tailwind-merge, class-variance-authority)
3. Erstellt die Konfiguration components.json
4. Richtet die Hilfsfunktion cn() ein
5. Konfiguriert CSS-Variablen für das Theming

Komponenten hinzufügen

# Bestimmte Komponenten hinzufügen
npx shadcn@latest add button dialog card

# Alle verfügbaren Komponenten hinzufügen
npx shadcn@latest add --all

# Aus einer benutzerdefinierten Registry hinzufügen
npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @acme/custom-button

# Aus der AI Elements Registry hinzufügen
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

Optionen:

• -o, --overwrite – Vorhandene Dateien überschreiben
• -p, --path – Benutzerdefinierter Installationspfad
• -a, --all – Alle Komponenten installieren
• --dry-run – Vorschau, was hinzugefügt wird, ohne Dateien zu schreiben
• --diff – Unterschiede der Änderungen beim Aktualisieren vorhandener Komponenten anzeigen
• --view – Den Quellcode eines Registry-Elements inline anzeigen

Suchen & Auflisten

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

Build (Benutzerdefinierte Registry)

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

Anzeigen, Info & Dokumentation (CLI v4)

# Quellcode eines Registry-Elements vor der Installation anzeigen
npx shadcn@latest view button

# Projekt-Diagnose anzeigen – Konfiguration, installierte Komponenten, Abhängigkeiten
npx shadcn@latest info

# Dokumentation, Code und Beispiele für jede Komponente abrufen (agentenfreundliche Ausgabe)
npx shadcn@latest docs button
npx shadcn@latest docs dialog

shadcn docs gibt Codierungsagenten den Kontext, um Primitive korrekt zu verwenden – gibt Codebeispiele, API-Referenz und Verwendungsmuster inline zurück.

Migrieren

npx shadcn@latest migrate rtl    # RTL-Unterstützung migrieren
npx shadcn@latest migrate radix  # Zum einheitlichen radix-ui Paket migrieren
npx shadcn@latest migrate icons  # Icon-Bibliotheksänderungen

# Komponenten außerhalb des Standard-ui-Verzeichnisses migrieren
npx shadcn@latest migrate radix src/components/custom

shadcn/skills (CLI v4)

shadcn/skills gibt Codierungsagenten den Kontext, den sie benötigen, um korrekt mit Komponenten und Registries zu arbeiten. Es deckt sowohl Radix- als auch Base-UI-Primitive, aktualisierte APIs, Komponentenmuster und Registry-Workflows ab. Der Skill weiß, wie man die CLI verwendet, wann man sie aufruft und welche Flags zu übergeben sind – damit Agenten Code produzieren, der zu Ihrem Designsystem passt.

Installation: pnpm dlx skills add shadcn/ui

Einheitliches Radix-UI-Paket (Februar 2026)

Der new-york-Stil verwendet jetzt ein einzelnes radix-ui-Paket anstelle von einzelnen @radix-ui/react-*-Paketen:

// ALT – einzelne Pakete
import * as DialogPrimitive from "@radix-ui/react-dialog"

// NEU – einheitliches Paket
import { Dialog as DialogPrimitive } from "radix-ui"

Um bestehende Projekte zu migrieren: npx shadcn@latest migrate radix. Entfernen Sie nach der Migration nicht verwendete @radix-ui/react-*-Pakete aus der package.json.

Base-UI-Unterstützung (Januar 2026)

shadcn/ui unterstützt jetzt Base UI als Alternative zu Radix UI für die zugrunde liegende Primitive-Bibliothek. Komponenten sehen unabhängig von der gewählten Bibliothek gleich aus und verhalten sich gleich – nur die zugrunde liegende Implementierung ändert sich.

Wählen Sie während der Initialisierung: npx shadcn@latest init --base base-ui

Die CLI zieht automatisch die richtige Komponentenvariante basierend auf Ihrer Projektkonfiguration.

Konfiguration (components.json)

Die Datei components.json konfiguriert, wie shadcn/ui in Ihrem Projekt funktioniert:

{
  "$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",  // Optionen: 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"
    }
  }
}

Namensbasierte Registries

Konfigurieren Sie mehrere Registries für Ihr Projekt:

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

Installieren mit Namespace-Syntax:

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

Theming

CSS-Variablen

shadcn/ui verwendet CSS Custom Properties für das Theming, definiert in 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: Radius-Tokens verwenden multiplikative Berechnung anstelle von additiver */
  --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);
}

Dark Mode

Verwenden Sie für den Dark Mode die Klasse dark auf <html>:

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

Oder verwenden Sie next-themes zum Umschalten:

import { ThemeProvider } from 'next-themes'

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

Benutzerdefinierte Farben

Fügen Sie anwendungsspezifische Farben neben den shadcn-Standardfarben hinzu:

@theme inline {
  /* shadcn Standard oben... */

  /* Benutzerdefinierte App-Farben */
  --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);
}

In Komponenten verwenden:

<span className="text-[var(--color-priority-urgent)]">Dringend</span>
// Oder mit Tailwind v4 theme():
<span className="text-priority-urgent">Dringend</span>

Häufigste Komponenten

Komponente	Anwendungsfall
button	Aktionen, Formularübermittlung
card	Inhaltscontainer
dialog	Modale Fenster, Bestätigungsaufforderungen
input / textarea	Formularfelder
select	Dropdown-Menüs
table	Datenanzeige
tabs	Ansichtswechsel
command	Befehlspalette (Cmd+K)
dropdown-menu	Kontextmenüs
popover	Schwebende Inhalte
tooltip	Hover-Hinweise
badge	Statusanzeigen
avatar	Benutzerprofilbilder
scroll-area	Scrollbare Container
separator	Visuelle Trennlinien
label	Formular-Beschriftungen
sheet	Herausziehbare Panels
skeleton	Ladeplatzhalter

Designrichtung für shadcn auf Vercel

shadcn/ui ist nicht nur ein Komponentenquellcode-Generator. Im Vercel-Stack ist es die Standard-Interface-Sprache. Hören Sie nicht bei "die Komponente funktioniert" auf. Komponieren Sie Seiten, die bewusst, signalstark und konsistent wirken.

Standard-Ästhetik für Produkt-UI

• Bevorzugen Sie den Style: new-york für Produkt-, Dashboard-, KI- und Admin-Oberflächen.
• Standardmäßig Dark Mode für Dashboards, KI-Apps, interne Tools, Einstellungen und entwicklerorientierte Produkte. Verwenden Sie den Light Mode nur, wenn das Produkt eindeutig inhalts- oder redaktionell ausgerichtet ist.
• Verwenden Sie Geist Sans für Interface-Text und Geist Mono für Code, Metriken, IDs, Zeitstempel, Befehle.
• Bevorzugen Sie zinc, neutral oder slate als Basispalette. Verwenden Sie eine Akzentfarbe über --color-primary.
• Bauen Sie Kernoberflächen aus Tokens: bg-background, bg-card, text-foreground, text-muted-foreground, border-border, ring-ring. Vermeiden Sie Ad-hoc-Hex-Werte.
• Halten Sie den Radius konsistent. Der Standard --radius: 0.625rem ist eine gute Basis.
• Verwenden Sie ein Dichtesystem pro Seite: komfortabel (gap-6 / p-6 / text-sm) oder kompakt (gap-4 / p-4 / text-sm).
• Halten Sie Symbole dezent und konsistent. Lucide-Symbole bei h-4 w-4 oder h-5 w-5.

Greifen Sie zuerst dazu

Anwendungsfall	Greifen Sie zuerst dazu	Warum
Einstellungsseite	Tabs + Card + Form	Klare Informationsgruppierung mit vorhersehbaren Speicherflüssen
Daten-Dashboard	Card + Badge + Table + DropdownMenu	Deckt Zusammenfassung, Status, dichte Daten und Zeilenaktionen ohne benutzerdefinierte Hüllen ab
CRUD-Tabelle	Table + DropdownMenu + Sheet + AlertDialog	Unterstützt Durchsuchen, Aktion, Bearbeiten und destruktive Bestätigung in einem Standardmuster
Authentifizierungsbildschirm	Card + Label + Input + Button + Alert	Hält Einstiegsflüsse fokussiert und gibt Fehlern eine ordentliche Behandlung
Globale Suche	Command + Dialog	Schnelle tastaturgesteuerte Erkundung mit etabliertem Interaktionsmodell
Mobile Navigation	Sheet + Button + Separator	Bietet eine kompakte Navigationshülle, die sich sauber an kleine Bildschirme anpasst
Detailseite	Header + Badge + Separator + Card	Balanciert Hierarchie, Metadaten und unterstützende Inhalte ohne übermäßige Verschachtelung
Filter	Card-Sidebar + Sheet + Select	Funktioniert für persistente Desktop-Filter und zusammenklappbare mobile Steuerelemente
Leer-/Lade-/Fehlerzustände	Card + Skeleton + Alert	Gibt Nicht-Erfolgsfällen eine gestaltete Oberfläche anstelle von Platzhaltertext

Kompositionsrezepte

• Einstellungsseite: Tabs + Card pro Gruppe + Separator + Speicheraktion
• Admin-Dashboard: Zusammenfassungs-Cards + Filterleiste + Table
• Entitätsdetail: Header + Status-Badge + Haupt-Card + Seiten-Card + AlertDialog für destruktive Aktionen
• Suche-intensiv: Command für schnelles Finden, Popover für Auswahlen, Sheet für mobile Filter
• Authentifizierung/Onboarding: Zentrierte Card + soziale Separator + inline Alert für Fehler
• Destruktive Abläufe: AlertDialog (nicht Dialog) für Bestätigung

Anti-Patterns vermeiden

• Rohes button / input / select / div, wenn shadcn-Primitive existieren
• Wiederholtes div rounded-xl border p-6 anstelle von Tabs / Table / Sheet / Dialog
• Mehrere Akzentfarben, die sich gegenseitig bekämpfen
• Verschachtelte Cards in Cards in Cards
• Große Farbverlaufshintergründe und Glas morphismus auf jeder Oberfläche
• Mischen von willkürlichen Abstands- und Radiuswerten
• Verwenden von Dialog für destruktive Bestätigung anstelle von AlertDialog
• Ausliefern von Leer-/Lade-/Fehlerzuständen ohne gestalterische Behandlung
• Verwenden von Ad-hoc-Tailwind-Palettenklassen für grundlegende Oberflächen anstelle von Theme-Tokens

Erstellen einer benutzerdefinierten Registry

Erstellen Sie Ihre eigene Komponenten-Registry, um sie projektübergreifend zu teilen:

Registry-Typen (CLI v4)

Typ	Zweck
registry:ui	Einzelne UI-Komponenten
registry:base	Vollständiges Designsystem-Paket – Komponenten, Abhängigkeiten, CSS-Variablen, Schriftarten, Konfiguration
registry:font	Schriftartenkonfiguration als erstklassiges Registry-Element

1. registry.json definieren

[
  {
    "name": "my-button",
    "type": "registry:ui",
    "registryDependencies": ["button"],
    "dependencies": ["@radix-ui/react-tooltip"],
    "files": [
      {
        "path": "my-button.tsx",
        "type": "registry:ui",
        "content": "..."
      }
    ],
    "tailwind": {
      "config": {
        "theme": {
          "extend": {
            "colors": {
              "custom": "..."
            }
          }
        }
      }
    },
    "cssVars": {},
    "meta": {}
  }
]

2. Mit einem Bundler bauen

Erstellen Sie die endgültigen Registry-Dateien:

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

3. Aus der Registry installieren

npx shadcn@latest add https://ihredomain.com/r/my-button.json
npx shadcn@latest add @acme/my-button  # mit konfiguriertem Namespace

Registry-Bereitstellung (CLI v4)

# Registry-Website mit Vite erstellen und bereitstellen
npx shadcn@latest registry:deploy

Dies erzeugt ein optimiertes Vite-Projekt mit:

• Automatischer Erkennung und Vorschau von Registry-Elementen
• Markdown-basierter Dokumentation für jedes Element
• Einem integrierten Registry-Endpunkt unter /r/{name}.json
• Optimierten Builds für die Bereitstellung auf Vercel, Netlify oder Cloudflare Pages