Zum Inhalt springen
Dokumentation

Grundlagen

Barrierefreiheit

Stabil

Was NEODIN UI für WCAG 2.2 AA mitbringt, wie es geprüft wird und was Produkte selbst sicherstellen müssen.

Das Ziel ist WCAG 2.2 Stufe AA. Die Library liefert dafür die Grundlage: semantisches Markup, Tastaturbedienung über Radix, sichtbare Fokusringe, geprüfte Kontraste und Texte für zugängliche Namen. Ein fertiges Produkt wird daraus aber erst, wenn die Anwendung ihre eigenen Teile richtig beschriftet und strukturiert.

Was die Library sicherstellt

Semantik und Tastatur

Interaktive Bausteine setzen auf Radix-UI-Primitives: Dialog, Select, DropdownMenu, Tabs, Slider, Switch, Accordion, Tooltip und die übrigen Overlays. Damit kommen Fokusfalle, Escape, Pfeiltasten und die Rollen, die Screenreader erwarten, aus einer geprüften Implementierung. Die Komponententests prüfen das Verhalten zusätzlich über getByRole und user.keyboard, etwa den Pfeiltastenwechsel in Select oder den Fokus nach dem Öffnen eines Dialogs.

Was eine Komponente an Tastatur und Rollen kann, steht auf ihrer Seite unter „Barrierefreiheit“. Diese Aussagen stammen aus den Tests der jeweiligen Komponente, nicht aus Vermutungen.

Fokus

Knöpfe, Felder und Menüeinträge tragen focus-visible-Ringe mit ring-ring und ring-offset-background. Der Ring erscheint bei Tastaturbedienung, nicht bei jedem Mausklick. Weil --ring in beiden Themes gegen --background und --page mindestens 3:1 erreicht, ist der Fokus auch auf farbigen Flächen sichtbar.

Kontrast

packages/ui/src/tokens.test.ts rechnet die Kontraste der Tokens nach, für hell und dunkel getrennt:

  • 21 Textpaare müssen mindestens 4,5:1 erreichen (WCAG 1.4.3), darunter foreground auf background, muted-foreground auf muted und die Statustexte auf ihren gedämpften Flächen.
  • Drei Paare für Bedienelemente müssen mindestens 3:1 erreichen (WCAG 1.4.11): input auf background, ring auf background und ring auf page.

Die Werte selbst stehen unter Design-Tokens, samt Kontrastspalte.

Automatische Prüfungen

  • Jede Komponente hat einen Test. components-have-tests.test.ts schlägt fehl, sobald eine Komponentendatei ohne gleichnamige .test.tsx dazukommt.
  • axe in hell und dunkel. expectNoAxeViolations (vitest-axe) läuft pro Komponente in beiden Themes. Die Regeln color-contrast und region sind dabei abgeschaltet: Kontrast prüft der Token-Test genauer, und ein Komponententest rendert absichtlich ohne Seitenlandmarken.
  • axe im Browser. Jede Seite dieser Doku läuft im Playwright-Test durch axe; die Themenseiten zusätzlich im dunklen Modus. Neue Seiten sind automatisch dabei, weil der Test die MDX-Dateien einliest.

Status ohne Farbe allein

Status wird immer durch Symbol und Text getragen: StatusBadge zeigt beides, Banner und Alert haben eine Überschrift und ein Icon je Variante. Wer nur die Farbe sieht oder sie nicht unterscheiden kann, verliert keine Information.

Bewegung

Spinner, Progress und der Schließen-Knopf im Banner respektieren prefers-reduced-motion (motion-reduce:animate-none, motion-reduce:transition-none). Es gibt keine automatisch startende Animation ohne diese Ausnahme.

Live-Regionen

Wo sich Inhalte ohne Seitenwechsel ändern, melden die Komponenten das an: Spinner hat role="status", die Seitennavigation der DataTable ein aria-live="polite", der Fehlerhinweis im FileUpload role="alert".

Was Produkte selbst tun müssen

Felder beschriften

Jedes Eingabefeld braucht eine sichtbare Beschriftung über Label und id oder über FormField im Form. Ein Platzhalter ist kein Ersatz: Er verschwindet beim Tippen und wird von manchen Screenreadern nicht als Name vorgelesen. Icon-only-Knöpfe brauchen aria-label, etwa aus dem Katalog (close, copy, toggleSidebar).

Überschriften und Landmarken

Eine Seite hat genau eine h1, danach keine Sprünge (kein h4 nach h2). Hauptinhalt, Navigation und Kopfzeile liegen in main, nav und header. Ein Skip-Link „Zum Inhalt springen“ gehört als erstes fokussierbares Element auf die Seite; diese Doku macht das im Doku-Layout vor.

Fehlermeldungen verbinden

Eine Fehlermeldung muss am Feld hängen, nicht nur darunter stehen. FormControl setzt aria-invalid und verweist über aria-describedby auf FormMessage und FormDescription – und nur auf die Elemente, die es wirklich gibt. Bei eigenen Feldern ohne Form setzt du beides selbst: aria-invalid am Feld und aria-describedby auf die ID der Meldung. FormMessage bekommt den Fehlertext aus der Validierung; wie das zusammenspielt, steht unter Formular (Form).

Bilder und Symbole

Jedes inhaltstragende Bild braucht einen Alternativtext, dekorative Symbole aria-hidden="true". Avatar zeigt ohne Bild die Initialen; wenn das Bild eine Person identifiziert, gehört der Name in den Alternativtext und nicht in den Dateinamen.

Farbe nicht als einziger Träger

Ein Status, ein Fehler oder ein Trend darf nicht nur an der Farbe hängen. Nutze StatusBadge, Banner oder Alert, die Symbol und Text mitbringen. Eigene Markierungen brauchen dasselbe Prinzip: Text dazu, nicht nur Rot.

Zielgrößen in kompakter Dichte

Die kompakte Dichte verkleinert Eingabefelder auf 30 px Höhe. Das liegt über den 24 × 24 px, die WCAG 2.2 (2.5.8) verlangt. Eigene kleine Ziele – Symbolknöpfe in Tabellenzeilen etwa – prüfst du trotzdem einzeln. Mehr dazu unter Dichte.

Sprache und Seitentitel

<html lang="de"> und ein eindeutiger <title> pro Seite gehören in jede Anwendung. Wechselt ein Abschnitt die Sprache, bekommt er ein eigenes lang-Attribut.

Selbst prüfen

Automatische Tests finden Strukturfehler, aber nicht jede Verständlichkeit. Vor der Abgabe: die Seite nur mit der Tastatur bedienen, den Fokus nie verlieren, mit einem Screenreader die wichtigsten Abläufe durchgehen und die Kontraste eigener Flächen nachrechnen.

Siehe auch