bbb-a11y-audit

Auditer le client HTML5 de BigBlueButton selon WCAG 2.2 niveau A et AA (EN 301 549 clause 9), un sujet à la fois (une directive, un principe ou un critère) ou l'ensemble du client, et produire un rapport HTML organisé par principe, directive et critère, où chaque critère se termine en échec, succès ou non applicable, avec preuves, captures d'écran annotées, correctifs et priorités. Combine une analyse statique, une exécution axe-core/Playwright dans une réunion en direct et une revue de code guidée, et compare avec la précédente exécution du même sujet. À utiliser lorsque l'utilisateur demande un audit d'accessibilité ou WCAG, pour auditer une directive ou un critère, pour un rapport d'accessibilité, ou pour vérifier les régressions d'accessibilité d'un composant ou d'une branche.

Qu'est-ce que bbb-a11y-audit ?

Ce skill permet de réaliser un audit d'accessibilité complet et reproductible du client HTML5 de BigBlueButton, conformément aux normes WCAG 2.2 niveau A et AA (EN 301 549 clause 9). Il fonctionne par sujet (directive, principe ou critère) ou en mode complet, et produit un rapport HTML structuré avec preuves, captures d'écran annotées et correctifs. L'audit est conçu pour être fiable : les résultats sont stables d'une exécution à l'autre, chaque constatation doit être prouvée (code source, capture d'écran, journal), et les critères non testés sont clairement identifiés. Le skill combine trois couches : une analyse statique (scanne les fichiers source avec des règles personnalisées et ESLint), une exécution dynamique avec axe-core/Playwright dans une réunion BigBlueButton réelle (neuf scénarios différents, avec contrôles de clavier, de réaffichage, d'espacement du texte, de contrastes et d'annonces ARIA), et une revue de code guidée pour les critères qui ne peuvent pas être automatisés. Il gère également la comparaison avec l'exécution précédente du même sujet, garantissant que les mêmes problèmes ne sont pas rapportés deux fois et que les correctifs sont suivis. Le skill est destiné aux développeurs et aux auditeurs d'accessibilité qui travaillent sur BigBlueButton, et peut être invoqué via des commandes spécifiques dans l'agent (par exemple `/bbb-a11y-audit directive 2.1`, `/bbb-a11y-audit critère 2.4.7`, `/bbb-a11y-audit complet`). Il est également utile pour vérifier les régressions d'accessibilité lors de modifications de code, grâce au mode `diff` qui compare la branche actuelle avec une référence.

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

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Audit d'accessibilité (WCAG 2.2 AA)

Produire une liste honnête de problèmes d'accessibilité pour le sujet choisi, pouvant être transformée en petites tâches et corrigée dans le cadre de la phase. L'audit est en lecture seule : ne pas modifier le code de l'application pendant l'audit, même pour des correctifs évidents. La correction fait l'objet d'une demande séparée.

Répertoire du skill : le dossier qui contient ce SKILL.md (ci-dessous : $SKILL ; dans ce dépôt, généralement .claude/skills/bbb-a11y-audit). Références, à lire lorsque l'étape en a besoin :

  • references/criteria.md : les 55 critères, quelle couche peut évaluer chacun, les points chauds BBB, les règles de couverture
  • references/rubric.md : impact, effort, cette phase ou backlog, regroupement, clés stables, le schéma findings.input.json
  • references/static-patterns.md : outils statiques, comment trier chaque motif, correspondances eslint et axe
  • references/bbb-map.md : flux, emplacements de code, composants partagés, comment exécuter la couche d'exécution
  • references/manual-checks.md : scripts de lecteur d'écran
  • runtime/ : la couche d'exécution, installée dans la suite Playwright de BigBlueButton lors de la première utilisation : wcagAudit.spec.ts (les scénarios), wcagAuditRecorder.ts (axe, captures d'écran, un JSON par scénario), wcagAuditChecks.ts (clavier, réaffichage, espacement du texte, infobulles, retour de focus, états ARIA) et wcagAuditAnnouncements.ts (enregistre ce qui atteint les régions live)

1. Portée et mode

Le mode de travail normal est un sujet à la fois : choisir une directive, auditer tout ce qu'elle contient, corriger ce qui a été trouvé, auditer à nouveau jusqu'à ce que ce soit terminé, puis passer à la suivante. Un audit complet est l'aperçu occasionnel utilisé pour choisir le prochain sujet.

