CommunityCodierung & Entwicklunggithub.com

bbb-a11y-audit

Auditiere den BigBlueButton HTML5-Client gegen WCAG 2.2 Level A und AA (EN 301 549 Abschnitt 9), ein Thema nach dem anderen (eine Richtlinie, ein Prinzip oder ein Kriterium) oder den gesamten Client, und erstelle einen HTML-Bericht, organisiert nach Prinzip, Richtlinie und Kriterium, wobei jedes Kriterium als fehlgeschlagen, bestanden oder nicht anwendbar endet, mit Belegen, kommentierten Screenshots, Korrekturen und Prioritäten. Kombiniert einen statischen Scan, einen axe-core/Playwright-Lauf gegen eine Live-Sitzung und eine geführte Code-Überprüfung und vergleicht mit dem vorherigen Lauf desselben Themas. Verwende dies, wenn der Benutzer nach einem Barrierefreiheits- oder WCAG-Audit fragt, um eine Richtlinie oder ein Kriterium zu auditieren, für einen a11y-Bericht oder um eine Komponente oder einen Branch auf Barrierefreiheits-Rückschritte zu überprüfen.

Was ist bbb-a11y-audit?

Dieses Skill für KI-Agenten führt ein umfassendes, mehrschichtiges Barrierefreiheitsaudit des BigBlueButton HTML5-Clients durch. Es kombiniert einen statischen Code-Scan mit eslint und einem benutzerdefinierten Skript, einen Live-Test mit axe-core und Playwright in einer echten BBB-Konferenz sowie eine manuelle Code-Überprüfung. Der Skill ist für die Arbeit in Iterationen konzipiert: Ein Benutzer kann ein einzelnes WCAG-Kriterium, eine Richtlinie oder ein ganzes Prinzip auditieren und erhält einen detaillierten HTML-Bericht. Der Bericht gruppiert die Ergebnisse nach Prinzip, Richtlinie und Kriterium und enthält Belege, Screenshots, Priorisierungen und Korrekturempfehlungen. Eine wichtige Eigenschaft ist die konsistenzbasierte Wiederholbarkeit: Der Skill vergleicht automatisch mit vorherigen Läufen desselben Themas und stellt sicher, dass bereits identifizierte Probleme nicht verloren gehen oder doppelt gemeldet werden. Dadurch eignet er sich ideal für schrittweise WCAG-Konformitätsprojekte und Regressionstests. Unterstützte Plattformen: Der Skill wird in KI-Agenten-Umgebungen wie Claude Code, Cursor, Codex oder ähnlichen verwendet und interagiert mit einem lokalen BigBlueButton-Repository, Playwright und Node.js-Skripten.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gugeldev/bbb-a11y-audit/tree/main/bbb-a11y-audit

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

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

Dokumentation

Barrierefreiheitsaudit (WCAG 2.2 AA)

Erstelle eine ehrliche Liste von Barrierefreiheitsproblemen für das gewählte Thema, die in kleine Aufgaben umgewandelt und innerhalb der Phase behoben werden können. Das Audit ist schreibgeschützt: Ändere während des Audits keinen Anwendungscode, nicht einmal für offensichtliche Korrekturen. Die Behebung ist eine separate Anfrage.

Skill-Verzeichnis: der Ordner, der diese SKILL.md enthält (im Folgenden: $SKILL; in diesem Repository normalerweise .claude/skills/bbb-a11y-audit). Referenzen, die bei Bedarf gelesen werden:

  • references/criteria.md: die 55 Kriterien, welche Schicht jedes bewerten kann, BBB-Hotspots, Abdeckungsregeln
  • references/rubric.md: Auswirkung, Aufwand, diese Phase oder Backlog, Gruppierung, stabile Schlüssel, das Schema von findings.input.json
  • references/static-patterns.md: statische Werkzeuge, wie man jedes Muster triagiert, eslint- und axe-Zuordnungen
  • references/bbb-map.md: Abläufe, Code-Stellen, gemeinsame Komponenten, wie die Laufzeitschicht ausgeführt wird
  • references/manual-checks.md: Screenreader-Skripte
  • runtime/: die Laufzeitschicht, die bei der ersten Verwendung in die BigBlueButton Playwright-Suite installiert wird: wcagAudit.spec.ts (die Szenarien), wcagAuditRecorder.ts (axe, Screenshots, ein JSON pro Szenario), wcagAuditChecks.ts (Tastatur, Reflow, Textabstand, Tooltips, Fokus-Rückkehr, ARIA-Zustände) und wcagAuditAnnouncements.ts (zeichnet auf, was Live-Regionen erreicht)

