Communitygithub.com

wcag-audit

Auditiert Web-UI auf WCAG 2.2-Barrierefreiheit (a11y) und behebt Fehler. Führt ein mehrphasiges Verfahren durch (statischer Source-Scan von HTML/JSX/TSX/Vue/Svelte/Astro/MDX/Angular/CSS, Browser-Laufzeitscan mit axe-core und Tastaturprüfungen, adversarielle Verifikation jedes Befunds, minimale Fixes mit Erklärungen und einen maschinenlesbaren Report).

Was ist wcag-audit?

Der Skill 'wcag-audit' ist ein umfassendes Werkzeug für die Prüfung und Reparatur von Barrierefreiheit nach WCAG 2.2. Er führt eine automatisierte, mehrphasige Analyse durch: Zuerst wird der Quellcode statisch nach häufigen Fehlern durchsucht (z.B. fehlende ARIA-Attribute, falsche Semantik). Danach wird die Anwendung in einem echten Browser mit axe-core und Tastaturtests getestet, um dynamische Probleme wie Kontrastfehler oder Fokus-Reihenfolgen zu erkennen. Jeder Befund wird in einer dritten Phase rigoros verifiziert, um Fehlalarme auszuschließen, bevor möglichst minimale und verhaltensbewahrende Korrekturen angewendet werden. Der Skill erstellt einen detaillierten maschinenlesbaren und menschenlesbaren Bericht und ist für Entwickler von Webanwendungen auf Basis moderner Frameworks (React, Vue, Angular, Svelte etc.) konzipiert. Er unterstützt sowohl CLI-basierte Scans als auch eine manuelle Modus, falls keine CLI verfügbar ist.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mintwork/wcag-audit-skill/tree/HEAD/skills/wcag-audit

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

WCAG Audit

Du prüfst eine Benutzeroberfläche auf Barrieren für die Barrierefreiheit und behebst sie. Benutzer mit Behinderungen können eine fehlende Beschriftung nicht wie ein sehender Mausbenutzer umgehen: Behandle jeden bestätigten Befund als echten Fehler, der eine reale Person blockiert.

Ziel: Eine Liste verifizierter Befunde, jeweils verknüpft mit einem WCAG 2.2-Erfolgskriterium, mit einer genauen Position, einem Nachweis und einer minimalen Korrektur – und dann die Korrekturen, angewendet und erneut verifiziert.

Grundsätze

  1. Verifiziert oder es wird nicht ausgeliefert. Jeder Befund muss Phase 3 bestehen. Eine kurze Liste echter Probleme ist besser als eine lange Liste, die der Benutzer ignoriert.
  2. Natives HTML zuerst. Das beste ARIA ist kein ARIA. Korrigiere <div onClick> indem du es zu einem <button> machst, nicht durch Anbringen von role, tabindex und Tasten-Handlern.
  3. Minimale, verhaltensbewahrende Korrekturen. Ändere das Markup, das fehlschlägt; gestalte den umgebenden Code nicht neu, formatiere ihn nicht um. Halte das visuelle Design unverändert, es sei denn, der Befund ist visuell (Kontrast, Fokusring, Zielgröße).
  4. Erfinde niemals Inhalte. Alternativtext, Beschriftungen und Linktext müssen widerspiegeln, was die Benutzeroberfläche tatsächlich bedeutet. Wenn du nicht sagen kannst, was ein Bild vermittelt, markiere den Befund als needs_validation und frage nach; schreibe nicht alt="image".
  5. Automatisierung ist ein Boden, keine Obergrenze. Tools erkennen etwa ein Drittel bis die Hälfte der WCAG-Fehler. Berichte, was nicht getestet wurde (siehe die manuelle Checkliste).

Einrichtung

Lege den Umfang aus der Anfrage des Benutzers fest: ganzes Repository, ein Verzeichnis, bestimmte Komponenten oder eine URL. Überprüfe dann die Werkzeuge:

npx --yes @mintwork/wcag-audit-skill --version        # CLI verfügbar?

Wenn die CLI nicht verfügbar ist (offline, kein Node), fahre im manuellen Modus fort: Wende die Regelliste in references/RULES.md an, indem du den Quellcode selbst liest, und überspringe Phase 2, es sei denn, die Umgebung des Benutzers bietet ein anderes Browser-Tool.

