> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Comment créer une documentation accessible

> Créez une documentation accessible selon les directives WCAG avec HTML sémantique, navigation clavier, texte alternatif et contenu inclusif.

Lorsque vous créez une documentation accessible, vous privilégiez une conception de contenu qui rend votre documentation utilisable par le plus grand nombre, quel que soit le moyen d'accès ou la manière dont les personnes interagissent avec elle.

Une documentation accessible améliore l'expérience de toutes et tous. Votre contenu est plus clair, mieux structuré et plus facile à parcourir, que les utilisateurs y accèdent avec un lecteur d'écran, la navigation au clavier, un appareil mobile ou des connexions réseau lentes.

Ce guide présente les bonnes pratiques pour une documentation accessible. L'accessibilité est un processus continu. Les technologies et les normes évoluent, et il y a toujours des opportunités d'amélioration. Commencez par les changements à fort impact et intégrez l'accessibilité à votre flux de travail.

<div id="what-is-accessibility">
  ## Qu'est-ce que l'accessibilité ?
</div>

L'accessibilité (parfois abrégée en a11y, pour le nombre de lettres entre la première et la dernière lettre d'« accessibility ») consiste à concevoir et à développer, de manière intentionnelle, des sites web et des outils utilisables par le plus grand nombre. Les personnes ayant un handicap temporaire ou permanent doivent bénéficier du même niveau d'accès aux technologies numériques. Concevoir pour l'accessibilité profite à tout le monde, y compris aux personnes qui consultent votre site web sur mobile ou via des réseaux lents.

Une documentation accessible respecte les normes d'accessibilité du web, principalement les [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/WCAG22/quickref/). Ces directives aident à garantir que votre contenu est perceptible, opérable, compréhensible et robuste.

<div id="get-started-with-accessibility">
  ## Premiers pas avec l'accessibilité
</div>

Rendre votre documentation accessible est un processus. Vous n'avez pas à tout corriger d'un coup et ce n'est pas quelque chose que l'on fait une seule fois.

Si vous commencez tout juste à mettre en place des pratiques d'accessibilité pour votre documentation, envisagez une approche progressive : commencez par les changements à fort impact, puis étoffez progressivement.

<div id="first-steps">
  ### Premiers pas
</div>

Voici trois actions que vous pouvez entreprendre dès maintenant pour améliorer l'accessibilité de votre documentation :

1. **Exécutez `mint a11y`** pour identifier les problèmes d'accessibilité dans votre contenu.
2. **Ajoutez un texte alternatif (alt text)** à toutes les images.
3. **Vérifiez la hiérarchie des titres** pour garantir un seul H1 par page et des titres qui se suivent dans l'ordre.

<div id="plan-your-accessibility-work">
  ### Planifiez votre travail en matière d'accessibilité
</div>

Le meilleur flux de travail est celui qui convient à votre équipe. Voici une approche possible de l'accessibilité :

**Phase 1 : Images et structure**

* Passez en revue toutes les images pour vérifier la présence d'un texte alternatif descriptif.
* Passez en revue les textes de lien et remplacez les formules génériques comme « cliquez ici ».
* Corrigez les problèmes de hiérarchie des titres dans l'ensemble de votre documentation.

**Phase 2 : Navigation et médias**

* Testez la navigation au clavier sur votre documentation.
* Testez la compatibilité avec les lecteurs d'écran.
* Ajoutez des sous-titres et des transcriptions aux vidéos intégrées.
* Vérifiez le contraste des couleurs.

**Phase 3 : Intégrez-la à votre flux de travail**

* Exécutez `mint a11y` avant de publier un nouveau contenu.
* Intégrez des vérifications d'accessibilité à votre processus de relecture de contenu.
* Testez la navigation au clavier lors de l'ajout de fonctionnalités interactives.
* Vérifiez que les nouveaux liens externes et contenus intégrés incluent des titles et descriptions appropriés.

