SocialGouv/ultra11y

ultra11y — auditez WCAG 2.2 AA et rédigez du balisage accessible

En matière d'accessibilité, un outil automatisé ne voit qu'une partie du problème. ultra11y assume cela avec une division du travail : le moteur déterministe, sans installation (node scripts/ultra11y.mjs <commande> — pas de npm install, pas de clé ; l'analyseur JSX/TSX est intégré dans le bundle) effectue le travail mécanique — détecte les non-conformités vérifiables par machine et les lie au bon critère de succès WCAG — et l'agent de codage actif juge lui-même les critères subjectifs — pertinence du texte alternatif, finalité du lien en contexte, ordre de lecture — de manière statique, à partir des preuves que le moteur récolte (verify --manual), chaque verdict étant verrouillé par verify/check. Seuls les critères véritablement liés au DOM rendu (contraste calculé, focus visible, zoom/reflow, contenu au survol) relèvent du niveau scan (axe-core dans un vrai navigateur) ; un humain n'est au maximum qu'une surveillance optionnelle. Les portes empêchent toute non-conformité hallucinée de survivre, et rien n'est jamais silencieusement « conforme ».

Ne confondez pas règles et critères. Le bundle intègre 93 vérifications statiques, WCAG AA a 55 critères de succès, et le RGAA a 106 critères. Plusieurs règles peuvent témoigner d'un critère, une règle peut contribuer à plusieurs critères du pack, et la plupart des critères restent ouverts jusqu'à un scan ou une adjudication. La seule couverture honnête au niveau de l'exécution est le décompte de provenance en direct de la grille (moteur + scan + agent, plus tout résidu indécidable nommé), jamais une promesse fixe comme « 48 critères d'agent ». Les résumés GitHub affichent donc décidé/total, pas un pourcentage sur le petit sous-ensemble décidé.

Le WCAG 2.2 Niveau AA est le socle mondial. Les normes nationales — le RGAA français, la Section 508 américaine, la EN 301 549 européenne — sont des packs de normes enfichables qui mappent leurs critères sur le WCAG. Ajoutez --standard rgaa pour reconfigurer chaque commande et chaque sortie — audit inclus, constats et tout ; branchez un pack externe à l'exécution avec --pack ./pack.json (ou un .ultra11yrc.json), sans recompilation ; ou contribuez à votre pays (voir references/standards.md). Les packs (et leurs directives de mise en œuvre concrètes — les bonnes/mauvaises pratiques RGAA de SocialGouv/etalab) peuvent être ingérés par IA et verrouillés par pack check afin qu'un mappage fabriqué ne passe jamais — voir references/packs.md et references/guidance.md.

La majeure partie du travail vous revient. Sur les 55 critères de succès WCAG 2.2 AA, le moteur peut en décider 3 directement ; 14 ont besoin d'une page rendue (scan) et 38 sont des appréciations que l'agent juge. Le résultat propre du moteur est donc un point de départ, jamais un verdict — et references/adjudication.md est la page à partir de laquelle vous travaillez réellement.

Règles fondamentales :

1. N'inventez jamais une non-conformité : chaque NC cite un élément réel et résoluble (check le vérifie).
2. HTML natif d'abord, ARIA en dernier ; ne dupliquez jamais les sémantiques implicites.
3. N'inventez jamais une conformité non plus : un C est cité exactement comme un NC — il nomme dans citations[] les preuves récoltées qu'il a validées, chaque ancre résoluble et tirée des preuves que ce critère a effectivement montrées. Un critère présenté sans preuve ne peut pas du tout être C ; il reste manual. Pas plus qu'un critère dont la lecture était INCOMPLÈTE (evidenceComplete: false) : un critère dont on n'a vu qu'une partie peut encore échouer sur ce qui a été vu, mais il ne peut jamais être validé sur ce qui n'a pas été vu. Et un C jugé n'est jamais fusionné avec un C décidé par le moteur : les rapports le listent séparément et le maintiennent en dehors du taux de réussite automatique. 3b. Ce qui vous est montré est la population entière, dite une fois par chose distincte. Les preuves sont un représentant par CLASSE DE CONTENU, portant occurrences, les autres ancres dans alsoAt, et les pages sur lesquelles il apparaît — 887 liens répartis sur 38 pages capturées sont 97 paires (texte, href) distinctes. Statuer sur le représentant, c'est statuer sur toutes, ce qui rend un C honnête atteignable ; et une citation nommant n'importe quelle occurrence d'une classe que porte le critère est acceptée, citez donc celle que vous avez réellement ouverte.
4. Le résidu est explicite, jamais silencieusement conforme : l'agent IA juge lui-même chaque critère subjectif (verify --manual, verrouillé), et les critères de rendu vont au scan — qui conclut maintenant C (decidedBy: "scan") lorsque chaque règle portant un critère a été exécutée sur chaque page du périmètre sans rien relever, et reste silencieux lorsqu'au moins une page a des signaux incomplets. Tout critère toujours non prouvé reste « à évaluer manuellement » — aucun statut sans un verdict enregistré et justifié. Pour faire de cela une porte plutôt qu'un espoir, check --in <audit.json> --require-decided échoue tant qu'il reste quelque chose à évaluer, et --allow-undecided <fichier> prend les critères que vous ne pouvez vraiment pas décider, chacun avec sa raison (une liste nommée, jamais un seuil). --require-decided=pages tient la propre grille de CHAQUE page à la même barre : un critère échouant sur un parcours est réglé pour l'exécution et peut encore n'être le verdict de personne sur les parcours où il ne s'est jamais déclenché, ce sur quoi un livrable par page est réellement jugé. La liste de travail émise fait autorité. Elle peut délibérément contenir un critère dont le statut global est déjà NC, parce que cet échec n'a pas décidé le critère sur les autres pages. Un tel élément n'est pas redondant : retournez un verdict fondé pour lui (ou une raison manual explicite), ne le laissez jamais vide parce que le total global semble décidé.
5. Consultez le critère ; ne le récitez jamais. criteria [--standard <pack>] <id> — ou ultra11y_criteria via MCP — renvoie le libellé du critère lui-même, ses tests numérotés et les définitions du glossaire que ces tests citent. Le RGAA 8.3 n'est pas « la page a besoin d'un attribut lang » ; c'est le test 8.3.1 avec deux conditions alternatives, et le glossaire décide ce que ses termes signifient. Un bloc d'auditeur qui cite 8.3.1 après l'avoir lu est fondé ; celui qui le cite de mémoire est une devinette déguisée en référence. Avant d'auditer selon une norme nationale, exécutez le plan (ultra11y_method) : il vous indique combien de ses critères ont encore besoin d'adjudication pour obtenir un C — pour le RGAA, 104 sur 106. Voir references/mcp.md.
6. Le HTML sémantique rendu final doit être correct. Le moteur ne voit que la source ; une bibliothèque de composants (DSFR/MUI…) ou un SFC .vue/.svelte/.astro masque le balisage réel, donc un audit source vert n'est pas une preuve. Vérifiez le HTML sémantique produit — installez le récupérateur capture sans intervention (render --setup) afin que chaque composant rendu par vos tests soit sérialisé dans .ultra11y/captures et audité, avec audit --require-captures verrouillant les angles morts. Voir references/automation.md / rendered.md.
7. Langue : passez TOUJOURS --lang correspondant à la langue de votre conversation avec l'utilisateur ; demandez à l'utilisateur en cas d'ambiguïté. Sans le drapeau, la CLI détecte automatiquement (dépôt <html lang> → la locale par défaut du standard actif → anglais) — un repli scripté/CI, pas un substitut au fait de passer --lang vous-même.
8. Les jetons techniques restent en anglais, même dans un texte français. Dans tout livrable français que vous rédigez (commentaire de rapport, PRD, tickets de suivi, verdicts de jugement), les noms d'attributs/éléments/rôles et leurs valeurs sont du code, pas de la prose — ne les traduisez jamais : aria-live reste aria-live (jamais « région live »), de même pour tabindex, alt, role="alert", les noms de rôles de points de repère. Le propre catalogue français du moteur suit cela ; respectez-le. Le vocabulaire normatif du standard (terminologie RGAA comme « lien d'évitement ») conserve son français officiel.

