Barrierefreier Code mit Cursor, Claude Code und anderen…

Coding-Assistenten wie Cursor, Claude Code, GitHub Copilot und Windsurf arbeiten in Ihrer eigenen Codebasis. Sie lesen Ihre Dateien, führen Befehle aus und schlagen Änderungen vor, die Sie prüfen. Das gibt Ihnen mehr Kontrolle als ein Website-Baukasten im Chatfenster. Es bedeutet aber auch, dass Barrierefreiheit von denselben drei Dingen abhängt wie der Rest Ihrer Codequalität: klaren Regeln, automatischen Prüfungen und einem menschlichen Review. Diese Anleitung richtet sich an Entwickler und behandelt alle drei, dazu die Prüfung des bereitgestellten Ergebnisses mit ibin.

Was Coding-Assistenten oft falsch machen

Assistenten übernehmen die Muster, die sie sehen, in Ihrer Codebasis und in ihren Trainingsdaten. Der größte Teil des Webs ist nicht barrierefrei: Die WebAIM-Analyse 2026 von einer Million Startseiten fand auf 95,9 % davon automatisch erkennbare Fehler. Typische Ergebnisse ohne Regeln:

Ein div oder span mit onClick-Handler statt eines Buttons, der mit der Tastatur nicht erreichbar ist.
Schaltflächen nur mit Symbol und ohne zugänglichen Namen, sodass ein Screenreader (Software, die den Bildschirminhalt vorliest) nur „Schaltfläche“ sagt.
outline: none, um einen Fokusrahmen zu entfernen, der im Design störte, ohne Ersatz.
Eigene Auswahllisten, Comboboxen und modale Dialoge von Grund auf neu gebaut, ohne Tastaturbedienung oder Fokusverwaltung.
ARIA-Attribute, die ein Problem lösen sollen, das ein natives Element nie gehabt hätte. Falsches ARIA ist oft schlimmer als gar keines.
Fest codierte Farben, die Ihre Design-Tokens umgehen und den Kontrast verfehlen.
Clientseitige Routenwechsel, bei denen Dokumenttitel und Fokus bleiben, wo sie waren.

Wo die Regeln je nach Tool hingehören

Jedes Tool liest zu Beginn einer Aufgabe eine bestimmte Datei. Prüfen Sie die Dokumentation Ihres Tools, denn diese Orte ändern sich.

Cursor: Projektregeln sind .mdc-Dateien in .cursor/rules, mit einem Kopfbereich (Frontmatter), der festlegt, wann sie gelten. Nutzen Sie alwaysApply: true für Regeln, die in jedem Chat gelten sollen. Cursor liest außerdem AGENTS.md als Alternative in einfachem Markdown. Siehe die Regel-Dokumentation von Cursor.
Claude Code: CLAUDE.md im Projektstamm (oder .claude/CLAUDE.md), geladen zu Beginn jeder Sitzung. Gibt es keine CLAUDE.md, liest Claude Code AGENTS.md, und eine CLAUDE.md kann diese Datei mit der Zeile @AGENTS.md importieren. Siehe die Dokumentation von Claude Code.
GitHub Copilot: Anweisungen für das ganze Repository in .github/copilot-instructions.md, pfadbezogene Anweisungen in .github/instructions/NAME.instructions.md mit einem applyTo-Muster. Die Agenten von Copilot lesen auch AGENTS.md. Siehe die Dokumentation von GitHub.
Windsurf (seit 2026 Devin Desktop): Workspace-Regeln sind Markdown-Dateien in .devin/rules, der ältere Ordner .windsurf/rules wird weiterhin gelesen. Setzen Sie trigger: always_on in den Kopfbereich. Eine AGENTS.md im Stammverzeichnis gilt immer. Siehe die Regel-Dokumentation.
AGENTS.md: ein offenes Format für Anweisungen an Agenten, betreut von der Agentic AI Foundation unter dem Dach der Linux Foundation und von vielen Tools gelesen, darunter OpenAI Codex, Gemini CLI, Cursor, Copilot und Windsurf.

Eine praktische Lösung für Teams mit unterschiedlichen Tools: Legen Sie die Regeln in AGENTS.md ab und verweisen Sie aus den toolspezifischen Dateien darauf. Für Claude Code reicht eine CLAUDE.md mit einer einzigen Importzeile:

@AGENTS.md

Wenn Sie in Cursor lieber eine eigene Regel statt AGENTS.md möchten, legen Sie .cursor/rules/accessibility.mdc an und beginnen Sie mit diesem Kopfbereich:

---
description: Anforderungen an die Barrierefreiheit für allen UI-Code
alwaysApply: true
---

Der Regelblock

Fügen Sie diesen Block in AGENTS.md oder in die Regeldatei Ihres Tools ein. Passen Sie Token-Namen und Befehle an Ihr Projekt an.

## Barrierefreiheit (WCAG 2.2 AA)

