Audit accessibilité WCAG 2.1 AA complet

Contexte

Vous devez garantir que votre SPA respecte les standards WCAG 2.1 AA. a11y-auditor scanne exhaustivement : keyboard navigation, screen reader support, color contrast, ARIA labels, form accessibility. Génère un rapport détaillé et crée les tâches de correction.

Prérequis

• Projet React/Vue/Svelte compilé et accessible en localhost
• Outils d’audit installés ou auto-détectés :
  • @axe-core/cli (npm)
  • pa11y (npm)
  • eslint-plugin-jsx-a11y (React)
  • ou vue-axe (Vue)
• Accès à docs/todo.md pour créer les tâches

Étapes

1. Invoquer a11y-auditor

/ulk:a11y-auditor
# ou
a11y-auditor

2. Phase 1 : Reconnaissance

L’agent détecte :

🔍 A11y Auditor — Initialisation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Framework UI    : React 19
CSS Framework   : Tailwind CSS
UI Library      : shadcn/ui (Radix UI)
Components      : 42 fichiers détectés

Surface à auditer:
  Pages/Routes : 18
  Formulaires  : 7
  Modales      : 3
  Tables       : 2

Outils disponibles:
  ✅ axe-core
  ✅ pa11y
  ✅ eslint-plugin-jsx-a11y

3. Phase 2 : Audit automatisé

Images :

• Images sans alt text
• Alt vides ou trop génériques
• Images décoratives vs informatives

Formulaires :

• Labels manquants
• Placeholders sans label
• Groupes radio/checkbox non associés
• Messages d’erreur non liés aux champs

Keyboard Navigation :

• Ordre de tabulation logique
• Éléments non-interactifs focusables
• Pièges de focus (modales, popovers)
• Raccourcis clavier accessibles

Color Contrast :

• Texte vs background (ratio minimum 4.5:1)
• Composants graphiques

ARIA :

• Rôles appropriés
• Live regions mal configurées
• Aria-labels redondants

Exécution :

npx axe-core --file ./index.html --tags wcag2aa
npx pa11y ./index.html --standard WCAG2AA --reporters json
eslint src/ --ext tsx --plugin jsx-a11y --rule jsx-a11y/rules: error

4. Phase 3-4 : Audit manuel + consolidation

L’agent teste manuellement :

• Navigation au clavier uniquement (Tab, Enter, Esc, Arrow keys)
• Lecteur d’écran (annonces, headings, landmarks)
• Zoom à 200% (responsive)
• Daltonisme (simulateurs de couleur)

Consolidation dans une matrice :

╔════════════════════════════════════════════════════════════╗
║ AUDIT A11Y — Résumé WCAG 2.1 AA                           ║
╠════════════════════════════════════════════════════════════╣
║                                                            ║
║ Images (Level A)              : 8/10 (2 manquants)       ║
║ Formulaires (Level A)         : 9/10 (1 label manquant)  ║
║ Keyboard (Level A)            : 7/10 (focus piégé modal) ║
║ Color Contrast (Level AA)     : 9/10 (button-danger)     ║
║ ARIA (Level A)                : 10/10 ✅                  ║
║                                                            ║
║ Score global WCAG 2.1 AA      : 8.6/10 (Bon)             ║
║                                                            ║
╠════════════════════════════════════════════════════════════╣
║ Violations critiques (Level A) : 3 → doivent être fixées  ║
║ Recommandations (Level AAA)    : 2 → optionnel           ║
╚════════════════════════════════════════════════════════════╝

5. Phase 6-7 : Rapport et tâches

a11y-auditor crée :

Rapport détaillé : docs/reports/audit-a11y-20260414.md

## Violations détectées

### 🔴 CRITIQUE (WCAG 2.1 Level A)

#### Image sans alt text
- Fichier: `src/components/HeroSection.tsx:42`
- Element: `<img src="hero.jpg" />`
- Fix: Ajouter `alt="Hero section with mountain landscape"`

#### Label manquant sur input email
- Fichier: `src/components/Form.tsx:18`
- Element: `<input type="email" placeholder="Email" />`
- Fix: Ajouter `<label htmlFor="email">Email</label>`

#### Focus piégé dans modal
- Fichier: `src/components/Modal.tsx:67`
- Issue: Tab-order échappe au modal (escapes to main document)
- Fix: Utiliser `Dialog` de Radix UI + focus-trap (via headlessui)

