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 :

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

Génère :

<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 :

<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" :

<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 :

<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

   <fr:fieldInput label="Nom" value="#{bean.nom}" />
   

2. Utiliser des labels descriptifs

   <!-- ✅ Bon -->
   <fr:fieldInput label="Adresse email professionnelle" value="#{bean.email}" />
   
   <!-- ❌ Mauvais -->
   <fr:fieldInput label="Email" value="#{bean.email}" />
   

3. Grouper les champs liés

   <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

   @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

   <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

   <!-- ❌ 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

   <!-- ❌ 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

   /* ❌ 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

<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é :

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

Taille de police

Respecter les préférences utilisateur :

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

Animations

Respecter prefers-reduced-motion :

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

📚 Ressources

• WCAG 2.1 Guidelines
• PrimeFaces Accessibility
• WAI-ARIA Authoring Practices
• WebAIM

🤝 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 ! 🎯