Contenus éditoriaux accessibles

Vue d'ensemble

La rédaction de contenus accessibles est essentielle pour garantir que l'information est perceptible, compréhensible et utilisable par tous les utilisateurs, quelles que soient leurs capacités cognitives, visuelles, auditives ou motrices.

Dans Codexia, les contenus éditoriaux incluent :

Documentation technique et fonctionnelle
Articles de blog
Messages d'interface
Contenus d'aide et tutoriels
Descriptions de fonctionnalités

Ce document définit les règles de rédaction et de structuration pour garantir la conformité RGAA 4.1 niveau AA.

Principes de rédaction accessible

1. Clarté et simplicité

Langage simple

Utiliser un vocabulaire courant et compréhensible
Éviter le jargon technique non expliqué
Préférer les phrases courtes (max 25-30 mots)
Une idée par phrase

Exemples :

❌ Mauvais :

L'instanciation du composant nécessite l'injection de dépendances via le conteneur de services afin de bénéficier de l'inversion de contrôle.

✅ Bon :

Pour créer ce composant, utilisez l'injection de dépendances. Cette technique permet de rendre le code plus modulaire et testable.

Définition des termes techniques

Définir les acronymes à la première occurrence
Fournir un glossaire pour les termes spécialisés (voir glossaire.md)

<!-- Première occurrence -->
<p>
  Le <abbr title="Référentiel Général d'Amélioration de l'Accessibilité">RGAA</abbr>
  est le référentiel français d'accessibilité numérique. Par la suite, nous utiliserons
  simplement RGAA.
</p>

2. Structure et hiérarchie

Hiérarchie des titres

Respecter l'ordre des titres (h1 → h2 → h3, sans saut)
Un seul <h1> par page (titre principal)
Titres descriptifs et informatifs

<h1>Accessibilité dans Codexia</h1>

  <h2>Principes généraux</h2>
    <h3>Perceptibilité</h3>
    <h3>Utilisabilité</h3>

  <h2>Standards de conformité</h2>
    <h3>RGAA 4.1</h3>
    <h3>WCAG 2.1</h3>

Listes

Utiliser des listes pour énumérer des éléments
<ul> pour les listes non ordonnées
<ol> pour les listes ordonnées ou les étapes

<!-- Étapes numérotées -->
<ol>
  <li>Cloner le dépôt Git</li>
  <li>Installer les dépendances avec <code>composer install</code></li>
  <li>Configurer le fichier <code>.env.local</code></li>
  <li>Lancer le serveur avec <code>symfony serve</code></li>
</ol>

Paragraphes

Un paragraphe = une idée principale
Paragraphes courts (3-5 phrases maximum)
Espacement suffisant entre les paragraphes

3. Liens explicites

Texte de lien descriptif

Le texte du lien doit être compréhensible hors contexte
Éviter "cliquez ici", "en savoir plus", "lire la suite"

❌ Mauvais :

Pour plus d'informations sur l'accessibilité, cliquez ici.

✅ Bon :

Consultez la documentation RGAA 4.1 pour plus d'informations.

Indication des liens externes

<a href="https://www.w3.org/WAI/WCAG21/" target="_blank" rel="noopener noreferrer">
  WCAG 2.1 (nouvelle fenêtre)
  <svg aria-hidden="true" class="icon-external">...</svg>
</a>

Liens vers des fichiers

Indiquer le format et le poids du fichier

<a href="/guide-complet.pdf">
  Guide complet de Codexia (PDF, 2,5 Mo)
</a>

4. Mise en forme et emphase

Gras et italique

<strong> pour une importance forte (sémantique)
<em> pour une emphase (sémantique)
Éviter l'utilisation excessive (ne pas mettre des paragraphes entiers en gras)

<p>
  <strong>Important :</strong> Assurez-vous de sauvegarder votre travail avant de continuer.
</p>

<p>
  L'accessibilité n'est <em>pas</em> une option, c'est une obligation légale.
</p>

Éviter les mises en forme uniquement visuelles

Ne pas utiliser uniquement la couleur, la taille ou la position pour transmettre une information
Toujours doubler avec du texte ou des icônes

❌ Mauvais :

Les champs en <span style="color: red;">rouge</span> sont obligatoires.

✅ Bon :

Les champs marqués d'un astérisque (*) sont obligatoires.

Images et médias

Images informatives

Alternative textuelle descriptive

<img
  src="/images/architecture-codexia.png"
  alt="Diagramme de l'architecture Codexia montrant les couches Controller, Service, Repository et Entity avec leurs relations"
  width="800"
  height="600"
/>

Règles pour les alt :

Décrire le contenu et la fonction de l'image
Ne pas commencer par "Image de..." ou "Photo de..."
Max 150 caractères (si plus long, utiliser longdesc ou une description adjacente)

Images décoratives

<img src="/images/decoration.png" alt="" role="presentation" />

