primefaces-freya-extension/ACCESSIBILITY.md

# Guide d'Accessibilité

PrimeFaces Freya Extension est conçu avec l'accessibilité en tête, suivant les directives **WCAG 2.1 niveau AA**.

## 🎯 Objectifs d'accessibilité

- ✅ **Navigation au clavier** - Tous les composants sont accessibles au clavier
- ✅ **Lecteurs d'écran** - Support ARIA pour les technologies d'assistance
- ✅ **Contraste des couleurs** - Respect des ratios de contraste WCAG
- ✅ **Focus visible** - Indicateurs de focus clairs
- ✅ **Labels explicites** - Tous les champs ont des labels associés
- ✅ **Messages d'erreur** - Validation accessible

## 🔍 Fonctionnalités d'accessibilité

### 1. Labels et associations

Tous les composants `fr:field*` génèrent automatiquement des labels associés :

```xml
<fr:fieldInput label="Nom complet" value="#{bean.nom}" required="true" />
```

Génère :
```html
<div class="field">
    <label for="inputComponent">Nom complet <span class="p-error">*</span></label>
    <input id="inputComponent" type="text" aria-required="true" />
    <span class="p-message" role="alert"></span>
</div>
```

### 2. Indicateurs requis

Les champs requis affichent automatiquement un astérisque et l'attribut `aria-required` :

```xml
<fr:fieldInput label="Email" value="#{bean.email}" required="true" />
```

### 3. Messages de validation

Les messages d'erreur sont annoncés aux lecteurs d'écran via `role="alert"` :

```xml
<fr:fieldInput label="Téléphone" value="#{bean.phone}" required="true" />
<!-- Si erreur : message annoncé automatiquement -->
```

### 4. Navigation au clavier

| Composant | Raccourcis clavier |
|-----------|-------------------|
| `fieldInput` | Tab, Shift+Tab |
| `fieldSelect` | Tab, ↑↓ pour naviguer, Enter pour sélectionner |
| `fieldCalendar` | Tab, ↑↓←→ pour naviguer dans le calendrier |
| `fieldCheckbox` | Tab, Espace pour cocher/décocher |
| `fieldRadio` | Tab, ↑↓ pour changer de sélection |
| `button` | Tab, Enter ou Espace pour activer |
| `actionDialog` | Esc pour fermer, Tab pour naviguer |
| `dataTable` | Tab pour naviguer, ↑↓ pour les lignes |
| `tabView` | ←→ pour changer d'onglet |

### 5. Focus management

Les dialogs gèrent automatiquement le focus :

```xml
<fr:actionDialog widgetVar="editDialog" header="Éditer">
    <!-- Le focus est automatiquement placé sur le premier champ -->
    <fr:fieldInput label="Nom" value="#{bean.nom}" />
</fr:actionDialog>
```

### 6. Contraste des couleurs

Le thème Freya respecte les ratios de contraste WCAG :

- **Texte normal** : Ratio minimum 4.5:1
- **Texte large** : Ratio minimum 3:1
- **Composants UI** : Ratio minimum 3:1

### 7. Attributs ARIA

Les composants PrimeFaces sous-jacents incluent automatiquement :

- `aria-label` - Label pour les composants sans label visible
- `aria-required` - Indique les champs obligatoires
- `aria-invalid` - Indique les champs en erreur
- `aria-describedby` - Associe les messages d'aide
- `role` - Définit le rôle sémantique

## 📋 Bonnes pratiques

### ✅ À faire

1. **Toujours fournir un label**
   ```xml
   <fr:fieldInput label="Nom" value="#{bean.nom}" />
   ```

2. **Utiliser des labels descriptifs**
   ```xml
   <!-- ✅ Bon -->
   <fr:fieldInput label="Adresse email professionnelle" value="#{bean.email}" />
   
   <!-- ❌ Mauvais -->
   <fr:fieldInput label="Email" value="#{bean.email}" />
   ```

3. **Grouper les champs liés**
   ```xml
   <fieldset>
       <legend>Informations personnelles</legend>
       <fr:fieldInput label="Prénom" value="#{bean.prenom}" />
       <fr:fieldInput label="Nom" value="#{bean.nom}" />
   </fieldset>
   ```

