Initial commit: PrimeFaces Freya Extension - Composants Freya pour PrimeFaces avec support Quarkus
This commit is contained in:
dahoud
252
ACCESSIBILITY.md
Normal file
252
ACCESSIBILITY.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# 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 ! 🎯
|
||||
|
||||
Reference in New Issue
Block a user