excalidraw-diagram-design

Excalidraw Diagram Design Guide

This skill teaches you how to structure the nodes and connections input for the Excalidraw Architect MCP so the auto-layout engine produces clean, readable diagrams - not spaghetti.

Core Principle

The layout engine (Sugiyama algorithm) works best with tree-like, flow-oriented graphs. Your job as the LLM is to model the data flow story, not the import graph.

Graph Topology Rules

1. Keep it tree-like - avoid diamond dependencies

The #1 cause of messy diagrams is multiple nodes connecting to the same shared target.

BAD: 4 arrows all pointing to "models.py"
  mermaid → models
  state   → models
  layout  → models
  builder → models

GOOD: Drop shared infrastructure nodes or show them as a single grouped leaf
  layout → builder → output

Rule: If a node has 4+ incoming edges, either remove it or group it with related nodes.

2. Limit edges to primary data flow

Show how data moves through the system, not every import statement.

BAD (16 edges for 12 nodes - dependency graph):
  server → mermaid, state, layout, excalidraw
  mermaid → models
  state → models, excalidraw_file
  layout → models, grandalf, components
  excalidraw → models, components, themes, excalidraw_file

GOOD (9 edges for 9 nodes - data flow):
  ide → server → [mermaid, state, layout]
  layout → renderer → [styling, output]

Rule: Aim for roughly N-1 to N+2 edges for N nodes (tree + a few extra).

3. Hub nodes should have 3–5 fan-out, not more

The layout engine auto-stretches "hub" nodes (≥3 connections) into gate-like rectangles. This looks great for API gateways, load balancers, and message brokers. But a node with 6+ fan-out creates too many parallel arrows.

GOOD: API Gateway → [Auth, Users, Orders, Payments]  (4 fan-out)
BAD:  Server → [A, B, C, D, E, F, G, H]             (8 fan-out)

Rule: If a node has 6+ connections, split it into two logical stages or group downstream nodes.

4. Keep layers balanced