Commencer modestement et intégrer l'accessibilité à votre flux de travail habituel la rend pérenne. Chaque amélioration aide davantage d'utilisateurs à accéder avec succès à votre documentation.

<div id="structure-your-content">
  ## Structurez votre contenu
</div>

Un contenu bien structuré est plus facile à parcourir et à comprendre, surtout pour les utilisateurs de lecteurs d'écran qui s'appuient sur les titres pour se déplacer dans les pages, ainsi que pour les personnes qui utilisent la navigation au clavier.

<div id="use-proper-heading-hierarchy">
  ### Utilisez une hiérarchie de titres correcte
</div>

Chaque page doit comporter un seul titre H1, défini par la propriété `title:` dans le frontmatter de la page. Utilisez ensuite les niveaux de titres dans l'ordre sans en sauter. Par exemple, ne passez pas de H2 à H4.

```mdx theme={null}
<!-- Bon -->
# Titre de la page (H1)

## Section principale (H2)

### Sous-section (H3)

### Autre sous-section (H3)

## Autre section principale (H2)

<!-- Mauvais -->
# Titre de la page (H1)

## Section principale (H2)

#### Sous-section (H4)

### Autre sous-section (H3)
```

Les titres d'un même niveau doivent avoir des noms uniques.

```mdx theme={null}
<!-- Bon -->
## Conseils d'accessibilité (H2)

### Rédiger un texte alternatif efficace (H3)

### Utiliser un contraste de couleur approprié (H3)

<!-- Mauvais -->
## Conseils d'accessibilité (H2)

### Conseil (H3)

### Conseil (H3)
```

<div id="write-descriptive-link-text">
  ### Rédigez un texte de lien descriptif
</div>

Le texte du lien doit être explicite et refléter la destination. Évitez les formulations vagues comme « cliquez ici » ou « en savoir plus ».

```mdx theme={null}
<!-- Bon -->
Découvrez comment [configurer votre navigation](/organize/navigation).

<!-- Relation peu claire entre le texte du lien et la destination -->
[En savoir plus](/organize/navigation).
```

<div id="keep-content-scannable">
  ### Facilitez le survol du contenu
</div>

* Scindez les longs paragraphes.
* Utilisez des listes pour les étapes et les options.
* Mettez en avant les informations avec des encadrés.

<div id="use-proper-table-structure">
  ### Utilisez une structure de tableau appropriée
</div>

N'utilisez les tableaux qu'avec parcimonie et uniquement pour des données tabulaires dont la signification découle des en-têtes de colonnes et de lignes.

Lorsque vous utilisez des tableaux, incluez des en-têtes afin que les lecteurs d'écran puissent associer les données à la bonne colonne :

<CodeGroup>
  ```mdx Bonne structure de tableau theme={null}
  | Fonctionnalité | Statut | Dernière mise à jour |
  | -------------- | ------ | -------------------- |
  | Recherche  | Actif | 2024-03-15   |
  | Analytics | Actif | 2024-03-10 |
  | Exports | Bêta | 2024-03-20 |
  ```

  ```mdx Structure de tableau médiocre theme={null}
  | Recherche | Actif | 2024-03-15 |
  | Analytics | Actif | 2024-03-10 |
  | Exports | Bêta | 2024-03-20 |
  ```
</CodeGroup>

L'exemple médiocre n'a pas d'en-têtes, ce qui empêche les lecteurs d'écran d'annoncer ce que représente chaque colonne.

<div id="write-descriptive-alt-text">
  ## Rédiger un texte alternatif descriptif
</div>

Le texte alternatif rend les images accessibles aux utilisateurs de lecteurs d'écran et s'affiche lorsque les images ne se chargent pas. Les images de votre documentation doivent comporter un texte alternatif qui décrit l'image et précise clairement pourquoi elle est incluse. Même avec un texte alternatif, ne vous fiez pas uniquement aux images pour transmettre des informations. Assurez-vous que votre contenu décrit ce que l'image communique.

