Grundlagen
Barrierefreiheit
StabilWas 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
foregroundaufbackground,muted-foregroundaufmutedund die Statustexte auf ihren gedämpften Flächen. - Drei Paare für Bedienelemente müssen mindestens 3:1 erreichen (WCAG
1.4.11):
inputaufbackground,ringaufbackgroundundringaufpage.
Die Werte selbst stehen unter Design-Tokens, samt Kontrastspalte.
Automatische Prüfungen
- Jede Komponente hat einen Test.
components-have-tests.test.tsschlägt fehl, sobald eine Komponentendatei ohne gleichnamige.test.tsxdazukommt. - axe in hell und dunkel.
expectNoAxeViolations(vitest-axe) läuft pro Komponente in beiden Themes. Die Regelncolor-contrastundregionsind 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.