Vercels UI SDK mit Tailwind stylen: data-slot, State-Attribute und Enter- und Exit-Animationen

Wie Styling in UI SDK funktioniert

UI SDK hat drei Schichten. @ui-sdk/core enthält Behaviors wie Roving Focus, Typeahead und Popups. Ein Primitive, geschrieben mit definePrimitive, verbindet Behaviors mit State und benannten Slots. Ein Framework-Adapter wie @ui-sdk/react rendert jeden Slot als Part, den du importierst, etwa SelectTrigger oder RatingItem.

Deine Styles setzen über drei Hooks an den Parts an:

• data-slot: Jeder Part hat eins, etwa data-slot="select-item". Es benennt den Part für globales CSS und für Agenten.
• State-Attribute: data-open, data-highlighted, data-selected, data-disabled und so weiter. Die meisten sind einfach vorhanden oder nicht. Manche tragen einen Wert, etwa data-side="top" oder data-orientation="vertical".
• CSS-Variablen: Werte, die eine Klasse nicht ausdrücken kann, etwa --anchor-width an einem Popup oder --rating-fill an einem Stern.

className und style können auch Funktionen des Zustands eines Parts sein, so wie bei Base UI. Mit Tailwind brauchst du das selten, weil v4 für jedes Data-Attribut eine Variante hat: data-highlighted:bg-accent greift, solange data-highlighted vorhanden ist.

Die Doku bittet dich, diese Attribute zu stylen statt generierter IDs, die sich ändern können. Jede Komponentenseite hat einen Abschnitt Styling und einen Abschnitt Data Attributes, die genau auflisten, was jeder Part bereitstellt. Diese Liste ist der Vertrag.

Tailwind v4 und den ui-sdk-Layer einrichten

UI SDK braucht ein wenig eigenes CSS, zum Beispiel um ein geschlossenes Popup versteckt zu halten. Dieses CSS fügt es zur Laufzeit in einem Cascade Layer namens ui-sdk ein. Deklariere den Layer zuerst in deinem globalen Stylesheet, über dem Tailwind-Import, damit deine Styles gewinnen, egal wo die Seite das Runtime-CSS einfügt:

@layer ui-sdk;
@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
}

@theme inline {
  --color-background: var(--background);
  --color-popover: var(--popover);
  --color-accent: var(--accent);
  --color-muted: var(--muted);
  --color-ring: var(--ring);
}

Die vollständige Token-Liste ist die, die shadcn/ui generiert, mit einem .dark-Block, der dieselben Namen überschreibt. Ich habe sie hier gekürzt. Nichts in UI SDK liest diese Tokens. Sie zählen nur, weil die Klassen unten sie nutzen, und das heißt, eine UI-SDK-Komponente und eine shadcn/ui-Komponente können sich ein Theme teilen.

Es gibt keinen Provider zum Mounten und kein Stylesheet zum Importieren aus dem Paket. Wenn du eine Content Security Policy ohne 'unsafe-inline' für Styles nutzt, lies den CSP-Abschnitt im Guide Styling and Animation, denn das Runtime-CSS braucht eine Nonce oder Constructed Stylesheets.

Select: State-Attribute und eine animierte Liste

Ein Select hat ein Label, einen Trigger, einen Wert, ein Content-Popup und Items. Dieses hier zeigt eine Rollenauswahl mit einem Haken am gewählten Item und einem kurzen Skalieren und Einblenden beim Öffnen und Schließen der Liste:

import {
  Select,
  SelectContent,
  SelectItem,
  SelectItemIndicator,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "@ui-sdk/react/select"

const roles = [
  { value: "viewer", label: "Viewer" },
  { value: "editor", label: "Editor" },
  { value: "admin", label: "Admin" },
]

function RoleSelect() {
  return (
    <Select defaultValue="editor" items={roles}>
      <SelectLabel className="text-sm font-medium">Role</SelectLabel>
      <SelectTrigger className="mt-2 flex h-9 w-48 items-center justify-between rounded-md border border-input bg-background px-3 text-sm outline-none focus-visible:ring-3 focus-visible:ring-ring/50 data-open:bg-accent data-placeholder:text-muted-foreground">
        <SelectValue />
      </SelectTrigger>
      <SelectContent
        sideOffset={4}
        className="min-w-(--anchor-width) origin-(--transform-origin) rounded-lg border border-border bg-popover p-1 text-popover-foreground shadow-md transition-[opacity,scale] duration-150 ease-out data-starting-style:scale-95 data-starting-style:opacity-0 data-ending-style:scale-95 data-ending-style:opacity-0 motion-reduce:transition-none"
      >
        {roles.map((role) => (
          <SelectItem
            key={role.value}
            value={role.value}
            className="flex h-8 cursor-default items-center justify-between gap-2 rounded-md px-2 text-sm outline-none data-highlighted:bg-accent data-highlighted:text-accent-foreground"
          >
            {role.label}
            <SelectItemIndicator className="text-xs">✓</SelectItemIndicator>
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  )
}

Was jede Klasse liest:

• data-open:bg-accent hält den Trigger eingefärbt, solange die Liste offen ist.
• data-placeholder: stylt den Trigger, solange nichts gewählt ist. Mit einem Standardwert greift es hier nie, aber es kostet nichts, es zu behalten.
• min-w-(--anchor-width) macht die Liste mindestens so breit wie den Trigger. Tailwind v4 schreibt einen CSS-Variablenwert als (--name), ohne var().
• origin-(--transform-origin) skaliert die Liste von der Seite aus, an der sie sich öffnet. UI SDK setzt diese Variable am Content.
• data-highlighted: markiert das Item unter dem Zeiger oder dem Tastaturfokus. Gewählte Items bekommen data-selected, und SelectItemIndicator rendert nur in einem gewählten Item.

items zu übergeben ist optional, aber die Doku empfiehlt es: Der Trigger kann das gewählte Label zeigen, bevor die Liste rendert, und die Agent-Bridge kann die Optionen lesen, während die Liste geschlossen ist.

Wenn du Tastatur-Hervorhebung von Zeiger-Hervorhebung unterscheiden musst: Der Content hat data-modality="keyboard" oder "pointer". Ein Fokusring, der nur für Tastaturnutzer erscheint, ist in-data-[modality=keyboard]:data-highlighted:ring-2 am Item.

Der Lebenszyklus eines Popups

Die Animation oben nutzt zwei Attribute, die es nur während einer Transition gibt. Der Content bekommt für seinen ersten Frame data-starting-style, damit eine Transition einen Startzustand hat. Beim Schließen bekommt er data-ending-style und bleibt gemountet, bis die Transition oder Animation fertig ist.

Drei Details sorgen dafür, dass das in der Praxis funktioniert.

Erstens: Leg Exit-Styles auf data-ending-style, nicht auf data-closed. data-closed beschreibt den Zustand, aber die Doku sagt klar, dass es das Element für einen Exit nicht im DOM hält.

Zweitens: Popups in UI SDK nutzen den Top Layer des Browsers. Der Content rendert an Ort und Stelle, als Kind der Komponente, und der Browser hebt ihn über die Seite. In meiner Test-App trug der offene Content popover="manual" und passte auf :popover-open. Es gibt keinen Portal- oder Positioner-Part, und z-index entscheidet nicht darüber, ob er über einem Sticky Header liegt.

Drittens: Wenn eine Animationsbibliothek wie Motion geschlossenen Content im DOM braucht, setz keepMounted. onOpenChangeComplete läuft, nachdem das Öffnen oder Schließen fertig ist, einschließlich der Animation.

Popover: ein schnellerer Exit als Enter

Ein- und Ausblenden brauchen nicht dasselbe Timing. Ein Popover, das über 200ms hereingleitet und über 100ms ausblendet, wirkt schneller als eins, das in beide Richtungen 200ms braucht. Weil der Exit sein eigenes Attribut hat, kann Tailwind ihm eine eigene Dauer geben:

import {
  Popover,
  PopoverClose,
  PopoverContent,
  PopoverDescription,
  PopoverTitle,
  PopoverTrigger,
} from "@ui-sdk/react/popover"

function ShareProject() {
  return (
    <Popover>
      <PopoverTrigger className="h-9 rounded-md border border-input bg-background px-3 text-sm font-medium outline-none hover:bg-accent focus-visible:ring-3 focus-visible:ring-ring/50 data-open:bg-accent">
        Share
      </PopoverTrigger>
      <PopoverContent
        side="bottom"
        align="start"
        sideOffset={8}
        className="w-72 origin-(--transform-origin) rounded-lg border border-border bg-popover p-4 text-popover-foreground shadow-md transition-[opacity,scale,translate] duration-200 ease-out data-starting-style:-translate-y-1 data-starting-style:scale-95 data-starting-style:opacity-0 data-ending-style:scale-95 data-ending-style:opacity-0 data-ending-style:duration-100 motion-reduce:transition-none"
      >
        <PopoverTitle className="text-sm font-medium">
          Share project
        </PopoverTitle>
        <PopoverDescription className="mt-1 text-sm text-muted-foreground">
          Anyone with the link can view Atlas.
        </PopoverDescription>
        <PopoverClose className="mt-3 h-8 rounded-md bg-primary px-3 text-sm font-medium text-primary-foreground">
          Copy link
        </PopoverClose>
      </PopoverContent>
    </Popover>
  )
}

Das Enter geht von -translate-y-1, scale-95 und opacity-0 in den Ruhezustand. Der Exit skaliert und blendet nur aus, mit data-ending-style:duration-100. motion-reduce:transition-none schaltet beides für Leute ab, die weniger Bewegung wollen, und das Popover öffnet und schließt trotzdem.

PopoverTitle und PopoverDescription zählen nicht nur fürs Aussehen. Der Content ist ein Dialog, und diese Parts geben ihm einen barrierefreien Namen und eine Beschreibung. Ohne Titel gib dem Content ein aria-label.

Rating: style die Füllung, nicht die Sterne

Ein Rating ist eine Radio-Gruppe, die als Sterne gezeichnet wird. Du renderst ein RatingItem, und das Rating wiederholt es für jeden Stern. Jedes Item meldet in --rating-fill von 0 bis 1, wie viel seines Sterns die angezeigte Bewertung abdeckt. data-filled markiert ganze Sterne, data-partial den Stern, in dem eine halbe Bewertung endet, und data-highlighted die Sterne bis zu der Bewertung, die der Zeiger als Vorschau zeigt.

Mit --rating-fill entstehen halbe Sterne aus einem Verlauf statt aus zwei Icons:

import { Rating, RatingItem } from "@ui-sdk/react/rating"

const star =
  "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 2l3.1 6.3 6.9 1-5 4.9 1.2 6.8L12 17.8 5.8 21l1.2-6.8-5-4.9 6.9-1z'/%3E%3C/svg%3E\")"

function StayRating() {
  return (
    <Rating
      aria-label="How was your stay?"
      step={0.5}
      defaultValue={3.5}
      className="inline-flex gap-1"
    >
      <RatingItem className="size-7 rounded-sm [&_button]:outline-none has-focus-visible:outline-2 has-focus-visible:outline-offset-2 has-focus-visible:outline-ring">
        <span
          aria-hidden="true"
          style={{ maskImage: star, WebkitMaskImage: star }}
          className="absolute inset-0 bg-[linear-gradient(to_right,var(--color-amber-400)_calc(var(--rating-fill)*100%),var(--color-muted)_0)] in-data-highlighted:bg-[linear-gradient(to_right,var(--color-amber-300)_calc(var(--rating-fill)*100%),var(--color-muted)_0)]"
        />
      </RatingItem>
    </Rating>
  )
}

Mit step={0.5} ist jeder halbe Stern ein eigenes Radio, benannt „3.5 stars“ und so weiter. Die Radios sind Buttons, die das Rating per Inline-Styles über dein Icon legt, und das Item bekommt auf dieselbe Weise position: relative. Deshalb kann der Span absolute inset-0 ohne zusätzliche Klasse nutzen.

Die Tastatur funktioniert, ohne dass du etwas tun musst. Den angehakten Stern zu fokussieren und die Pfeiltaste nach rechts zu drücken, hob die Bewertung in meinem Test von 3,5 auf 4, und die Füllung folgte.

Halte die Maske vom fokussierbaren Item fern

Meine erste Version legte die Sternmaske direkt auf RatingItem. Das sah richtig aus, bis ich per Tab hineinging: Eine CSS-Maske schneidet alles ab, was das Element zeichnet, auch Outlines, also verschwand der Fokusring. Die Maske auf einen inneren Span zu verschieben, hat es behoben. Das Item behält seine abgerundete Outline über has-focus-visible:, und [&_button]:outline-none blendet den Standardring des Browsers am halb breiten Radio-Button darin aus, der sonst einen dünnen Kasten um einen halben Stern zeichnet.

Das ist nicht spezifisch für UI SDK, aber Masken in Icon-Form sind ein üblicher Weg, Bewertungen zu zeichnen, also lohnt es sich, das vor dem Release mit der Tastatur zu prüfen.

Color Picker: CSS-Variablen übernehmen das Zeichnen

Der Color Picker stellt von den vier die meisten Variablen bereit. Jeder Part schreibt die aktuelle Farbe als --color-picker-color. Die Fläche bekommt --color-area-background, eine Reihe von Verläufen für ihre zwei Kanäle, und jeder Slider bekommt --color-slider-background. Deine Klassen geben den Parts eine Größe und nutzen diese Variablen als Hintergrund.

import {
  ColorPicker,
  ColorPickerArea,
  ColorPickerAreaThumb,
  ColorPickerInput,
  ColorPickerSlider,
  ColorPickerSliderThumb,
  ColorPickerSwatch,
} from "@ui-sdk/react/color-picker"
import { Popover, PopoverContent, PopoverTrigger } from "@ui-sdk/react/popover"

const thumb =
  "absolute size-4 -translate-1/2 rounded-full border-2 border-white bg-(--color-picker-color) shadow outline-none ring-1 ring-black/20 focus-visible:ring-3 focus-visible:ring-ring"

function BrandColor() {
  return (
    <ColorPicker aria-label="Brand color" defaultValue="#6366f1">
      <Popover>
        <PopoverTrigger
          aria-label="Brand color"
          className="flex h-9 items-center gap-2 rounded-md border border-input bg-background pr-3 pl-1.5 text-sm outline-none focus-visible:ring-3 focus-visible:ring-ring/50"
        >
          <ColorPickerSwatch className="size-6 rounded-sm bg-(--color-picker-color) ring-1 ring-black/10 ring-inset" />
          Brand color
        </PopoverTrigger>
        <PopoverContent
          sideOffset={8}
          className="flex w-60 origin-(--transform-origin) flex-col gap-3 rounded-lg border border-border bg-popover p-3 shadow-md transition-[opacity,scale] duration-150 ease-out data-starting-style:scale-95 data-starting-style:opacity-0 data-ending-style:scale-95 data-ending-style:opacity-0 motion-reduce:transition-none"
        >
          <ColorPickerArea className="relative h-36 rounded-md bg-(image:--color-area-background)">
            <ColorPickerAreaThumb className={thumb} />
          </ColorPickerArea>
          <ColorPickerSlider
            channel="hue"
            className="relative h-3 rounded-full bg-(image:--color-slider-background)"
          >
            <ColorPickerSliderThumb className={`${thumb} top-1/2`} />
          </ColorPickerSlider>
          <ColorPickerInput
            aria-label="Hex"
            className="h-8 rounded-md border border-input bg-background px-2 font-mono text-sm outline-none focus-visible:ring-3 focus-visible:ring-ring/50"
          />
        </PopoverContent>
      </Popover>
    </ColorPicker>
  )
}

Was du wissen solltest, bevor du das kopierst:

• Das Popover kommt in den ColorPicker. Die Parts im Popup und das Farbfeld im Trigger bearbeiten und zeigen dann dieselbe Farbe.
• bg-(image:--color-area-background) ist der Typhinweis von Tailwind v4. Ohne image: würde Tailwind die Variable als Farbe lesen, und Verläufe würden nicht gemalt.
• Die Thumbs bekommen position: absolute und ihre Position in Prozent als Inline-Styles. Deine Klasse muss jeden Thumb nur auf seinem Punkt zentrieren, und genau das macht -translate-1/2. Der Slider-Thumb braucht außerdem top-1/2, weil sein Inline-Style nur die Position entlang der Spur setzt.
• Das Farbfeld ist für Screenreader ein Bild, benannt nach der Farbe. In meinem Build wurde es für #6366f1 als „vivid purple“ angesagt. Benenne den Trigger selbst, denn der sichtbare Text allein sagt vielleicht nicht, wofür die Farbe ist.
• Für OKLCH fügst du ColorPickerAreaCanvas in die Fläche ein. Ein Verlauf kann die Gamut-Grenze von OKLCH nicht zeichnen, deshalb malt das Canvas sie Pixel für Pixel.

Styling über data-slot in reinem CSS

Utility-Klassen an jedem Part sind eine Möglichkeit. Die andere ist ein Stylesheet, das auf data-slot basiert. Das hält das Markup kurz und bündelt das Aussehen einer Komponente an einer Stelle:

[data-slot="select-item"] {
  display: flex;
  height: 2rem;
  align-items: center;
  border-radius: calc(var(--radius) - 2px);
  padding-inline: 0.5rem;
}

[data-slot="select-item"][data-highlighted] {
  background: var(--accent);
  color: var(--accent-foreground);
}

[data-slot="select-content"][data-starting-style],
[data-slot="select-content"][data-ending-style] {
  opacity: 0;
  scale: 0.95;
}

Die UI-SDK-Doku stylt ihre eigenen Demos ebenfalls mit reinem CSS. Das funktioniert, weil data-slot zu den Attributen gehört, die ein Part immer behält: Die Doku führt es neben Rollen und tabindex als verwaltete Attribute, die deine Props nicht überschreiben können. In einem Projekt im shadcn/ui-Stil, in dem jede Komponentendatei die Parts umschließt und eigene Klassen hinzufügt, sind Utilities an den Parts meist einfacher. Ein Theme in reinem CSS lässt sich leichter komplett austauschen.

Klassen im shadcn-Stil von Radix oder Base UI übernehmen

Wenn deine Komponenten von shadcn/ui kommen, lassen sich die meisten Klassen übernehmen. Die Unterschiede liegen in ein paar Attributnamen und in der Popup-Struktur.

Wenn du von Base UI kommst, sind die Attributnamen für Popups dieselben, die Klassen-Strings lassen sich also größtenteils übernehmen. Du löschst die Wrapper Portal und Positioner und verschiebst Platzierungs-Props wie side, align und sideOffset auf den Content. Wenn du von Radix kommst, ersetzt du data-[state=…]-Varianten und Keyframe-Animationen durch die Starting- und Ending-Attribute. So oder so: Prüfe die Liste der Data Attributes jeder Komponente, denn Namen, die gleich aussehen, können sich unterscheiden. Das Select von Base UI hat zum Beispiel seinen eigenen Attributsatz, und das von UI SDK auch.

Den Vergleich der drei Bibliotheken als Ganzes, über das Styling hinaus, findest du in UI SDK vs Base UI vs Radix.

Woran ich hängen geblieben bin

Eine kurze Liste, damit du es nicht wiederholst:

• data-closed für einen Exit stylen. Nichts wird animiert. Nutze data-ending-style.
• @layer ui-sdk; vergessen. Steht es nicht zuerst, kann das Runtime-CSS in der Kaskade nach deinen Styles landen.
• Masken auf fokussierbaren Parts. Sie schneiden den Fokusrahmen ab. Maskiere ein inneres Element.
• --available-height in einem Kind lesen. Laut Doku wird es nicht vererbt. Kopiere es am Popup, zum Beispiel [--list-height:var(--available-height)], und lies weiter unten max-h-(--list-height).
• Verläufe aus Variablen. Nutze bg-(image:--name), nicht bg-(--name).

UI SDK ist eine Beta, zum Zeitpunkt des Schreibens einen Tag alt. Alles hier hat in 0.1.0-beta.1 wie dokumentiert funktioniert, und die Attributlisten in der mitgelieferten Doku unter node_modules/@ui-sdk/react/docs/ stimmen mit dem überein, was die Komponenten gerendert haben. HextaUI arbeitet an einer gestylten UI-SDK-Variante seiner Komponenten, getrennt von der Base-UI-Variante, und dieser Post ist das, was ich beim Bauen der ersten Teile gelernt habe.