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 couverturereferences/rubric.md: impact, effort, cette phase ou backlog, regroupement, clés stables, le schémafindings.input.jsonreferences/static-patterns.md: outils statiques, comment trier chaque motif, correspondances eslint et axereferences/bbb-map.md: flux, emplacements de code, composants partagés, comment exécuter la couche d'exécutionreferences/manual-checks.md: scripts de lecteur d'écranruntime/: 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) etwcagAuditAnnouncements.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.
| Invocation | Mode | Portée |
|---|---|---|
/bbb-a11y-audit directriz 2.1 (ou guideline ; plusieurs : directriz 2.1 2.4 ; un principe entier : principio 2) | guideline | chaque 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) | criterion | un ou plusieurs critères, même profondeur |
/bbb-a11y-audit ou full | full | les 55 critères (aperçu / carte) |
/bbb-a11y-audit <chemin> | path | ce dossier ou fichier, tous les critères |
/bbb-a11y-audit diff [base] | diff | fichiers 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-runtime | sauter 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 :
- Partir de l'exécution précédente. Avant de chercher quoi que ce soit de nouveau, ouvrir le
findings.jsonde 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éediscardedpar rapport au code actuel : toujours présent → conserver sakey(ou définir sonid) ; disparu → ce n'est pas une constatation, et dire dansmeta.summarypourquoi 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. - Répondre à la liste de vérification, puis explorer. Si
references/checklists.jsona des éléments pour un critère dans la portée, répondre à chaque élément avecpass,failounaet 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é danscoverage[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. - Prouver chaque constatation. Les constatations statiques et de revue comportent
quote, le code exact àlocation.line;build-report.mjsrejette 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. - 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
incompleteet 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 dansdiscarded. - 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: truesignifie 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 attachershotsaux constatations (voirreferences/rubric.md) afin que le rapport montre où se trouve chaque problème. - Un état avec
ok: falseou une vérification avec une erreur signifie qu'il n'a pas été audité. Le lister sousmeta.notCovered; ne pas marquer ses critèrespassà 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
keyprécédente, ou définiridexplicitement, pour chaque problème qui est toujours présent. - Remplir
coveragepour chaque critère dans la portée qui n'est pas en échec (et ajoutermethod/howà ceux en échec aussi), en suivant la règle de couverture dansreferences/criteria.md:passounaavecmethodethow,humanuniquement pour ce qui nécessite vraiment une personne (avec son script),not-covereduniquement 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.mjsrefuse les entrées manquantes. - Écrire
manualChecksuniquement pour ce que l'automatisation ne peut pas répondre : un pour chaque critèrehuman. 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.reviewedFlowsetmeta.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).