> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arkatech.fr/llms.txt
> Use this file to discover all available pages before exploring further.
# Bonnes pratiques
> L'excellence du Frontend ne se limite pas à la beauté visuelle, mais inclut la robustesse, la rapidité et l'inclusivité.
# Accessibilité (RGAA, WCAG, ARIA)
L'accessibilité web vise à rendre les interfaces utilisables par le plus grand nombre de personnes, quelles que soient leurs capacités ou les outils qu'elles utilisent (lecteurs d'écran, navigation au clavier, etc.).
### **WCAG (Web Content Accessibility Guidelines)**
* **Définition :** Norme internationale, publiée par le W3C, fournissant des lignes directrices détaillées pour l'accessibilité des contenus web. C'est la référence mondiale.
* **Principes (POUR) :** Le contenu doit être :
* **P**erceptible (informations et composants UI présentés de manière perceptible).
* **O**pérable (l'utilisateur peut interagir avec les composants UI).
* **U**nterstable (le contenu doit être compréhensible).
* **R**obuste (le contenu peut être interprété de manière fiable par une grande variété d'agents utilisateurs, y compris les technologies d'assistance).
* **Niveaux de Conformité :** A (le plus bas), AA (le plus courant et souvent exigé légalement), et AAA (le plus strict).
### **RGAA (Référentiel Général d'Amélioration de l'Accessibilité)**
* **Définition :** Adaptation française et obligation légale, basée sur la WCAG, qui s'applique à toutes les entités publiques et à certaines grandes entreprises privées en France.
* **Objectif :** Garantir la mise en conformité des sites et applications web aux normes internationales pour le contexte administratif et légal français.
### **ARIA (Accessible Rich Internet Applications)**
* **Définition :** Ensemble d'attributs HTML spéciaux (`role`, `aria-*`) utilisés pour ajouter des informations sémantiques aux éléments d'interface qui n'en ont pas naturellement (widgets complexes créés avec des `div`).
* **Rôle :** Indiquer aux technologies d'assistance (comme les lecteurs d'écran) la fonction, l'état et la valeur d'un élément d'interface.
**Exemple de Code ARIA (Rendre un bouton de fermeture accessible)**
Un simple `div` stylisé n'est pas reconnu comme un bouton par un lecteur d'écran. ARIA corrige cela.
```
X
X
```
# Performance et Core Web Vitals
La performance Frontend est mesurée par l'expérience utilisateur réelle. Google a formalisé cette mesure avec les **Core Web Vitals (CWV)**, qui influencent directement le classement SEO.
**Métriques Clés (CWV)**
| **Métrique** | **Description** | **Objectif (Seuil)** |
| :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------- |
| **LCP (Largest Contentful Paint)** | Mesure le temps nécessaire pour que le plus grand élément (image ou bloc de texte) soit rendu visible à l'écran. | **\< 2.5 secondes** |
| **FID (First Input Delay)** | Mesure le temps entre la première interaction de l'utilisateur (clic, tap) et le moment où le navigateur peut commencer à traiter l'événement. | **\< 100 millisecondes** |
| **CLS (Cumulative Layout Shift)** | Mesure l'instabilité visuelle de la page (déplacements inattendus de contenu pendant le chargement). | **\< 0.1** |
**Bonnes Pratiques de Performance**
* **Optimisation des Ressources :**
* **Compression :** Utiliser des formats d'image modernes (WebP, AVIF) et compresser les fichiers JS/CSS.
* **Lazy Loading :** Différer le chargement des images et des composants situés hors écran (below the fold).
* **Critial CSS :** Isoler et charger *en ligne* (`inline`) le minimum de CSS nécessaire pour afficher le contenu visible immédiatement (le "Above the Fold"). Le reste du CSS peut être chargé de manière asynchrone.
* **Réduction du JS Bloquant :** Minimiser le code JavaScript qui doit être exécuté avant que la page ne devienne interactive. Utiliser le *code splitting* (séparer le code en petits paquets) et le chargement différé (`defer`, `async`).
* **Mise en Cache Agresive :** Utiliser des entêtes de mise en cache HTTP appropriées et des **Service Workers** (pour les PWA) afin de servir les ressources directement depuis le cache du navigateur.
# Documentation des Composants (Storybook)
Dans les applications modernes basées sur des composants (React, Vue, Angular), la documentation ne doit pas être un simple document statique, mais un **environnement de travail vivant**.
**Le Rôle de Storybook**
* **Définition :** Storybook est l'outil standard de l'industrie pour le développement, le test et la documentation des composants d'interface utilisateur (UI).
* **Fonctionnement :** Chaque composant est documenté par des "stories" qui représentent ses différents états (ex: un bouton `désactivé`, `actif`, `en chargement`).
* **Avantages :**
* **Développement Isolé :** Permet de développer les composants indépendamment du contexte de l'application, améliorant la concentration et les tests.
* **Bibliothèque de Design :** Sert de référence visuelle unique pour les designers et les développeurs, assurant la cohérence du système de design.
* **Tests de Régression Visuelle :** Facilite la vérification que les changements de code n'ont pas introduit d'effets secondaires visuels indésirables sur d'autres états du composant.
**Exemple de Code (Storybook)**
Une "story" décrit comment un composant doit être rendu dans un état particulier.
```typescript theme={null}
// Button.stories.js (Fichier de documentation pour un composant 'Button')
import { Button } from './Button';
// Exportation de l'état "Primaire"
export const Primary = {
args: {
label: 'Envoyer les données',
variant: 'primary',
disabled: false,
},
};
// Exportation de l'état "Désactivé"
export const Disabled = {
args: {
label: 'Opération impossible',
variant: 'secondary',
disabled: true, // Seul ce prop change
},
};
```