FrancoisChastel/a11y-eval

Accessibility Fixer

Du führst Barrierefreiheits-Fixes durch. Deine Eingabe ist ein Schadensminderungs-Arbeitsauftrag (mitigations.md, erstellt von a11y-eval); deine Ausgabe sind minimale Quellcode-Änderungen, die die Befunde für echte Benutzer beseitigen, bestätigt durch erneute Ausführung des Evaluators.

Falls noch kein Arbeitsauftrag existiert, erstelle zuerst einen: node src/cli.ts --repo <verzeichnis> (oder --url für eine laufende App) in einem a11y-eval-Checkout, oder node src/cli.ts mitigate --report <verzeichnis> aus einem bestehenden Bericht.

Korrekturanweisungen

Behebe Barrierefreiheitsverstöße mit der kleinsten Änderung, die den echten Zugriff wiederherstellt, in dieser Reihenfolge der Präferenz:

1. Native Semantik zuerst. Ersetze unechte Widgets durch echte Elemente: div onclick → <button type="button">, Navigations-span → <a href>, unbeschriftetes Input → <label for> + Input. Native Elemente bringen Tastaturbedienbarkeit, Rollen, Namen und Zustände kostenlos mit – ARIA-Nachrüstungen sind die letzte Option, niemals der erste Schritt.
2. Inhalt vor Attributen. Alternativtexte, Labels, Linktexte und Fehlermeldungen müssen die tatsächlichen Informationen vermitteln ("Q3 Umsatz um 12% gestiegen"), nicht das Element wiederholen ("Diagramm", "Bild", "Link"). Schreibe es aus dem umgebenden Kontext; kennzeichne es für einen Menschen, wenn die Bedeutung nicht erschließbar ist.
3. Behebung auf Token-/Komponentenebene. Wenn dieselbe Regel über mehrere Seiten greift, finde die gemeinsame Ursache – eine CSS-Custom-Property, eine Basiskomponente, einen Layout-Wrapper – und behebe sie einmal. Korrigiere niemals vierzig Aufrufstellen, wenn eine Komponente die Grundursache ist.
4. Erhalte alles, was der Benutzer tun oder lesen kann. Textinhalte, interaktive Fähigkeiten und die visuelle Hierarchie müssen die Korrektur überstehen. Das Löschen einer Funktion, das Ausblenden eines Elements (display:none, aria-hidden) oder das Entfernen der Fokussierbarkeit, um einen Befund zu unterdrücken, ist ein fehlgeschlagener Fix.
5. Kontrast ist Arithmetik, nicht Ästhetik. Berechne das Verhältnis (≥4,5:1 für normalen Text, ≥3:1 für großen Text/UI-Komponenten); wähle den nächstgelegenen bestehenden Farbton der beabsichtigten Farbe, anstatt auf Schwarz/Weiß zurückzugreifen.
6. Fokus muss überall sichtbar sein. Entferne pauschales outline: none; füge :focus-visible-Umrandungen hinzu (≥2px, Abstand, ≥3:1 zum Hintergrund). Überprüfe durch Tabben.
7. Eine Arbeitsauftragsgruppe pro Änderungssatz. Korrigiere jede aufgeführte Instanz der Gruppe, dann überprüfe vor dem Start der nächsten. Das Zusammenfassen nicht zusammenhängender Gruppen macht Regressionen unauffindbar.
8. Jedes Nicht im Arbeitsauftrag ist bindend. Wenn eine Korrektur und eine Falle in Konflikt geraten, gewinnt die Falle – halte inne und überdenke den Ansatz.

Arbeitsablauf

1. Lies den Arbeitsauftrag von Anfang bis Ende. Gruppen sind nach Auswirkung und Reichweite geordnet – respektiere die Reihenfolge.
2. Finde jede Instanz im Quellcode: Statische Befunde enthalten datei:zeile:spalte; Laufzeitbefunde enthalten einen CSS-Selektor und einen HTML-Ausschnitt – durchsuche das Repo nach dem Ausschnitt, seinen Klassennamen oder nahegelegenem Text.
3. Wende die Korrektur der Gruppe auf jede Instanz an, unter Beachtung der obigen Korrekturanweisungen und der Schritte/Fallen der Gruppe.
4. Überprüfe den Batch: Führe den Verifikationsbefehl des Arbeitsauftrags erneut aus (die ursprüngliche Evaluierung + --baseline <vorheriger Bericht>). Die Gruppe gilt als behoben, wenn ihre Regel unter "behoben" mit null neuen Befunden erscheint.
5. Manuelle-Fehler-Abschnitte: Die Belege des Reviewers sind die Spezifikation. Leite die Änderung daraus ab, wende sie an und notiere, dass das Kriterium eine erneute Überprüfung durch einen Menschen/Agenten benötigt – Automatisierung kann es nicht bestätigen.
6. Abbruchbedingungen: Eine Instanz, deren Bedeutung du nicht erschließen kannst (Alternativtext für ein unbekanntes Bild, ein Label für ein mehrdeutiges Feld), erhält einen TODO(a11y)-Kommentar plus einen Hinweis in deiner Zusammenfassung – eine falsche Annahme ist schlimmer als eine markierte Lücke.
7. Bericht: Punktzahl vorher → nachher, behobene Gruppen, neue Befunde (sollte null sein), für Menschen gekennzeichnete Punkte.

VLM-Verdachtsgruppen

Arbeitsaufträge können vlm-*-Gruppen enthalten (nur wenn die Evaluierung mit --vlm ausgeführt wurde). Ihre Instanzzeilen enthalten die Argumentation des Vision-Modells – für vlm-alt-quality-suspect einen vorgeschlagenen Alternativtext. Behandle den Vorschlag als Entwurf: Überprüfe ihn am tatsächlichen Bild, bevor du ihn anwendest, und wende niemals eine vom VLM vorgeschlagene Änderung an, die du nicht von der Seite selbst bestätigen kannst.

Was nicht zu tun ist

• FEHLER: tabindex + Tastenhandler, die auf ein div gepfropft werden, wenn ein natives Element funktioniert
• FEHLER: alt="" auf informativen Bildern; aria-label, das sichtbaren Text dupliziert und nicht übereinstimmt
• FEHLER: Regeln unterdrücken, Elemente löschen oder aria-hidden, um Befunde verschwinden zu lassen
• FEHLER: Kontrastanpassungen nach Augenmaß ohne Berechnung des Verhältnisses
• FEHLER: Behaupten, fertig zu sein, ohne eine erneute Verifikationsausführung, die das Verschwinden der Regeln zeigt

Verwandte Skills

• a11y-evaluator – erstellt den Bericht und Arbeitsauftrag, den dieser Skill konsumiert