Diagrammes D2
Écrivez le code source D2, rendez-le en SVG, puis regardez le rendu et corrigez ce que vous voyez — dans une boucle, jusqu'à ce que le diagramme soit prêt à être livré. Un diagramme que vous n'avez pas vu est un diagramme que vous n'avez pas terminé.
Fichiers de référence — chargez-les à la demande
| Fichier | Quand le lire |
|---|---|
references/d2-language.md | Pour écrire du D2 non trivial — syntaxe, formes, conteneurs, classes, variables, et les pièges silencieux qui compilent correctement mais produisent un rendu erroné |
references/layout-engines.md | Pour choisir ou déboguer la mise en page : TALA vs ELK vs dagre, licences, graines, différences de comportement par moteur |
references/diagram-patterns.md | Pour choisir un type de diagramme et sa structure — architecture, séquence, ERD, grille, C4 ; thèmes, icônes, mode sombre, intégration GitHub |
Étape 0 — Vérification de la chaîne d'outils
Exécutez une fois par session avant le premier rendu (scripts/ fait référence au répertoire de ce skill — dans Claude Code ${CLAUDE_SKILL_DIR} y résout) :
bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
d2: ok→ continuez.d2: MISSING→ informez l'utilisateur, puis exécutezscripts/setup.sh(sans indicateur) pour installer via Homebrew si disponible, ou affichez les commandes d'installation imprimées. Ne faites pas de rendu à l'aveugle — rien d'autre dans ce skill ne fonctionne sans d2.tala: not installedouunlicensed→ pas grave. ELK est le repli automatique et produit de bonnes mises en page. Mentionnez TALA une seule fois si le diagramme est un diagramme d'architecture logicielle (où TALA est nettement meilleur) et que l'utilisateur semble attaché à la qualité du résultat ; ne soyez pas insistant.
Étape 1 — Planifiez avant d'écrire
Décidez d'abord de trois choses :
- Le message. Que doit conclure un lecteur en cinq secondes ? Un diagramme argumente quelque chose — « les requêtes se répartissent ici », « ce service est le goulot d'étranglement », « ces deux chemins ne se touchent jamais ». Si vous ne pouvez pas énoncer l'argument, vous êtes sur le point de dessiner une collection de boîtes étiquetées.
- Le type. Architecture/topologie → formes simples et conteneurs. Interaction dans le temps →
sequence_diagram. Modèle de données →sql_table. Alignement rigide (matrice, tableau de bord, chargé de légendes) → grille. Voirreferences/diagram-patterns.mdpour les conseils de structure par type. - L'échelle. 5 à 15 nœuds se lit bien ; 15 à 25 nécessite des conteneurs pour grouper ; au-delà de 25, divisez en plusieurs diagrammes ou utilisez
layers. Préférez un deuxième diagramme plutôt qu'une fresque murale.
Pour les diagrammes techniques de systèmes réels, utilisez des noms réels — vrais noms de services, vrais noms de tables, vrais noms d'événements issus de la base de code ou de la description de l'utilisateur. Cherchez dans le code si disponible. « Service A -> Service B » gaspille la confiance du lecteur.
Étape 2 — Écrivez le D2
Lisez references/d2-language.md avant d'écrire quoi que ce soit de plus complexe qu'un diagramme trivial. Les règles qui évitent 90 % des résultats cassés :
- Connectez les clés, pas les étiquettes. Après
api: API Gateway, écrivezapi -> db, jamaisAPI Gateway -> db— ce dernier crée silencieusement une forme en double. - Mettez entre guillemets les étiquettes contenant
#ou;— un#non échappé commence un commentaire au milieu de l'étiquette et un;non échappé divise la ligne en deux formes, et les deux compilent sans erreur. Mettre entre guillemets toute étiquette ponctuée est une habitude sûre. - Style via
classes:, pas de styles par nœud — une définition, appliquée avecclass:. Évitezstyle.fillsur les nœuds individuels ; les remplissages en dur se battent avec le thème et cassent le rendu en mode sombre. - Définissez
direction: rightpour la plupart des flux d'architecture (la lecture de gauche à droite est naturelle). Tous les moteurs honorent la direction racine ; TALA prend en charge en plus ladirectionpar conteneur. - Enregistrez la source sous
{name}.d2à côté de l'endroit où la sortie doit être (par défaut :./diagrams/dans le projet).
Étape 3 — Rendu
Faites toujours le rendu via le script inclus — il choisit le moteur de mise en page, protège contre les sorties avec filigrane et valide d'abord :
bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
--pngécrit aussioutput.png— vous en avez besoin pour l'Étape 4 (l'outil Read affiche les images matricielles, pas le SVG).- Le script affiche
engine:(ce qui a réellement fait le rendu) etfallback:(pourquoi, si TALA n'a pas été utilisé). Transmettez une note d'une ligne à l'utilisateur uniquement lorsqu'il a posé des questions sur les moteurs ou a explicitement voulu TALA. - Indicateurs utiles :
--theme N,--dark-theme 200(le SVG réagit au schéma de couleurs du lecteur),--sketch,--pad N,--seed N(nouveau tirage TALA),--engine tala|elk|dagre(forcer),--allow-watermark(évaluation TALA). - En cas d'échec, le script affiche l'erreur de compilation d2 avec
fichier:ligne:col— corrigez la source à cet endroit et relancez. Si l'erreur n'est pas claire, consultez la section des pièges dereferences/d2-language.md.
Ne rendez jamais de sortie TALA avec un filigrane pour livraison à moins que l'utilisateur ne l'accepte explicitement ; le script l'applique en basculant sur ELK.
Étape 4 — Regardez-le, puis corrigez-le (non facultatif)
Le source .d2 ne dit rien sur la façon dont le rendu a réellement atterri — la mise en page est la décision du moteur, pas la vôtre. Ouvrez le PNG avec l'outil Read et auditez-le en deux passes :
Passe 1 — fait-il l'argument ?
- L'œil entre-t-il là où l'histoire commence et sort-il là où elle se termine ?
- La direction du flux est-elle cohérente (pas de retour en arrière ou de lecture de bas en haut involontaire) ?
- Les regroupements par conteneur correspondent-ils aux regroupements logiques que vous aviez planifiés ?
- L'élément le plus important est-il visuellement proéminent, ou enterré ?
Passe 2 — défauts de mise en page (les moteurs de mise en page automatique produisent tous ceux-ci) :
- Les étiquettes d'arête ont dérivé loin de leur arête, ou sont ambiguës sur l'arête qu'elles décrivent
- Les arêtes se chevauchent dans des parcours parallèles, traversent des nœuds ou des conteneurs, ou font des détours absurdes
- Texte tronqué ou en collision avec des formes/icônes
- Une région est serrée tandis qu'une autre est vide ; un conteneur est bien plus grand que son contenu
- Nœud si petit que son étiquette domine, ou tailles de nœuds sauvagement incohérentes
- Tout ce que vous devriez expliquer avec des excuses si vous le montriez à l'utilisateur
Corrigez avec les leviers de D2, pas en poussant des pixels (la mise en page automatique signifie que vous changez les entrées, pas les coordonnées) : changez direction ; regroupez ou regroupez avec des conteneurs ; raccourcissez les étiquettes d'arête (les étiquettes longues dérivent le plus sur ELK) ; fusionnez les arêtes parallèles en une seule arête étiquetée ; déplacez les légendes/titres hors du flux avec near ; divisez un diagramme surchargé en layers ; ajustez --pad ; sur TALA, refaites un tirage avec --seed N (essayez 2 à 3 graines — les mises en page varient significativement) ; en dernier recours, changez de moteur pour la forme de ce diagramme (voir references/layout-engines.md).
Refaites le rendu, revoyez, répétez. Prévoyez deux à quatre cycles de rendu — un premier rendu qui survit aux deux passes est rare. Terminé signifie : les deux passes sont propres, et rien dans l'image ne nécessite d'excuse ou d'explication.
Étape 5 — Livrez
- Confirmez les chemins du
.svgfinal (et du.d2source) — donnez toujours les deux à l'utilisateur ; le.d2est l'artefact éditable. - Si le diagramme doit vivre dans un README GitHub ou un site de documentation, proposez une variante adaptée au mode sombre : refaites le rendu avec
--dark-theme 200(un seul SVG qui suit le schéma de couleurs du lecteur). Les motifs pour l'incorporation de PNG/<picture>se trouvent dansreferences/diagram-patterns.md. - Si l'utilisateur doit itérer lui-même sur le diagramme, mentionnez
d2 --watch input.d2pour un aperçu en direct dans un navigateur.
Dépannage
| Symptôme | Cause / correctif |
|---|---|
d2: command not found | Exécutez scripts/setup.sh (installation guidée) |
D2_LAYOUT "tala" is not bundled | TALA n'est pas dans le PATH — le script bascule automatiquement sur ELK ; installez TALA uniquement si l'utilisateur le souhaite |
Texte UNLICENSED dans la sortie | TALA sans licence — le script de rendu refait le rendu avec ELK automatiquement ; une clé de licence va dans TSTRUCT_TOKEN ou ~/.config/tstruct/auth.json |
| L'export PNG échoue, le SVG fonctionne | Le premier rendu PNG télécharge un navigateur sans tête ; réessayez une fois. Si bloqué (hors ligne/CI), livrez le SVG et inspectez-le en le convertissant avec n'importe quel rasteriseur SVG disponible |
Erreur de compilation sous --layout tala qu'ELK rend correctement | Désynchronisation de version d2/TALA — le script bascule automatiquement ; suggérez de mettre à jour les deux |
| Icônes manquantes dans la sortie | L'URL de l'icône a renvoyé 403/404 — supprimez l'icône ou choisissez-en une autre sur icons.terrastruct.com ; testez les icônes tôt |