L'attribut alt="" (vide) indique que l'image est décorative et sera ignorée par les lecteurs d'écran.

Images complexes

Pour les graphiques, diagrammes, ou images contenant beaucoup d'informations :

<figure>
  <img
    src="/images/stats-codexia.png"
    alt="Graphique montrant l'évolution des commits Codexia"
    aria-describedby="chart-description"
  />
  <figcaption id="chart-description">
    Le graphique montre l'évolution du nombre de commits par mois sur le projet Codexia
    de janvier à décembre 2025. On observe une progression constante avec un pic en juin
    (127 commits) et une moyenne de 85 commits par mois.
  </figcaption>
</figure>

Vidéos

Exigences d'accessibilité :

Sous-titres pour tout contenu audio (dialogues, narration, sons importants)
Transcription textuelle complète
Audiodescription pour le contenu visuel important non décrit dans l'audio
Contrôles accessibles au clavier

<video controls>
  <source src="/videos/demo-codexia.mp4" type="video/mp4" />
  <track kind="captions" src="/videos/demo-codexia.vtt" srclang="fr" label="Français" default />
  <track kind="descriptions" src="/videos/demo-codexia-ad.vtt" srclang="fr" label="Audiodescription" />
  <p>
    Votre navigateur ne supporte pas la vidéo HTML5.
    <a href="/videos/demo-codexia-transcript.html">Consulter la transcription</a>
  </p>
</video>

Audio

<audio controls>
  <source src="/audio/interview.mp3" type="audio/mpeg" />
  <p>
    Votre navigateur ne supporte pas l'élément audio.
    <a href="/audio/interview-transcript.html">Lire la transcription</a>
  </p>
</audio>

Transcription :

Fournir une transcription textuelle complète
Indiquer les changements de locuteur
Décrire les sons non verbaux significatifs

Tableaux de données

Tableaux simples

<table>
  <caption>Liste des fonctionnalités Codexia par version</caption>
  <thead>
    <tr>
      <th scope="col">Fonctionnalité</th>
      <th scope="col">Version</th>
      <th scope="col">Statut</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Authentification</td>
      <td>1.0</td>
      <td>Stable</td>
    </tr>
    <tr>
      <td>API REST</td>
      <td>1.1</td>
      <td>Beta</td>
    </tr>
  </tbody>
</table>

Exigences :

<caption> pour décrire le tableau
<th scope="col"> pour les en-têtes de colonne
<th scope="row"> pour les en-têtes de ligne

Tableaux complexes

Pour les tableaux avec en-têtes sur plusieurs niveaux ou cellules fusionnées :

<table>
  <caption>Compatibilité navigateurs de Codexia</caption>
  <thead>
    <tr>
      <th scope="col">Navigateur</th>
      <th scope="col" colspan="2">Desktop</th>
      <th scope="col" colspan="2">Mobile</th>
    </tr>
    <tr>
      <th scope="col"></th>
      <th scope="col">Windows</th>
      <th scope="col">macOS</th>
      <th scope="col">iOS</th>
      <th scope="col">Android</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Chrome</th>
      <td id="chrome-win">✓</td>
      <td headers="chrome-mac">✓</td>
      <td>✓</td>
      <td>✓</td>
    </tr>
  </tbody>
</table>

Alternatives aux tableaux

Pour les données simples, préférer des listes ou des cartes :

<!-- Au lieu d'un tableau 2 colonnes -->
<dl>
  <dt>Version</dt>
  <dd>1.2.0</dd>

  <dt>Date de sortie</dt>
  <dd>20 février 2026</dd>

  <dt>Auteur</dt>
  <dd>Mathieu Adrien</dd>
</dl>

Citations et code

Citations

<!-- Citation courte -->
<p>
  Comme le dit Tim Berners-Lee :
  <q cite="https://www.w3.org/standards/webdesign/accessibility">
    The power of the Web is in its universality.
    Access by everyone regardless of disability is an essential aspect.
  </q>
</p>

<!-- Citation longue -->
<blockquote cite="https://www.w3.org/standards/webdesign/accessibility">
  <p>
    The power of the Web is in its universality.
    Access by everyone regardless of disability is an essential aspect.
  </p>
  <footer>
    — <cite>Tim Berners-Lee</cite>, inventeur du World Wide Web
  </footer>
</blockquote>

Extraits de code

<!-- Code inline -->
<p>
  Utilisez la commande <code>composer install</code> pour installer les dépendances.
</p>

<!-- Bloc de code -->
<pre><code class="language-php">
&lt;?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class HomeController extends AbstractController
{
    public function index()
    {
        return $this->render('home/index.html.twig');
    }
}
</code></pre>

Accessibilité du code :

Indenter correctement pour faciliter la lecture
Utiliser la coloration syntaxique (améliore la lisibilité)
Limiter la largeur des lignes (max 80-120 caractères)
Fournir une explication textuelle avant ou après le code

