excalidraw-diagrams

Excalidraw Diagrams

Build genuinely good diagrams on a live, editable Excalidraw canvas through the Excalidraw MCP. Every shape is a native, individually-editable element — not a locked image — so you compose, refine per element, verify visually, and export a committable artefact.

This skill covers the full MCP surface (28 tools) and the craft of using it well. Read the reference files on demand; they are the detail behind this page.

• references/tool-reference.md — every tool, its parameters, and its gotchas.
• references/element-model.md — element types, the full property catalogue, and verified defaults.
• references/visual-quality.md — palette, spacing, arrow semantics, light/dark portability, and the quality bar.
• references/patterns.md — ready-to-adapt templates (layered architecture, flowchart, ERD, sequence, C4) and the Mermaid→canvas bridge.
• references/multiple-diagrams-and-stencils.md — the scene model, holding several diagrams on one canvas, and reusable-component stencils (the practical stand-in for Excalidraw libraries).

When to use this skill

Use it when the diagram must be visual and editable, not just Mermaid source in a .md.

• The audience will drag, restyle, or annotate it (design reviews, workshops, stakeholder walkthroughs).
• You need per-element control the Mermaid renderer can't give (precise colour bands, zones, mixed arrow semantics).
• You want a committable .excalidraw artefact plus a PNG/SVG for embedding.
• You already authored Mermaid and want it on an editable canvas — import it, then refine (see the bridge in patterns.md).

If the diagram only needs to render inline in GitHub/PRs and never be hand-edited, plain Mermaid is lighter — use the mermaid-diagrams skill instead.

Canvas basics (read once)

• The MCP runs a local canvas at http://127.0.0.1:3000 (Node ≥ 18, no API keys).
• Drawing commands auto-start the server; set EXCALIDRAW_NO_AUTOSTART=1 to opt out.
• Storage is in-memory. Restarting the server clears everything — persist with export_scene (repo artefact) or snapshot_scene (named, server-side, this session only).
• A browser tab on the canvas URL is required for get_canvas_screenshot, export_to_image, set_viewport, and create_from_mermaid — those run in the canvas browser.
• Coordinates are a plain top-left origin: x grows right, y grows down. Lay content out on a 20px grid.

The golden workflow

Follow this loop every time; it is the difference between a clean diagram and a tangle.

1. Guide first — required reading before any real diagram. Call read_diagram_guide for the live palette/sizing reference, and read references/visual-quality.md for the full quality bar (palette, spacing, arrow semantics, light/dark portability). This overview page is not a substitute for that reference — open it before you draw anything beyond a throwaway sketch.
2. Plan on a grid. Decide tiers/zones and rough coordinates before drawing. Group same-role shapes to one size. Reserve column/row bands.
3. Draw in dependency order (see visual-quality.md → Drawing order): background zones → primary shapes → bound arrows → annotations.
   • Use batch_create_elements for whole tiers in one call. Give shapes custom ids so arrows can bind to them.
   • Bind every arrow with startElementId/endElementId — never hand-place arrow endpoints.
4. Arrange precisely. align_elements and distribute_elements to snap rows/columns; group_elements for clusters you'll move together.
5. Verify — always, and never skip it. describe_scene for structure + connections, then get_canvas_screenshot with background on and off (light and dark). Fix any overflow, overlap, misalignment, or stroke that vanishes on either theme before you consider the diagram done. Structure alone is not trustworthy — render it and look.
6. Refine per element. query_elements to find a shape, then update_element / create_element / delete_element. Never regenerate the whole diagram for a small change.
7. Persist. export_scene → a committable .excalidraw beside the doc; export_to_image → PNG/SVG for embedding; snapshot_scene for in-session checkpoints before risky refactors.

Non-negotiable defaults (verified)

The MCP's raw defaults look sketchy and unprofessional. Override them every time.

• roughness: 0 on every shape and arrow. The default 1 is a hand-drawn wobble — fine for a napkin, wrong for a spec.
• fontFamily: 2 (sans) for UI/architecture, 3 (mono) for code/tool names. The default 1 is a handwriting font.
• strokeWidth: 2 for primary shapes/flows, 1.5 for secondary. Below 1.5 disappears when zoomed out.
• Mid-tone strokes, pastel fills. Never pure black (#000000) or pure white (#ffffff) for strokes/text — each vanishes on one canvas theme. Full palette + reasoning in visual-quality.md.
• Fill renders solid by default here (no sketchy hachure) — pastel backgroundColor paired with a mid-tone strokeColor reads correctly on light and dark.

Palette quick reference

Stroke = the family's meaning; fill = its pale partner. One colour family per relationship/layer; cap at 3–4 per diagram.

Family	Stroke	Fill	Use for
Blue	#1971c2	#a5d8ff	primary services, links, frontend
Purple	#9c36b5	#eebefa	middleware, services, certs
Cyan	#0c8599	#99e9f2	data stores, databases, networking
Orange	#e8590c	#ffd8a8	async, queues, events, ingress
Green	#2f9e44	#b2f2bb	success, healthy, storage
Red	#e03131	#ffc9c9	errors, warnings, critical
Gray	#868e96	#e9ecef	annotations, secondary, infra

Zones (background bands) use the palest tint of their family at reduced opacity; see patterns.md.

Arrows carry meaning — four channels

Set each deliberately and decode them in a legend. Full rules in visual-quality.md.

• Stroke style: solid → primary flow; dashed → async/optional/delegation; dotted → weak dependency/annotation.
• Arrowhead: triangle → directed flow (default); arrow → lighter directed; dot → data store/endpoint; bar → boundary; null → association.
• Colour: one colour = one relationship type; cap at 3–4.
• Label: put a short text on any arrow whose meaning isn't obvious; give labelled arrows 120px+ of length.

Cardinal layout rules

These prevent the two most common ways a diagram turns to spaghetti.

• Never fan arrows across the canvas to shared resources. List shared items (tools, stores, services) inside each node's card instead. Long shared-target arrows are the #1 cause of mess.
• Isolate distinct relationship types into their own bordered panels. Don't overlay a "uses" graph and a "delegates-to" graph on the same nodes.
• Fan-out/fan-in stays clean when the middle tier is a single vertical column: A → {stack} → Z.
• Group by container, then place tiers in aligned rows/columns — equal-height cards beat a free-form scatter.

Multiple diagrams and reusable components

The canvas is one shared in-memory scene — there are no native frames, and get_resource library just returns the current elements (no separate component library). Both needs are still covered — full detail in references/multiple-diagrams-and-stencils.md:

• Several diagrams at once — give each its own coordinate region and labelled panel, id-prefix and group_elements each, and use set_viewport(scrollToElementId) + get_canvas_screenshot to review/capture one at a time. export_scene is scene-global, so for separate committable files build and export sequentially (snapshot_scene → build A → export → clear_canvas → build B → export).
• Reusable components (the "library" stand-in) — save a styled component as a .excalidraw stencil and import_scene(mode: "merge") to stamp it; duplicate_elements to clone one already on the canvas. Keep a repo stencils/ folder as your kit. Export/import paths are sandboxed — use relative paths (EXCALIDRAW_EXPORT_DIR sets the base).

Failure modes to avoid

• Drawing arrows with manual coordinates instead of binding — they detach and overshoot. Always bind.
• Leaving roughness/fontFamily at defaults — the diagram looks like a sketch.
• Text overflowing its box — estimate width first (chars × 0.55 × fontSize ≤ boxWidth − 2·padding) and re-measure after.
• More than 3–4 colours, or colour used for decoration rather than meaning.
• Skipping the screenshot verify — you cannot trust structure alone; render it and look.