ultra11y

Intégration : où ultra11y se branche

Le même moteur sert à deux moments : pendant le développement, pour relire chaque changement, et en recette, pour auditer tout le site. Deux skills se partagent ces deux moments.

Deux skills, un même moteur

Une skill est un mode d’emploi qu’un agent de code (Claude Code, Codex, OpenCode…) charge quand la tâche s’y prête. Les deux skills embarquent le même moteur, sans installation.

review-a11yLa revue de code

Question
« Ce changement est-il accessible ? »
Périmètre
Le diff : fichiers indexés (staged), branche, pull request
Déclenchement
Automatique : un hook avant commit, push et pull request
Résultat
Une revue classée par gravité, avec fichier et ligne

ultra11yL’audit de conformité RGAA

Question
« Ce site est-il conforme au RGAA ? »
Périmètre
Le dépôt, le site, un échantillon de pages
Déclenchement
À la demande
Résultat
Rapport daté, grille RGAA, backlog, tickets

Règle commune : ne jamais inventer une non-conformité, ni une conformité.

Les quatre moments

review-a11y · boucle courte, sur le changement

ultra11y · audit complet

  1. J’écris du codedans mon agent (Claude Code, Codex…)
  2. git commit ou pushle hook audite le diff et bloque une seule fois
  3. Pull requestla GitHub Action annote le diff
  4. Recette ou auditrapport RGAA daté, backlog, tickets

Aussi : checkA11y(page) dans les tests Playwright ou Cypress, et un serveur MCP.

Les quatre moments où ultra11y se branche. La skill review-a11y couvre les trois premiers, en boucle courte sur le changement : pendant l’écriture du code, au commit ou au push, sur la pull request. La skill ultra11y prend le relais au quatrième, pour l’audit complet de recette.

Chaque moment est détaillé dans la suite de cette page.

1. Pendant que j’écris du code

Installé comme extension (plugin) de l’agent, ultra11y fournit les deux skills et un hook : un petit programme que l’agent exécute avant certaines commandes.

/plugin marketplace add SocialGouv/ultra11y        # Claude Code, dans la conversation
/plugin install ultra11y@ultra11y
codex plugin marketplace add SocialGouv/ultra11y   # Codex CLI, dans le terminal
codex plugin add ultra11y@ultra11y
npx ultra11y install --opencode                    # OpenCode

Pas à pas, depuis zéro : installer la skill dans Claude Code ou Codex.

2. Au commit et au push

Quand l’agent lance git commit, git push ou gh pr create, le hook audite le diff. S’il trouve un problème, il bloque la commande une seule fois et transmet les constats à l’agent, qui lance alors review-a11y. Une nouvelle tentative passe toujours : le hook ne bloque jamais deux fois pour les mêmes constats.

Ce que le hook ne fait pas :

Pour le couper : SKIP_A11Y=1 pour une commande, ULTRA11Y_HOOK=off pour une session, ou "hook": { "failOn": "off" } dans .ultra11yrc.json pour le dépôt.

3. Sur la pull request

La GitHub Action audite le diff de la pull request et annote les lignes concernées. Elle peut aussi ouvrir les pages servies dans un vrai navigateur.

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }      # le diff a besoin de la branche de base
- uses: SocialGouv/ultra11y@v5
  with:
    since: auto                 # compare à la branche de base de la PR
    standard: rgaa
    fail-on: blocking           # échoue seulement sur les défauts bloquants

Le détail (annotations SARIF, commentaire de PR, audit page par page, pages derrière une connexion) est dans references/ci.md.

4. En recette ou pour l’audit

Pour un audit de conformité, on demande à l’agent : « audite ce site selon le RGAA ». La skill ultra11y déroule alors la boucle complète décrite sur la page Audit.

Dans vos tests de bout en bout : Playwright et Cypress

La commande scan ouvre son propre navigateur, sans l’état que vos tests ont construit : pas de session connectée, pas de formulaire rempli, pas de fenêtre modale ouverte. checkA11y audite au contraire la page telle que votre test l’a laissée.

import { test } from "@playwright/test";
import { checkA11y } from "ultra11y/playwright";   // Cypress : "ultra11y/cypress"

test("tableau de bord", async ({ page }) => {
  await page.goto("/tableau-de-bord");
  await checkA11y(page, { as: "tableau-de-bord" });
});

failOn règle le seuil d’échec du test. failOn: false enregistre sans faire échouer : pratique pour démarrer sur un projet qui a déjà une dette. Sans dépendance npm, npx ultra11y render --e2e écrit des fixtures équivalentes. Voir references/e2e.md.

Comme serveur MCP

MCP est un protocole qui permet à un agent d’appeler un outil directement, avec des entrées et des sorties typées, au lieu de lancer des commandes et d’en lire la sortie.

claude mcp add ultra11y -- npx -y ultra11y mcp

Le serveur expose l’audit (audit, rapport, garde-fous, grille par page) et le référentiel (texte officiel d’un critère, glossaire, plan de travail). L’outil à appeler en premier est ultra11y_method : il dit ce que le moteur tranche, ce qui demande une page affichée et ce qui revient au jugement. Le scan navigateur n’est pas disponible par MCP ; il se lance en ligne de commande. Voir references/mcp.md.

Pendant le développement d’une page

Sur un projet Next.js, npx ultra11y dev --next ajoute un composant d’une ligne, puis npx ultra11y dev affiche un panneau flottant dans l’application en développement. Ce panneau liste les non-conformités de la page affichée ; chacune ouvre son fichier et sa ligne dans l’éditeur. Rien n’est rendu en production. Voir references/devtools.md.