Conception de diagrammes
Créez des diagrammes sous forme de fichiers HTML autonomes avec SVG intégré et un système de design éditorial.
Quarante-cinq types visuels. Les motifs sémantiques décrivent le comportement ; les références de type décrivent la mise en page.
0. Configuration initiale — Porte du guide de style
Avant de générer votre premier diagramme dans un nouveau projet, vérifiez que le guide de style a été personnalisé.
Ne livrez pas silencieusement des diagrammes avec les skins par défaut dans un projet de marque.
Résolvez d'abord tout marqueur .diagram-design du projet conformément à references/profiles.md ; un marqueur résolu avec succès sélectionne son profil et contourne cette porte. Cette référence gère les échecs, le défaut protégé et le comportement de sauvegarde.
Ouvrez references/style-guide.md et vérifiez les tokens par défaut. S'ils sont toujours les valeurs par défaut livrées (fond #f5f5f5, encre #2d3142, accent #bf4520), faites une pause et demandez à l'utilisateur :
"Ceci est votre premier diagramme dans ce projet et le guide de style est toujours celui par défaut. Personnaliser maintenant ? Options : (a) URL du site web, (b) compétence installée, (c) dossier local / système de design, (d) coller les tokens, (e) conserver le défaut, (f) charger un profil sauvegardé."
Ensuite, orientez-vous selon la section correspondante de references/onboarding.md ; pour (f) suivez references/profiles.md.
Une fois le guide de style personnalisé (ou l'utilisateur a explicitement choisi le défaut), sautez cette porte lors des exécutions ultérieures. Un en-tête de profil principal nomme le profil actif copié. Sans en-tête, toute valeur de rôle sémantique ou famille typographique différente des valeurs par défaut livrées signifie personnalisé-non-sauvegardé : sautez la porte et proposez de le sauvegarder en tant que profil. Des tokens tous par défaut sans marqueur ni en-tête déclenchent la porte. Après l'onboarding, proposez de sauvegarder en tant que profil client nommé conformément à references/profiles.md.
1. Philosophie
La meilleure action est généralement la suppression.
Appliqué aux schémas :
- Chaque nœud représente une idée distincte. Deux nœuds qui voyagent toujours ensemble sont un seul nœud.
- Chaque connexion porte une information. Si la relation est évidente par la disposition, supprimez la ligne.
- Le corail est éditorial, pas un drapeau. 1–2 nœuds focaux par diagramme. L'utiliser sur 5 nœuds efface le signal.
- Le schéma n'est pas terminé quand tout a été ajouté. Il est terminé quand rien ne peut être retiré.
Densité cible : 4/10. Assez pour être techniquement complet. Pas assez dense pour nécessiter un guide. Au-dessus de 9 nœuds, c'est probablement deux diagrammes.
2. Quand utiliser
Utilisez pour n'importe lequel des 45 types visuels (§3) lorsqu'un lecteur apprendra plus d'un visuel que d'un texte, d'un tableau ou d'une liste à puces.
N'utilisez pas pour :
- Des diagrammes Unicode rapides → un outil texte séparé comme wiretext. Cette compétence n'en fournit pas.
- Des listes de choses → un tableau ou des puces.
- Des avant/après uniquement attributifs → un tableau ; changements de topologie → Architecture delta.
- Des "diagrammes" à une seule forme → écrivez simplement la phrase.
Avant de dessiner, demandez : Le lecteur apprendrait-il plus de cela que d'un paragraphe bien écrit ? Si non, ne dessinez pas.
3. Sélection : motif sémantique, puis type visuel
Lorsque le comportement, l'état, l'application ou le risque porte le sens, chargez d'abord references/semantic-patterns.md et choisissez un motif principal. Ensuite, choisissez le type visuel le plus proche pour la mise en page. Si aucun motif ne correspond, choisissez le type directement.
| Déclencheur comportemental | Motif sémantique → type le plus proche |
|---|---|
| Convergence, profondeur de file d'attente, capacité finie, goulot d'étranglement | File d'attente de convergence / goulot d'étranglement → Flux de données |
| Créneaux Question / Entrée / Gouvernance / Sortie répétés à travers les étapes | Cadre d'étape avec créneaux sémantiques → Processus |
| Une conversation ou une entrée libre devient un artefact structuré durable | Entrée non structurée → artefact structuré → Flux de données |
| Deux traces de règles nécessitent succès/échec/sauté/non-atteint et première divergence | Traces d'évaluation de politiques appariées → Organigramme |
| Frontières de confiance plus chemins d'entrée ou de déploiement autorisés/interdits | Voie pavée sécurisée → Architecture |
| Contrôles regroupés par où ils sont appliqués | Catalogue de gouvernance / contrôle → Pile de couches |
| Les défenses compensent les lacunes antérieures et le risque résiduel se propage | Couches de sécurité compensatoires → Pile de couches |
| Décomposition hiérarchique adressable par ID nécessitant E/S, contraintes et un lien de code par bloc | Décomposition de bloc traçable → Arbre |
| Un sujet progresse à travers des phases, attend, réessaie, annule et aboutit à des résultats terminaux | Carte du cycle de vie → Machine d'état |
Le motif possède les primitives sémantiques et son budget plus serré ; le type possède la grammaire de mise en page. Utilisez references/animation.md uniquement lorsque l'animation est demandée ou clarifie matériellement un changement ordonné ; le statique reste la valeur par défaut.
Guide des types visuels (45)
| Si vous montrez… | Utilisez | Référence |
|---|---|---|
| Composants + connexions en un instantané ; portées imbriquées admin vs trafic | Architecture | type-architecture.md |
| Changement structurel entre des topologies Avant / Après synchronisées, avec un registre des Changements | Architecture delta | type-architecture-delta.md |
| Paysage informatique existant par phase ou département ; montre l'état avant | État actuel IT | type-it-state.md |
| Logique de décision avec branches | Organigramme | type-flowchart.md |
| Messages ordonnés dans le temps entre acteurs | Séquence | type-sequence.md |
| États + transitions + gardes | Machine à états | type-state.md |
| Entités + champs + relations | ER / modèle de données | type-er.md |
| Événements positionnés dans le temps | Chronologie | type-timeline.md |
| Processus interfonctionnel avec transferts | Couloirs de nage | type-swimlane.md |
| Positionnement / priorisation à deux axes | Quadrant | type-quadrant.md |
| Plusieurs entités notées sur 3–5 critères quantitatifs | Radar / Araignée | type-radar.md |
| Une série quantitative à travers des catégories cycliques ; angle=catégorie, rayon=magnitude | Graphique polaire | type-polar.md |
| Cycle de renforcement ; la dernière étape alimente la première et un hub accumule l'état | Boucle | type-loop.md |
| Hiérarchie par contenu / portée | Imbriqué | type-nested.md |
| Relations parent → enfants | Arbre | type-tree.md |
| Propriété humaine/agent/équipe, reporting, routage, escalade | Organigramme | type-org-chart.md |
| Niveaux d'abstraction empilés | Pile de couches | type-layers.md |
| Parties d'un objet éclatées le long d'un axe : démontage, déballage, ordre d'assemblage | Axonométrique éclaté | type-exploded.md |
| Un étage ou site vu du dessus en angle : pièces avec meubles, bâtiments par phase | Plan axonométrique | type-axonometric-plan.md |
| Chevauchement entre ensembles | Venn | type-venn.md |
| Hiérarchie classée ou attrition de conversion | Pyramide / entonnoir | type-pyramid.md |
| Comparaison quantitative entre catégories | Diagramme à barres | type-bar.md |
| Un total de départ relié à un total d'arrivée par des contributions signées (pont budgétaire, delta d'effectifs) | Cascade | type-waterfall.md |
| Partie d'un tout où les tailles relatives sont l'histoire | Treemap | type-treemap.md |
| Données croisées ; le remplissage encode la valeur par cellule | Carte de chaleur | type-heatmap.md |
| Tendances continues dans le temps, changement entre exactement deux états (slopegraph), une distribution par série (ridgeline), ou mouvement de rang à travers plusieurs instantanés (bump) | Graphique linéaire | type-line.md |
| Tâches et phases sur une chronologie | Gantt | type-gantt.md |
| Corrélation ou distribution de deux variables ; variantes bulle (trois variables), essaim de points (une variable, un point par élément) et boîte à moustaches (résumé à cinq nombres par groupe) | Nuage de points | type-scatter.md |
| Stack de données de bout en bout sur un cluster de conteneurs | Haut niveau | type-high-level.md |
| Processus séquentiel multi-acteurs avec transferts de données | Processus | type-process.md |
| Stockage de données à plusieurs niveaux avec niveaux de qualité et politiques d'accès | Médaille | type-medallion.md |
| Flux de données par rôle : qui fait quoi à chaque étape du pipeline | Flux de données | type-data-flow.md |
| Topologie d'intégration d'une plateforme de données — sources → cœur → consommateurs | Intégration DP | type-dp-integration.md |
| Matrice des permissions d'accès par rôle / composant | Matrice de sécurité DP | type-dp-security-matrix.md |
| Une quantité se divisant et fusionnant à travers les étapes, largeur de bande = quantité | Sankey | type-sankey.md |
| Causes d'un effet observé, regroupées par catégorie (analyse de cause racine) | Arête de poisson | type-fishbone.md |
| Chaîne de valeur face à l'évolution — quoi construire, quoi acheter, et ce qui bouge | Carte Wardley | type-wardley.md |
| Travail en cours par état, avec limites WIP et éléments bloqués | Kanban | type-kanban.md |
| Ce qu'une personne fait à travers les étapes d'une expérience, et comment elle se sent | Parcours utilisateur | type-journey.md |
| Ce que le client fait vs ce que le service cache, à travers les étapes, avec une ligne de visibilité | Blueprint de service | type-service-blueprint.md |
| Où le logiciel s'exécute — zones, hôtes, artefacts, réplicas, ports | Déploiement | type-deployment.md |
| Quoi dépend de quoi, avec convergence et cycles qu'un arbre ne peut pas exprimer | Graphe de dépendances | type-dependency.md |
| Classes avec opérations, héritage, composition (autres voies UML ailleurs) | Classe UML | type-uml-class.md |
| Colonne vertébrale narrative découpée en versions, avec la ligne de coupe | Story map | type-story-map.md |
| Tables physiques : types SQL, contraintes, index, FK au niveau colonne | Schéma de base de données | type-db-schema.md |
Règles empiriques :
- Si un tableau à 3 colonnes communique la même chose, choisissez le tableau.
- Si deux types semblent utiles, choisissez l'axe dominant ; un motif sémantique peut ajouter des primitives spécifiques au comportement, pas une deuxième grammaire de mise en page.
- Si vous dépassez le budget de complexité (§7), divisez en une vue d'ensemble + un détail.
Chargez toujours la référence de type choisie liée dans le guide avant de dessiner. Lorsqu'il est orienté ci-dessus, chargez également semantic-patterns.md ; lorsque l'animation est choisie, chargez animation.md.
Confirmer avant de dessiner
Avant le rendu, énoncez le plan en un court message : le type visuel choisi (et le motif sémantique, si orienté), le préréglage de taille, et tout ce que le budget de complexité (§7) forcera à exclure. Si l'utilisateur est joignable, laissez-le rediriger avant de dessiner ; sinon, procédez et notez les hypothèses à côté du livrable. Sautez la pause uniquement lorsque la demande spécifie déjà exactement le type, la taille et le contenu.
4. Anti-patrons universels
Ceux-ci marquent des schémas "IA bâclée" de tout type :
| Anti-patron | Pourquoi il échoue |
|---|---|
| Mode sombre + lueur cyan/violet | A l'air "technique" sans décisions de design |
| JetBrains Mono comme police "dev" généralisée | Mono est pour le contenu technique — ports, commandes, URL. Les noms vont dans Geist sans. |
| Boîtes identiques pour chaque nœud | Efface la hiérarchie |
| Légende flottant à l'intérieur de la zone du diagramme | Entre en collision avec les nœuds |
| Étiquettes de flèche sans rectangle de masquage | Saigne à travers la ligne |
Texte vertical writing-mode sur les flèches | Illisible |
| 3 cartes récapitulatives de largeur égale par défaut | Grille générique — variez les largeurs |
| Ombre sur n'importe quel élément | Les ombres sont finies. Les bordures sont à la mode. |
rounded-2xl sur les boîtes | Rayon max 6–10 px ou aucun |
| Corail sur chaque nœud "important" | Le corail est pour 1–2 accents éditoriaux, pas un système de signalisation |
| Reproduire la disposition du rendu de Mermaid | Importe le placement et le routage automatiques au lieu de faire une disposition éditoriale |
| Toute violation des six règles de connexion du §6 | Échec automatique : obliques, étiquettes touchant leur trait, masques coupés par un nœud ultérieur, chemins se chevauchant, points d'attache partagés, transit derrière une boîte non terminale |
Les anti-patrons spécifiques à chaque type vivent dans chaque référence de type liée dans le guide.
5. Système de design
Le système de design est personnalisable. references/style-guide.md est la source unique de vérité pour les couleurs, la typographie, les tokens et la palette par défaut ; ce fichier nomme les rôles sémantiques (paper, ink, muted, accent, link, …). Pour appliquer une marque, modifiez style-guide.md ou exécutez le flux basé sur URL dans references/onboarding.md.
Lorsque les spécifications ci-dessous ou dans les références de type mentionnent "encre", "accent", "muted", etc., recherchez la valeur hexadécimale actuelle dans
style-guide.md.
Les extraits de références de type écrivent les rôles comme des espaces réservés : {ink}, {ink @ 0.40} pour un rôle à une opacité, et {node-name}, {sublabel}, {eyebrow}, {arrow-label}, {title}, {callout} pour les polices. Résolvez chaque espace réservé par rapport à style-guide.md avant d'émettre.
Rôles sémantiques (en un coup d'œil)
| Rôle | Objectif |
|---|---|
paper, paper-2 | Fond de page et fond de conteneur |
ink | Texte / trait principal |
muted, soft | Texte / trait secondaire |
accent | Couleur d'accentuation éditoriale |
link | Texte de lien |
success, warning, error | États / validation |
Typographie
| Rôle de police | Cas d'usage |
|---|---|
{title} | Titre du diagramme |
{node-name} | Étiquette de nœud |
{sublabel} | Sous-étiquette / métadonnée |
{eyebrow} | Sur-titre / catégorie |
{callout} | Annotation / légende |
{arrow-label} | Étiquette de flèche |
6. Règles des connecteurs
Chaque ligne de connexion doit suivre ces six règles :
- Pas de diagonales. Les lignes sont orthogonales (horizontales/verticales) ou courbes de Bézier.
- Les étiquettes ne touchent pas leur trait. Un rectangle de fond blanc ou de la couleur du fond (
paper) doit être placé sous chaque étiquette de flèche. - Les masques ne sont pas coupés par un nœud ultérieur. Le rectangle de masquage d'une étiquette de flèche ne doit pas être obscurci par un autre nœud.
- Pas de chevauchement de chemins. Deux lignes ne doivent pas se croiser sans un saut de pont ou un routage délibéré.
- Points d'attache partagés interdits. Chaque connexion a son propre point d'attache sur la boîte source et la boîte cible.
- Pas de transit derrière une boîte non terminale. Une ligne ne passe pas derrière une boîte qui n'est ni sa source ni sa cible.
7. Budget de complexité
| Seuil | Action |
|---|---|
| ≤ 6 nœuds | Un seul diagramme, disposition simple |
| 7–12 nœuds | Envisagez de regrouper ou d'utiliser un type plus spacieux (par exemple, une pile de couches au lieu d'un seul organigramme) |
| 13–20 nœuds | Divisez en un diagramme d'aperçu + des diagrammes de détail séparés |
| > 20 nœuds | Nécessite un plan de navigation : plusieurs fichiers HTML liés |
8. Formats de sortie
| Format | Commande / extension | Notes |
|---|---|---|
| HTML | Sortie standard | SVG intégré, CSS en ligne, autonome |
| SVG | Enregistrer sous .svg | Vectoriel, éditable |
| PNG | Enregistrer sous .png | Raster, fond blanc |
Import .drawio | Lire le fichier et le convertir | Conserve la disposition |
| Import Mermaid | Lire le code et le convertir | La disposition peut nécessiter une édition |
Import .excalidraw | Lire le fichier et le convertir | Styles dessinés à la main conservés |
9. Références
references/profiles.md— Profils de projets clientsreferences/style-guide.md— Guide de style (couleurs, polices, tokens)references/onboarding.md— Flux de personnalisationreferences/semantic-patterns.md— Motifs sémantiquesreferences/animation.md— Animation (optionnelle)references/type-*.md— Références individuelles pour les 45 types de diagrammes