<Tip>
  Pour en savoir plus sur l'utilisation des images, consultez le [guide des médias](/fr/guides/media).
</Tip>

<div id="write-effective-alt-text">
  ### Rédigez un texte alternatif efficace
</div>

* **Soyez précis** : Décrivez ce que montre l'image, pas seulement que c'est une image.
* **Soyez concis** : Contentez-vous d'une à deux phrases.
* **Évitez les redondances** : Ne commencez pas par « Image de » car les lecteurs d'écran savent déjà que le texte alternatif est associé à une image. En revanche, incluez des formulations comme « Capture d'écran de » ou « Schéma de » si ce contexte est important pour l'image.

```mdx theme={null}
<!-- Bon -->
![Capture d'écran du Dashboard montrant trois projets actifs et deux invitations en attente](/images/dashboard.png)

<!-- Pas utile -->
![Capture d'écran du Dashboard](/images/dashboard.png)
```

<div id="add-alt-text-to-images">
  ### Ajouter un texte alternatif aux images
</div>

Pour les images en Markdown, ajoutez un texte alternatif entre crochets :

```mdx theme={null}
![Description de l'image](/path/to/image.png)
```

Pour les images HTML, utilisez l'attribut « alt » :

```html theme={null}
<img
  src="/images/screenshot.png"
  alt="Panneau de paramètres avec les options d'accessibilité activées. Les options sont mises en évidence par un rectangle orange."
/>
```

<div id="add-titles-to-embedded-content">
  ### Ajouter des titres au contenu intégré
</div>

Les iframes et les vidéos intégrées doivent avoir des titres descriptifs :

```html theme={null}
<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutoriel : Configuration de votre premier site de documentation"
></iframe>
```

<div id="design-for-readability">
  ## Concevoir pour la lisibilité
</div>

Les choix de conception visuelle influencent l'accessibilité de votre documentation pour les personnes ayant une basse vision, un daltonisme ou d'autres déficiences visuelles.

<div id="ensure-sufficient-color-contrast">
  ### Assurez un contraste de couleurs suffisant
</div>

Si vous personnalisez les couleurs de votre thème, vérifiez que les taux de contraste respectent les exigences WCAG :

* Texte courant : taux de contraste minimal de 4,5:1
* Texte large : taux de contraste minimal de 3:1
* Éléments interactifs : taux de contraste minimal de 3:1

Testez le mode light et le mode sombre. La commande `mint a11y` vérifie le contraste des couleurs.

<CodeGroup>
  ```json Exemple de bon contraste theme={null}
  {
    "colors": {
      "primary": "#0066CC",
      "background": {
        "light": "#FFFFFF",
        "dark": "#1A1A1A"
      }
    }
  }
  ```

  ```json Exemple de contraste insuffisant theme={null}
  {
    "colors": {
      "primary": "#FFCC00",
      "background": {
        "light": "#FFFFFF",
        "dark": "#333333"
      }
    }
  }
  ```
</CodeGroup>

