Regeln für eine Barrierefreiheitsprüfung schreiben, die bestanden, fehlgeschlagen oder unvollständig melden

## Lint und Tests als Teil jeder Änderung behandeln, nicht als Aufräumarbeit Behandle Formatierung, Linting, Tests, Dokumentation und Commit-Konventionen als Teil der Änderung und nicht als Aufräumarbeiten nach der Implementierung. ### Erforderliche Prüfungen - Führe vor dem Commit den Formatter und Linter des Repositorys aus. - Führe vor dem Abschluss die vollständige Testsuite aus und decke Verhaltensänderungen durch Unit- und Integrationstests ab. - Nutze dokumentierte Ausnahmen nur für Änderungen, die das Laufzeitverhalten nicht beeinflussen können. - Halte ungelöste Arbeiten im Issue-Tracker des Projekts fest, statt sie in nicht zugehörigen Änderungen zu verbergen. - Committe keine vorübergehende Protokollierung oder lokalen Debug-Einstellungen. ### Codekonventionen - Behandle Fehler und Grenzfälle frühzeitig, damit der erfolgreiche Pfad leicht nachvollziehbar bleibt. - Befolge die festgelegte Platzierung von export, die Benennungsregeln und den import-Stil. - Benenne Dateien und Regelbezeichner einheitlich; unterscheide Funktionen, boolesche Werte und Konstanten gemäß den Projektkonventionen. - Deklariere Variablen in der Nähe ihrer ersten Verwendung. - Dokumentiere exportierte APIs, Parameter, Rückgabewerte und komplexe Logik. - Trenne Refaktorierungen von einer gezielten Funktion oder Korrektur. ## Zwischen virtuellen und echten DOM-Knoten wählen und Abhängigkeiten nur in eine Richtung führen Entscheide bewusst zwischen einer Abstraktion des virtuellen Baums und echten DOM-Knoten. Die Abstraktion verarbeitet zwischengespeicherte Attribute und Eigenschaften effizient, während echtes DOM für Browser-APIs und Layoutverhalten erforderlich ist. ### Knotenauswahl - Bevorzuge virtuelle Knoten für Attributzugriff, zwischengespeicherte Eigenschaften, Baumdurchläufe und Selektorarbeit. - Verwende echte DOM-Knoten für Layout, Geometrie, Wurzelsuche, vom Browser berechnetes Verhalten und andere native APIs. - Löse mehrdeutige Eingaben über eine einzige dokumentierte Konvertierungsgrenze auf. - Stütze allgemeine Hilfsfunktionen auf Ein- und Ausgaben mit echtem DOM, sofern eine Abhängigkeit von virtuellen Knoten keinen klaren API- oder Leistungsvorteil bietet. - Verteile Konvertierungslogik nicht auf einzelne Regeln. ### Abhängigkeitsrichtung - Halte Standarddefinitionen als reine Daten ohne Laufzeit-import. - Erlaube Low-Level-Hilfsfunktionen nur über explizite Pfade Abhängigkeiten von noch niedrigerem Basiscode und Standarddaten. - Zentralisiere import von Drittanbietermodulen in einer festgelegten Adapterschicht. - Erlaube gemeinsamen Domänenhilfen, Low-Level-Hilfsfunktionen zu verwenden, aber kehre diese Abhängigkeit niemals um. - Erlaube High-Level-Prüfungen und -Regeln, niedrigere Schichten zusammenzusetzen, ohne Zyklen zu erzeugen. - Erzwinge diese Grenzen mechanisch durch Lint- oder Buildregeln. ## Bestanden, fehlgeschlagen oder unvollständig melden und Meldungen in Metadaten halten Lege den Ergebnisvertrag ausdrücklich fest, damit Verbraucher Konformität, Fehler und unzureichende Nachweise unterscheiden können. ### Prüfergebnisse - Gib `pass` zurück, wenn die geprüfte Bedingung erfüllt ist. - Gib `fail` zurück, wenn gegen die geprüfte Bedingung verstoßen wird. - Gib `incomplete` zurück, wenn die Engine das Ergebnis nicht zuverlässig bestimmen kann. - Füge strukturierte Daten für Meldungsvorlagen und zur Erklärung von `incomplete`-Ergebnissen bei. - Ordne Unsicherheit nicht allein deshalb `pass` oder `fail` zu, um eine binäre Antwort zu erzeugen. ### Regeldefinitionen - Kombiniere Prüfungen mit expliziten Gruppen `all`, `any` und `none`. - Begrenze Kandidatenelemente mit einem Selektor und einem optionalen zusätzlichen Matcher. - Beschränke die Auswirkung auf die vom Projekt deklarierten Schweregradwerte. - Lies HTML- und ARIA-Definitionen aus zentralisierten Standarddaten, statt Listen in Prüfungen fest zu codieren. ### Meldungen für Benutzer - Halte Meldungen in Regel- oder Prüfungsmetadaten statt im Implementierungscode. - Verwende benannte Datenplatzhalter, deren Werte vom Prüfergebnis bereitgestellt werden. - Stelle Singular- und Pluralvarianten bereit, wenn die Grammatik sie erfordert. - Aktualisiere die Lokalisierungsvorlage bei jeder Änderung einer Ausgangsmeldung. ## Farbkontrast und Rollenprüfung besonders sorgfältig überprüfen Einige Ergebnisse zur Barrierefreiheit hängen von unvollständigen Browserinformationen oder sich schnell entwickelnden Standards ab. Diese Bereiche erfordern konservative Ergebnisse und eine gezielte Prüfung. ### Farbe und Sichtbarkeit - Berücksichtige unterstützte Farbformate, Deckkraft, Überblendung, Stapelkontexte und Texteffekte. - Gib `incomplete` zurück, wenn der wirksame Hintergrund oder Kontrast nicht bestimmt werden kann. - Bewerte die Sichtbarkeit für Screenreader semantisch, statt dich allein auf die CSS-Sichtbarkeit zu verlassen. - Beziehe Attribute für ausgeblendete Zustände, zusammengesetzte Bäume und Shadow-DOM-Grenzen ein. ### Semantische Standards - Halte die Validierung von `role` und Attributen mit der aktuellen Spezifikation zur Barrierefreiheit synchron. - Löse implizite und explizite `role` getrennt auf. - Frage zentralisierte Definitionen von `role` und Attributen ab, damit jede Regel dieselbe maßgebliche Quelle verwendet. - Ergänze Regressionsfälle für Aktualisierungen der Spezifikation und zuvor falsch klassifiziertes Markup. - Verlange eine gezielte Prüfung, wenn eine Änderung Ergebnisse über viele Regeln hinweg verändern kann. ## Jede Regel auf realistischen Seiten testen, auch mit Shadow DOM Spiegle die Quellstruktur im Unit-Test-Baum, damit die Zuständigkeit für Implementierung und Tests klar bleibt. ### Unit- und Prüfungstests - Verwende den vom Projekt bereitgestellten Standard-Prüfkontext oder das Harness. - Setze nur den Zustand zurück, der dem Test gehört, wenn gemeinsam verwendete Fixtures und virtuelle Bäume bereits vom Harness bereinigt wurden. - Teste die Ergebnisse `pass`, `fail` und `incomplete` einschließlich der beigefügten Meldungsdaten. - Ergänze vor einer breiten Integrationsabdeckung gezielte Fälle für Randbedingungen. ### Integrationstests - Verknüpfe jedes Regel-Fixture mit strukturierten erwarteten Ergebnissen. - Verwende die kanonische Selektordarstellung der Engine einschließlich verschachtelter Selektoren für Frames. - Verwende eine vollständige HTML-Seite, wenn sich Verhalten auf Dokumentebene nicht durch ein Fragment darstellen lässt. - Ergänze für jede relevante Regel oder Prüfung einen Fall mit open Shadow DOM. - Aktualisiere die Abdeckung virtueller Regeln, wenn eine Änderung die Auswertung des virtuellen Baums betrifft. - Führe während der Iteration gezielte Tests und vor der Übergabe die maßgebliche vollständige Testsuite aus. ## Übersetzungsvorlagen im selben Commit wie die Meldungen neu erzeugen Unterscheide generierte Release-Bundles von generierten Quellartefakten, die das Repository absichtlich verfolgt. ### Artefaktrichtlinie - Bearbeite gebündelte oder minimierte Release-Ausgaben nicht direkt. - Erzeuge verfolgte Vorlagen oder Quellartefakte über den genehmigten Build neu. - Committe eine generierte Lokalisierungsvorlage in derselben Änderung wie die Ausgangsmeldung, aus der sie erzeugt wurde. - Teile synchronisierte Aktualisierungen von Quellen und generierten Inhalten nicht auf getrennte Commits auf. - Halte ignorierte Veröffentlichungs-Bundles aus gewöhnlichen Funktions-Commits heraus. ### Überprüfung - Prüfe den generierten Diff auf unerwartete Änderungen an Meldungen, Gebietsschemata oder Regeln. - Bestätige, dass jeder neue Platzhalter in den erzeugenden Prüfdaten vorhanden ist. - Führe nach Meldungsänderungen die Lokalisierungs- und Buildvalidierung aus. - Dokumentiere, welche Artefakte generiert, welche verfolgt und welche nur für Releases bestimmt sind. ## Changelog und API-Doku aktualisieren und Breaking Changes vermeiden Halte jede Änderung fokussiert und mache ihre öffentlichen Folgen für Prüfende und Verbraucher sichtbar. ### Änderungsdokumentation - Aktualisiere das Änderungsprotokoll, wenn du eine Regel hinzufügst oder wesentlich änderst. - Aktualisiere API-Dokumentation und Typdefinitionen gemeinsam, wenn sich eine öffentliche Schnittstelle ändert. - Verwende die vom Repository vorgeschriebene Form des conventional commit mit einem knappen Betreff und der Begründung im Textkörper. - Verknüpfe das gelöste Issue über den unterstützten Footer oder die Metadaten des Pull Requests. - Schließe vor der Übergabe die Prüfliste des Projekts ab. ### Kompatibilität - Vermeide inkompatible Änderungen, wenn alte und neue Formate gemeinsam unterstützt werden können. - Kennzeichne veraltete APIs deutlich und stelle einen Migrationspfad bereit. - Wenn ein Bruch unvermeidbar ist, benenne ihn ausdrücklich in den Release-Metadaten und im Änderungsprotokoll. - Füge Migrationsanleitungen, aktualisierte Tests, synchronisierte generierte Dateien und für Prüfende sichtbare Nachweise bei. - Behaupte keine Einsatzbereitschaft, bevor Formatierung, Linting, gezielte Tests, Integrationstests, die vollständige Testsuite und Dokumentationsprüfungen tatsächliche Ergebnisse geliefert haben.