La bibliothèque de référence

Les connaissances métier d'abord, puis l'outillage. Lisez celle qui correspond à la question que vous avez devant vous.

Connaissances en accessibilité
references/adjudication.md	Comment décider chacun des 52 critères que le moteur vous remet — la règle de décision, quand NA est légitime, les questions
references/naming.md	Calcul du nom accessible, 2.5.3 label-in-name, CSS visuellement masqué, nommage des images/SVG/figures
references/widgets.md	Modèles composites ARIA APG, contrats clavier, gestion du focus, changements de route SPA, régions live
references/forms-and-errors.md	Étiquettes et instructions, la liste de jetons autocomplete, identification/suggestion/prévention d'erreur, saisie redondante, authentification accessible
references/structure.md	Titres, points de repère, listes et dl, tableaux simples et complexes, séquence significative
references/media-and-motion.md	Sous-titres/audiodescription/transcriptions, gestes du pointeur, taille des cibles, orientation, reflow, mouvement réduit
references/forbidden-patterns.md	15 anti-patrons : mauvais → pourquoi → correction native → critère
references/focus-and-logic.md	Les critères de focus/clavier qui vous reviennent, et comment raisonner à leur sujet
references/criteria.md	Les 55 critères : niveau, classe d'automatisabilité, règles du moteur, mapping de pack (généré)
references/rgaa-automation.md	RGAA 4.1.2 : matrice générée de 106 critères / 258 tests, règles décisives, signaux candidats et politique de silence
references/act.md	Ce que le moteur est mesuré pour détecter — et ce qu'il ne détecte manifestement pas (généré)

