docs(a11y): plan for better world

Author: philibea

A11Y.md

@@ -0,0 +1,129 @@
+# Accessibilité (A11Y) - Ultraviolet Design System
+
+## 🎯 Vision
+
+Rendre la Design System Ultraviolet **entièrement accessible** et conforme aux standards **WCAG 2.1 niveau AA**, afin que tous les utilisateurs, quel que soit leur handicap, puissent utiliser les composants UI.
+
+## 📂 Structure
+
+Toute la documentation, l'outillage et les tickets relatifs à l'accessibilité sont centralisés dans le dossier [`a11y/`](./a11y/).
+
+## 📋 Ce que nous allons faire
+
+### Phase 1 : Infrastructure & Outillage 🔧
+- [`UV-001`](./a11y/UV-001-setup-eslint-plugin-jsx-a11y.txt) : Configuration de `oxlint` avec règles A11y
+- [`UV-002`](./a11y/UV-002-configuration-jest-axe-tests-unitaires.txt) : Mise en place de `vitest-axe` pour les tests unitaires
+- [`UV-003`](./a11y/UV-003-storybook-a11y-configuration-avancee.txt) : Configuration avancée de Storybook avec addon a11y
+- [`UV-004`](./a11y/UV-004-ci-cd-tests-a11y-automatises.txt) : Intégration des tests A11y dans la CI/CD
+
+### Phase 2 : Audit & Correctifs 🔍
+- [`UV-005`](./a11y/UV-005-audit-complet-composants-ui.txt) : Audit complet de tous les composants UI
+- [`UV-006`](./a11y/UV-006-corriger-violations-critiques.txt) : Correction des violations critiques et serious
+- [`UV-007`](./a11y/UV-007-focus-management-modal-dialog.txt) : Focus management pour les modals/dialogs
+- [`UV-008`](./a11y/UV-008-navigation-clavier-composants-interactifs.txt) : Navigation clavier sur les composants interactifs
+- [`UV-009`](./a11y/UV-009-aria-labels-roles.txt) : ARIA labels et roles
+
+### Phase 3 : Tests E2E A11y 🧪
+- [`UV-010`](./a11y/UV-010-setup-playwright-a11y-tests.txt) : Setup de Playwright pour les tests d'accessibilité
+- [`UV-011`](./a11y/UV-011-tests-navigation-clavier-e2e.txt) : Tests automatisés de navigation clavier
+- [`UV-012`](./a11y/UV-012-tests-screen-readers.txt) : Tests de compatibilité avec les screen readers
+
+### Phase 4 : Documentation & Guidelines 📚
+- [`UV-013`](./a11y/UV-013-documentation-a11y-developpeurs.txt) : Documentation A11y pour les développeurs
+- [`UV-014`](./a11y/UV-014-stories-demonstration-a11y.txt) : Stories de démonstration des bonnes pratiques
+- [`UV-015`](./a11y/UV-015-template-pr-checklist-a11y.txt) : Template de PR avec checklist A11y obligatoire
+
+### Phase 5 : Monitoring & Maintenance 📊
+- [`UV-016`](./a11y/UV-016-dashboard-suivi-a11y.txt) : Dashboard de suivi des violations
+- [`UV-017`](./a11y/UV-017-audit-regulier-automatise.txt) : Audit régulier automatisé
+
+## 🤔 Pourquoi faire ça ?
+
+### 1. **Inclusion** 🌍
+L'accessibilité numérique est un droit fondamental. Environ **15% de la population mondiale** vit avec un handicap. Rendre nos composants accessibles, c'est permettre à tous d'utiliser nos applications.
+
+### 2. **Conformité légale** ⚖️
+De nombreuses réglementations imposent l'accessibilité numérique :
+- **RGAA** en France (Référentiel Général d'Amélioration de l'Accessibilité)
+- **ADA** aux États-Unis
+- **European Accessibility Act** pour l'UE
+
+### 3. **Qualité technique** 💎
+L'accessibilité améliore :
+- La sémantique HTML
+- La navigation clavier
+- La compatibilité avec les technologies d'assistance
+- Le SEO (les bonnes pratiques A11y beneficient aussi au référencement)
+
+### 4. **Expérience utilisateur** ✨
+Les fonctionnalités accessibles profitent à tous :
+- Sous-titres → utiles dans un environnement bruyant
+- Navigation clavier → utile pour les power users
+- Contrastes élevés → utile en extérieur ou sur écrans de mauvaise qualité
+
+## 🛠️ Comment nous allons procéder
+
+### 1. Outillage automatique
+```bash
+# Linting A11y en temps réel
+oxlint
+
+# Tests unitaires
+npm test -- --testNamePattern="a11y"
+
+# Tests E2E
+npm run test:e2e:a11y
+```
+
+### 2. Workflow de développement
+- **Avant chaque commit** : lint A11y via pre-commit hooks
+- **Avant chaque PR** : tests A11y automatisés + checklist manuelle
+- **Dans la CI** : blocage si violations critiques ou serious
+- **Dans Storybook** : validation A11y sur chaque story
+
+### 3. Processus de correction
+1. Détection automatique via oxlint/storybook
+2. Audit manuel sur les composants critiques
+3. Correction des violations par ordre de priorité (critical → serious → moderate)
+4. Tests de validation (clavier + screen reader)
+5. Documentation des patterns utilisés
+
+### 4. Formation & Sensibilisation
+- Documentation des bonnes pratiques
+- Exemples concrets dans Storybook
+- Revue de code systématique sur les aspects A11y
+
+## 📊 Métriques de succès
+
+| Objectif | Cible | Échéance |
+|----------|-------|----------|
+| 0 violation critical | ✅ 0 | Sprint 2 |
+| 0 violation serious | ✅ 0 | Sprint 3 |
+| < 50 violations moderate | ⚠️ < 50 | Sprint 4 |
+| WCAG AA compliance | 📈 95%+ | Sprint 6 |
+| Composants testés | ✅ 100% | Sprint 4 |
+
+## 📚 Ressources
+
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
+- [RGAA 4.1](https://accessibilite.numerique.gouv.fr/rgaa/)
+- [A11y Project Checklist](https://www.a11yproject.com/checklist/)
+
+## 🚀 Démarrage
+
+1. Consulter la [roadmap détaillée et les 17 tickets](./a11y/README.md)
+2. Review des tickets dans [`a11y/`](./a11y/) :
+   - Phase 1 : [`UV-001`](./a11y/UV-001-setup-eslint-plugin-jsx-a11y.txt), [`UV-002`](./a11y/UV-002-configuration-jest-axe-tests-unitaires.txt), [`UV-003`](./a11y/UV-003-storybook-a11y-configuration-avancee.txt), [`UV-004`](./a11y/UV-004-ci-cd-tests-a11y-automatises.txt)
+   - Phase 2 : [`UV-005`](./a11y/UV-005-audit-complet-composants-ui.txt) à [`UV-009`](./a11y/UV-009-aria-labels-roles.txt)
+   - Phase 3 : [`UV-010`](./a11y/UV-010-setup-playwright-a11y-tests.txt) à [`UV-012`](./a11y/UV-012-tests-screen-readers.txt)
+   - Phase 4 : [`UV-013`](./a11y/UV-013-documentation-a11y-developpeurs.txt) à [`UV-015`](./a11y/UV-015-template-pr-checklist-a11y.txt)
+   - Phase 5 : [`UV-016`](./a11y/UV-016-dashboard-suivi-a11y.txt), [`UV-017`](./a11y/UV-017-audit-regulier-automatise.txt)
+3. Priorisation avec l'équipe
+4. Lancement du Sprint 1
+
+---
+
+**Contact** : A11y Audit Team  
+**Date** : Avril 2026  
+**Statut** : En cours

a11y/README.md

@@ -0,0 +1,106 @@
+# A11y Audit Tickets - Ultraviolet Design System
+
+Ce dossier contient 17 tickets Jira pour l'audit d'accessibilité de la Design System Ultraviolet.
+
+## 📋 Liste des tickets
+
+### Phase 1 : Infrastructure & Outillage 🔧
+- **UV-001** - Setup eslint-plugin-jsx-a11y (High)
+- **UV-002** - Configuration jest-axe pour les tests unitaires (High)
+- **UV-003** - Storybook A11y - Configuration avancée (Medium)
+- **UV-004** - CI/CD - Tests A11y automatisés (High)
+
+### Phase 2 : Audit & Correctifs 🔍
+- **UV-005** - Audit complet des composants UI (High)
+- **UV-006** - Corriger les violations critiques (High)
+- **UV-007** - Focus Management - Modal/Dialog (High)
+- **UV-008** - Navigation clavier - Composants interactifs (Medium)
+- **UV-009** - ARIA Labels & Roles (Medium)
+
+### Phase 3 : Tests E2E A11y 🧪
+- **UV-010** - Setup Playwright A11y Tests (Medium)
+- **UV-011** - Tests E2E de navigation clavier (Medium)
+- **UV-012** - Tests Screen Readers (Low)
+
+### Phase 4 : Documentation & Guidelines 📚
+- **UV-013** - Documentation A11y pour les développeurs (Medium)
+- **UV-014** - Stories de démonstration A11y (Medium)
+- **UV-015** - Template de PR avec checklist A11y (Low)
+
+### Phase 5 : Monitoring & Maintenance 📊
+- **UV-016** - Dashboard de suivi A11y (Low)
+- **UV-017** - Audit régulier automatisé (Low)
+
+## 🎯 Roadmap recommandée
+
+### Sprint 1 (Semaines 1-2)
+- UV-001: Setup eslint-plugin-jsx-a11y
+- UV-004: CI/CD - Tests A11y automatisés
+- UV-005: Audit complet des composants
+
+### Sprint 2 (Semaines 3-4)
+- UV-002: Configuration jest-axe
+- UV-006: Corriger les violations critiques
+- UV-007: Focus Management Modal
+
+### Sprint 3 (Semaines 5-6)
+- UV-008: Navigation clavier
+- UV-009: ARIA Labels & Roles
+- UV-010: Setup Playwright A11y
+
+### Sprint 4 (Semaines 7-8)
+- UV-011: Tests navigation clavier E2E
+- UV-013: Documentation A11y
+- UV-014: Stories de démonstration
+
+### Sprint 5 (Semaines 9-10)
+- UV-003: Storybook configuration avancée
+- UV-015: Template PR checklist
+- UV-016: Dashboard de suivi
+
+### Sprint 6 (Semaines 11-12)
+- UV-012: Tests Screen Readers
+- UV-017: Audit régulier automatisé
+
+## 📊 Métriques de succès
+
+- **0 violation critical** (objectif sprint 2)
+- **0 violation serious** (objectif sprint 3)
+- **< 50 violations moderate** (objectif sprint 4)
+- **WCAG AA compliance 95%+** (objectif sprint 6)
+- **100% des composants testés** (objectif sprint 4)
+
+## 🔗 Import dans Jira
+
+Pour importer ces tickets dans Jira:
+
+1. Aller dans Jira → Issues → Import issues from CSV
+2. Mapper les champs:
+   - Summary → Summary
+   - Issue Type → Issue Type
+   - Priority → Priority
+   - Labels → Labels
+   - Description → Description
+   - Estimation → Original Estimate (en heures)
+3. Utiliser le format de fichier fourni
+
+## 📝 Notes
+
+- Chaque ticket est dans un fichier `.txt` séparé
+- Le format est compatible avec l'import CSV Jira
+- Les dépendances entre tickets sont notées dans chaque fichier
+- Les estimations sont en heures
+
+## 🚀 Prochaines étapes
+
+1. Review des tickets avec l'équipe
+2. Priorisation selon la roadmap
+3. Création des tickets dans Jira
+4. Assignation des premiers tickets (Sprint 1)
+5. Kick-off de l'audit A11y
+
+---
+
+**Contact**: A11y Audit Team
+**Date de création**: Avril 2026
+**Version**: 1.0

a11y/UV-001-setup-eslint-plugin-jsx-a11y.txt

@@ -0,0 +1,58 @@
+Summary: Setup eslint-plugin-jsx-a11y pour l'audit A11y
+Issue Type: Story
+Priority: High
+Labels: a11y, devops, infrastructure, eslint
+
+Description:
+Intégrer eslint-plugin-jsx-a11y dans la configuration oxlint pour détecter automatiquement les problèmes d'accessibilité dans le code.
+
+Contexte:
+- Actuellement 52 occurrences de règles a11y désactivées avec oxlint-disable
+- Nécessité d'avoir un linting a11y automatisé dans le workflow de développement
+- Premier pilier de l'infrastructure a11y
+
+Tâches:
+[ ] Ajouter eslint-plugin-jsx-a11y aux devDependencies
+[ ] Configurer les règles dans .oxlintrc.jsonc
+[ ] Commencer en mode warning uniquement (ne pas bloquer la CI)
+[ ] Documenter les règles activées dans CONTRIBUTING.md
+[ ] Tester sur un échantillon de composants
+
+Règles à activer (priorité haute):
+- accessible-emoji
+- alt-text
+- anchor-has-content
+- aria-activedescendant-has-tabindex
+- aria-props
+- aria-role
+- aria-unsupported-roles
+- autocomplete-valid
+- click-events-have-key-events
+- heading-has-content
+- html-has-lang
+- iframe-has-title
+- img-redundant-alt
+- label-has-associated-control
+- lang
+- media-has-caption
+- mouse-events-have-key-events
+- no-access-key
+- no-autofocus
+- no-noninteractive-element-interactions
+- no-noninteractive-element-to-interactive-role
+- no-noninteractive-tabindex
+- no-redundant-roles
+- no-static-element-interactions
+- role-has-required-aria-props
+- scope
+- tabindex-no-positive
+
+Critères d'acceptation:
+- [ ] La configuration oxlint inclut eslint-plugin-jsx-a11y
+- [ ] Les règles sont documentées
+- [ ] Le linting tourne en local sans erreurs bloquantes
+- [ ] La CI affiche les warnings a11y sans échouer
+
+Estimation: 3h
+Assignee: Unassigned
+Reporter: A11y Audit Team

a11y/UV-002-configuration-jest-axe-tests-unitaires.txt

@@ -0,0 +1,53 @@
+Summary: Configuration jest-axe pour les tests unitaires A11y
+Issue Type: Story
+Priority: High
+Labels: a11y, testing, jest-axe, vitest
+
+Description:
+Implémenter axe-core dans les tests unitaires via jest-axe pour détecter les violations d'accessibilité automatiquement.
+
+Contexte:
+- jest-axe est déjà installé (voir jest-axe.d.ts et expect.d.ts)
+- Mais peu ou pas utilisé dans les tests actuels
+- Utils/test contient les helpers de test (renderWithTheme, etc.)
+
+Tâches:
+[ ] Ajouter axe-core aux dependencies de test (utils/test/package.json)
+[ ] Créer un helper toHaveNoAxeViolations dans utils/test/src/vitest/helpers/
+[ ] Configurer les règles axe personnalisées (WCAG AA)
+[ ] Ajouter la documentation d'usage dans utils/test/README.md
+[ ] Tester sur 2-3 composants existants (Button, Alert)
+[ ] Ajouter un exemple dans les tests existants
+
+Configuration axe recommandée:
+```typescript
+const axeConfig = {
+  rules: {
+    'color-contrast': { enabled: true },
+    'label': { enabled: true },
+    'landmark-one-main': { enabled: false }, // Pas pertinent pour les composants isolés
+    'region': { enabled: false }, // Idem
+  }
+}
+```
+
+Helper à créer:
+```typescript
+export const renderWithAxe = (component, options) => {
+  const { container } = renderWithTheme(component, options)
+  const results = await axe(container)
+  expect(results).toHaveNoViolations()
+  return renderWithTheme(component, options)
+}
+```
+
+Critères d'acceptation:
+- [ ] Helper toHaveNoAxeViolations disponible dans @utils/test
+- [ ] Documentation à jour
+- [ ] Au moins 2 composants testés avec axe
+- [ ] Les tests passent en local et en CI
+
+Estimation: 5h
+Assignee: Unassigned
+Reporter: A11y Audit Team
+Dependencies: UV-001