### 🟡 RECOMMANDATIONS (WCAG 2.1 Level AAA)

#### Color contrast insuffisant (button-danger)
- Current: 3.5:1 (minimum AA = 4.5:1)
- Fix: Changer couleur du bouton ou du background

Tâches créées dans docs/todo.md :

- [ ] A11y: Ajouter alt text aux 8 images (HeroSection, Features)
- [ ] A11y: Ajouter labels manquants aux 3 inputs de forme
- [ ] A11y: Fixer focus piégé dans modal (Dialog + focus-trap)
- [ ] A11y: Améliorer contraste button-danger (3.5:1 → 4.5:1)

Exemple de sortie

Passage dans un rapport structuré :

---
title: Audit Accessibilité WCAG 2.1 AA
date: 2026-04-14
project: portfolio-saas
score: 8.6/10
---

# Audit Accessibilité

## Résumé Exécutif

Ce rapport évalue la conformité du projet aux standards WCAG 2.1 AA.
Score global : 8.6/10 (Bon).
3 violations critiques détectées (Level A) — doivent être fixées.

## Critères évalués

- ✅ Perception (4.1)
- ✅ Utilisation (3.2)
- ⚠️ Compréhension (2.8)
- ✅ Robustesse (3.5)

## Violations par catégorie

### Images (alt text)
- 2 images sans alt
- 1 alt trop générique
→ Effort : ~10 min

### Formulaires (labels)
- 1 input email sans label
- 1 select sans label
→ Effort : ~15 min

### Keyboard Navigation
- 1 modal avec focus piégé
→ Effort : ~30 min (refactor Dialog)

### Color Contrast
- 1 bouton en-dessous du seuil AA
→ Effort : ~5 min

## Checklist de remédiation

- [ ] Ajouter alt texts descriptifs aux images
- [ ] Lier tous les inputs à leurs labels
- [ ] Implémenter Dialog avec focus-trap
- [ ] Tester keyboard navigation (Tab, Shift+Tab, Esc)
- [ ] Tester contraste avec daltonisme simulator
- [ ] Revalider post-fixes

Variantes

• Variante A : Focus critiques uniquement (Mode Rapide) — --critical-only pour ignorer les recommandations AAA et gagner 20 min
• Variante B : Audit en mode contexte — Si Bruce/godspeed passent CONTEXTE PROJET:, a11y-auditor skips la Phase 1 et commence directement à l’audit
• Variante C : Comparaison pré/post — Si un audit antérieur existe, l’agent compare les scores et reporte l’évolution

Agents enchaînés

Flux linéaire (peut être parallélisé avec d’autres audits) :

a11y-auditor (06)
  ├─ Phase 1 : Reconnaissance (5 min)
  ├─ Phase 2 : Audit automatisé axe-core + pa11y (15 min)
  ├─ Phase 3 : Tests manuels keyboard + screen reader (20 min)
  ├─ Phase 4 : Consolidation (5 min)
  └─ Phase 6-7 : Rapport + tâches (10 min)

Si lancé via Black Emperor mode=release, parallélisé avec code-auditor et perf-auditor.

Troubleshooting

Symptôme	Cause probable	Résolution
”axe-core not found”	Outils d’audit non installés	npm install -D @axe-core/cli pa11y
Audit incomplete (skip certains fichiers)	Fichiers dans node_modules ou dist/	L’agent exclut automatiquement, vérifiez src/
Contraste difficile à vérifier visuellement	Couleurs Tailwind non finales	a11y-auditor utilise des outils auto, résultats fiables
Beaucoup de faux positifs ARIA	Règles strictes vs code legacy	Utilisez --strict pour maximiser, ou --lenient pour ignorer AAA

Voir aussi

• ./02-blackemperor-pre-release.md — Audit pré-release (inclut a11y)
• ./05-a11y-audit.md — Cette fiche (accessibilité)
• ./06-perf-auditor.md — Audit performance (Core Web Vitals)
• agents/audit/06-a11y-auditor.md — Documentation complète
• agents/_shared/auditor-base.md — Base commune à tous les auditors
• agents/_shared/checklists/accessibility-checklist.md — Checklist WCAG 2.1 AA rapide