Excalidraw

Excalidraw - Technical Diagram Skill

Build professional, consistent Excalidraw diagrams via MCP. Skill covers: tool mechanics, sizing formulas, write-check-review verification cycle, and domain-specific styling presets for software engineering, system architecture, and data solutions.

Step 0 - Detect Connection

Check in order:

1. MCP server: tools prefixed mcp__excalidraw-mcp__* (e.g. batch_create_elements, describe_scene) available → use MCP mode. This is the default for this user.
2. REST fallback: only if MCP missing - curl -s $EXPRESS_SERVER_URL/health returns {"status":"ok"}.
3. Nothing → auto-bootstrap the MCP config (see below), then tell user to reconnect the MCP so it registers. Do not fake output.

Auto-bootstrap .mcp.json

When neither the MCP tools nor the REST fallback are available:

1. Resolve project root: git rev-parse --show-toplevel (fallback to CWD if not a git repo). Inside a git worktree this correctly returns the worktree itself - .mcp.json must live at the working root the session runs in, so the MCP registers for that session.

2. Derive project name = basename of the project root.

3. If <project_root>/.mcp.json does not exist, create it with this exact template (substitute <project_name>):

   {
     "mcpServers": {
       "excalidraw-mcp": {
         "type": "http",
         "url": "https://mcp.dataplanelabs.com/excalidraw/mcp",
         "headers": {
           "Authorization": "Bearer ${EXCALIDRAW_MCP_TOKEN}",
           "X-Tenant-Id": "<project_name>"
         }
       }
     }
   }
   

4. If .mcp.json already exists, merge - add the excalidraw-mcp entry under mcpServers without clobbering other servers. Skip if excalidraw-mcp already present.

5. Tell the user: file written, ensure EXCALIDRAW_MCP_TOKEN is exported in shell env, then reconnect before re-running the skill - Claude Code: restart it (or run /mcp). Codex: the .mcp.json above is Claude Code-specific; register the same server with codex mcp add excalidraw-mcp or add [mcp_servers.excalidraw-mcp] (url + headers) to ~/.codex/config.toml, then restart Codex.

Never write the bootstrap file outside the resolved project root, and never echo the token value.

