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
- 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.
- Natives HTML zuerst. Das beste ARIA ist kein ARIA. Korrigiere
<div onClick>indem du es zu einem<button>machst, nicht durch Anbringen vonrole,tabindexund Tasten-Handlern. - 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).
- 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_validationund frage nach; schreibe nichtalt="image". - 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:
- Nimm die kleinste Änderung vor, die das Kriterium erfüllt, im Idiom des Frameworks (
htmlForin React,:aria-labelin Vue usw.). - Erkläre es in ein oder zwei Sätzen: Was war falsch, wen es betraf, was sich geändert hat.
- 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
| Schweregrad | Bedeutung | Beispiele |
|---|---|---|
| kritisch | Blockiert eine Aufgabe für einige Benutzer vollständig | unbeschriftetes Formularfeld, <div onClick> als einzige Möglichkeit zum Absenden, Tastaturfalle, Zoom deaktiviert |
| schwerwiegend | Große Schwierigkeiten oder fehlende Informationen | niedriger Kontrast des Fließtexts, fehlende Seitensprache, Link ohne Namen |
| moderat | Reibung, verwirrende Struktur | übersprungene Überschriftsebenen, redundanter oder vager Linktext im Kontext |
| gering | Feinschliff, Best Practice | vager 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-labelhinzu, 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
- references/RULES.md – jede statische und Laufzeitregel, zugeordnet zu WCAG
- references/STATIC-SCAN.md – Phase 1 manuelle Überprüfung nach Framework
- references/RUNTIME-SCAN.md – Phase 2 Seiten, Zustände, SPAs, Authentifizierung
- references/VERIFICATION.md – Phase 3 Widerlegungsverfahren pro Regel
- references/FIX-PATTERNS.md – Phase 4 Vorher/Nachher-Korrekturen
- references/REPORTING.md – Phase 5 Berichtsformat
- references/MANUAL-CHECKLIST.md – was Automatisierung nicht prüfen kann
- assets/report-schema.json – Schema für findings.json
scripts/validate-findings.mjs– abhängigkeitsfreier Validator für findings.json