Utilisation de l'outil
references/runbook.md	L'exécution fiable : la recette unique, le transport à utiliser et pourquoi, et ce que coûte un passage. Lisez ceci avant de payer pour une adjudication
references/claude-code-report.md	Le parcours de publication détaillé de Claude Code : périmètre rendu, adjudication directe, vérification contradictoire, Markdown + HTML + preuves par page
references/audit.md	La boucle d'audit de bout en bout, et l'échantillon de page normatif
references/judgment.md	Les listes de travail d'adjudication + réfutation, vocabulaire de verdict, repli échoué-fermé
references/verify.md	Les portes check/verify
references/false-positives.md	Quand un constat peut encore être erroné, et comment le réfuter
references/rendered.md · references/automation.md	Audit du HTML produit, captures, hooks et CI
references/harnesses.md	Là où cela s'exécute : Claude Code, Codex CLI, OpenCode, et le repli AGENTS.md
references/orchestrators.md	Pilotage du moteur depuis un moteur de workflow / CI non GitHub : épinglage, pipeline en six étapes, codes de sortie, le jeu de tickets au format JSON pour tout tracker
references/ci.md	`--format sarif
references/pages.md	Instantanés de page + la grille de critères par page (pages), et ses règles d'honnêteté
references/e2e.md	render --e2e : audit d'une page pendant votre exécution Playwright/Cypress
references/devtools.md	dev : la superposition en direct pendant que vous développez, et le tableau de bord par page
references/extension.md	L'extension navigateur : auditez la page que vous regardez, via le side-car
references/dynamic.md	Le niveau scan : environnements d'exécution, sondes, pages authentifiées
references/scale.md	Cibler un audit sur un grand dépôt
references/fix.md · references/correction.md	Application des correctifs, par priorité, sans régressions
references/prd.md	Le bloc d'auditeur comme backlog (markdown)
references/tickets.md	Saisie de ce backlog sous forme de tickets : GitHub, GitLab, Jira, et à quel niveau de granularité
references/standards.md · references/packs.md · references/guidance.md	Normes nationales, création d'un pack, directives de mise en œuvre
references/mcp.md	Les normes comme moteur de règles : consultez un critère au lieu de le réciter — ses tests numérotés, les termes qu'il définit, le correctif, et le plan de travail. Sous forme d'outils MCP et de ressources std://, ou les mêmes données sur la CLI
references/methodology.md	Statuts, taux de réussite, sévérités, format du rapport
references/cross-file.md	--graph : importations et règles inter-fichiers
references/orchestration.md	Répartition des phases de jugement entre sous-agents

Choisissez selon la situation

• « Produire un audit/rapport détaillé dans Claude Code » → utilisez la session Claude active comme auditeur, fermez les critères rendus et jugés, contestez ses affirmations, puis publiez le rapport Markdown daté, le HTML imprimable et les dossiers par page avec preuves. Lisez references/claude-code-report.md. C'est le profil de publication interactif ; terminez avec son ensemble complet de livrables. Le résumé compact est la branche CI ci-dessous.
• « Audit / rapport de conformité » → node scripts/ultra11y.mjs audit … --json, puis report (tableau de synthèse + un bloc de conformité d'auditeur par critère NC — le même bloc qu'utilisent prd et tickets), puis check ; lisez references/audit.md.
• « Code rendu par une bibliothèque (DSFR, MUI…) ou un SFC .vue/.svelte/.astro / éviter les faux négatifs » → auditez le HTML produit, pas le modèle source. Le plus simple : installez le récupérateur capture sans intervention (render --setup) afin que vos tests sérialisent chaque composant rendu dans .ultra11y/captures (ingéré automatiquement, les constats attribués au composant source ; render --coverage et audit --require-captures suivent les angles morts). Ou render (recette build→audit ou instantané SSR --scaffold) puis audit sur la sortie, et scan pour le rendu calculé. Les constats sur source SFC sont marqués preliminary (une réserve scope.sourceTemplate) ; lisez references/rendered.md.
• « Un constat semble erroné / faux positif sur un composant » → le moteur supprime automatiquement la plupart des faux positifs de composants (noms injectés par slot/prop, enfants de composant, liaisons dynamiques, titres conditionnels) et marque les constats sur source SFC/bibliothèque comme preliminary ; confirmez ou réfutez le reste avec verify --apply ; lisez references/false-positives.md.
• « Grand dépôt / auditer intelligemment » → ciblez : --changed (git diff), priorisation des modèles, dédup, --max-files ; lisez references/scale.md.
• « Analyse inter-fichiers (arbre + dépendances), JSX/TSX comme un véritable AST » → audit --graph résout les importations et applique les règles inter-fichiers