InvocationModePortée
/bbb-a11y-audit directriz 2.1 (ou guideline ; plusieurs : directriz 2.1 2.4 ; un principe entier : principio 2)guidelinechaque critère du sujet, sur l'ensemble du client et de chaque flux, décidé complètement. Tout le reste est exclu de l'exécution et du rapport.
/bbb-a11y-audit criterio 2.4.7 (ou criterion)criterionun ou plusieurs critères, même profondeur
/bbb-a11y-audit ou fullfullles 55 critères (aperçu / carte)
/bbb-a11y-audit <chemin>pathce dossier ou fichier, tous les critères
/bbb-a11y-audit diff [base]difffichiers modifiés par rapport à git merge-base HEAD <base> (base par défaut : la branche principale du dépôt, v4.1.x-develop) sous bigbluebutton-html5/
ajouter --no-runtimesauter la couche d'exécution
ajouter --server <url> --secret <secret>exécuter la couche d'exécution sur un autre serveur de test BigBlueButton au lieu de celui dans bigbluebutton-tests/playwright/.env (<url> comme https://host/bigbluebutton/)

Si la demande est ambiguë, choisir le mode le plus proche et dire lequel a été utilisé. Ne pas demander.

Créer le répertoire d'exécution à la racine du dépôt : a11y-reports/<YYYY-MM-DD_HHMM>[_<topic>]/raw/, par exemple 2026-11-20_1430_d2.1 ou 2026-11-20_1500_full. Il doit commencer par la date et l'heure : le rapport compare avec les exécutions plus anciennes du même sujet, c'est-à-dire les mêmes critères, quelle que soit la façon dont ils ont été demandés (principio 4 et directriz 4.1 sont le même sujet), ou, la première fois, avec la dernière exécution complète restreinte au sujet. L'audit ne doit laisser aucune trace dans le dépôt : si git check-ignore -q a11y-reports/ échoue, ajouter a11y-reports/ à .git/info/exclude (local à ce clone, jamais à .gitignore).

