IbrahimSobh/content-mermaid

Content Mermaid

Produit des diagrammes Mermaid pour des processus et structures techniques. C'est l'équivalent rapide et basé sur la syntaxe de content-diagrams : mêmes standards de clarté visuelle, mais construit sur un langage qui garantit déjà une géométrie correcte, de sorte que l'effort porte sur le choix du type de diagramme et d'un système de couleurs lisible et cohérent, plutôt que sur la vérification des coordonnées.

Relation avec content-diagrams

Les deux compétences partagent les mêmes standards — texte lisible, un vrai système de couleurs plutôt que de la décoration, la clarté avant la densité — mais content-diagrams calcule sa propre géométrie SVG à la main tandis que cette compétence confie entièrement la géométrie au moteur de disposition de Mermaid ; choisissez entre elles en fonction de l'endroit où le diagramme sera réellement visualisé (surface Mermaid native vs. une plateforme qui n'affiche que des images statiques), pas par habitude, et en cas de doute, demandez — une source Mermaid ne se capture pas proprement en une image autonome soignée sans un vrai remaniement.

Pourquoi il n'y a pas de boucle de vérification ici

content-diagrams consacre la majeure partie de ses efforts à la géométrie : une ligne, une boîte ou une étiquette SVG ne sont que des nombres calculés par Claude, et des nombres calculés peuvent être erronés — d'où le rendu, la capture d'écran, le recadrage et la vérification.

Mermaid élimine complètement ce mode d'échec. La largeur des nœuds, le retour à la ligne du texte, les chemins des flèches et l'évitement des collisions entre éléments sont le travail du moteur de rendu, pas de Claude — le moteur de rendu ne placera pas une étiquette sur une boîte ni ne fera passer une ligne à travers une forme. Re-dériver cette boucle de vérification ici (capturer le diagramme rendu, recadrer, vérifier les chevauchements) ne ferait que brûler des tokens et de la latence pour confirmer quelque chose que l'outil garantit déjà.

Ce qui peut encore mal tourner est complètement différent et entièrement textuel :

• Syntaxe cassée (crochets non fermés, mot réservé utilisé comme ID de nœud, types de flèches incompatibles)
• Une arête qui référence un ID de nœud jamais défini
• Mauvais contraste des couleurs (un remplissage et une couleur de texte qui ne se lisent pas réellement l'un contre l'autre)
• Le mauvais type de diagramme pour la structure réelle du contenu

Donc, la vérification ici signifie : lire la syntaxe une fois pour vérifier l'exactitude, vérifier que chaque classDef associe un remplissage à une couleur de texte vraiment contrastée, et confirmer que le type de diagramme correspond à ce qui est modélisé. Aucun rendu d'image requis.

Sélection du type de diagramme

Choisissez le type en fonction de ce qu'est structurellement le contenu — c'est l'équivalent Mermaid de la sélection de motif de content-diagrams :

