Je refuse les boîtes arrondies génériques, les ombres portées inutiles et le style brut de Mermaid. Chaque fois que je rédigeais un article sur DeepLearn, obtenir un schéma demandait un combat de trente minutes sur Figma. diagram-design résout ce problème précis : générer des schémas HTML et SVG autonomes, taillés pour la publication, directement via Claude Code, Codex ou Pi.
Le principe fondamental reste la suppression. Chaque nœud prouve sa valeur. La couleur d’accent met en valeur un ou deux éléments clés. La densité visuelle cible reste fixée à 4 sur 10. La grille repose sur un pas strict de 4 pixels pour éliminer l’aspect produit par une IA.
Typologies visuelles et catalogue
Le système contient vingt-sept archétypes visuels déclinés en trois variantes statiques : clair minimal, sombre minimal et pleine page éditoriale. Le code HTML s’ouvre dans n’importe quel navigateur sans étape de compilation, sans JavaScript et sans dépendance d’image externe.
Une galerie vivante est accessible en ligne sur cathrynlavery.github.io/diagram-design ou en local via le fichier skills/diagram-design/assets/index.html.
| Type visuel | Description et cas d’usage | Type visuel | Description et cas d’usage |
|---|---|---|---|
| Architecture | Composants et connexions | Flowchart | Logique de décision |
| Sequence | Échanges de messages dans le temps | State machine | États et transitions logiques |
| ER / data model | Entités et champs relationnels | Timeline | Événements sur un axe temporel |
| Swimlane | Flux interfonctionnels distribués | Quadrant | Positionnement sur deux axes |
| Nested | Hiérarchie par conteneurs imbriqués | Tree | Relations parent vers enfants |
| Org chart | Périmètres de propriété et routage | Venn | Recouvrement d’ensembles |
| Layers | Empilement d’abstractions | Pyramid / funnel | Hiérarchie classée ou attrition |
| Consultant 2×2 | Matrice de scénarios aux cellules nommées | Radar / Spider | Comparaison multiaxe |
| Loop (Nouveau 2.0) | Flywheel et stations autour d’un hub partagé | IT current-state | Paysage hérité et modernisation |
| High-Level | Stack de bout en bout sur cluster | Bar chart | Comparaison catégorique |
| Line chart | Tendances chronologiques | Gantt | Tâches et phases de calendrier |
| Scatter plot | Distribution et corrélation de points | Process | Workflow séquentiel multiacteur |
| Medallion | Stockage de données multi-niveaux | Data flow | Étapes de pipeline par rôle |
| DP integration | Sources vers cœur puis consommateurs | DP security matrix | Permissions d’accès selon le rôle |
La version 2.0 introduit le type Loop pour représenter les boucles vertueuses où les lignes pointillées matérialisent les écritures retour vers la mémoire partagée. La version 2.3 ajoute des motifs sémantiques et un moteur de mouvement optionnel.
Installation sur votre environnement de travail
Le composant fonctionne au sein des outils compatibles avec les Agent Skills.
Claude Code :
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-designActivez les mises à jour en arrière-plan : tapez /plugin, ouvrez Marketplaces, choisissez diagram-design puis activez Enable auto-update. Utilisez la commande /reload-plugins quand le système le demande.
Codex :
codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-designPour forcer une mise à jour sur Codex : codex plugin marketplace upgrade diagram-design.
Claude Cowork (Organisation) :
Les catalogues d’entreprise exigent un dépôt privé ou interne. Créez un miroir du dépôt public dans votre organisation. Dans Organization settings → Plugins, cliquez sur Add plugin → GitHub, liez le miroir et activez Sync automatically. La synchronisation s’exécute lors de la fusion d’une pull request incrémentant la version du plugin sur la branche par défaut.
Pi :
pi install https://github.com/cathrynlavery/diagram-designRechargez la session Pi avec /reload. Lancez le skill par /skill:diagram-design ou exploitez les modèles d’instructions /export-diagram, /import-mermaid et /profile. Pour mettre à jour : pi update --extensions.
Installation locale modifiable :
git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
# Pour Pi
pi install ~/code/diagram-design
# Pour Claude Code
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-designPersonnalisation de marque et profils
Par défaut, la palette utilise le papier blanc fumée, l’encre noir jais et l’accent mandarine atomique. L’intégration de votre propre charte graphique prend une minute par extraction de site web.
Le flux d’onboarding :
- Demande :
onboard diagram-design to https://monsite.com - L’agent analyse la page d’accueil et extrait palette et polices.
- L’agent mappe les valeurs détectées (papier, encre, atténué, accent, lien).
- L’agent propose un diff et vérifie le contraste WCAG AA.
- Validation par l’utilisateur et écriture des jetons dans
references/style-guide.md.
| Élément extrait du site | Jeton assigné dans le guide |
|---|---|
Fond de balise <body> | Jeton paper |
| Couleur de texte principale | Jeton ink |
| Texte secondaire ou légende | Jeton muted |
| Cartes et conteneurs | Jeton paper-2 |
| Couleur d’action majeure (boutons, titres) | Jeton accent |
Police des titres <h1> | Police de titre (ex: Instrument Serif) |
Police du corps <body> | Police des nœuds (ex: Geist sans) |
Police <code> et <pre> | Police technique (ex: Geist Mono) |
La génération fournit un reçu de fidélité listant les URL cibles, les rôles de couleur exacts, les graisses de fonte et les polices de secours. Lors du premier appel dans un projet sans style personnalisé, le système suspend son action et propose l’onboarding, l’insertion manuelle ou l’usage du thème par défaut.
Gestion multi-clients : Enregistrez les styles sous forme de profils nommés dans ~/.diagram-design/profiles/<slug>.md. Dans un projet client, ajoutez un fichier marqueur .diagram-design contenant la ligne profile: <slug>. La commande /diagram-design:profile ou /profile gère ces bascules.
Motifs sémantiques et animations
Quand la logique comportementale prime sur l’agencement spatial, le moteur applique d’abord un motif sémantique avant de choisir la forme visuelle. Sept motifs structurent ces cas : files d’attente à goulot d’étranglement, étapes répétées en créneaux, transformation d’entrées brutes, traces d’audit de règles appariées, chemins sécurisés par défaut, catalogues de gouvernance et couches de sécurité compensatoires.
L’animation reste optionnelle. Le mode par défaut reste statique sans script. Quatre modes existent : none, reveal, step et loop. Le premier écran reste complet et lisible sans exécution d’animation. L’option prefers-reduced-motion désactive la lecture et présente le diagramme fixe. Le fichier skills/diagram-design/assets/template-motion.html fournit le contrôleur JavaScript validé.
Primitives graphiques
- Annotations éditoriales : Texte en italique Instrument Serif relié par une courbe de Bézier en pointillés dans les marges.
- Filtre Sketchy : Déformation par turbulence SVG pour un rendu dessiné à la main.
- Jeu de 55 icônes système : Symboles monochromes (serveurs, conteneurs Docker, bases SQL, terminaux, cloud) héritant de
currentColor.
Importation depuis draw.io et Mermaid
Le module reconstruit les diagrammes existants pour les intégrer au système de design :
/diagram-design:import architecture.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-mermaid schema.mmd --format=png --detail=faithfulLes quatre paramètres d’ajustement :
- Format :
html,svg,pngouhtml+png. - Taille (Size) :
doc-inline,doc-wide,slide-16x9,slide-4x3,social-og,social-square,print-a4-landscape,print-letter-landscape,fit. - Détail :
faithful(24 nœuds maximum),balanced(12 nœuds maximum),simplified(7 nœuds maximum). - Audience :
engineer,mixedouexecutive(ajuste la technicité du vocabulaire sans altérer les composants).
Exportation d’images
L’exportation extrait le visuel hors de son cadre éditorial :
# Claude Code
/diagram-design:export chemin/schema.html --png-only --scale=3
/diagram-design:export chemin/schema.html --svg-only
# Pi
/export-diagram chemin/schema.html --png-only --scale=2L’export SVG incorpore les polices Google Fonts. L’export PNG s’appuie sur Chromium via Playwright (installation : pip install playwright && playwright install chromium). Pour capturer un diagramme animé, ouvrez l’URL avec le paramètre ?motion=static et vérifiez l’attribut data-frame="static".
Arborescence et chargement progressif
L’agent charge uniquement la documentation indispensable à la tâche courante pour préserver sa fenêtre de contexte :
diagram-design/
├── .agents/plugins/marketplace.json
├── .claude-plugin/
├── .codex-plugin/
├── commands/
│ ├── export-diagram.md
│ ├── import-drawio.md
│ ├── import-mermaid.md
│ └── profile.md
├── prompts/
├── skills/
│ └── diagram-design/
│ ├── SKILL.md
│ ├── references/
│ │ ├── style-guide.md
│ │ ├── semantic-patterns.md
│ │ ├── animation.md
│ │ ├── onboarding.md
│ │ ├── profiles.md
│ │ ├── import-drawio.md
│ │ ├── import-mermaid.md
│ │ ├── output-spec.md
│ │ ├── export.md
│ │ └── type-*.md
│ ├── scripts/
│ │ ├── drawio_extract.py
│ │ ├── mermaid_extract.py
│ │ └── self_check.py
│ └── assets/
└── scripts/
├── lint-skin.py
├── verify-geometry.py
├── verify-semantic-motion.py
└── verify-docs-sync.pyVérification et validation de conformité
Avant d’enregistrer un diagramme, le système valide sa structure avec self_check.py. Les tests d’intégration vérifient l’accessibilité SVG (balise role="img", attribut aria-labelledby, balises <title> et <desc> sans collisions d’identifiants), la conformité géométrique des étiquettes face au masquage et l’absence d’attributs exécutables non sécurisés.
# Contrôle d'un fichier généré
python3 skills/diagram-design/scripts/self_check.py mon-diagramme.html
# Contrôle du dépôt et des styles
python3 scripts/lint-skin.py --all --baseline
python3 scripts/verify-geometry.py --all
python3 scripts/verify-docs-sync.pyCritères d’exclusion
N’utilisez pas cet outil dans les situations suivantes :
- Schémas textuels en caractères Unicode pour un terminal ou un message court.
- Listes d’éléments simples : préférez un tableau HTML ou une liste à puces.
- Comparaisons avant/après directes : utilisez un tableau comparatif.
- Schéma contenant une boîte isolée : écrivez une phrase explicative claire.