4. **Fournir des messages d'erreur clairs**
   ```java
   @NotBlank(message = "Le nom est obligatoire")
   @Size(min = 2, max = 50, message = "Le nom doit contenir entre 2 et 50 caractères")
   private String nom;
   ```

5. **Utiliser des placeholders informatifs**
   ```xml
   <fr:fieldInput label="Téléphone" 
                  value="#{bean.phone}" 
                  placeholder="Ex: +33 6 12 34 56 78" />
   ```

### ❌ À éviter

1. **Ne pas utiliser uniquement la couleur pour transmettre l'information**
   ```xml
   <!-- ❌ Mauvais : uniquement la couleur rouge -->
   <span style="color: red;">Champ obligatoire</span>
   
   <!-- ✅ Bon : icône + texte + couleur -->
   <span class="p-error"><i class="pi pi-exclamation-circle"></i> Champ obligatoire</span>
   ```

2. **Ne pas omettre les labels**
   ```xml
   <!-- ❌ Mauvais -->
   <fr:fieldInput value="#{bean.nom}" placeholder="Nom" />
   
   <!-- ✅ Bon -->
   <fr:fieldInput label="Nom" value="#{bean.nom}" placeholder="Ex: Dupont" />
   ```

3. **Ne pas désactiver le focus visible**
   ```css
   /* ❌ Mauvais */
   *:focus {
       outline: none;
   }
   
   /* ✅ Bon : personnaliser mais garder visible */
   *:focus {
       outline: 2px solid var(--primary-color);
       outline-offset: 2px;
   }
   ```

## 🧪 Tests d'accessibilité

### Outils recommandés

1. **axe DevTools** - Extension Chrome/Firefox pour audit automatique
2. **WAVE** - Extension pour évaluation visuelle
3. **Lighthouse** - Audit intégré dans Chrome DevTools
4. **NVDA** (Windows) ou **VoiceOver** (Mac) - Lecteurs d'écran

### Checklist de test

- [ ] Navigation complète au clavier (Tab, Shift+Tab)
- [ ] Tous les champs ont des labels visibles
- [ ] Les champs requis sont indiqués
- [ ] Les messages d'erreur sont annoncés
- [ ] Le focus est visible sur tous les éléments interactifs
- [ ] Les dialogs piègent le focus
- [ ] Esc ferme les dialogs
- [ ] Les tableaux ont des en-têtes appropriés
- [ ] Les images ont des textes alternatifs
- [ ] Le contraste des couleurs est suffisant

### Exemple de test avec lecteur d'écran

```xml
<fr:fieldInput label="Nom complet" 
               value="#{bean.nom}" 
               required="true" 
               placeholder="Ex: Jean Dupont" />
```

**Annonce attendue** :
> "Nom complet, champ obligatoire, zone de texte, Ex: Jean Dupont"

## 🎨 Personnalisation accessible

### Thème sombre

Le thème Freya supporte le mode sombre avec contraste approprié :

```xml
<fr:themeSelector />
<!-- Permet à l'utilisateur de choisir light/dark -->
```

### Taille de police

Respecter les préférences utilisateur :

```css
/* ✅ Utiliser rem au lieu de px */
.custom-text {
    font-size: 1rem; /* S'adapte aux préférences utilisateur */
}
```

### Animations

Respecter `prefers-reduced-motion` :

```css
@media (prefers-reduced-motion: reduce) {
    * {
        animation-duration: 0.01ms !important;
        transition-duration: 0.01ms !important;
    }
}
```

## 📚 Ressources

- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [PrimeFaces Accessibility](https://www.primefaces.org/showcase/ui/misc/accessibility.xhtml)
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [WebAIM](https://webaim.org/)

## 🤝 Contribution

Si vous identifiez un problème d'accessibilité, veuillez :
1. Ouvrir une issue sur GitHub
2. Décrire le problème et le contexte
3. Fournir des suggestions de correction si possible

L'accessibilité est une priorité pour ce projet ! 🎯