Formulaires et messages

Messages d'erreur

Messages clairs et actionnables :

❌ Mauvais :

Erreur dans le formulaire.

✅ Bon :

Le champ "Adresse email" est obligatoire. Veuillez saisir une adresse email valide.

Positionnement :

Messages généraux en haut du formulaire
Messages spécifiques à côté du champ concerné
Utiliser aria-describedby pour lier le message au champ

Messages d'interface

Ton et style :

Courtois et professionnel
Direct et concis
Éviter l'humour ambigu ou le sarcasme
Utiliser "vous" pour s'adresser à l'utilisateur

Exemples :

❌ Mauvais :

Oups ! Quelque chose s'est cassé...

✅ Bon :

Une erreur est survenue lors de l'enregistrement. Veuillez réessayer.

Instructions

Avant l'action :

Fournir les instructions avant le champ ou l'action
Expliquer le format attendu
Indiquer les champs obligatoires

<div class="form-group">
  <label for="phone">
    Numéro de téléphone
    <span class="required" aria-label="obligatoire">*</span>
  </label>
  <small id="phone-help" class="form-text">
    Format attendu : 01 23 45 67 89 (10 chiffres, espaces optionnels)
  </small>
  <input
    type="tel"
    id="phone"
    name="phone"
    aria-describedby="phone-help"
    pattern="[0-9\s]{10,14}"
    required
  />
</div>

Langue et internationalisation

Langue du document

<!DOCTYPE html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <title>Codexia - Documentation</title>
</head>
<body>
  <!-- Contenu en français -->
</body>
</html>

Passages dans une autre langue

<p>
  L'accessibilité web est définie par le W3C comme
  <q lang="en">The power of the Web is in its universality</q>,
  ce qui signifie "La puissance du Web réside dans son universalité".
</p>

Traductions

Pour Codexia (support FR/EN, voir inputs/legacy/i18n.md) :

Traduire tous les contenus éditoriaux
Traduire les messages d'interface
Traduire les alternatives textuelles
Adapter les exemples et références culturelles

Documents téléchargeables

PDF accessibles

Exigences :

Conformes PDF/UA (ISO 14289)
Structure de document avec balises sémantiques
Ordre de lecture correct
Alternatives textuelles pour les images
Tableaux structurés
Formulaires accessibles

Outils :

Adobe Acrobat Pro (vérification et correction)
PAC (PDF Accessibility Checker)

Documents Office

Exigences :

Structure de titres
Alternatives textuelles
Tableaux simples et correctement structurés
Utiliser les fonctions d'accessibilité intégrées (Word, LibreOffice)

Formats alternatifs

Toujours proposer plusieurs formats :

HTML (le plus accessible)
EPUB (pour les longs documents, voir accessibility/epub.md)
PDF accessible
Version texte simple (.txt) en dernier recours

<p>Télécharger la documentation :</p>
<ul>
  <li><a href="/guide.html">Version HTML</a> (recommandé)</li>
  <li><a href="/guide.epub">Version EPUB</a> (PDF, 2,5 Mo)</li>
  <li><a href="/guide.pdf">Version PDF accessible</a> (PDF, 3,2 Mo)</li>
</ul>

Checklist contenus éditoriaux

Langage clair et simple
Phrases courtes (max 25-30 mots)
Acronymes définis à la première occurrence
Hiérarchie des titres respectée (h1 → h2 → h3)
Un seul h1 par page
Listes utilisées pour les énumérations
Paragraphes courts (3-5 phrases)
Liens explicites (pas de "cliquez ici")
Liens externes indiqués
Format et poids des fichiers indiqués
Images informatives avec alt descriptif
Images décoratives avec alt vide
Images complexes avec description longue
Vidéos avec sous-titres et transcription
Audio avec transcription
Tableaux avec caption et th scope
Citations avec balises sémantiques
Code indenté et commenté
Messages d'erreur clairs et actionnables
Instructions fournies avant l'action
Langue du document déclarée
Passages en langue étrangère marqués
PDF accessibles (PDF/UA)
Formats alternatifs proposés

Contenus éditoriaux accessibles

Vue d'ensemble

Principes de rédaction accessible

1. Clarté et simplicité

2. Structure et hiérarchie

3. Liens explicites

4. Mise en forme et emphase

Images et médias

Images informatives

Images décoratives

Images complexes

Vidéos

Audio

Tableaux de données

Tableaux simples

Tableaux complexes

Alternatives aux tableaux

Citations et code

Citations

Extraits de code

Formulaires et messages

Messages d'erreur

Messages d'interface

Instructions

Langue et internationalisation

Langue du document

Passages dans une autre langue

Traductions

Documents téléchargeables

PDF accessibles

Documents Office

Formats alternatifs

Checklist contenus éditoriaux

Outils de validation

Lisibilité

Accessibilité

PDF

Ressources

Guides de rédaction

Standards

Outils

Assistant documentaire