The remote canvas (when this user's MCP is used) is at https://draw.dataplanelabs.com. For visual verification beyond get_canvas_screenshot, use Chrome DevTools MCP to take_screenshot of the canvas URL - get_canvas_screenshot sometimes returns blank PNGs.

Step 1 - Tenant & Project Setup

The remote Excalidraw MCP is multi-tenant. Tenant is selected via the X-Tenant-Id header (configured in .mcp.json) or via tools.

Before any drawing:

1. list_tenants - confirm active tenant
2. list_projects - confirm active project; switch_project with createName if a fresh canvas is wanted
3. describe_scene - read existing diagram zones + suggested next placement coordinates

Never call clear_canvas unless the user explicitly says wipe. Place new diagrams spatially offset (≥300px) from existing ones.

Core Principles (Read Before Any Diagram)

1. Write → Check → Review → Fix (Mandatory Loop)

WRITE batch → set_viewport(scrollToContent: true) → screenshot
  → REVIEW against Quality Checklist → FIX issues → re-screenshot
    → only proceed when all checks pass

2. Use batch_create_elements - Not create_from_mermaid

create_from_mermaid produces overlapping text and broken layouts. Use it only as a quick preview, never for final output. For quality, always plan coordinates and call batch_create_elements.

3. Two Batches: Shapes First, Arrows Second

Arrow binding (startElementId/endElementId) requires shapes to exist already. Mixing in one batch causes binding errors.

4. roughness: 0 for Technical Diagrams

Excalidraw defaults to hand-drawn (roughness > 0). For professional system / data / architecture diagrams, set roughness: 0 on every element. Use strokeWidth: 2 for arrows.

5. Multi-Diagram Canvas

Never clear canvas between diagrams. Place side-by-side or stacked with ≥300px gap. Add a title text element (fontSize 24-28) above each. Group with group_elements so describe_scene reports it as a named zone.

6. Add a Compact Legend When It Clarifies

Include a small legend whenever colors, shapes, stroke styles, or arrow colors encode non-obvious meaning. Keep it minimal:

• Trigger: 3+ semantic node colors, 2+ arrow styles/colors, or mixed ownership/status meanings (internal/external, allow/deny, batch/stream).
• Size: 3-5 entries total; include only semantics actually used in the diagram.
• Placement: top-right or bottom-right whitespace, outside primary flow paths; fontSize 13-14.
• Content: one swatch/mini-line + a short label (Stream, Batch, External, Denied).
• Skip it when labels already make the encoding obvious and the diagram only uses 1-2 semantic styles.

Do not build a full catalog. A legend should explain the visual language, not duplicate every node or edge label.

Sizing Rules (Prevents Truncation)

Excalidraw's font is ~30% wider than typical sans-serif. Use these formulas:

Arrow Visibility (Prevents Invisible Arrows)

Bound arrows shrink to gap_between_shapes - 16 (8px binding padding each side). Below 80px, arrows vanish.

gap = nextShape.y - (currentShape.y + currentShape.height)

Domain Styling Presets

Pick the preset matching the diagram type. Apply fill + stroke + shape per row. Don't mix palettes within one diagram unless intentional.

Active Color Budget

Use at most 5 active semantic colors in any one diagram. Similar components share one color family: all internal services together, all data stores together, all compute/jobs together, all external systems together, all security/blocked paths together.

Treat long preset tables as menus, not a requirement to use every color. If the diagram needs more than five meanings, keep the color and vary shape, stroke style, arrow width, grouping boundary, or label. Neutral gray boundaries/backgrounds and black/white text do not count against the 5-color budget.

Minimal Legend Defaults

Use these entries only when the matching semantics appear in the diagram:

For node legends, show only the shape/color roles that are not already obvious from labels, such as Internal service, External system, Database, Queue, or Security boundary.

Software Architecture (C4 / Microservices)

Rule: all elements in one C4 view share the same abstraction level. Don't mix Container with Component shapes in one diagram - split into two.

Cloud Architecture (AWS / GCP / Azure)

Color by service category, label by service name + bracket type:

Bound zones (VPC, subnet, account) with a translucent rectangle: backgroundColor: "#e9ecef", opacity: 30, label as title above.

No icons? Use [Compute], [Storage], etc. in the label and the category color does the visual work.

Data Pipeline / Lakehouse / ETL

Encode batch vs stream via stroke width and color, lineage via dotted, async via dashed:

Layout: sources top → processing middle → sinks bottom; warehouse layers (raw → staging → marts) flow top-down with consistent column alignment.

UML - Sequence / ER / State / Class

Sequence

• Actors: hexagon #fff3e0 / #f57c00
• Lifeline: vertical dashed line #999, strokeWidth 1
• Service: rectangle on top of lifeline #e3f2fd / #1976d2
• Sync message: solid arrow #1976d2, label method()
• Async message: dashed arrow #f57c00, label event
• Return: dashed arrow #b0bec5, label result

ER

• Entity: rectangle #e8f5e9 / #388e3c, label = TableName
• Attribute: ellipse #f3e5f5 / #7b1fa2, label = column\ntype
• Primary key: ellipse, underline label
• Relationship: diamond #fff3e0 / #f57c00, label = verb (has, owns)
• Cardinality: text on the connection line (1:N, M:N)

State

• State: rounded rectangle #bbdefb / #1976d2
• Initial: small filled ellipse #212121
• Final: ellipse with inner dot
• Transition: solid arrow with event [guard] / action label

Class

• Class: rectangle, three sections separated by horizontal lines (name / fields / methods)
• Inheritance: solid arrow with empty triangle head, color #1976d2
• Composition: arrow with filled diamond, color #d32f2f
• Aggregation: arrow with empty diamond, color #757575

Deployment - Kubernetes / Docker

K8s blue is #326ce5. Use it as the cluster boundary.

Arrows: API call solid #1976d2, mount dotted #7b1fa2, replication dashed #f57c00, denied policy thick red.

Quality Checklist

After every batch, verify ALL:

If any check fails: STOP. Use update_element or delete + recreate. Re-screenshot. Only proceed when all checks pass.

Standard Workflow

1. describe_scene                              # see existing
2. Plan: list elements, layout direction, IDs, coordinates
3. Pick a domain preset (architecture/cloud/data/UML/deployment)
4. batch_create_elements: shapes (Batch 1)
5. batch_create_elements: arrows (Batch 2)
6. Add compact legend if trigger conditions apply
7. group_elements                              # group new diagram
8. set_viewport(scrollToContent: true)
9. Screenshot → Quality Checklist → fix → repeat

Anti-Patterns (Avoid)

MCP Tool Quick Reference

When exporting through export_scene or export_to_image, write finalized images into the injected Visuals: path (it resolves under the umbrella even from a worktree, so exports survive worktree clean); fall back to a temp dir only when no Visuals: path was injected. Then hand off an openable output location:

• Clickable absolute file link: [diagram.png](/absolute/path/to/diagram.png)
• Plain browser URI when useful: file:///absolute/path/to/diagram.png
• Remote share URL from export_to_excalidraw_url, if generated

Never report only diagram.png or another basename; include the canvas URL plus the file path/URI for every finalized exported file.

Element Creation Cheat Notes

• Always assign a custom id to each shape so arrows can bind via startElementId / endElementId.
• For shape labels (rectangles, diamonds, ellipses): set text directly on the element - MCP auto-creates the bound text child.
• Curved arrows: roundness: { type: 2 } plus 3+ points.
• Elbowed arrows: elbowed: true.
• Dashed stroke: strokeStyle: "dashed". Dotted: strokeStyle: "dotted".
• Translucent zone backgrounds: backgroundColor: "#e9ecef", opacity: 30.
• Compact legend: small swatch rectangles or 80px mini-lines with short labels; group legend elements with the diagram.

References

• references/styling-presets.md - full color palettes per domain, layout templates, accessibility, comprehensive examples.
• references/cheatsheet.md - MCP tool list, REST API mapping, env vars, multi-tenancy notes.

When in doubt, re-read the preset table for your domain before drawing. Color and shape consistency matters more than how many shapes you draw.