En mode guideline et criterion, définir meta.guidelines / meta.criteria dans findings.input.json (un principe est une entrée de directive d'un chiffre : principio 2 est "guidelines": ["2"]), et dans chaque couche, ne regarder que ce qui peut informer le sujet (chaque étape ci-dessous le précise). Les critères hors sujet sont automatiquement exclus.

Règles de cohérence (à lire avant d'auditer)

Deux exécutions sur le même code doivent aboutir au même résultat, et chaque constatation doit être réelle. Donc :

  1. Partir de l'exécution précédente. Avant de chercher quoi que ce soit de nouveau, ouvrir le findings.json de la dernière exécution de ce sujet (ou de la dernière exécution complète). Revérifier chaque constatation précédente et chaque entrée discarded par rapport au code actuel : toujours présent → conserver sa key (ou définir son id) ; disparu → ce n'est pas une constatation, et dire dans meta.summary pourquoi il a disparu (code modifié, ou c'était une erreur). Si le commit est le même que celui de l'exécution (meta.commit) et qu'une constatation semble disparue, supposer qu'elle a été manquée et regarder à nouveau avant de la supprimer.
  2. Répondre à la liste de vérification, puis explorer. Si references/checklists.json a des éléments pour un critère dans la portée, répondre à chaque élément avec pass, fail ou na et des preuves (coverage[c].checklist). La liste de vérification est le minimum, pas le maximum : chercher ensuite tout ce qui peut faire échouer ce critère dans BBB et écrire ce qui a été recherché dans coverage[c].explored. Les éléments récurrents trouvés en dehors de la liste de vérification valent la peine d'être proposés comme nouveaux éléments de liste dans le message final.
  3. Prouver chaque constatation. Les constatations statiques et de revue comportent quote, le code exact à location.line ; build-report.mjs rejette les constatations dont le fichier, la ligne ou la citation n'existe pas. Les constatations d'exécution pointent vers la règle et l'écran dont elles proviennent (shots). Pas de preuve, pas de constatation.
  4. Pas de remplissage. Une constatation est un correctif ; fusionner les doublons ; ne pas diviser un problème pour allonger la liste, et ne pas signaler des préférences de style ou des bonnes pratiques qui ne font pas échouer un critère. En cas de doute, vérifier à nouveau ; si ce n'est toujours pas clair, écrire un script de lecteur d'écran au lieu d'une constatation.

2. Couche statique

node $SKILL/scripts/static-scan.mjs [--guidelines=2.1] <chemins de portée…> > <run>/raw/static.json
$SKILL/scripts/eslint-a11y.sh <run>/raw/eslint.json <chemins de portée…>

Avec un sujet, passer --guidelines au scan (il ne conserve que les motifs du sujet) et trier uniquement les messages eslint dont la règle correspond au sujet (references/static-patterns.md).

Trier ensuite chaque candidat comme décrit dans references/static-patterns.md : ouvrir le code, décider, regrouper par cause racine. Les candidats rejetés vont dans discarded avec une raison. Si une exécution précédente existe, lire sa liste discarded de findings.json et réutiliser les décisions pour le code non modifié au lieu de le relire.

3. Couche d'exécution

D'abord, s'assurer que les fichiers d'exécution sont installés, en suivant "Setting up the runtime layer" dans references/bbb-map.md : chaque fichier dans $SKILL/runtime/ doit être dans la suite Playwright de BigBlueButton, et @axe-core/playwright dans ses dépendances. Les copier et installer le package est une configuration, pas une modification de code de l'application ; le faire lorsqu'ils sont manquants ou obsolètes et le mentionner dans le message final.

Avec --server/--secret, les passer comme variables d'environnement BBB_URL et BBB_SECRET sur la commande Playwright (elles ont priorité sur .env ; ne jamais les écrire dans .env). Le rapport enregistre le serveur audité et sa version du client (meta.server) ; si cette version n'est pas le commit du checkout local, dire dans meta.summary que les constatations d'exécution proviennent de la version de ce serveur et que leurs références de fichier et de ligne pointent vers le code local, qui peut différer.

Ensuite, vérifier s'il peut s'exécuter (bigbluebutton-tests/playwright/.env, ou --server/--secret, donne des valeurs non vides pour BBB_URL et BBB_SECRET, node_modules existe, Chromium est installé). Si quelque chose manque, sauter la couche, enregistrer "ran": false avec une courte reason, et dire à l'utilisateur dans le message final exactement quoi configurer. Ne pas essayer d'installer un serveur BigBlueButton ou de modifier .env.

Lorsqu'il peut s'exécuter, suivre "Running the runtime layer" dans references/bbb-map.md avec A11Y_AUDIT_DIR=<abs run dir>/raw/runtime, plus A11Y_GUIDELINES=<sujet> dans les modes de sujet (par exemple 2.1) : la spec saute alors les vérifications et les scénarios qui ne peuvent pas informer le sujet et exécute axe uniquement avec les règles du sujet. Exécution complète : environ 15 minutes sur un serveur distant ; un sujet est généralement plus rapide. Prévoir 30 minutes. Il exécute neuf scénarios (tour modérateur, interactions modérateur + participant, salles de sous-commission, hall d'invités, écran de configuration pré-vol, connexion perdue, pt-BR, thème sombre, mobile) et écrit un JSON par scénario plus une capture d'écran de chaque état. Ensuite :

  • Mapper chaque violation axe à son critère via la balise wcag…. Regrouper par règle et cause racine entre les états et les scénarios (la même règle dans de nombreux états est généralement une seule constatation). Tracer les sélecteurs vers les fichiers source.
  • Traiter incomplete et les vérifications personnalisées (keyboard.noOutlineOrShadow, keyboard.obscured, reflow.offenders, textSpacing.newlyClipped, nonTextContrast) comme des candidats : confirmer avant de signaler. Les rejetés vont dans discarded.
  • Lire announcements (ce qui a atteint les régions live, par acteur et moment) pour 4.1.3 et 4.1.2 : un moment sans annonce là où une est attendue (quelqu'un est parti, un sondage a commencé) est un candidat ; regionCreatedWithMessage: true signifie que la région a été insérée avec son texte et peut ne pas être lue.
  • Regarder les captures d'écran des états avec des constatations (raw/runtime/shots/), et attacher shots aux constatations (voir references/rubric.md) afin que le rapport montre où se trouve chaque problème.
  • Un état avec ok: false ou une vérification avec une erreur signifie qu'il n'a pas été audité. Le lister sous meta.notCovered ; ne pas marquer ses critères pass à cause de cela.

En mode diff et path, ne conserver que les constatations d'exécution qui remontent dans la portée.

4. Revue guidée

Pour les critères marqués V dans references/criteria.md qui sont dans la portée, lire le code des flux pertinents de references/bbb-map.md jusqu'à ce que chaque critère soit décidé. En mode full, commencer par les flux de base ; en mode guideline et criterion, parcourir chaque flux dans bbb-map.md pour les critères dans la portée. Lister dans meta.reviewedFlows ce qui a été lu. Chaque constatation de revue a besoin d'une preuve de fichier et de ligne ; lorsqu'il n'est pas possible de confirmer le comportement sans l'exécuter, utiliser "confidence": "likely" et dire quoi confirmer.

Ne pas signaler ce qui ne peut pas être pointé. Si quelque chose ne peut être confirmé que par une personne, écrire un script (references/manual-checks.md) ; s'il peut être confirmé en lisant plus de code ou les données d'exécution, faire cela à la place.

5. Classifier, couvrir, script

  • Classifier chaque constatation avec references/rubric.md (impact, effort, partagé, externe, clé).
  • Maintenir les ID stables entre les exécutions (règle de cohérence 1) : réutiliser la key précédente, ou définir id explicitement, pour chaque problème qui est toujours présent.
  • Remplir coverage pour chaque critère dans la portée qui n'est pas en échec (et ajouter method/how à ceux en échec aussi), en suivant la règle de couverture dans references/criteria.md : pass ou na avec method et how, human uniquement pour ce qui nécessite vraiment une personne (avec son script), not-covered uniquement lorsque cette exécution n'a pas pu le décider (avec ce qui manque). L'objectif est qu'une directive puisse être fermée sans rien laisser d'ouvert ; build-report.mjs refuse les entrées manquantes.
  • Écrire manualChecks uniquement pour ce que l'automatisation ne peut pas répondre : un pour chaque critère human. Si un véritable lecteur d'écran est nécessaire pour confirmer quelque chose que l'exécution a déjà décidé, l'ajouter avec "optional": true ; ne jamais écrire de script pour quelque chose que les données d'exécution ou le code peuvent décider (les changements d'état, les annonces, les compte à rebours, la sélection de périphérique sont tous enregistrés).
  • Remplir meta.summary, meta.reviewedFlows et meta.notCovered : ils constituent l'onglet "O que foi testado", qui indique au lecteur exactement ce qui a été et n'a pas été vérifié.

6. Construire le rapport

Écrire <run>/raw/findings.input.json (schéma dans references/rubric.md), puis :

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

Il valide l'entrée (corriger et réexécuter s'il se plaint), attribue des ID stables, place chaque constatation dans cette phase ou le backlog, ajoute la clause EN 301 549, vérifie que chaque fichier, ligne et citation existe, vérifie que chaque élément de la liste de vérification a reçu une réponse, enregistre la comparaison avec l'exécution précédente dans findings.json (pour la prochaine exécution ; le rapport ne l'affiche pas) et écrit <run>/findings.json et <run>/report.html. Ouvrir le rapport pour l'utilisateur (xdg-open sur Linux, open sur macOS).

7. Informer l'utilisateur

Garder le message de chat court ; le rapport contient les détails :

  • verdict, quels critères réussissent et lesquels échouent, combien de constatations sont pour cette phase et combien sont allées dans le backlog (avec pourquoi)
  • par directive : terminé, combien de critères échouent, ou ce qui est encore ouvert (human, not-covered)
  • quelles couches ont été exécutées, lesquelles ont été sautées et pourquoi, quels états de réunion ou flux n'ont pas été couverts
  • le bloquant et les constatations à fort impact sur une ligne chacun (titre, critère, fichier)
  • les nouveaux éléments de liste de vérification proposés, si l'exploration a trouvé des problèmes récurrents en dehors de la liste de vérification
  • le chemin du rapport

Proposer de transformer les constatations en tâches, regroupées par directive (une phase par directive, une tâche par constatation, plus une tâche par critère human). Ne pas ouvrir de problèmes ou de PR sauf demande explicite.

Sécurité : si une constatation pourrait être exploitée (par exemple un contournement d'authentification trouvé lors de la vérification de 3.3.8), la laisser en dehors du rapport et informer l'utilisateur en privé de suivre la politique de sécurité du dépôt (avis privé, pas de problème ou de PR public).

Skills associés