Structure du contenu	Type Mermaid
Étapes séquentielles avec branches/boucles (un processus, un workflow, un algorithme)	flowchart TD (haut en bas) ou LR (gauche à droite pour pipelines/timelines)
Messages ordonnés dans le temps entre acteurs/services (appels API, échanges de protocoles)	sequenceDiagram
États d'une entité et transitions entre eux (un cycle de vie, une machine à états)	stateDiagram-v2
Modèle de données / relations entre entités (schémas, tables de base de données)	erDiagram
Structure orientée objet (classes, héritage, interfaces)	classDiagram
Planning avec durées et dépendances	gantt
Décomposition hiérarchique / brainstorming sans séquence stricte	mindmap
Récit chronologique (historique d'un projet, historique de versions)	timeline
Priorisation sur deux axes (impact vs. effort, etc.)	quadrantChart

Ne faites pas par défaut de flowchart pour tout — une demande comme « diagrammez comment nos services s'appellent mutuellement » est un sequenceDiagram même s'il est tentant de le dessiner avec des boîtes et des flèches ; une demande comme « montrez les états par lesquels passe un ticket » est un stateDiagram-v2, pas un organigramme avec des losanges représentant des états.

Système de couleurs et de lisibilité

C'est le seul endroit où la vérification manuelle compte encore, car Mermaid rendra volontiers des choix de couleurs illisibles sans se plaindre.

La règle : chaque classDef doit associer un remplissage à une couleur de texte délibérément choisie pour contraster avec lui — ne laissez jamais color non défini en espérant que le thème par défaut fonctionnera. La palette par défaut de Mermaid (vert/rose/bleu doux avec texte noir) est correcte précisément parce que le remplissage et le texte ont été choisis ensemble ; dès que vous remplacez fill par quelque chose de plus saturé ou plus foncé, vous devez également définir color explicitement, sinon vous reproduirez un défaut courant : des boîtes d'aspect lisible avec un texte qui est en réalité à faible contraste par rapport à elles.

Deux recettes de palette, choisissez-en une et utilisez-la de manière cohérente pour chaque classe d'un diagramme (ne mélangez pas) :

1. Remplissage sombre / texte blanc (le défaut — éprouvé, contraste élevé, se lit bien dans les thèmes de chat clairs et sombres) :

   classDef category1 fill:#1e3a5f,stroke:#0d1f33,stroke-width:2px,color:#ffffff
   

2. Remplissage teinté clair / texte foncé / contour saturé (à utiliser lorsqu'un diagramme doit se situer visuellement à côté d'un SVG de content-diagrams qui suit sa convention de teinte claire) :

   classDef category1 fill:#e1f0ff,stroke:#1e3a5f,stroke-width:2px,color:#1a1a1a
   

Empruntez directement la règle de content-diagrams : une teinte par catégorie, appliquée partout où cette catégorie apparaît — la même couleur en remplissage/contour sur chaque nœud de ce rôle, pas un one-off. Attribuez les teintes par rôle, par exemple :

• Bleu → entrées / données / éléments du backlog
• Vert → processus / étapes de travail actif
• Ambre ou marron → points de décision / portes
• Violet → sorties / livraisons / états terminaux
• Rouge → boucles de rétroaction / chemins d'échec / rétrospectives

Verrouillez le canevas pour qu'il ne dépende pas du mode clair/sombre de l'hôte. Placez une directive init comme toute première ligne du diagramme :

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Trebuchet MS, Verdana, Arial, sans-serif', 'fontSize': '16px', 'primaryColor': '#1e3a5f', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0d1f33', 'lineColor': '#666666', 'background': '#ffffff' } } }%%

theme: 'base' plus des themeVariables explicites signifie que le diagramme aura la même apparence, quel que soit le thème Mermaid par défaut de l'environnement hôte — ne vous fiez pas uniquement au nom du thème par défaut (default, dark, forest, etc.), car cela laisse les couleurs réelles à la discrétion du moteur de rendu.

Taille de police : 16px minimum pour tout diagramme avec plus de quelques nœuds ; 14px uniquement si le diagramme est suffisamment simple pour que la lisibilité ne soit pas en question. Si un diagramme doit rétrécir en dessous de 14px pour que ses étiquettes tiennent, c'est le même signal « clarté avant densité » de content-diagrams — divisez le diagramme ou réduisez le contenu, ne réduisez pas davantage le texte.

La portée du style diffère selon le type de diagramme : flowchart, stateDiagram-v2 et classDiagram prennent tous en charge l'assignation classDef/class par nœud directement, donc utilisez le système de couleurs par catégorie ci-dessus nœud par nœud. sequenceDiagram, erDiagram et gantt ont un style par élément beaucoup plus limité — pour ceux-ci, mettez l'effort dans les themeVariables dans le bloc init (actorBkg, actorTextColor, noteBkgColor, etc. pour les diagrammes de séquence) plutôt que de vous attendre à ce que les classes au niveau du nœud fonctionnent de la même manière.

Grammaire des flèches

Contrairement au SVG codé à la main, Mermaid rend les étiquettes des flèches proprement avec un placement automatique — -->|label| ne risque pas de placer le texte sur une forme comme le ferait une étiquette SVG positionnée manuellement. Ainsi, contrairement au défaut de content-diagrams « gardez le texte hors des flèches, décodez via la légende », étiqueter directement les flèches est acceptable et souvent plus clair ici. Gardez toujours les étiquettes courtes (des fragments comme « approuvé », « réessayer », « en cas d'échec ») plutôt que des phrases — une étiquette est une balise, pas une phrase.

Réservez le style de ligne pour la même distinction large que celle utilisée par content-diagrams :

• Flèche pleine (-->) → flux principal/normal
• Flèche pointillée (-.->) → rétroaction, chemin facultatif ou interaction externe/indirecte
• Flèche épaisse (==>) → chemin mis en évidence ou critique, utilisé avec parcimonie

Gardez les étiquettes courtes ; utilisez des sous-graphes pour regrouper

Le texte d'un nœud doit être une courte phrase, pas une phrase complète — Mermaid gérera mal le retour à la ligne ou les débordements sur les étiquettes de longueur paragraphe, comme tout autre outil. Si un nœud nécessite plusieurs lignes, insérez-les explicitement avec <br/> à l'intérieur de l'étiquette plutôt que de faire confiance au retour à la ligne automatique pour couper à un endroit judicieux.

Utilisez subgraph pour regrouper les étapes connexes (par exemple, tout ce qui se trouve à l'intérieur d'un sprint, d'une étape de déploiement, d'une limite de service) — c'est l'équivalent Mermaid d'une boîte de regroupement, et peut être stylé avec sa propre ligne style SubgraphName fill:...,stroke:.... N'imbriquez pas les sous-graphes à plus d'un niveau de profondeur ; cela devient rapidement difficile à lire.

Workflow

1. Identifiez la structure sous-jacente et choisissez le type de diagramme dans le tableau ci-dessus avant d'écrire une syntaxe.
2. Attribuez les couleurs de catégorie aux rôles présents (entrées, étapes de processus, décisions, sorties, rétroaction) — esquissez cela en une ou deux phrases avant d'écrire les classDef, comme l'étape « esquisser le raisonnement du motif » de content-diagrams, afin que le choix soit vérifiable si l'utilisateur souhaite ajuster un élément.
3. Écrivez le diagramme, en commençant par la directive %%{init: ...}%%, puis la structure, puis les assignations classDef/class (ou themeVariables pour les types qui ne prennent pas en charge les classes par nœud).
4. Auto-vérifiez la syntaxe — chaque ID de nœud utilisé dans une arête est défini quelque part ; chaque classDef a à la fois fill et color définis ; les crochets/guillemets sont équilibrés ; pas d'étiquette de longueur paragraphe. Pas de rendu, pas de capture d'écran.
5. Enregistrez sous forme de fichier .mermaid via create_file afin qu'il s'affiche en ligne comme un artefact, en utilisant un slug descriptif : /mnt/user-data/outputs/<slug>.mermaid. Présentez avec present_files.
6. Si l'utilisateur a besoin du diagramme sous forme d'image statique portable (pour l'intégrer dans un endroit qui ne rend pas Mermaid, ou pour l'archivage), dites-le franchement : cet environnement ne supporte pas de manière fiable l'exportation Mermaid vers une image sans tête (cela dépend d'un téléchargement Chromium que le réseau sandboxé ne peut généralement pas atteindre). Dirigez vers mermaid.live pour une exportation manuelle, ou passez à content-diagrams si le vrai besoin est un graphique autonome.

Ce qu'il ne faut pas faire

• Ne laissez pas color d'un classDef non défini après avoir remplacé fill — c'est exactement le bogue de contraste que cette compétence existe pour éviter.
• Ne mélangez pas les recettes de palette à remplissage sombre et à remplissage clair dans un même diagramme.
• Ne faites pas par défaut flowchart pour chaque demande — choisissez le type qui correspond à la structure réelle (séquence, état, ER, etc.).
• Ne réintroduisez pas la boucle rendu/capture/vérification de content-diagrams ici — elle résout un problème que le moteur de disposition de Mermaid n'a pas.
• Ne mettez pas de texte de longueur paragraphe dans une étiquette de nœud ; utilisez <br/> ou réduisez le contenu.
• N'imbriquez pas les sous-graphes à plus d'un niveau.
• Ne promettez pas un export PNG/SVG propre depuis ce bac à sable sans préciser que le rendu Mermaid sans tête peut ne pas fonctionner ici.