Compétence Excalidraw

Que fait Compétence Excalidraw ?

Étape 0 : Choisir une interface

Trois interfaces pilotent le même canevas en direct. Choisissez la première qui s'applique :

1. Outils MCP — si les outils excalidraw/* (par ex. batch_create_elements) figurent dans votre liste d'outils, privilégiez-les : les résultats atterrissent directement dans votre contexte, et les captures d'écran reviennent sous forme d'images sans toucher au disque.
2. CLI (par défaut lorsqu'aucun outil MCP n'est présent) :

   npx -y mcp-excalidraw-server <commande>
   

   Aucune configuration nécessaire — toute commande touchant au canevas démarre automatiquement le serveur de canevas sur http://127.0.0.1:3000 (la première exécution de npx télécharge le paquet). Si le CLI est installé globalement (npm i -g mcp-excalidraw-server), l'alias plus court excalidraw-canvas <commande> fonctionne aussi.
3. API REST (en dernier recours, par exemple depuis du code applicatif) : points de terminaison HTTP sur http://127.0.0.1:3000 — voir references/cheatsheet.md pour les charges utiles. Le serveur doit déjà être en cours d'exécution.

L'URL du canevas provient de EXPRESS_SERVER_URL (par défaut http://127.0.0.1:3000). Rappelez à l'utilisateur d'ouvrir cette URL dans un navigateur — les captures d'écran, l'exportation d'images, la conversion mermaid et le contrôle de la zone d'affichage nécessitent un onglet ouvert (le CLI se termine avec le code 4 s'il est manquant).

Référence rapide du CLI

Les résultats sont au format JSON sur stdout — sauf pour describe (texte brut) et la sortie en contenu brut lorsque --out est omis (export du JSON de la scène, screenshot --format svg). Les diagnostics sur stderr. Codes de sortie : 0 ok, 1 erreur, 2 utilisation, 3 canevas inaccessible, 4 onglet navigateur requis.

Tâche	Commande
Démarrer / arrêter / inspecter le serveur	start, stop, status
Créer des éléments (par lots)	add elements.json ou `echo '[...]'
Patch multi-opération en un appel	apply patch.json — {"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}
Lire un / interroger plusieurs	get <id>, query [--type t] [--bbox x0,y0,x1,y1] [--filter k=v] [--filter-json '{...}']
Mettre à jour / supprimer	update <id> --set '{...}', delete <id> [...]
Comprendre la scène	describe (résumé en texte brut : ids, positions, étiquettes, connexions)
Voir la scène	screenshot [--out f.png] (PNG sans --out → chemin de fichier temporaire dans JSON ; SVG sans --out → SVG brut)
Opérations de disposition	`arrange align
Fichiers de scène	export [--out scene.excalidraw], `import [scene.excalidraw
Mermaid → canevas	`mermaid [diagram.mmd
Instantanés	`snapshot save
Lien de partage	share (téléchargement chiffré → URL excalidraw.com)
Effacer le canevas	clear --yes
Installer / mettre à niveau cette compétence	install-skill --dir <racine-des-competences> (l'agent choisit la racine projet/globale)

Format des éléments (CLI et MCP)

Le CLI et les outils MCP acceptent le même format adapté aux agents et le normalisent automatiquement :

• Étiquettes : placez "text": "Mon Étiquette" sur n'importe quelle forme — converti au format d'étiquette liée d'Excalidraw pour vous.
• Liaison de flèches : "startElementId": "a" / "endElementId": "b" — les flèches se routent automatiquement vers les bords des éléments.
• fontFamily : passez un nom de chaîne ("helvetica", "cascadia", "excalifont", ...) ou un numéro de chaîne "1"–"8".
• points : les tuples [[x,y], ...] et les objets [{"x":..,"y":..}] sont tous deux acceptés.
• Mises à jour par patch : dans apply, les entrées de mise à jour peuvent utiliser soit des champs directs ({"id":"a","x":120}) soit un objet set ({"id":"a","set":{"x":120}}). Ne mélangez pas les deux formes dans une seule entrée de mise à jour.

Le REST brut est plus strict : les étiquettes doivent être "label": {"text": "..."}, les liaisons doivent être "start": {"id": "..."} / "end": {"id": "..."}. Ne vous en souciez que lorsque vous publiez directement sur l'API.

---

Système de coordonnées

Le canevas utilise une grille de coordonnées 2D : (0, 0) est l'origine, x augmente vers la droite, y augmente vers le bas. Planifiez votre disposition avant d'écrire du JSON.

Directives générales d'espacement :

• Espacement vertical entre les niveaux : 80–120 px (assez pour que les flèches ne surchargent pas les étiquettes)
• Espacement horizontal entre les frères : minimum 40–60 px ; donnez 120 px+ aux flèches étiquetées
• Largeur de forme : max(160, nombreCaractèresÉtiquette * 12) pour garder l'étiquette sur une seule ligne
• Hauteur de forme : 60 px pour une ligne, 80 px pour deux lignes d'étiquettes
• Remplissage de l'arrière-plan/de la zone : 50 px de tous les côtés autour des éléments contenus

Styling pour un aspect professionnel :

• "fillStyle": "solid" sur les formes donne des remplissages plats et nets — la valeur par défaut est un motif hachuré esquissé
• Associez les remplissages pastel backgroundColor avec leur strokeColor plus foncé (palette dans l'aide-mémoire)
• "strokeStyle": "dashed" sur les bordures de zone et les flèches asynchrones se lit comme "limite / arrière-plan"

---

Anti-modèles de disposition (Critiques pour les diagrammes complexes)

Ce sont les erreurs les plus courantes qui produisent des diagrammes illisibles. Évitez-les toutes.

1. N'utilisez PAS label.text (ou text) sur les grands rectangles de zone d'arrière-plan

Lorsque vous placez une étiquette sur un rectangle d'arrière-plan, Excalidraw crée un élément de texte lié centré au milieu de cette forme — là où vos boîtes de service seront placées. Le texte chevauche tout à l'intérieur de la zone et ne peut pas être repositionné.

Mauvais :

{"id": "zone-vpc", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "text": "VPC (10.0.0.0/16)"}

Correct — utilisez un élément de texte libre ancré en haut de la zone :

{"id": "zone-vpc", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "backgroundColor": "#e3f2fd"},
{"id": "etiquette-vpc", "type": "text", "x": 70, "y": 60, "width": 300, "height": 30, "text": "VPC (10.0.0.0/16)", "fontSize": 18}

L'élément de texte libre se trouve dans le coin supérieur de la zone et n'interfère pas avec les éléments placés à l'intérieur.

2. Évitez les flèches traversant les zones dans les diagrammes complexes

Une flèche d'un élément dans une zone de disposition à un élément dans une zone éloignée tracera une longue ligne diagonale traversant tout ce qui se trouve entre les deux. Dans un diagramme d'infrastructure multi-zone, cela produit un enchevêtrement de spaghetti illisible.

Règle de conception : Gardez les flèches dans la même zone ou le même niveau. Pour montrer les relations entre zones, utilisez du texte d'annotation ou séparez les zones afin que leurs bords soient adjacents (aucun élément entre elles), et acheminez la flèche le long du bord.

Si vous devez absolument connecter entre les zones, utilisez une flèche coudée qui longe le périmètre — jamais à travers le milieu d'une autre zone.

3. Utilisez les étiquettes de flèches avec parcimonie

Les étiquettes de flèches sont placées au milieu de la flèche. Sur les flèches courtes, elles chevauchent les formes aux deux extrémités. Sur les diagrammes denses, elles entrent en collision avec les éléments voisins.

• N'ajoutez une étiquette de flèche que lorsque le nom de la relation est vraiment essentiel (par exemple, protocole, numéro de port, direction des données).
• Si vous ajoutez une étiquette à chaque flèche, reconsidérez — cela ajoute généralement du bruit visuel, pas de la clarté.
• Gardez les étiquettes de flèches à ≤ 12 caractères. Préférez les omettre entièrement sur les diagrammes denses.

---

Qualité : Pourquoi c'est important (et comment vérifier)

Les diagrammes Excalidraw sont une communication visuelle. Si le texte est coupé, les éléments se chevauchent ou les flèches traversent des formes sans rapport, le diagramme devient déroutant et non professionnel — cela va à l'encontre de l'objectif même de son dessin. Donc, après chaque lot d'éléments, vérifiez avant d'en ajouter d'autres.

Liste de contrôle qualité

Après chaque add / apply / batch_create_elements, prenez une capture d'écran et vérifiez :

1. Troncature de texte — Tout le texte de l'étiquette est-il entièrement visible ? Un texte tronqué signifie que la forme est trop petite. Augmentez width et/ou height.
2. Chevauchement — Des formes partagent-elles le même espace ? Les zones d'arrière-plan doivent entièrement contenir les enfants avec un espacement.
3. Croisement de flèches — Les flèches traversent-elles des éléments sans rapport ? Si oui, contournez-les en utilisant des flèches courbes ou coudées (voir Routage des flèches ci-dessous).
4. Chevauchement étiquette-flèche — Les étiquettes de flèches se trouvent au milieu. Si elles chevauchent une forme, raccourcissez l'étiquette ou ajustez le chemin de la flèche.
5. Espacement — Au moins 40 px d'écart entre les éléments. Les dispositions serrées sont difficiles à lire.
6. Lisibilité — Taille de police ≥ 16 pour le texte du corps, ≥ 20 pour les titres.
7. Placement de l'étiquette de zone — Si vous avez utilisé text/label.text sur un rectangle de zone d'arrière-plan, l'étiquette de zone sera centrée au milieu de la zone, chevauchant tout à l'intérieur. Correctif : supprimez l'élément de texte lié et ajoutez un élément de texte libre en haut de la zone à la place (voir Anti-modèles de disposition ci-dessus).

Si vous trouvez un problème : arrêtez, corrigez-le, refaites la capture d'écran, puis continuez. Dites "Je vois [problème], je le corrige" plutôt que de passer les problèmes sous silence. Ne continuez que lorsque toutes les vérifications sont réussies.

---

Flux de travail : Dessiner un nouveau diagramme

Mermaid vs. Création directe — Lequel utiliser ?

Utilisez mermaid / create_from_mermaid lorsque : l'utilisateur a déjà un diagramme Mermaid, ou la structure se mappe proprement à un organigramme/séquence/diagramme ER avec la syntaxe Mermaid standard. C'est rapide et gère la conversion automatiquement, même si vous avez moins de contrôle sur la disposition exacte.

Créez des éléments directement lorsque : vous avez besoin d'un contrôle précis de la disposition, le type de diagramme ne se mappe pas bien à Mermaid (par exemple, architecture personnalisée, diagrammes cloud annotés), ou vous voulez que les éléments soient positionnés dans une grille de coordonnées spécifique.

Étapes (CLI montré ; les outils MCP sont en correspondance 1:1 — voir l'aide-mémoire)

1. Planifiez votre grille de coordonnées — cartographiez les niveaux et les positions x avant d'écrire du JSON. (Mode MCP : appelez read_diagram_guide pour les couleurs/taille ; les mêmes conseils se trouvent dans references/cheatsheet.md.)
2. Départ à neuf facultatif : npx -y mcp-excalidraw-server clear --yes
3. Créez des formes et des flèches en un seul appel. Les champs id personnalisés (par ex. "id": "auth-svc") facilitent les mises à jour ultérieures :

   npx -y mcp-excalidraw-server add - <<'EOF'
   [
     {"id": "lb", "type": "rectangle", "x": 300, "y": 50, "width": 180, "height": 60, "text": "Équilibreur de charge"},
     {"id": "svc-a", "type": "rectangle", "x": 100, "y": 200, "width": 160, "height": 60, "text": "Serveur Web 1"},
     {"id": "svc-b", "type": "rectangle", "x": 450, "y": 200, "width": 160, "height": 60, "text": "Serveur Web 2"},
     {"id": "db", "type": "rectangle", "x": 275, "y": 350, "width": 210, "height": 60, "text": "PostgreSQL"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "lb", "endElementId": "svc-a"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "lb", "endElementId": "svc-b"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-a", "endElementId": "db"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-b", "endElementId": "db"}
   ]
   EOF
   

   (Le - positionnel est facultatif — sans argument de fichier, add lit stdin.)
4. Définissez les largeurs de forme en utilisant max(160, longueurÉtiquette * 12).
5. screenshot → visualisez le fichier → exécutez la liste de contrôle qualité → corrigez les problèmes avant le lot suivant.

---

Routage des flèches — Éviter les chevauchements

Les flèches droites peuvent traverser des éléments dans les diagrammes complexes. Utilisez des flèches courbes ou coudées si nécessaire :

Flèches courbes (arc lisse par-dessus les obstacles) :

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": {"type": 2}
}

Le point de passage intermédiaire [50, -40] soulève la flèche vers le haut. roundness: {type: 2} la rend lisse.

Flèches coudées (routage en angle droit / en L) :

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true
}

Quand utiliser quoi :

• Éventail (une source → plusieurs cibles) : flèches courbes avec points de passage répartis pour éviter les chevauchements
• Traversée de couloir (connexion à des panneaux latéraux) : flèches coudées qui montent, puis traversent, puis descendent
• Connexions horizontales longues : flèches courbes avec un léger décalage vertical

Règle : Si une flèche devait traverser une forme sans rapport, ajoutez un point de passage pour la contourner.

---

Flux de travail : Affinement itératif

Associer describe avec screenshot est ce qui rend cette compétence puissante.

• describe (describe_scene dans MCP) → texte structuré : IDs d'éléments, types, positions, étiquettes, connexions. Utilisez-le pour savoir ce qu'il y a sur le canevas avant de faire des mises à jour programmatiques (trouver des IDs, comprendre les boîtes englobantes).
• screenshot (get_canvas_screenshot dans MCP) → PNG du canevas réellement rendu. Utilisez-le pour la vérification visuelle de la qualité — il montre exactement ce que l'utilisateur voit, y compris la troncature, le chevauchement et le routage des flèches. Le CLI imprime le chemin du fichier sauvegardé sous forme de JSON ; lisez/visualisez ce fichier.

Boucle de rétroaction :

add elements
  → screenshot → visualiser → "texte tronqué sur auth-svc"
  → update auth-svc --set '{"width": 220}' → screenshot → "chevauchement entre auth-svc et rate-limiter"
  → update rate-limiter --set '{"x": 520}' → screenshot → "toutes les vérifications réussies"
  → continuer

Flux de travail : Affiner un diagramme existant

1. describe pour comprendre l'état actuel — notez les IDs d'éléments et les positions.
2. Identifiez les éléments par id ou texte d'étiquette (pas par coordonnées x/y — elles changent).
3. update <id> --set '{...}' pour redimensionner/recolorer/déplacer ; delete <id> pour supprimer ; ou regroupez le tout dans un seul patch apply. Les flèches liées se reroutent automatiquement lorsque vous déplacez ou redimensionnez leurs points d'extrémité — pas besoin de les supprimer et de les recréer.
4. screenshot pour confirmer que le changement est correct.
5. Si les mises à jour échouent : vérifiez que l'ID existe avec get <id> ; déverrouillez avec arrange unlock --ids <id> si verrouillé.

Flux de travail : Conversion Mermaid

echo 'graph TD
  A[Client] --> B[API]
  B --> C[(BD)]' | npx -y mcp-excalidraw-server mermaid

Nécessite un onglet de navigateur ouvert (la conversion s'exécute dans le frontend ; le code de sortie 4 vous indique d'ouvrir l'URL du canevas). Ensuite, screenshot pour vérifier la disposition. Si la disposition automatique est médiocre (nœuds entassés, arêtes qui se croisent), trouvez les éléments problématiques avec describe et repositionnez-les avec update.

Flux de travail : Entrée/Sortie de fichier

• Exporter la scène : export --out diagram.excalidraw (sans --out → JSON sur stdout)
• Importer la scène : import diagram.excalidraw (ajouter) ou import diagram.excalidraw --replace
• Image : screenshot --out diagram.png / screenshot --format svg --out diagram.svg (onglet navigateur requis)
• Lien de partage : share — chiffre la scène et renvoie un lien partagé exc

…

[tronqué pour la traduction]