Créateur de Diagrammes HTML
Générez des fichiers .html autonomes avec un seul <svg> en ligne qui argumentent visuellement, pas seulement qui affichent des informations. Capturez-les ensuite avec Playwright, inspectez le PNG et corrigez jusqu'à ce que ce soit parfait.
Fichiers de cette compétence
| Fichier | Utilité | Quand le lire |
|---|---|---|
references/color-palette.md | Toutes les couleurs et styles de marque : la source unique de vérité | Avant chaque diagramme |
references/visual-patterns.md | Croquis de chaque motif de disposition (fan-out, timeline, arbre...) | Étape de conception 2 |
references/starter.html | Coquille de page : tokens CSS, classes de texte/formes, marqueurs de flèche, un exemple de chaque convention | Copiez-le comme point de départ de chaque diagramme |
scripts/render.py | Capture l'HTML en PNG et vérifie la géométrie | Exécutez après chaque édition (voir Rendu & Validation) |
examples/ | Deux diagrammes terminés avec leurs PNG | Lorsque vous voulez une référence pour la densité et le style |
Pour restyler chaque diagramme pour une marque, éditez color-palette.md (et les tokens correspondants dans starter.html). Tout le reste est une méthode universelle.
Deux décisions déjà prises (Ne pas les remettre en question par diagramme)
1. Tout est SVG. HTML n'est que la page autour.
Les boîtes, le texte, les flèches et les blocs de code vivent tous dans un seul <svg id="diagram">. Ne construisez pas de boîtes avec du HTML/CSS (flexbox/grid div) avec une superposition SVG pour les connecteurs.
Pourquoi : un diagramme est un problème de géométrie, et les flèches ont besoin de coordonnées exactes pour les deux extrémités. Avec du SVG intégral, chaque nœud et chaque flèche partagent un système de coordonnées unique qui est écrit dans le fichier, vous pouvez donc calculer une extrémité de flèche par arithmétique et la corriger en modifiant un nombre. Avec des boîtes HTML, les positions proviennent du moteur de mise en page du navigateur : elles ne sont pas dans la source, elles changent avec les polices et la largeur de la fenêtre, et les connecteurs ont alors besoin de JavaScript qui mesure les boîtes à l'exécution. C'est un deuxième programme à déboguer, et la fenêtre du lecteur peut différer de celle que vous avez validée. Les coûts du SVG intégral sont réels mais plus petits : le texte SVG ne se retourne pas (coupez les lignes vous-même avec <tspan>) et sa largeur n'est pas connue avant le rendu (le vérificateur la mesure et signale les débordements).
<foreignObject> (HTML dans SVG) est désactivé par défaut : c'est le seul endroit où vous auriez un retour à la ligne automatique, mais il s'affiche de manière incohérente en dehors des navigateurs et le vérificateur ne peut pas le contrôler. Utilisez-le uniquement si l'utilisateur a besoin de paragraphes à l'intérieur d'une forme.
2. Pas de Graphviz ou D2 pour la disposition. Placez les coordonnées à la main.
Pourquoi : la méthodologie exige que la disposition reflète le concept : fan-outs, timelines, cycles, comparaisons côte à côte, annotations flottantes, blocs de code placés à côté de l'étape qu'ils illustrent. Les moteurs de disposition automatique optimisent pour un objectif différent (graphes en couches avec peu d'intersections d'arêtes), donc ils aplatissent chaque diagramme dans la même hiérarchie de haut en bas, ce qui est exactement la sortie « boîtes uniformes » que cette compétence existe pour éviter. Ils ajoutent également une dépendance binaire et produisent un SVG difficile à restyler et à annoter.
L'exception : un sujet vraiment en forme de graphe (environ 15+ nœuds avec de nombreuses connexions croisées, comme un graphe de dépendances) où les croisements sont le problème principal. Dans ce cas, exécutez dot -Tplain (Graphviz) uniquement pour obtenir les coordonnées des nœuds, puis dessinez les nœuds vous-même avec les styles et conventions de cette compétence. Dites que vous faites cela et pourquoi.
Philosophie fondamentale
Les diagrammes doivent ARGUMENTER, pas AFFICHER.
Un diagramme n'est pas du texte formaté. C'est un argument visuel qui montre des relations, des causalités et des flux que les mots seuls ne peuvent pas exprimer. La forme DOIT être le sens.
Le test d'isomorphisme : si vous supprimez tout le texte, la structure seule communique-t-elle le concept ? Sinon, reconcevez.
Le test d'éducation : Quelqu'un pourrait-il apprendre quelque chose de concret à partir de ce diagramme, ou se contente-t-il d'étiqueter des boîtes ? Un bon diagramme enseigne – il montre des formats réels, des noms d'événements réels, des exemples concrets.
Évaluation de la profondeur (À faire en premier)
Avant de concevoir, déterminez le niveau de détail dont ce diagramme a besoin :
Diagrammes simples / conceptuels
Utilisez des formes abstraites lorsque :
- Vous expliquez un modèle mental ou une philosophie
- Le public n'a pas besoin de spécificités techniques
- Le concept EST l'abstraction (ex. : « séparation des préoccupations »)
Diagrammes complets / techniques
Utilisez des exemples concrets lorsque :
- Vous diagrammez un système, un protocole ou une architecture réelle
- Le diagramme sera utilisé pour enseigner ou expliquer (ex. : vidéo YouTube)
- Le public a besoin de comprendre à quoi les choses ressemblent réellement
- Vous montrez comment plusieurs technologies s'intègrent
Pour les diagrammes techniques, vous DEVEZ inclure des artefacts de preuve (voir ci-dessous).
Mandat de recherche (Pour les diagrammes techniques)
Avant de dessiner quoi que ce soit de technique, recherchez les spécifications réelles.
Si vous diagrammez un protocole, une API ou un framework :
- Recherchez les formats JSON/données réels
- Trouvez les vrais noms d'événements, noms de méthodes ou points de terminaison API
- Comprenez comment les pièces se connectent réellement
- Utilisez la terminologie réelle, pas des espaces réservés génériques
Mauvais : « Protocole » → « Frontend » Bon : « AG-UI diffuse des événements (RUN_STARTED, STATE_DELTA, A2UI_UPDATE) » → « CopilotKit rend via createA2UIMessageRenderer() »
La recherche rend les diagrammes précis ET éducatifs.
Artefacts de preuve
Les artefacts de preuve sont des exemples concrets qui prouvent que votre diagramme est précis et aident les spectateurs à apprendre. Incluez-les dans les diagrammes techniques.
Types d'artefacts de preuve (choisissez ce qui est pertinent pour votre diagramme) :
| Type d'artefact | Quand l'utiliser | Comment le rendre |
|---|---|---|
| Extraits de code | API, intégrations, détails d'implémentation | Rectangle sombre + texte coloré par syntaxe (voir palette de couleurs pour les couleurs des artefacts de preuve) |
| Exemples de données/JSON | Formats de données, schémas, payloads | Rectangle sombre + texte coloré (voir palette de couleurs) |
| Séquences d'événements/étapes | Protocoles, workflows, cycles de vie | Motif de timeline (ligne + points + étiquettes) |
| Maquettes d'interface | Montrer les résultats/sorties réelles | Rectangles imbriqués imitant une interface réelle |
| Contenu d'entrée réel | Montrer ce qui ENTRE dans un système | Rectangle avec un exemple de contenu visible |
| Noms d'API/méthodes | Appels de fonction réels, points de terminaison | Utilisez les noms réels de la documentation, pas des espaces réservés |
Exemple : Pour un diagramme sur un protocole de streaming, vous pourriez montrer :
- Les vrais noms d'événements de la spécification (pas seulement « Événement 1 », « Événement 2 »)
- Un extrait de code montrant comment se connecter
- À quoi ressemblent réellement les données streamées
Exemple : Pour un diagramme sur un pipeline de transformation de données :
- Montrez des données d'entrée exemple (format réel, pas « Entrée »)
- Montrez des données de sortie exemple (format réel, pas « Sortie »)
- Montrez les états intermédiaires si pertinent
Le principe clé : montrez à quoi les choses ressemblent réellement, pas seulement comment elles s'appellent.
Architecture multi-zoom
Les diagrammes complets fonctionnent à plusieurs niveaux de zoom simultanément. Pensez-y comme à une carte qui montre à la fois les frontières des pays ET les noms des rues.
Niveau 1 : Flux résumé
Un aperçu simplifié montrant l'ensemble du pipeline ou du processus en un coup d'œil. Souvent placé en haut ou en bas du diagramme.
Exemple : Entrée → Traitement → Sortie ou Client → Serveur → Base de données
Niveau 2 : Limites de sections
Des régions étiquetées qui regroupent des composants connexes. Cela crée des « pièces » visuelles qui aident les spectateurs à comprendre ce qui va ensemble.
Exemple : Regroupement par responsabilité (Backend / Frontend), par phase (Configuration / Exécution / Nettoyage), ou par équipe (Utilisateur / Système / Externe)
Niveau 3 : Détails à l'intérieur des sections
Des artefacts de preuve, des extraits de code et des exemples concrets dans chaque section. C'est là que réside la valeur éducative.
Exemple : Dans une section « Backend », vous pourriez montrer le format de réponse API réel, pas seulement une boîte étiquetée « Réponse API »
Pour les diagrammes complets, visez à inclure les trois niveaux. Le résumé donne le contexte, les sections organisent, et les détails enseignent.
Mauvais vs Bon
| Mauvais (Affichage) | Bon (Argumentation) |
|---|---|
| 5 boîtes égales avec des étiquettes | Chaque concept a une forme qui reflète son comportement |
| Disposition en grille de cartes | La structure visuelle correspond à la structure conceptuelle |
| Icônes décorant le texte | Des formes qui SONT le sens |
| Même conteneur pour tout | Vocabulaire visuel distinct par concept |
| Tout dans une boîte | Texte flottant avec des conteneurs sélectifs |
Simple vs Complet (Sachez lequel vous avez besoin)
| Diagramme Simple | Diagramme Complet |
|---|---|
| Étiquettes génériques : « Entrée » → « Traitement » → « Sortie » | Spécifique : montre à quoi ressemblent réellement l'entrée/la sortie |
| Boîtes nommées : « API », « Base de données », « Client » | Boîtes nommées + exemples de requêtes/réponses réelles |
| Étiquette « Événements » ou « Messages » | Timeline avec les vrais noms d'événements/messages de la spécification |
| Rectangle « UI » ou « Tableau de bord » | Maquette montrant les éléments d'interface et le contenu réels |
| ~30 secondes pour expliquer | ~2-3 minutes de contenu pédagogique |
| Le spectateur apprend la structure | Le spectateur apprend la structure ET les détails |
Les diagrammes simples sont parfaits pour les concepts abstraits, les aperçus rapides ou lorsque le public connaît déjà les détails. Les diagrammes complets sont nécessaires pour les architectures techniques, les tutoriels, le contenu éducatif ou lorsque vous voulez que le diagramme lui-même enseigne.
Texte en conteneur vs texte flottant
Tout texte n'a pas besoin d'une forme autour de lui. Par défaut, utilisez du texte flottant. Ajoutez des conteneurs uniquement lorsqu'ils servent un objectif.
| Utilisez un Conteneur Lorsque... | Utilisez du Texte Flottant Lorsque... |
|---|---|
| C'est le point central d'une section | C'est une étiquette ou une description |
| Il a besoin d'un regroupement visuel avec d'autres éléments | C'est un détail de support ou des métadonnées |
| Des flèches doivent s'y connecter | Il décrit quelque chose à proximité |
| La forme elle-même porte un sens (losange de décision, etc.) | La typographie seule crée une hiérarchie suffisante |
| Il représente une « chose » distincte dans le système | C'est un titre de section, un sous-titre ou une annotation |
La typographie comme hiérarchie : Utilisez la taille, le poids et la couleur de la police pour créer une hiérarchie visuelle sans boîtes. Un titre de 28 px n'a pas besoin d'un rectangle autour de lui.
Le test du conteneur : Pour chaque élément encadré, demandez-vous « Cela fonctionnerait-il comme du texte flottant ? » Si oui, supprimez le conteneur.
Processus de conception (À faire AVANT d'écrire le SVG)
Étape 0 : Évaluer la profondeur requise
Avant toute chose, déterminez si cela doit être :
- Simple / Conceptuel : Formes abstraites, étiquettes, relations (modèles mentaux, philosophies)
- Complet / Technique : Exemples concrets, extraits de code, données réelles (systèmes, architectures, tutoriels)
Si complet : Faites des recherches d'abord. Recherchez les spécifications réelles, les formats, les noms d'événements, les API.
Étape 1 : Comprendre en profondeur
Lisez le contenu. Pour chaque concept, demandez-vous :
- Que FAIT ce concept ? (pas ce qu'IL EST)
- Quelles relations existent entre les concepts ?
- Quelle est la transformation ou le flux central ?
- De quoi quelqu'un aurait-il besoin de VOIR pour comprendre cela ? (pas seulement lire à ce sujet)
Étape 2 : Mapper les concepts aux motifs
Pour chaque concept, trouvez le motif visuel qui reflète son comportement. Les croquis et les notes d'utilisation pour chaque motif se trouvent dans references/visual-patterns.md.
| Si le concept... | Utilisez ce motif |
|---|---|
| Génère plusieurs sorties | Fan-out (flèches radiales depuis le centre) |
| Combine des entrées en une seule | Convergence (entonnoir, flèches qui fusionnent) |
| A une hiérarchie / imbrication | Arbre (lignes + texte flottant) |
| Est une séquence d'étapes | Timeline (ligne + points + étiquettes flottantes) |
| Boucle ou s'améliore en continu | Spirale / Cycle (flèche retournant au début) |
| Est un état ou un contexte abstrait | Nuage (ellipses qui se chevauchent) |
| Transforme l'entrée en sortie | Chaîne de montage (avant → processus → après) |
| Compare deux choses | Côte à côte (parallèle avec contraste) |
| Se sépare en phases | Espace / Pause (séparation visuelle entre les sections) |
Étape 3 : Assurer la variété
Pour les diagrammes à concepts multiples : chaque concept majeur doit utiliser un motif visuel différent. Pas de cartes ou grilles uniformes.
Étape 4 : Esquisser le flux
Avant d'écrire le balisage, tracez mentalement comment l'œil se déplace dans le diagramme. Il doit y avoir une histoire visuelle claire.
Étape 5 : Construire le HTML/SVG
Ce n'est qu'à ce moment-là que vous écrivez le fichier, en commençant par references/starter.html. Disposez sur une grille de 20 px et notez les coordonnées clés (colonnes, lignes, centres des nœuds) avant de placer quoi que ce soit. Voir ci-dessous pour savoir comment traiter les grands diagrammes.
Étape 6 : Rendu & Validation (OBLIGATOIRE)
Après avoir écrit le fichier, vous DEVEZ exécuter la boucle rendu-visualisation-correction jusqu'à ce que le diagramme ait l'air correct. Ce n'est pas facultatif — voir la section Rendu & Validation ci-dessous pour le processus complet.
Stratégie pour les grands / diagrammes complets
Pour les diagrammes complets ou techniques, construisez le SVG une section à la fois. N'écrivez pas le fichier entier en une seule fois. Un diagramme complet peut dépasser la limite de sortie par réponse, et même lorsque cela tient, une section par passe donne à chaque section une attention réelle.
Le flux de travail section par section
Phase 1 : Construire chaque section
- Créez le fichier à partir de
references/starter.html: définissez le<title>, leviewBox, et ajoutez la première section. - Ajoutez une section par édition, chacune dans son propre
<g id="sec-...">. Réfléchissez à la disposition de cette section, à son espacement et à la façon dont elle se connecte à ce qui est déjà là. - Utilisez des ids descriptifs (
data-node="trigger",id="sec-backend") afin que les arêtes entre sections soient lisibles :data-from="trigger" data-to="router". - Conservez un plan de coordonnées dans un commentaire HTML en haut du svg (x des colonnes, y des lignes, limites des sections). Chaque section ultérieure et chaque arête le lisent, et c'est ainsi que vous corrigez l'espacement sans deviner.
Phase 2 : Réviser l'ensemble
Lisez le fichier complet et vérifiez :
- Est-ce que chaque
data-from/data-tonomme undata-nodequi existe ? - L'espacement est-il équilibré, ou certaines sections sont-elles à l'étroit tandis que d'autres sont clairsemées ?
- Est-ce que le
viewBoxcontient tout, avec une marge d'environ 40 px ?
Phase 3 : Rendu & validation (ci-dessous).
Rendu & Validation
Utilisez toujours python scripts/render.py <fichier.html> après chaque édition.
Ce script :
- Lance un serveur HTTP local
- Ouvre la page dans Playwright (headless Chromium)
- Capture une capture d'écran en PNG
- Vérifie la géométrie (taille de la viewBox, débordement de texte, placement des nœuds)
- Signale les erreurs dans la sortie standard
Inspectez le PNG. Le script enregistre <fichier>.png à côté de <fichier>.html. Ouvrez-le et regardez-le :
- Le texte est-il lisible ?
- Les flèches touchent-elles leurs cibles ?
- La disposition est-elle agréable ?
- Y a-t-il un chevauchement ou un espacement excessif ?
Corrigez et recommencez. Éditez le fichier HTML, réexécutez python scripts/render.py, inspectez à nouveau. Répétez jusqu'à ce qu'il n'y ait pas de problèmes de vérification et que le PNG ait l'air correct.
Ne sautez pas cette étape. Les diagrammes non rendus ont systématiquement des problèmes : texte débordant, flèches qui ratent leurs cibles, ou viewBox qui rogne le contenu. Le processus de vérification de la géométrie détecte également les nœuds qui se chevauchent et les lignes de base de texte mal alignées.
Aide-mémoire SVG
Éléments SVG utiles qui travaillent avec starter.html :
<!-- Boîte rectangulaire -->
<rect x="100" y="200" width="240" height="60" rx="8" class="box-primary"/>
<!-- Cercle / Ellipse -->
<ellipse cx="200" cy="300" rx="100" ry="40" class="box-secondary"/>
<!-- Chemin de ligne (pour les flèches / timelines) -->
<path d="M 200 400 L 400 400" stroke="#888" stroke-width="2"/>
<!-- Texte (positionné par x,y – le y est la ligne de base) -->
<text x="220" y="235" class="text-label">Étiquette</text>
<!-- Ligne de retour à la ligne manuelle avec tspan -->
<text x="200" y="300" class="text-body">
<tspan x="200" dy="0">Ligne 1</tspan>
<tspan x="200" dy="20">Ligne 2</tspan>
</text>
<!-- Grouper des éléments -->
<g id="sec-intro" data-node="trigger">
<rect ... />
<text ... />
</g>
<!-- Chemin de flèche (le fichier starter définit les marqueurs) -->
<path d="M 220 260 L 220 300" class="arrow arrow-down" marker-end="url(#arrow)"/>
<!-- Bloc de code (conteneur sombre) -->
<rect x="400" y="200" width="300" height="100" rx="4" class="code-block"/>
<text x="410" y="220" font-family="monospace" font-size="12" fill="#e6e6e6">const x = 1;</text>
Résumé du flux de travail
1. Évaluer la profondeur → Simple ou Complet ?
2. Si complet : Faire des recherches → Lire les spécifications réelles
3. Comprendre profondément → Que doit faire la forme ?
4. Mapper les motifs → Chaque concept obtient sa propre forme
5. Esquisser le flux → L'œil se déplace-t-il logiquement ?
6. Construire le HTML/SVG → Commencer par starter.html, section par section
7. Rendre & valider → `python scripts/render.py diagram.html`, inspecter
8. Corriger & recommencer → Jusqu'à ce que ce soit parfait
Rappelez-vous : un bon diagramme enseigne. Montrez aux gens ce que les choses sont réellement, pas seulement comment elles s'appellent.
Fichier de palette de couleurs (references/color-palette.md)
Chaque diagramme a besoin d'une palette de couleurs. Avant de commencer un diagramme, lisez toujours ce fichier pour comprendre les tokens de couleur actuels et les conventions de style de la marque.