Des schémas en code : chaque figure de ce site est une petite fonction

Niveau IntermédiaireTemps estimé 45 minUn mot inconnu ? Lexique

Un schéma dessiné dans un éditeur est une image : il ne se traduit pas, il ne suit pas les couleurs du site, et personne ne le met à jour quand le système change. Chaque figure de ce site est du code à la place : une petite fonction qui écrit le SVG, si bien que le schéma vit à côté du texte, dans le dépôt, dans les deux langues.

Ce que vous y gagnez. Une cinquantaine de schémas rendus en français et en anglais à partir d'une seule source, nets à toutes les tailles, légers à charger, décrits pour les lecteurs d'écran, et vérifiés par un test à chaque construction. Changer un libellé tient en un commit d'une ligne.

1. Quelques aides, une fonction par schéma

def agents(lang):
    L = {"en": labels(cap="Three coding agents, three roles...", of="OpenFox", ...),
         "fr": labels(cap="Trois agents de code, trois rôles...", of="OpenFox", ...)}[lang]
    body  = box(20, 20, 230, 50, L["of"], L["ofs"], stroke=GOOD)
    body += box(500, 55, 220, 54, L["gw"], L["gws"], stroke=GOOD)
    body += arrow(250, 45, 498, 75, None, GOOD, marker="good")
    return figure("agents", 740, 295, L["cap"], body)

box, arrow et une aide pour le texte écrivent des formes SVG natives ; les couleurs viennent d'une poignée de constantes.
figure enveloppe le dessin dans <figure> avec sa légende, et donne au SVG role="img" et un aria-label portant la même phrase.
Une page appelle un schéma par un marqueur, {{diagram:agents}}, et la construction le remplace par la figure dans la langue de la page.

2. Les règles qui les gardent utiles

Une figure, une affirmation. La légende dit ce que montre l'image, en une ou deux phrases.
Dessinez le mécanisme, pas son nom : le chemin d'une requête, la flèche qui disparaît quand on retire une pièce.
Étiquetez les flèches quand l'étiquette porte une information (« votre tap », « réponse signée »).
La couleur veut dire quelque chose : une couleur pour le local, une pour le cloud, une pour un problème. Rien de décoratif.

3. Un test pour chaque schéma

Les tests du site rendent chaque schéma dans les deux langues et échouent si l'un manque ou n'a pas de légende, et la construction s'arrête sur un marqueur qui ne nomme aucun schéma. Une faute de frappe dans un marqueur ne peut pas atteindre le site.

Un nom de marqueur contenant un chiffre n'a pas été remplacé une fois, et s'est affiché brut sur la page. Le correctif était dans le motif ; la leçon, tester le marqueur et pas seulement le dessin.

4. Pour des graphiques plus riches : une skill de schémas

Pour un schéma autonome (une architecture, une frise, une machine à états, un couloir de nage), nous laissons un agent utiliser une skill de schémas : quarante-cinq types, chacun un fichier HTML autonome avec du SVG intégré et un style éditorial. Sa première règle est bonne : avant le premier schéma d'un projet, elle s'arrête et demande vos couleurs, plutôt que de livrer les siennes.

Pièges

Regardez un schéma rendu avant de le publier : des libellés qui se chevauchent ne lèvent aucune erreur. Nous rendons chaque nouvelle figure dans un navigateur sans écran et regardons la capture.

Utile ? Dites-nous ce qu'il faut mesurer ensuite.