Schreibe alle Artefakte in .wcag-audit/ im Repository-Stammverzeichnis (erstelle es; schlage vor, es zu .gitignore hinzuzufügen, und behalte .wcag-audit/baseline.json, wenn das Projekt eine CI-Baseline festlegt). Schreibe niemals woanders hin, es sei denn, der Benutzer fragt danach.

Arbeitsablauf

Führe die Phasen in der Reihenfolge aus. Sage dem Benutzer, in welcher Phase du dich befindest. Bei kleinen Umfängen (eine Komponente) können die Phasen kurz sein, aber überspringe Phase 3 nicht.

Phase 1 – Statischer Scan (Quellcode)

npx @mintwork/wcag-audit-skill scan <Pfad> --json -o .wcag-audit/static.json --fail-on none

Prüfe ohne --baseline, selbst wenn das Projekt eine Baseline festlegt (.wcag-audit/baseline.json): Die Baseline lässt CI nur bekannte Befunde ignorieren, und diese müssen trotzdem überprüft werden.

Lies dann references/STATIC-SCAN.md und führe die Überprüfung durch, die das Tool nicht leisten kann: benutzerdefinierte Komponenten, die native Elemente umschließen, bedingtes Rendering, Design-System-Props (<Icon label=…>), Fokusstile, die in CSS-in-JS entfernt oder in einem anderen Stylesheet ersetzt wurden (die CLI prüft .css / .scss / .less und Tailwind-Klassen eine Datei nach der anderen), farbigen Zustand und alles, was der Scanner aufgrund von Spread-Props oder dynamischen Werten übersprungen hat. Füge diese als Kandidatenbefunde mit "source": "static" und "confidence": "medium" hinzu.

Phase 2 – Laufzeitscan (echter Browser)

Nur wenn eine URL verfügbar ist oder die App gestartet werden kann. Finde den Entwicklungsbefehl (package.json-Scripts, README), starte ihn im Hintergrund, warte, bis er antwortet, dann:

npx @mintwork/wcag-audit-skill scan http://localhost:3000 --source src --json -o .wcag-audit/runtime.json --fail-on none
# Weitere Seiten / Zustände:
npx @mintwork/wcag-audit-skill scan http://localhost:3000/login http://localhost:3000/cart --json -o .wcag-audit/runtime-2.json --fail-on none

Scanne die relevanten Seiten (Startseite, Hauptabläufe, Formulare, geöffnete Modale) – siehe references/RUNTIME-SCAN.md für abzudeckende Zustände, SPA-Wartezeiten und Authentifizierung. Lege Zustände (ein Modal öffnen, ein leeres Formular absenden, Dunkelmodus, 320px) in einer Konfiguration fest und führe scan --config .wcag-audit/config.json aus; für angemeldete Seiten verwende --storage-state <Datei> vom Benutzer, niemals Anmeldedaten. Wenn das Projekt Storybook hat, führe auch scan --storybook storybook-static (oder die laufende Storybook-URL) aus, um jeden Komponentenzustand abzudecken. Der sourceHint jedes Laufzeitbefunds ist ein Suchergebnis: Bestätige es vor der Korrektur. Laufzeitbefunde erfassen, was die statische Analyse nicht erfassen kann: berechneten Kontrast, echte zugängliche Namen, Fokusreihenfolge, Tastaturfallen, unsichtbaren Fokus.

Phase 3 – Verifikation (Falschmeldungen entfernen)

Befolge für jeden Kandidaten references/VERIFICATION.md. Versuche, ihn zu widerlegen: Öffne den Quellcode an der gemeldeten Zeile, verfolge Props/Slots/Spreads bis zu der Stelle, an der der Wert gesetzt wird, prüfe, ob ein übergeordnetes Element die Beschriftung bereitstellt, überprüfe das gerenderte DOM für Laufzeitbefunde. Weise ein Urteil zu:

  • confirmed – du hast es zurückverfolgt und es erfüllt das Kriterium nicht. Halte fest, woran du es erkennst.
  • needs_validation – plausibel, aber du konntest es nicht feststellen (z.B. Qualität des Alternativtexts, Inhalte, die du nicht sehen kannst, eine Seite, die du nicht erreichen kannst). Es wird keine Korrektur angewendet.
  • rejected – widerlegt. Halte den Grund fest (dies lehrt den Benutzer, welche Regeln er anpassen sollte).

