Système d'UI pour Blocs de Code
Objectif
Le Système d'UI pour Blocs de Code fournit un cadre de mise en page standardisé, accessible et à haute lisibilité pour afficher des extraits de code source, des corps de requêtes/réponses API, des exemples de code multi-fichiers, des lignes de commande de terminal et des comparaisons de différences de code. Les blocs de code sont des composants d'interaction critiques dans la documentation technique, les sites marketing d'outils pour développeurs, les portails API, les blogs d'ingénierie et les plateformes SaaS.
Concevoir des interfaces de code efficaces nécessite d'équilibrer la lisibilité de la typographie à chasse fixe, le surlignage des jetons de syntaxe à contraste élevé dans les thèmes clair et sombre, les barres d'outils d'action auto-fixées (badges de langage, navigation par onglets de fichiers, déclencheurs de copie dans le presse-papier), la numérotation des lignes, le surlignage/focalisation au niveau des lignes, les comportements de retour à la ligne vs défilement horizontal, et des expériences de lecteur d'écran accessibles. Cette compétence établit des règles spatiales, des normes de contraste des couleurs des jetons, des mécanismes d'interaction et des directives de conformité WCAG AA pour la présentation UI des blocs de code.
Cas d'Utilisation
- Documentation Développeur et Portails de Référence API : Présenter des exemples SDK multi-langages (par exemple, cURL, Node.js, Python, Go, Rust) et des réponses API.
- Pages d'Atterrissage d'Outils Développeur : Présenter des extraits de code héros, des commandes d'installation CLI et des blocs de démonstration de produit interactifs.
- Blogs d'Ingénierie et Tutoriels : Rendre des exemples de code en ligne et en bloc avec des appels de ligne spécifiques, des surlignages de code étape par étape et des annotations en ligne.
- Interfaces de Contrôle de Version et de Revue de Code : Afficher des différences de code (
+ajouts,-suppressions), des commentaires en ligne et des extraits de commit. - Outils de Partage d'Extraits de Code et de Bac à Sable : Structurer des éditeurs de fichiers multi-onglets, des volets de prévisualisation et des cartes d'extraits intégrables.
Quand NE PAS l'Utiliser
- Éditeurs de Code Complets dans le Navigateur (IDE) : Pour les IDE web interactifs complexes nécessitant un rendu par canevas, des arbres AST virtualisés, une édition multi-curseur et des intégrations de protocole de serveur de langage (LSP) (par exemple, Monaco Editor, CodeMirror), utilisez des implémentations d'éditeur dédiées.
- Champs de Saisie de Texte Généraux de Formulaires : Pour les champs de texte brut multilignes sans surlignage de syntaxe ni numérotation de lignes, utilisez
form-design-system. - Badges de Code en Ligne : Pour de brèves références de code d'un seul mot à l'intérieur de paragraphes de prose (par exemple,
npm install), utilisez le style<code>en ligne dansarticle-layout-system. - Tableaux de Données Structurées : Pour les données clé-valeur tabulaires ou les requêtes de base de données formatées en lignes et colonnes, utilisez
data-table-ui-systemouproperty-and-attribute-system.
Entrées
- Contenu du Code et Types de Syntaxe : La taxonomie du langage (par exemple, TypeScript, JSON, Bash, YAML, GraphQL, SQL) et les caractéristiques structurelles (fichier unique, onglets multi-fichiers, diff).
- Contexte du Thème : Jetons de palette de couleurs actifs pour les arrière-plans de surface, les bordures et les jetons de syntaxe en mode clair et en mode sombre (provenant de
accessible-color-systemetdark-theme-design-system). - Jetons de Typographie à Chasse Fixe : Pile de polices préférée (par exemple,
ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace), tailles de police et hauteurs de ligne (provenant defluid-typography-system). - Déclencheurs d'Action : Capacités interactives spécifiques requises par bloc (par exemple, bouton Copier en un clic, bascule de numérotation de lignes, bascule de retour à la ligne, expansion en plein écran, lien de bac à sable externe).
Sorties
- Spécification du Conteneur de Code et de la Barre d'Outils d'En-tête : Dispositions spatiales pour les conteneurs de blocs de code, les barres d'en-tête auto-fixées, les indicateurs de langage, les onglets de chemin de fichier et les groupes de boutons d'action.
- Palette de Couleurs de Jetons de Syntaxe Accessible : Correspondance des couleurs des jetons WCAG AA (rapport de contraste minimum de 4.5:1) pour les mots-clés, les chaînes, les fonctions, les variables, les commentaires, les opérateurs et les types dans les thèmes clair et sombre.
- Système de Hiérarchie et d'Annotation au Niveau de la Ligne : Plan directeur pour la numérotation des lignes, le surlignage/focalisation des lignes, les indicateurs de diff (
+/-) et les liens d'ancrage au niveau des lignes. - Modèle de Navigation Accessible pour Lecteur d'Écran et Clavier : Attributs de rôle ARIA, parcours de focus clavier, masquage des numéros de ligne (
aria-hidden="true"), et annonces de statut de copiearia-live. - Stratégie de Débordement et de Défilement Réactif : Règles pour les barres de défilement horizontales, les barres d'outils d'action auto-fixées, les bascules de retour à la ligne et les adaptations pour les petites fenêtres d'affichage mobiles.
Flux de Travail
1. Structurer l'Enveloppe du Bloc de Code et la Barre d'En-tête
Concevoir le conteneur et la barre d'action d'en-tête comme une unité cohérente et unifiée :
- Architecture du Conteneur : Définir un conteneur arrondi (
border-radius: 8px; border: 1px solid var(--border-subtle); overflow: hidden; background: var(--surface-code);). Utiliser un arrière-plan de surface distinct (généralement en mode sombre par défaut ou correspondant à la surface du thème). - Disposition de la Barre d'Outils d'En-tête : Rendre une barre d'en-tête auto-fixée en haut (
display: flex; align-items: center; justify-content: space-between; padding: 8px 16px; background: var(--surface-code-header); border-bottom: 1px solid var(--border-subtle);). - Section Gauche de l'En-tête (Onglets et Métadonnées) :
- Fichier Unique : Afficher le chemin/nom du fichier (par exemple,
src/auth/jwt.ts) avec une icône de type de fichier subtile, ou un badge de langage en majuscules (par exemple,TYPESCRIPT). - Multi-Fichiers / Multi-Langages : Rendre des boutons à onglets (
role="tablist"). L'onglet actif présente un texte à contraste élevé et un indicateur de bordure inférieure/pilulier (border-bottom: 2px solid var(--brand-primary)).
- Fichier Unique : Afficher le chemin/nom du fichier (par exemple,
- Section Droite de l'En-tête (Actions) : Grouper les déclencheurs d'action utilitaires :
- Bouton Copier : Bouton icône 32x32px (
aria-label="Copier le code dans le presse-papier") avec une icône de copie claire et un libellé sur les fenêtres plus larges. - Bascule Retour à la Ligne / Défilement (Optionnel) : Bouton icône pour basculer entre le retour à la ligne souple (
white-space: pre-wrap) et le défilement horizontal (white-space: pre). - Lien d'Expansion / Bac à Sable (Optionnel) : Déclencheur pour ouvrir l'extrait dans StackBlitz, CodeSandbox, ou en plein écran.
- Bouton Copier : Bouton icône 32x32px (
2. Établir la Typographie à Chasse Fixe et la Grille de Disposition
Assurer une lisibilité optimale pour la lecture technique et le scan du code :
- Pile de Polices : Définir une pile de polices à chasse fixe propre et à haute lisibilité :
ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace. Assurer que les réglages de fonctionnalités de police permettent une distinction claire entre0(zéro) etO(o majuscule), et1(un),l(L minuscule) etI(i majuscule). - Taille de Police et Hauteur de Ligne : Définir
font-size: 0.875rem(14px) avec une hauteur de ligne généreuse (line-height: 1.6/ 22.4px). Éviter les hauteurs de ligne serrées qui provoquent la collision des crochets et opérateurs de code. - Conteneur du Corps du Code : Utiliser
<pre class="code-block"><code class="language-typescript">avecdisplay: block; overflow-x: auto; padding: 16px 0; margin: 0; font-family: var(--font-mono);.
3. Concevoir les Numéros de Ligne, les Surlignages de Ligne et les Diffs
Structurer les éléments au niveau des lignes sans dégrader le comportement de copier-coller ou du lecteur d'écran :
- Structure de Ligne : Formater chaque ligne comme un conteneur de bloc distinct (
display: table-row;oudisplay: flex; width: 100%;). - Numéros de Ligne : Rendre les numéros de ligne dans une gouttière gauche (
display: table-cell; text-align: right; width: 40px; padding-right: 16px; user-select: none; color: var(--text-code-muted);).- Règle d'Accessibilité : Envelopper les numéros de ligne dans
<span aria-hidden="true">ou utiliser le contenu du compteur CSS (content: counter(line)) afin que les numéros de ligne ne soient pas copiés lors de la sélection de texte et ne soient pas lus à haute voix par les lecteurs d'écran entre les instructions de code.
- Règle d'Accessibilité : Envelopper les numéros de ligne dans
- Lignes Surlignées / Focalisées : Pour attirer l'attention sur les lignes clés dans un tutoriel ou un diff :
- Appliquer un arrière-plan de surlignage de ligne explicite (
background: var(--surface-code-highlight); border-left: 3px solid var(--brand-primary);). - S'assurer que la superposition de surlignage couvre toute la largeur défilable du conteneur de code (
min-width: 100%).
- Appliquer un arrière-plan de surlignage de ligne explicite (
- Lignes de Vue Diff (
+Ajout /-Suppression) :- Ligne Ajoutée : Arrière-plan vert subtil (
background: rgba(34, 197, 94, 0.15); border-left: 3px solid var(--color-success);). Afficher un symbole+dans la gouttière enveloppé dans<span class="sr-only">Ajouté :</span>pour les lecteurs d'écran. - Ligne Supprimée : Arrière-plan rouge subtil (
background: rgba(239, 68, 68, 0.15); border-left: 3px solid var(--color-danger);). Afficher un symbole-dans la gouttière enveloppé dans<span class="sr-only">Supprimé :</span>pour les lecteurs d'écran.
- Ligne Ajoutée : Arrière-plan vert subtil (
4. Créer une Palette de Couleurs de Jetons de Syntaxe Accessible
Les jetons de syntaxe doivent satisfaire aux ratios de contraste WCAG AA (minimum 4.5:1) par rapport à l'arrière-plan du bloc de code (var(--surface-code)) :
- Texte de Base / Variables : Lumineux neutre (par exemple,
#E2E8F0sur fond#0F172A; ratio ~12.5:1). - Mots-clés (
const,import,return,async) : Violet/magenta vif (par exemple,#C084FC; ratio ~7.2:1). - Fonctions et Méthodes (
fetchData,useState) : Bleu/cyan vif (par exemple,#38BDF8; ratio ~8.5:1). - Chaînes (
"https://api.example.com") : Vert/émeraude doux (par exemple,#4ADE80; ratio ~9.1:1). - Nombres et Booléens (
404,true) : Orange/ambre chaud (par exemple,#FB923C; ratio ~7.8:1). - Commentaires (
// Gérer la réponse du jeton) : Gris froid atténué conforme WCAG AA (par exemple,#94A3B8; ratio ~5.1:1). Ne jamais utiliser de gris à faible contraste (par exemple 2:1) pour les commentaires. - Opérateurs et Ponctuation (
=>,{,},;) : Neutre moyen (par exemple,#CBD5E1; ratio ~10.2:1).
5. Construire les États de Copie dans le Presse-papier et de Retour d'Action
Fournir un retour instantané pour les actions de copie empêche les clics en double et la frustration des utilisateurs :
- État Par Défaut : Afficher un bouton icône avec une icône de copie (deux rectangles se chevauchant) et un libellé optionnel ("Copier").
- État Hover / Focus : Arrière-plan de surface surélevé ou surlignage de bordure (
background: var(--surface-hover); outline: 2px solid var(--focus-ring)). - État Actif / Succès : Au clic, changer l'icône en une icône de coche, mettre à jour le libellé du bouton en "Copié !", et appliquer une teinte de couleur de succès (
color: var(--color-success)). - Notification pour Lecteur d'Écran : Annoncer dynamiquement le statut de la copie via une région
aria-live="polite"invisible : "Code copié dans le presse-papier". - Réinitialisation après Temporisation : Réinitialiser le bouton à l'état par défaut après 2000ms.
6. Adaptation Mobile et Réactive
Assurer que les longs extraits de code restent fonctionnels sur les petites fenêtres :
- Contention du Défilement Horizontal : Permettre le défilement horizontal (
overflow-x: auto) pour les longues lignes sur mobile sans déclencher de débordements de barre de défilement horizontale au niveau de la page. - Barre d'Outils d'En-tête Auto-fixée : Maintenir la barre d'outils d'en-tête épinglée (
position: sticky; top: 0; z-index: 10;) afin que le bouton de copie et l'onglet de fichier actif restent accessibles même lors du défilement de plus de 100 lignes de code. - Cibles Tactiles Mobiles : Assurer que les boutons de copie, les bascules de retour à la ligne et les onglets multi-fichiers satisfont une cible tactile minimale de 44x44px sur les appareils tactiles.
Règles de Décision
Contraste des Jetons de Syntaxe et Modes de Thème
| Catégorie de Syntaxe | Rôle de Jeton Recommandé | Couleur Thème Clair (sur #F8FAFC) | Couleur Thème Sombre (sur #0F172A) | Ratio de Contraste Min |
|---|---|---|---|---|
| Mots-clés | --token-keyword | Violet Foncé (#6B21A8) | Violet Vif (#C084FC) | ≥ 4.5:1 |
| Fonctions | --token-function | Cyan Foncé (#0369A1) | Bleu Ciel (#38BDF8) | ≥ 4.5:1 |
| Chaînes | --token-string | Vert Forêt (#15803D) | Émeraude Vif (#4ADE80) | ≥ 4.5:1 |
| Nombres / Booléens | --token-number | Ambre Foncé (#C2410C) | Ambre Vif (#FB923C) | ≥ 4.5:1 |
| Commentaires | --token-comment | Ardoise Atténué (#475569) | Ardoise Doux (#94A3B8) | ≥ 4.5:1 |
| Base / Variables | --token-base | Charbon (#0F172A) | Lumière Croustillante (#F8FAFC) | ≥ 7.0:1 |
Stratégie Retour à la Ligne vs Défilement Horizontal
- Défilement Horizontal (
white-space: pre) (Recommandé par Défaut) : Préserve l'intégrité de la mise en page du code, les alignements d'indentation et le formatage multi-ligne. Essentiel pour Python, YAML et les diffs de code où l'indentation véhicule la structure sémantique. - Retour à la Ligne Souple (
white-space: pre-wrap) (Mode Optionnel) : Recommandé pour les longues chaînes de sortie de terminal, les exemples de lignes de commande ou les widgets de barre latérale étroits où le défilement horizontal perturbe le flux de lecture.
Contraintes
- Accessibilité (WCAG 2.1 AA) :
- SC 1.4.3 Contraste (Minimum) : Toutes les couleurs des jetons de surlignage de syntaxe et les commentaires doivent atteindre un rapport de contraste minimum de 4.5:1 par rapport à l'arrière-plan du code.
- SC 2.1.1 Clavier : Les utilisateurs doivent pouvoir naviguer vers et activer les boutons de l'en-tête du bloc de code (onglets, bouton de copie) en utilisant
TabetSpace/Entrée. - SC 4.1.3 Messages de Statut : Le retour du bouton de copie doit être annoncé aux technologies d'assistance via une région
aria-live="polite". - SC 1.3.1 Informations et Relations : Les numéros de ligne doivent être cachés aux lecteurs d'écran (
aria-hidden="true"ou compteurs CSS) pour éviter les chiffres entrelacés pendant la lecture.
- Sélection de Texte et Copie : La sélection de texte à l'intérieur du bloc de code ne doit jamais sélectionner les numéros de ligne ou les marqueurs de diff (
+/-) dans le tampon du presse-papier. - Prévention des Changements de Mise en Page : L'expansion des onglets multi-fichiers ou le basculement du retour à la ligne doivent spécifier des hauteurs de ligne fixes ou des limites de conteneur pour éviter le Cumulative Layout Shift (CLS).
Schémas d'Échec Courants
- Commentaires à Faible Contraste Illisibles : Utilisation d'un texte gris pâle (par exemple,
#4A5568sur#1A202C, contraste 2.8:1) pour les commentaires, en supposant que les commentaires ne sont pas importants, en violation des directives WCAG AA. - Copie des Numéros de Ligne : Rendu des numéros de ligne comme texte brut à l'intérieur de
<pre>, ce qui fait que le copier-coller produit des extraits de code invalides préfixés par1 2 3 4. - Actions de Copie Non Annoncées : Modification des icônes visuelles du bouton de copie sans mettre à jour
aria-labelou envoyer une annoncearia-live, laissant les utilisateurs de lecteurs d'écran incertains si l'action a réussi. - Débordements de Page : Défaut de définir
max-width: 100%etoverflow-x: autosur<pre>, ce qui fait que les lignes de code de 120 caractères font exploser la mise en page de la page sur les écrans mobiles. - Pièges de Focus Inaccessibles dans le Défilement Horizontal : Placement de
tabindex="0"sur le bloc de code défilable sans indicateurs de contour visuel de clavier clairs, ce qui fait que les utilisateurs de clavier se retrouvent coincés à l'intérieur des longs blocs de code.
Critères de Validation
- Le bloc de code comprend un conteneur structuré avec une barre d'outils d'en-tête auto-fixée affichant la langue, le fichier