- Bevorzuge native Elemente: button für Aktionen, a href für Navigation, label für Felder, fieldset/legend für Gruppen, dialog oder den Dialog des Designsystems für modale Fenster. Setze nie onClick auf ein div oder span.
- Nutze ARIA nur, wenn kein natives Element passt. Überschreibe nie eine native Rolle.
- Jedes interaktive Element hat einen zugänglichen Namen. Schaltflächen nur mit Symbol bekommen aria-label; dekorative Symbole bekommen aria-hidden="true".
- Jedes Eingabefeld hat eine sichtbare Beschriftung, die im Code damit verknüpft ist. Fehler werden mit aria-describedby verknüpft und als Text angezeigt.
- Entferne nie einen Fokusrahmen ohne sichtbaren Ersatz über :focus-visible mit mindestens 3:1 Kontrast.
- Nutze nur Farb-Tokens aus dem Designsystem. Text-Tokens erreichen 4.5:1 auf den Flächen, auf denen sie verwendet werden (3:1 für großen Text und UI-Bestandteile). Keine fest codierten Farben.
- Fokusverwaltung: Setze den Fokus in Dialoge, halte ihn dort, solange sie offen sind, und gib ihn beim Schließen zurück. Aktualisiere bei clientseitigen Routenwechseln document.title und setze den Fokus auf die Hauptüberschrift.
- Beachte prefers-reduced-motion für alle nicht wesentlichen Animationen.
- Eine h1 pro Seite, Überschriften in der richtigen Reihenfolge. Setze lang auf das html-Element.
- Interaktive Ziele sind mindestens 24x24 CSS-Pixel groß.
- Führe vor dem Abschluss einer UI-Änderung den Linter und die Barrierefreiheitstests aus (npm run lint, npm run test:a11y) und behebe neue Fehler.

Automatische Prüfungen in CI

Regeln machen guten Code wahrscheinlicher; Prüfungen fangen auf, was trotzdem durchrutscht. Zwei Ebenen ergänzen sich gut.

Ein Linter für Ihre Templates. Für React und anderen JSX-Code meldet eslint-plugin-jsx-a11y fehlende Alternativtexte, klickbare divs, Beschriftungen ohne Feld und ähnliche Fehler schon beim Tippen. Vue-Projekte können eslint-plugin-vuejs-accessibility nutzen. Mit der Flat Config von ESLint (prüfen Sie, ob das Plugin Ihre ESLint-Version unterstützt):

import jsxA11y from "eslint-plugin-jsx-a11y";

export default [
  jsxA11y.flatConfigs.recommended,
  // your other configs
];

Ein Browsertest für gerenderte Seiten. axe-core ist eine Open-Source-Engine, die eine gerenderte Seite anhand vieler WCAG-Regeln prüft. Playwright, ein Werkzeug für Browsertests, kann sie mit dem Paket @axe-core/playwright auf Ihren wichtigsten Seiten ausführen:

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test("home page has no detectable accessibility violations", async ({ page }) => {
  await page.goto("/");
  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"])
    .analyze();
  expect(results.violations).toEqual([]);
});

Lassen Sie beides bei jedem Pull Request in CI laufen und nennen Sie die Befehle in AGENTS.md, damit der Assistent sie ausführt, bevor er meldet, dass er fertig ist. Assistenten beheben fehlschlagende Prüfungen gut, wenn sie die Fehlermeldung sehen.

Die bereitgestellte Vorschau mit ibin prüfen

Tests laufen gegen Ihren lokalen Build und die Seiten, die Sie ausgewählt haben. Eine Prüfung der bereitgestellten Website findet, was sie übersehen: Skripte von Drittanbietern, Cookie-Banner, Inhalte aus Ihrem CMS und Seiten, für die niemand einen Test geschrieben hat.

Vorschau bereitstellen. Die meisten Hosting-Anbieter erstellen für jeden Pull Request eine Vorschauadresse. Ist die Vorschau durch eine Anmeldung geschützt, nutzen Sie eine Staging-Adresse ohne Schutz oder nach dem Merge die Produktionsadresse; ein Prüfwerkzeug kann sich nicht anmelden.
Vorschau mit ibin prüfen. Der Bericht beschreibt die Probleme verständlich, sortiert nach Dringlichkeit, mit einer Nahaufnahme jeder Stelle. Die technischen Details stehen unter „Code für Entwickler“.
Korrektur an den Assistenten geben. Bei jedem Problem gibt es die Schaltfläche „Anleitung für ein KI-Tool kopieren“. Der Prompt funktioniert in Cursor, Claude Code oder Copilot genauso wie in einem Baukasten: einfügen und den Diff prüfen.
Die ganze Website prüfen. Melden Sie sich an, um bis zu 200 Seiten zu prüfen, und schalten Sie wöchentliche Prüfungen ein, damit Rückschritte in Ihrem Postfach landen.

Automatische Werkzeuge, axe-core und ibin eingeschlossen, finden ungefähr ein Drittel bis die Hälfte aller Barrieren. Machen Sie bei neuen Abläufen den Tastaturtest in zehn Minuten und probieren Sie einen Screenreader an Ihrem wichtigsten Formular aus.

Was kein Assistent und kein Test beurteilen kann

Ob ein Alternativtext zutrifft, ob Linktexte ohne Zusammenhang verständlich sind, ob eine Fehlermeldung hilft und ob Ihr Text klar ist, hängt von der Bedeutung ab. Ein Assistent kann einen Alternativtext vorschlagen, weiß aber nicht, warum das Bild auf der Seite steht. Prüfen Sie diese Punkte von Hand, wenn sich Inhalte ändern. Der optionale zweite Blick der KI in ibin bewertet Bildbeschreibungen, Linktexte, Tastaturbedienung und Sprache von 1 bis 5, als Hinweise für ein menschliches Review.

Die nicht technische Fassung dieses Vorgehens finden Sie in der Übersicht für KI-Baukästen. Die Anleitungen zur Barrierefreiheit erklären jedes Problem, zum Beispiel zu Linktexten.

Prüfen Sie Ihre bereitgestellte Website

Stellen Sie eine Vorschau bereit und prüfen Sie eine Seite kostenlos mit ibin. Fügen Sie die Anleitung zu jedem Problem in Ihren Coding-Assistenten ein, prüfen Sie die Änderung und prüfen Sie die Seite erneut.

Sehen Sie, wie Ihre Website abschneidet

Prüfen Sie kostenlos eine Seite, ohne Konto. Sie erhalten eine klare Liste, was zuerst zu beheben ist, mit Bildern, wo jedes Problem liegt.