Fasse Duplikate zusammen: Die gleiche Ursache, die von statischer und Laufzeit-Untersuchung gemeldet wurde, ist ein Befund mit beiden Positionen.

Phase 4 – Korrektur

Korrigiere confirmed-Befunde, beginnend mit der höchsten Schwere, unter Verwendung von references/FIX-PATTERNS.md. Für jede Korrektur:

  1. Nimm die kleinste Änderung vor, die das Kriterium erfüllt, im Idiom des Frameworks (htmlFor in React, :aria-label in Vue usw.).
  2. Erkläre es in ein oder zwei Sätzen: Was war falsch, wen es betraf, was sich geändert hat.
  3. Frage nach, bevor Änderungen die sichtbare Benutzeroberfläche oder den Text verändern (Kontrastfarben, neue sichtbare Beschriftungen, Linktext), es sei denn, der Benutzer hat bereits grünes Licht gegeben.

Mechanische Befunde (html-lang-Reparaturen, meta-viewport-zoom, aria-attr-valid-Tippfehler) können von der CLI korrigiert werden: Führe scan <Pfad> --dry-run aus, zeige dem Benutzer den Diff, dann scan <Pfad> --fix. Ein fehlendes lang wird nur mit --lang <Code> hinzugefügt, sobald du die Sprache der Seite kennst.

Führe dann eine mechanische Überprüfung durch:

npx @mintwork/wcag-audit-skill verify .wcag-audit/static.json
npx @mintwork/wcag-audit-skill verify .wcag-audit/runtime.json   # Dev-Server läuft noch

verify beendet sich mit einem Fehler, wenn noch etwas übrig ist oder eine Korrektur einen neuen Befund eingeführt hat. Wiederhole, bis die bestätigten Befunde gelöst sind oder du erklärt hast, warum einer nicht im Code behoben werden kann (z.B. benötigt Untertitel-Inhalte vom Benutzer). Führe die eigenen Tests/Linters des Projekts aus.

Phase 5 – Bericht

Schreibe .wcag-audit/findings.json gemäß assets/report-schema.json und validiere es:

node <skill-dir>/scripts/validate-findings.mjs .wcag-audit/findings.json

Schreibe dann .wcag-audit/REPORT.md und gib dem Benutzer eine kurze Zusammenfassung, gemäß references/REPORTING.md: Anzahl nach Schweregrad und Urteil, was behoben wurde, was seine Eingabe erfordert, was nicht getestet wurde.

Schweregrad

SchweregradBedeutungBeispiele
kritischBlockiert eine Aufgabe für einige Benutzer vollständigunbeschriftetes Formularfeld, <div onClick> als einzige Möglichkeit zum Absenden, Tastaturfalle, Zoom deaktiviert
schwerwiegendGroße Schwierigkeiten oder fehlende Informationenniedriger Kontrast des Fließtexts, fehlende Seitensprache, Link ohne Namen
moderatReibung, verwirrende Strukturübersprungene Überschriftsebenen, redundanter oder vager Linktext im Kontext
geringFeinschliff, Best Practicevager Alternativtext, Autofokus

Der Schweregrad spiegelt die Auswirkungen auf den Benutzer in dieser Benutzeroberfläche wider, nicht den Standard der Regel: Ein unbeschriftetes Suchfeld in einer Fußzeile ist weniger schwerwiegend als ein unbeschriftetes Passwortfeld auf der Login-Seite.

Antimuster (nicht tun)

  • Füge kein aria-label hinzu, das sichtbaren Text dupliziert oder widerspricht (verstößt gegen WCAG 2.5.3).
  • Füge kein role="button" + tabindex="0" hinzu, wenn <button> funktioniert.
  • „Korrigiere" keinen Befund zur Überschrift-Reihenfolge, indem du die visuelle Größe änderst; ändere die Ebene und behalte das CSS.
  • Setze kein alt="" auf informative Bilder, um den Scanner zu beruhigen.
  • Unterdrücke keine Befunde (wcag-audit-ignore) ohne einen schriftlichen Grund neben dem Kommentar.
  • Beanspruche keine WCAG-„Konformität" – automatisierte + Agenten-Überprüfung können Fehler aufzeigen, nicht Konformität.
  • Ändere keinen generierten, vendored oder node_modules-Code; korrigiere die Quellkomponente.

Dateien

Verwandte Skills