Dans l'exemple insuffisant, le jaune (#FFCC00) sur blanc présente un contraste insuffisant. L'arrière-plan en mode sombre (#333333) est trop clair pour une lisibilité optimale.

<div id="dont-rely-on-color-alone">
  ### Ne vous fiez pas uniquement à la couleur
</div>

Si vous utilisez la couleur pour transmettre une information, ajoutez également un libellé textuel ou une icône. Par exemple, ne signalez pas les erreurs uniquement avec du texte rouge. Ajoutez une icône d'erreur ou le mot « Erreur ».

<div id="use-clear-concise-language">
  ### Utilisez un langage clair et concis
</div>

* Rédigez dans un langage simple.
* Définissez les termes techniques lors de leur première utilisation.
* Évitez les phrases trop longues.
* Utilisez la voix active.

<Tip>
  Consultez le [guide de style et de ton](/fr/guides/style-and-tone) pour découvrir d'autres bonnes pratiques de rédaction.
</Tip>

<div id="make-code-examples-accessible">
  ## Rendre les exemples de code accessibles
</div>

Les code blocks sont un élément essentiel de la documentation technique, mais ils nécessitent des considérations d'accessibilité spécifiques pour que les utilisateurs de lecteurs d'écran puissent les comprendre. De manière générale, suivez ces recommandations :

* Divisez les longs exemples de code en sections plus petites et cohérentes.
* Commentez la logique complexe dans le code.
* Envisagez de fournir une description textuelle pour les algorithmes complexes.
* Lors de la présentation d'une arborescence de fichiers, utilisez de vrais code blocks avec des labels de langage plutôt que de l'art ASCII.

<div id="specify-the-programming-language">
  ### Indiquez le langage de programmation
</div>

Déclarez toujours la langue pour la coloration syntaxique. Cela aide les lecteurs d'écran à annoncer le contexte du code aux utilisateurs :

````mdx theme={null}
```javascript
function getUserData(id) {
  return fetch(`/api/users/${id}`);
}
```
````

<div id="provide-context-around-code">
  ### Fournir du contexte autour du code
</div>

Fournissez un contexte clair pour les code block :

````mdx theme={null}
La fonction suivante récupère les données utilisateur depuis l'API :

```javascript
function getUserData(id) {
  return fetch(`/api/users/${id}`);
}
```

Cela retourne une promesse qui se résout vers l'objet utilisateur.
````

<div id="video-and-multimedia-accessibility">
  ## Accessibilité des vidéos et des contenus multimédias
</div>

Les vidéos, animations et autres contenus multimédias doivent être accompagnés d'alternatives textuelles afin que tous les utilisateurs puissent accéder aux informations qu'ils contiennent.

<div id="add-captions-to-videos">
  ### Ajouter des sous-titres aux vidéos
</div>

Les sous-titres rendent le contenu vidéo accessible aux personnes sourdes ou malentendantes. Ils aident aussi les utilisateurs dans des environnements sensibles au bruit ainsi que les personnes non natives :

* Utilisez des sous-titres pour tout le contenu parlé des vidéos.
* Incluez les effets sonores pertinents dans les sous-titres.
* Assurez-vous que les sous-titres sont synchronisés avec l'audio.
* Utilisez une ponctuation appropriée et identifiez les locuteurs lorsque plusieurs personnes parlent.

La plupart des plateformes d'hébergement vidéo permettent d'ajouter des sous-titres. Importez des fichiers de sous-titres ou utilisez des sous-titres générés automatiquement comme point de départ, puis vérifiez leur exactitude.

<div id="provide-transcripts">
  ### Fournir des transcriptions
</div>

Les transcriptions offrent un autre moyen d'accéder au contenu vidéo. Elles sont consultables par recherche, plus faciles à référencer et accessibles aux lecteurs d'écran :

```mdx theme={null}
<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutoriel : Configuration de l'authentification"
></iframe>

<Accordion title="Transcription vidéo">
Dans ce tutoriel, nous allons voir comment configurer l'authentification...
</Accordion>
```

Placez les transcriptions à proximité de la vidéo ou fournissez un lien clair pour y accéder.

<div id="consider-alternatives-to-video-only-content">
  ### Envisagez des alternatives au contenu exclusivement vidéo
</div>

Si des informations essentielles ne figurent que dans une vidéo :

* Fournissez les mêmes informations sous forme de texte.
* Ajoutez des captures d'écran clés avec un texte alternatif descriptif.
* Rédigez un tutoriel qui couvre la même matière.

Ainsi, les utilisateurs qui n'ont pas accès au contenu vidéo peuvent tout de même mener à bien leur tâche.

<div id="test-your-documentation">
  ## Testez votre documentation
</div>

Des tests réguliers vous aident à repérer les problèmes d'accessibilité avant que les utilisateurs ne les rencontrent.

<div id="check-for-accessibility-issues-with-mint-a11y">
  ### Vérifiez les problèmes d'accessibilité avec `mint a11y`
</div>

Utilisez la commande d'interface en ligne de commande (CLI) `mint a11y` pour analyser automatiquement votre documentation à la recherche de problèmes d'accessibilité courants :

```bash theme={null}
mint a11y
```

La commande vérifie :

* Texte alternatif manquant pour les images et les vidéos.
* Contraste des couleurs insuffisant.

<div id="interpret-the-output">
  #### Interpréter le résultat
</div>

Une fois l'analyse terminée, un rapport similaire au suivant s'affiche :

```bash theme={null}
Accessibility Issues Found:

❌ Missing alt text (3 issues)
  - /guides/quickstart.mdx:45 - Image missing alt text
  - /api-reference/users.mdx:12 - Image missing alt text
  - /guides/setup.mdx:89 - Video missing title attribute

⚠️  Color contrast (2 issues)
  - Primary color (#FFCC00) on light background fails WCAG AA (2.1:1)
  - Link color (#FF6B6B) on dark background fails WCAG AA (3.2:1)

✅ 0 issues found in 15 other pages
```

<div id="fix-common-issues">
  #### Corriger les problèmes courants
</div>

**Texte alternatif manquant** : Ajoutez un texte alternatif descriptif à l'image ou à la vidéo :

```mdx theme={null}
<!-- Avant -->
![](/images/dashboard.png)

<!-- Après -->
![Dashboard montrant trois projets actifs et deux invitations en attente](/images/dashboard.png)
```

**Échecs de contraste de couleurs** : Mettez à jour les couleurs de votre thème dans `docs.json` :

```json theme={null}
{
  "colors": {
    "primary": "#0066CC",  // Modifié depuis #FFCC00
    "light": "#3399FF",
    "dark": "#004C99"
  }
}
```

Exécutez à nouveau `mint a11y` pour valider vos corrections.

<div id="use-flags-for-targeted-checks">
  #### Utilisez des flags pour des vérifications ciblées
</div>

Utilisez des flags pour vérifier des problèmes d'accessibilité spécifiques :

```bash theme={null}
# Vérifier uniquement les textes alternatifs manquants
mint a11y --skip-contrast

# Vérifier uniquement les problèmes de contraste des couleurs
mint a11y --skip-alt-text

# Faire échouer le pipeline CI/CD si des problèmes sont détectés
mint a11y --fail-on-error
```

<div id="basic-keyboard-navigation-test">
  ### Test de base de la navigation au clavier
</div>

Parcourez votre documentation en utilisant uniquement votre clavier :

1. Appuyez sur <kbd>Tab</kbd> pour avancer dans les éléments interactifs.
2. Appuyez sur <kbd>Shift</kbd> + <kbd>Tab</kbd> pour revenir en arrière.
3. Appuyez sur <kbd>Enter</kbd> pour activer les liens et les boutons.
4. Vérifiez que tous les éléments interactifs sont accessibles et affichent un indicateur de focus visible.

<div id="go-deeper-with-accessibility-testing">
  ### Approfondissez vos tests d'accessibilité
</div>

Pour des évaluations plus complètes :

* **Lecteurs d'écran** : Testez avec [NVDA (Windows)](https://www.nvaccess.org/) ou [VoiceOver (Mac)](https://www.apple.com/accessibility/voiceover/).
* **Extensions de navigateur** : Installez [axe DevTools](https://www.deque.com/axe/browser-extensions/) ou [WAVE](https://wave.webaim.org/extension/) pour analyser les pages et détecter les problèmes.
* **Directives WCAG** : Consultez les [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG22/quickref/) pour connaître les normes détaillées.

<div id="frequently-asked-questions">
  ## Foire aux questions
</div>

<AccordionGroup>
  <Accordion title="Ma documentation doit-elle être conforme à WCAG AA ou AAA ?">
    La plupart des organisations visent la conformité WCAG 2.1 niveau AA, qui constitue la norme pour de nombreuses obligations légales et offre un bon équilibre entre accessibilité et faisabilité. Le niveau AAA est plus exigeant et n'est pas toujours réalisable pour tous les types de contenu.

    Commencez par le niveau AA comme référence. La commande `mint a11y` vérifie les exigences courantes du niveau AA, comme le contraste des couleurs et le texte alternatif.
  </Accordion>

  <Accordion title="Comment tester ma documentation avec un lecteur d'écran ?">
    Sur Mac, utilisez VoiceOver intégré (appuyez sur <kbd>Cmd</kbd> + <kbd>F5</kbd> pour l'activer). Sur Windows, téléchargez [NVDA](https://www.nvaccess.org/) (gratuit et open source). Parcourez votre documentation en n'utilisant que le lecteur d'écran et écoutez si les titres sont annoncés correctement, si les textes de lien sont descriptifs, si les images ont un texte alternatif et si l'ordre de lecture est logique. Pas besoin d'être expert pour repérer les principaux problèmes.
  </Accordion>

  <Accordion title="Quelle est la différence entre le texte alternatif et les légendes d'image ?">
    **Le texte alternatif** est lu par les lecteurs d'écran et s'affiche lorsque les images ne se chargent pas. Il décrit ce que montre l'image et pourquoi elle est pertinente. Le texte alternatif est obligatoire pour l'accessibilité.

    **Les légendes** apparaissent sous les images pour tous les utilisateurs. Elles fournissent un contexte supplémentaire, l'attribution ou une explication. Les légendes sont facultatives et complètent le texte alternatif.

    Utilisez les deux lorsqu'une image nécessite à la fois une description (texte alternatif) et un contexte supplémentaire (légende).
  </Accordion>

  <Accordion title="Puis-je utiliser des emojis dans une documentation accessible ?">
    Oui, mais avec parcimonie. Les lecteurs d'écran annoncent à voix haute le nom des emojis ; plusieurs emojis à la suite deviennent donc gênants. Par exemple, 🎉 devient « party popper » et 🚀 devient « rocket », si bien que 🎉 🚀 devient « party popper rocket ». Évitez d'utiliser des emojis pour transmettre des informations essentielles. Si l'emoji était supprimé, le sens devrait rester clair. En cas de doute, préférez le texte.
  </Accordion>

  <Accordion title="Comment gérer l'accessibilité des exemples de code ?">
    Indiquez le langage sur chaque code block pour la coloration syntaxique. Apportez du contexte avant et après les code blocks afin que les utilisateurs de lecteurs d'écran comprennent ce que fait le code, car les lecteurs d'écran survolent souvent le code lui-même. Divisez les longs exemples en plus petits morceaux et utilisez des noms de variables descriptifs qui ont du sens à l'oral.
  </Accordion>

  <Accordion title="Que faire si je ne peux pas corriger tous les problèmes d'accessibilité immédiatement ?">
    Priorisez par impact. Corrigez en premier le texte alternatif manquant, la navigation au clavier défaillante et le contraste des couleurs insuffisant : ce sont les problèmes qui touchent le plus d'utilisateurs. Viennent ensuite la mauvaise hiérarchie des titres et les textes de lien vagues. Documentez les problèmes connus avec un plan pour les traiter. Le progrès vaut mieux que la perfection.
  </Accordion>
</AccordionGroup>

<div id="additional-resources">
  ## Ressources supplémentaires
</div>

Approfondissez vos connaissances en accessibilité avec ces ressources de confiance :

* **[WebAIM](https://webaim.org/)** : articles et tutoriels pratiques sur l'accessibilité du web
* **[The A11y Project](https://www.a11yproject.com/)** : ressources communautaires et liste de vérification sur l'accessibilité
* **[W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)** : normes officielles et recommandations en matière d'accessibilité