Radix UI Designsystem
Baue produktionsreife, zugängliche Designsysteme mit Radix UI Primitiven – mit voller Anpassungskontrolle und ohne Stilvorgaben.
Überblick
Radix UI bietet unstyled, barrierefreie Komponenten (Primitive), die du an jedes Designsystem anpassen kannst. Dieser Skill führt dich durch den Aufbau skalierbarer Komponentenbibliotheken mit Radix UI, mit Fokus auf Accessibility-First-Design, Theming-Architektur und komponierbare Muster.
Kernstärken:
- Headless by Design: Volle Stilkontrolle, ohne gegen Voreinstellungen kämpfen zu müssen
- Eingebaute Barrierefreiheit: WAI-ARIA-konform, Tastaturnavigation, Screenreader-Unterstützung
- Komponierbare Primitive: Baue komplexe Komponenten aus einfachen Bausteinen
- Framework-agnostisch: Funktioniert mit React, aber Styles funktionieren überall
Wann dieser Skill verwendet werden sollte
- Erstellen eines eigenen Designsystems von Grund auf
- Aufbau barrierefreier UI-Komponentenbibliotheken
- Implementierung komplexer interaktiver Komponenten (Dialog, Dropdown, Tabs, usw.)
- Migration von gestylten Komponentenbibliotheken zu unstyled Primitiven
- Einrichtung von Theming-Systemen mit CSS-Variablen oder Tailwind
- Volle Kontrolle über Komponentenverhalten und Styling erforderlich
- Erstellung von Anwendungen, die WCAG 2.1 AA/AAA-Konformität erfordern
Verwende diesen Skill nicht, wenn
- Du sofort einsatzbereite, gestylte Komponenten benötigst (verwende shadcn/ui, Mantine, usw.)
- Du einfache statische Seiten ohne Interaktivität baust
- Das Projekt React 16.8+ nicht verwendet (Radix benötigt Hooks)
- Du Komponenten für andere Frameworks als React benötigst
Kernprinzipien
1. Barrierefreiheit zuerst
Jedes Radix-Primitiv ist mit Barrierefreiheit als Grundlage gebaut:
- Tastaturnavigation: Vollständige Tastaturunterstützung (Tab, Pfeiltasten, Eingabetaste, Escape)
- Screenreader: Korrekte ARIA-Attribute und Live-Regionen
- Fokus-Management: Automatischer Fokus-Einfang und -Wiederherstellung
- Deaktivierte Zustände: Korrekte Behandlung von disabled und aria-disabled
Regel: Überschreibe niemals Barrierefreiheitsfunktionen. Verbessere, ersetze nicht.
2. Headless-Architektur
Radix bietet Verhalten, du bietest Aussehen:
// ❌ Kämpfe nicht mit vorgestylten Komponenten
<Button className="override-everything" />
// ✅ Radix gibt dir Verhalten, du fügst Styling hinzu
<Dialog.Root>
<Dialog.Trigger className="your-button-styles" />
<Dialog.Content className="your-modal-styles" />
</Dialog.Root>
3. Komposition über Konfiguration
Baue komplexe Komponenten aus einfachen Primitiven:
// Primitive Komponenten komponieren natürlich
<Tabs.Root>
<Tabs.List>
<Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
<Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="tab1">Inhalt 1</Tabs.Content>
<Tabs.Content value="tab2">Inhalt 2</Tabs.Content>
</Tabs.Root>
Erste Schritte
Installation
# Einzelne Primitive installieren (empfohlen)
npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu
# Oder mehrere auf einmal installieren
npm install @radix-ui/react-{dialog,dropdown-menu,tabs,tooltip}
# Für Styling (optional, aber üblich)
npm install clsx tailwind-merge class-variance-authority
Grundlegendes Komponentenmuster
Jede Radix-Komponente folgt diesem Muster:
import * as Dialog from '@radix-ui/react-dialog';
export function MyDialog() {
return (
<Dialog.Root>
{/* Dialog auslösen */}
<Dialog.Trigger asChild>
<button className="trigger-styles">Öffnen</button>
</Dialog.Trigger>
{/* Portal rendert außerhalb der DOM-Hierarchie */}
<Dialog.Portal>
{/* Overlay (Hintergrund) */}
<Dialog.Overlay className="overlay-styles" />
{/* Inhalt (Modal) */}
<Dialog.Content className="content-styles">
<Dialog.Title>Titel</Dialog.Title>
<Dialog.Description>Beschreibung</Dialog.Description>
{/* Dein Inhalt hier */}
<Dialog.Close asChild>
<button>Schließen</button>
</Dialog.Close>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
);
}
Theming-Strategien
Strategie 1: CSS-Variablen (Framework-agnostisch)
Am besten für: Maximale Portabilität, SSR-freundlich
/* globals.css */
:root {
--color-primary: 220 90% 56%;
--color-surface: 0 0% 100%;
--radius-base: 0.5rem;
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
}
[data-theme="dark"] {
--color-primary: 220 90% 66%;
--color-surface: 222 47% 11%;
}
// Component.tsx
<Dialog.Content
className="
bg-[hsl(var(--color-surface))]
rounded-[var(--radius-base)]
shadow-[var(--shadow-lg)]
"
/>
Strategie 2: Tailwind + CVA (Class Variance Authority)
Am besten für: Tailwind-Projekte, variantenreiche Komponenten
// button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
const buttonVariants = cva(
// Basis-Styles
"inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/90",
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
outline: "border border-input bg-background hover:bg-accent",
ghost: "hover:bg-accent hover:text-accent-foreground",
},
size: {
default: "h-10 px-4 py-2",
sm: "h-9 rounded-md px-3",
lg: "h-11 rounded-md px-8",
icon: "h-10 w-10",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
}
);
interface ButtonProps extends VariantProps<typeof buttonVariants> {
children: React.ReactNode;
}
export function Button({ variant, size, children }: ButtonProps) {
return (
<button className={cn(buttonVariants({ variant, size }))}>
{children}
</button>
);
}
Strategie 3: Stitches (CSS-in-JS)
Am besten für: Laufzeit-Theming, bereichsbezogene Styles
import { styled } from '@stitches/react';
import * as Dialog from '@radix-ui/react-dialog';
const StyledContent = styled(Dialog.Content, {
backgroundColor: '$surface',
borderRadius: '$md',
padding: '$6',
variants: {
size: {
small: { width: '300px' },
medium: { width: '500px' },
large: { width: '700px' },
},
},
defaultVariants: {
size: 'medium',
},
});
Komponentenmuster
Muster 1: Zusammengesetzte Komponenten mit Context
Anwendungsfall: Zustand zwischen primitiven Teilen teilen
// Select.tsx
import * as Select from '@radix-ui/react-select';
import { CheckIcon, ChevronDownIcon } from '@radix-ui/react-icons';
export function CustomSelect({ items, placeholder, onValueChange }) {
return (
<Select.Root onValueChange={onValueChange}>
<Select.Trigger className="select-trigger">
<Select.Value placeholder={placeholder} />
<Select.Icon>
<ChevronDownIcon />
</Select.Icon>
</Select.Trigger>
<Select.Portal>
<Select.Content className="select-content">
<Select.Viewport>
{items.map((item) => (
<Select.Item
key={item.value}
value={item.value}
className="select-item"
>
<Select.ItemText>{item.label}</Select.ItemText>
<Select.ItemIndicator>
<CheckIcon />
</Select.ItemIndicator>
</Select.Item>
))}
</Select.Viewport>
</Select.Content>
</Select.Portal>
</Select.Root>
);
}
Muster 2: Polymorphe Komponenten mit asChild
Anwendungsfall: Als verschiedene Elemente rendern, ohne Verhalten zu verlieren
// ✅ Als Next.js Link rendern, aber Radix-Verhalten beibehalten
<Dialog.Trigger asChild>
<Link href="/settings">Einstellungen öffnen</Link>
</Dialog.Trigger>
// ✅ Als benutzerdefinierte Komponente rendern
<DropdownMenu.Item asChild>
<YourCustomButton icon={<Icon />}>Aktion</YourCustomButton>
</DropdownMenu.Item>
Warum asChild wichtig ist: Verhindert verschachtelte Button/Link-Probleme im Barrierefreiheits-Baum.
Muster 3: Kontrolliert vs. Unkontrolliert
// Unkontrolliert (Radix verwaltet den Zustand)
<Tabs.Root defaultValue="tab1">
<Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
</Tabs.Root>
// Kontrolliert (Du verwaltest den Zustand)
const [activeTab, setActiveTab] = useState('tab1');
<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
<Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
</Tabs.Root>
Regel: Verwende kontrolliert, wenn du mit externem Zustand (URL, Redux, usw.) synchronisieren musst.
Muster 4: Animation mit Framer Motion
import * as Dialog from '@radix-ui/react-dialog';
import { motion, AnimatePresence } from 'framer-motion';
export function AnimatedDialog({ open, onOpenChange }) {
return (
<Dialog.Root open={open} onOpenChange={onOpenChange}>
<Dialog.Portal forceMount>
<AnimatePresence>
{open && (
<>
<Dialog.Overlay asChild>
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
className="dialog-overlay"
/>
</Dialog.Overlay>
<Dialog.Content asChild>
<motion.div
initial={{ opacity: 0, scale: 0.95 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.95 }}
className="dialog-content"
>
{/* Inhalt */}
</motion.div>
</Dialog.Content>
</>
)}
</AnimatePresence>
</Dialog.Portal>
</Dialog.Root>
);
}
Referenz zu gängigen Primitiven
Dialog (Modal)
<Dialog.Root> {/* Zustandscontainer */}
<Dialog.Trigger /> {/* Öffnet Dialog */}
<Dialog.Portal> {/* Rendert in Portal */}
<Dialog.Overlay /> {/* Hintergrund */}
<Dialog.Content> {/* Modaler Inhalt */}
<Dialog.Title /> {/* Erforderlich für Barrierefreiheit */}
<Dialog.Description /> {/* Erforderlich für Barrierefreiheit */}
<Dialog.Close /> {/* Schließt Dialog */}
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
Dropdown-Menü
<DropdownMenu.Root>
<DropdownMenu.Trigger />
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item />
<DropdownMenu.Separator />
<DropdownMenu.CheckboxItem />
<DropdownMenu.RadioGroup>
<DropdownMenu.RadioItem />
</DropdownMenu.RadioGroup>
<DropdownMenu.Sub> {/* Verschachtelte Menüs */}
<DropdownMenu.SubTrigger />
<DropdownMenu.SubContent />
</DropdownMenu.Sub>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
Tabs
<Tabs.Root defaultValue="tab1">
<Tabs.List>
<Tabs.Trigger value="tab1" />
<Tabs.Trigger value="tab2" />
</Tabs.List>
<Tabs.Content value="tab1" />
<Tabs.Content value="tab2" />
</Tabs.Root>
Tooltip
<Tooltip.Provider delayDuration={200}>
<Tooltip.Root>
<Tooltip.Trigger />
<Tooltip.Portal>
<Tooltip.Content side="top" align="center">
Tooltip-Text
<Tooltip.Arrow />
</Tooltip.Content>
</Tooltip.Portal>
</Tooltip.Root>
</Tooltip.Provider>
Popover
<Popover.Root>
<Popover.Trigger />
<Popover.Portal>
<Popover.Content side="bottom" align="start">
Inhalt
<Popover.Arrow />
<Popover.Close />
</Popover.Content>
</Popover.Portal>
</Popover.Root>
Barrierefreiheits-Checkliste
Jede Komponente muss Folgendes haben:
- Fokus-Management: Sichtbare Fokus-Indikatoren auf allen interaktiven Elementen
- Tastaturnavigation: Vollständige Tastaturunterstützung (Tab, Pfeile, Eingabetaste, Esc)
- ARIA-Labels: Sinnvolle Beschriftungen für Screenreader
- Farbkontrast: WCAG AA Minimum (4,5:1 für Text, 3:1 für UI)
- Fehlerzustände: Klare Fehlermeldungen mit
aria-invalidundaria-describedby - Ladezustände: Korrektes
aria-busywährend asynchroner Vorgänge
Dialogspezifisch:
-
Dialog.Titleist vorhanden (erforderlich für Screenreader) -
Dialog.Descriptionliefert Kontext - Fokus ist innerhalb des Modals eingeschlossen, wenn es geöffnet ist
- Escape-Taste schließt den Dialog
- Fokus kehrt beim Schließen zum Auslöser zurück
Dropdown-spezifisch:
- Pfeiltasten navigieren durch die Elemente
- Type-Ahead-Suche funktioniert
- Verhalten beim ersten/letzten Element (Wrapping)
- Ausgewählter Zustand wird visuell und mit ARIA angezeigt
Best Practices
✅ Tu dies
-
Verwende immer
asChild, um Wrapper-Divs zu vermeiden<Dialog.Trigger asChild> <button>Öffnen</button> </Dialog.Trigger> -
Biete semantisches HTML
<Dialog.Content asChild> <article role="dialog" aria-labelledby="title"> {/* Inhalt */} </article> </Dialog.Content> -
Verwende CSS-Variablen für Theming
.dialog-content { background: hsl(var(--surface)); color: hsl(var(--on-surface)); } -
Komponiere Primitive für komplexe Komponenten
function CommandPalette() { return ( <Dialog.Root> <Dialog.Content> <Combobox /> {/* Radix Combobox innerhalb von Dialog */} </Dialog.Content> </Dialog.Root> ); }
❌ Tu dies nicht
-
Überspringe keine Barrierefreiheitsteile
// ❌ Fehlender Titel und Beschreibung <Dialog.Content> <div>Inhalt</div> </Dialog.Content> -
Kämpfe nicht gegen die Primitive
// ❌ Überschreiben des internen Verhaltens <Dialog.Content onClick={(e) => e.stopPropagation()}> -
Mische nicht kontrollierte und unkontrollierte Zustände
// ❌ Inkonsistente Zustandsverwaltung <Tabs.Root defaultValue="tab1" value={activeTab}> -
Ignoriere keine Tastaturnavigation
// ❌ Deaktivieren des Tastaturverhaltens <DropdownMenu.Item onKeyDown={(e) => e.preventDefault()}>
Fehlerbehebung
Häufige Probleme
Problem: Komponente rendert nicht
- Lösung: Stelle sicher, dass der Radix-Portal-Container vorhanden ist. Radix verwendet
Portal, das einen Container im DOM benötigt. Prüfe, ob@radix-ui/react-portalkorrekt eingerichtet ist.
Problem: Styling wird nicht angewendet
- Lösung: Stelle sicher, dass das
className-Prop korrekt gesetzt ist. Radix-Primitive haben keine Standard-Styles. Füge CSS-Klassen direkt oder überasChildmit einer gestylten Komponente hinzu.
Problem: Barrierefreiheitsprobleme
- Lösung: Verwende die Barrierefreiheits-Checkliste oben. Stelle sicher, dass alle erforderlichen ARIA-Attribute vorhanden sind und die Tastaturnavigation vollständig funktioniert.
Fazit
Mit Radix UI und diesen Mustern kannst du skalierbare, barrierefreie Designsysteme erstellen, die sich an jedes Projekt anpassen. Denke daran: Barrierefreiheit ist keine Funktion, sie ist die Grundlage.