1. Umfang und Modus

Die normale Arbeitsweise ist ein Thema nach dem anderen: Wähle eine Richtlinie aus, auditiere alles darin, behebe die Funde, auditiere erneut, bis es abgeschlossen ist, und fahre dann mit dem nächsten fort. Ein vollständiges Audit ist der gelegentliche Überblick, der zur Auswahl des nächsten Themas dient.

AufrufModusUmfang
/bbb-a11y-audit diretriz 2.1 (oder guideline; mehrere: diretriz 2.1 2.4; ein ganzes Prinzip: principio 2)guidelinejedes Kriterium des Themas, gesamter Client und alle Abläufe, vollständig entschieden. Alles andere bleibt außerhalb des Laufs und des Berichts.
/bbb-a11y-audit criterio 2.4.7 (oder criterion)criterionein oder mehrere Kriterien, gleiche Tiefe
/bbb-a11y-audit oder fullfullalle 55 Kriterien (Überblick / Karte)
/bbb-a11y-audit <path>pathdieser Ordner oder diese Datei, alle Kriterien
/bbb-a11y-audit diff [base]diffgeänderte Dateien vs. git merge-base HEAD <base> (Standard-Base: der Hauptbranch des Repos, v4.1.x-develop) unter bigbluebutton-html5/
Ergänzung --no-runtimeüberspringt die Laufzeitschicht
Ergänzung --server <url> --secret <secret>führt die Laufzeitschicht gegen einen anderen BigBlueButton-Testserver aus statt gegen den in bigbluebutton-tests/playwright/.env (<url> wie https://host/bigbluebutton/)

Wenn die Anfrage mehrdeutig ist, wähle den nächstgelegenen Modus und gib an, welchen du verwendet hast. Frage nicht nach.

Erstelle das Ausführungsverzeichnis im Stammverzeichnis des Repos: a11y-reports/<YYYY-MM-DD_HHMM>[_<topic>]/raw/, z.B. 2026-11-20_1430_d2.1 oder 2026-11-20_1500_full. Es muss mit Datum und Uhrzeit beginnen: Der Bericht vergleicht mit älteren Läufen desselben Themas, d.h. derselben Kriterien, unabhängig davon, wie sie angefragt wurden (principio 4 und diretriz 4.1 sind dasselbe Thema), oder, beim ersten Mal, gegen den letzten vollständigen Lauf, eingeschränkt auf das Thema. Das Audit darf keine Spuren im Repository hinterlassen: Wenn git check-ignore -q a11y-reports/ fehlschlägt, füge a11y-reports/ zu .git/info/exclude hinzu (lokal für diesen Clone, niemals zu .gitignore).

Setze in den Modi guideline und criterion in findings.input.json die meta.guidelines / meta.criteria (ein Prinzip ist ein Richtlinieneintrag mit einer Ziffer: principio 2 ist "guidelines": ["2"]), und betrachte in jeder Schicht nur das, was das Thema informieren kann (jeder Schritt unten sagt wie). Kriterien außerhalb des Themas werden automatisch ausgelassen.

Konsistenzregeln (vor dem Audit lesen)

Zwei Läufe auf demselben Code müssen zum gleichen Ergebnis führen, und jeder Fund muss echt sein. Also:

  1. Beginne mit dem vorherigen Lauf. Bevor du nach etwas Neuem suchst, öffne die findings.json des letzten Laufs dieses Themas (oder des letzten vollständigen Laufs). Überprüfe jeden vorherigen Fund und jeden discarded-Eintrag erneut gegen den aktuellen Code: noch vorhanden → behalte seinen key (oder setze seine id); weg → es ist kein Fund, und sag in meta.summary, warum es weg ist (Code geändert, oder es war falsch). Wenn der Commit derselbe ist wie der dieses Laufs (meta.commit) und ein Fund scheinbar weg ist, nimm an, dass du ihn übersehen hast, und schau noch einmal nach, bevor du ihn verwirfst.
  2. Beantworte die Checkliste, dann erkunde. Wenn references/checklists.json Elemente für ein Kriterium im Umfang enthält, beantworte jedes Element mit pass, fail oder na und Belegen (coverage[c].checklist). Die Checkliste ist das Minimum, nicht die Obergrenze: Suche dann nach allem anderen, was dieses Kriterium in BBB verletzen könnte, und schreibe, wonach du gesucht hast, in coverage[c].explored. Wiederkehrende Dinge, die du außerhalb der Checkliste findest, sind es wert, in der abschließenden Nachricht als neue Checklisten-Elemente vorgeschlagen zu werden.
  3. Belege jeden Fund. Statische und Überprüfungsfunde enthalten quote, den genauen Code an location.line; build-report.mjs lehnt Funde ab, deren Datei, Zeile oder Quote nicht existiert. Laufzeitfunde verweisen auf die Regel und den Bildschirm, von dem sie stammen (shots). Kein Beleg, kein Fund.
  4. Keine Aufblähung. Ein Fund ist eine Korrektur; führe Duplikate zusammen; teile ein Problem nicht auf, um die Liste länger zu machen, und melde keine Stilpräferenzen oder Best Practices, die kein Kriterium verletzen. Wenn du dir unsicher bist, überprüfe es noch einmal; wenn es immer noch unklar ist, schreibe ein Screenreader-Skript anstelle eines Fundes.

2. Statische Schicht

node $SKILL/scripts/static-scan.mjs [--guidelines=2.1] <scope paths…> > <run>/raw/static.json
$SKILL/scripts/eslint-a11y.sh <run>/raw/eslint.json <scope paths…>

Mit einem Thema übergibst du --guidelines an den Scan (er behält nur die Muster des Themas) und triagierst nur die eslint-Meldungen, deren Regel auf das Thema abbildet (references/static-patterns.md).

Triagiere dann jeden Kandidaten wie in references/static-patterns.md beschrieben: öffne den Code, entscheide, gruppiere nach Ursache. Abgelehnte Kandidaten gehen mit einem Grund zu discarded. Wenn ein vorheriger Lauf existiert, lies seine discarded-Liste in findings.json und verwende Entscheidungen für unveränderten Code erneut, anstatt ihn erneut zu lesen.

3. Laufzeitschicht

Stelle zunächst sicher, dass die Laufzeitdateien installiert sind, indem du "Setting up the runtime layer" in references/bbb-map.md befolgst: Jede Datei in $SKILL/runtime/ muss in der BigBlueButton Playwright-Suite sein, und @axe-core/playwright in ihren Abhängigkeiten. Das Kopieren und Installieren des Pakets ist Einrichtung, keine Codeänderung an der Anwendung; führe es durch, wenn es fehlt oder veraltet ist, und erwähne es in der abschließenden Nachricht.

Mit --server/--secret übergibst du diese als Umgebungsvariablen BBB_URL und BBB_SECRET an den Playwright-Befehl (sie haben Vorrang vor .env; schreibe sie niemals in .env). Der Bericht zeichnet den auditierten Server und seinen Client-Build auf (meta.server); wenn dieser Build nicht der Commit des lokalen Checkouts ist, sag in meta.summary, dass die Laufzeitfunde von der Version dieses Servers stammen und ihre Datei- und Zeilenverweise auf den lokalen Code verweisen, der abweichen kann.

Überprüfe dann, ob es ausgeführt werden kann (bigbluebutton-tests/playwright/.env oder --server/--secret geben nicht-leere BBB_URL und BBB_SECRET, node_modules existiert, ein Chromium ist installiert). Wenn etwas fehlt, überspringe die Schicht, zeichne "ran": false mit einem kurzen reason auf und teile dem Benutzer in der abschließenden Nachricht mit, was genau eingerichtet werden muss. Versuche nicht, einen BigBlueButton-Server zu installieren oder .env zu bearbeiten.

Wenn es ausgeführt werden kann, folge "Running the runtime layer" in references/bbb-map.md mit A11Y_AUDIT_DIR=<abs run dir>/raw/runtime, plus A11Y_GUIDELINES=<topic> in Themenmodi (z.B. 2.1): Die Spezifikation überspringt dann die Prüfungen und Szenarien, die das Thema nicht informieren können, und führt axe nur mit den Regeln des Themas aus. Vollständiger Lauf: etwa 15 Minuten auf einem entfernten Server; ein Thema ist normalerweise schneller. Erlaube 30 Minuten. Es führt neun Szenarien aus (Moderator-Tour, Moderator-+ Teilnehmer-Interaktionen, Breakout-Räume, Gästelobby, Vorkonfigurationsbildschirm, Verbindung verloren, pt-BR, dunkles Thema, mobil) und schreibt ein JSON pro Szenario plus einen Screenshot jedes Zustands. Dann:

  • Ordne jede axe-Verletzung über das wcag…-Tag ihrem Kriterium zu. Gruppiere nach Regel und Ursache über Zustände und Szenarien hinweg (dieselbe Regel in vielen Zuständen ist normalerweise ein Fund). Verfolge Selektoren zu Quelldateien.
  • Behandle incomplete und die benutzerdefinierten Prüfungen (keyboard.noOutlineOrShadow, keyboard.obscured, reflow.offenders, textSpacing.newlyClipped, nonTextContrast) als Kandidaten: Bestätige vor der Meldung. Abgelehnte gehen zu discarded.
  • Lese announcements (was Live-Regionen erreicht hat, nach Akteur und Zeitpunkt) für 4.1.3 und 4.1.2: Ein Zeitpunkt ohne Ankündigung, an dem eine erwartet wird (jemand hat die Sitzung verlassen, eine Umfrage wurde gestartet), ist ein Kandidat; regionCreatedWithMessage: true bedeutet, dass die Region mit ihrem Text eingefügt wurde und möglicherweise nicht vorgelesen wird.
  • Betrachte die Screenshots von Zuständen mit Funden (raw/runtime/shots/) und füge shots zu den Funden hinzu (siehe references/rubric.md), damit der Bericht zeigt, wo jedes Problem ist.
  • Ein Zustand mit ok: false oder eine Prüfung mit einem Fehler bedeutet, dass er/sie nicht auditiert wurde. Führe es unter meta.notCovered auf; markiere seine Kriterien deswegen nicht als pass.

Behalte in den Modi diff und path nur die Laufzeitfunde, die in den Umfang zurückverfolgt werden können.

4. Geführte Überprüfung

Für Kriterien, die in references/criteria.md mit V markiert sind und im Umfang liegen, lies den Code der relevanten Abläufe aus references/bbb-map.md, bis jedes Kriterium entschieden ist. Beginne im Modus full mit den Kernabläufen; gehe in den Modi guideline und criterion jeden Ablauf in bbb-map.md für die Kriterien im Umfang durch. Führe in meta.reviewedFlows auf, was du gelesen hast. Jeder Überprüfungsfund benötigt Datei- und Zeilenbelege; wenn du das Verhalten nicht bestätigen konntest, ohne es auszuführen, verwende "confidence": "likely" und sag, was bestätigt werden soll.

Melde nicht, worauf du nicht zeigen kannst. Wenn etwas nur von einer Person bestätigt werden kann, schreibe ein Skript (references/manual-checks.md); wenn es durch Lesen von mehr Code oder der Laufzeitdaten bestätigt werden kann, tue stattdessen das.

5. Klassifizieren, abdecken, skripten

  • Klassifiziere jeden Fund mit references/rubric.md (Auswirkung, Aufwand, gemeinsam, extern, Schlüssel).
  • Halte IDs über Läufe hinweg stabil (Konsistenzregel 1): Verwende den vorherigen key erneut oder setze id explizit für jedes Problem, das noch vorhanden ist.
  • Fülle coverage für jedes im Umfang befindliche Kriterium aus, das nicht fehlschlägt (und füge auch bei fehlschlagenden method/how hinzu), gemäß der Abdeckungsregel in references/criteria.md: pass oder na mit method und how, human nur für das, was wirklich eine Person benötigt (mit ihrem Skript), not-covered nur, wenn dieser Lauf es nicht entscheiden konnte (mit dem, was fehlt). Das Ziel ist, dass eine Richtlinie abgeschlossen werden kann, ohne dass etwas offen bleibt; build-report.mjs weist fehlende Einträge zurück.
  • Schreibe manualChecks nur für das, was die Automatisierung nicht beantworten kann: eines für jedes human-Kriterium. Wenn du möchtest, dass ein echter Screenreader etwas bestätigt, das die Laufzeit bereits entschieden hat, füge es mit "optional": true hinzu; schreibe niemals ein Skript für etwas, das die Laufzeitdaten oder der Code entscheiden können (Zustandsänderungen, Ankündigungen, Countdowns, Geräteauswahl werden alle aufgezeichnet).
  • Fülle meta.summary, meta.reviewedFlows und meta.notCovered: Sie bilden den Tab "O que foi testado", der dem Leser genau sagt, was geprüft wurde und was nicht.

6. Bericht erstellen

Schreibe <run>/raw/findings.input.json (Schema in references/rubric.md), dann:

node $SKILL/scripts/build-report.mjs <run>

Es validiert die Eingabe (korrigiere und führe erneut aus, wenn es sich beschwert), weist stabile IDs zu, ordnet jeden Fund dieser Phase oder dem Backlog zu, fügt die EN 301 549-Klausel hinzu, überprüft, dass jede Datei, Zeile und jedes Zitat existiert, überprüft, dass jedes Checklisten-Element beantwortet ist, zeichnet den Vergleich mit dem vorherigen Lauf in findings.json auf (für den nächsten Lauf; der Bericht zeigt es nicht) und schreibt <run>/findings.json und <run>/report.html. Öffne den Bericht für den Benutzer (xdg-open unter Linux, open unter macOS).

7. Dem Benutzer mitteilen

Halte die Chat-Nachricht kurz; der Bericht enthält die Details:

  • Urteil: welche Kriterien bestanden und welche fehlgeschlagen sind, wie viele Funde für diese Phase sind und wie viele an den Backlog gingen (mit Begründung)
  • Pro Richtlinie: erledigt, wie viele Kriterien fehlschlagen oder was noch offen ist (human, not-covered)
  • Welche Schichten liefen, welche übersprungen wurden und warum, welche Sitzungszustände oder Abläufe nicht abgedeckt wurden
  • Die Blocker- und hochwirksamen Funde als eine Zeile pro Fund (Titel, Kriterium, Datei)
  • Vorgeschlagene neue Checklisten-Elemente, wenn die Erkundung wiederkehrende Probleme außerhalb der Checkliste gefunden hat
  • Der Pfad zum Bericht

Biete an, Funde in Aufgaben umzuwandeln, gruppiert nach Richtlinie (eine Phase pro Richtlinie, eine Aufgabe pro Fund, plus eine Aufgabe pro human-Kriterium). Erstelle keine Issues oder PRs, es sei denn, du wirst darum gebeten.

Sicherheit: Wenn ein Fund ausgenutzt werden könnte (z. B. eine Umgehung der Authentifizierung, die bei der Überprüfung von 3.3.8 gefunden wurde), lasse ihn aus dem Bericht und teile dem Benutzer privat mit, der Sicherheitsrichtlinie des Repositorys zu folgen (private Beratung, kein öffentliches Issue oder PR).

Verwandte Skills