Excalidraw Skill

Excalidraw Skill

Step 0: Detect Connection Mode

Before doing anything, determine which mode is available. Run these checks in order:

Check 1: MCP Server (Best experience)

mcp-cli tools | grep excalidraw

If you see tools like excalidraw/batch_create_elements → use MCP mode. Call MCP tools directly.

Check 2: REST API (Fallback — works without MCP server)

curl -s http://localhost:3000/health

If you get {"status":"ok"} → use REST API mode. Use HTTP endpoints (curl / fetch) from the cheatsheet.

Check 3: Nothing works → Guide user to install

If neither works, tell the user:

The Excalidraw canvas server is not running. To set up: 1. Clone: git clone https://github.com/yctimlin/mcp_excalidraw && cd mcp_excalidraw 2. Build: npm ci && npm run build 3. Start canvas: HOST=0.0.0.0 PORT=3000 npm run canvas 4. Open http://localhost:3000 in a browser 5. (Recommended) Install the MCP server for the best experience: `` claude mcp add excalidraw -s user -e EXPRESS_SERVER_URL=http://localhost:3000 -- node /path/to/mcp_excalidraw/dist/index.js ``

MCP vs REST API Quick Reference

REST API Gotchas (Critical — read before using REST API)

1. Labels: Use "label": {"text": "My Label"} (not "text": "My Label"). MCP tools auto-convert, REST API does not.
2. Arrow binding: Use "start": {"id": "svc-a"}, "end": {"id": "svc-b"} (not "startElementId"/"endElementId"). MCP tools accept startElementId and convert, REST API requires the start/end object format directly.
3. fontFamily: Must be a string (e.g. "1") or omit it entirely. Do NOT pass a number like 1.
4. Updating labels: When updating a shape via PUT /api/elements/:id, include the full label in the update body to preserve it. Omitting label from the update won't delete it, but re-sending ensures it renders correctly.
5. Screenshot in REST mode: POST /api/export/image returns {"data": "<base64>"}. Save to file and read it back for visual verification. Requires browser open.

Quality Gate (MANDATORY — read before creating any diagram)

After EVERY iteration (each batch of elements added), you MUST run a quality check before proceeding. NEVER say "looks great" unless ALL checks pass.

Quality Checklist — verify ALL before adding more elements:

1. Text truncation: Is ALL text fully visible? Labels must fit inside their shapes. If text is cut off or wrapping badly → increase width and/or height.
2. Overlap: Do ANY elements overlap each other? Check that no rectangles, ellipses, or text elements share the same space. Background zones must fully contain their children with padding.
3. Arrow crossing: Do arrows cross through unrelated elements or overlap with text labels? If yes → use curved/elbowed arrows with waypoints to route around obstacles (see "Arrow Routing" section). Never accept crossing arrows.
4. Arrow-text overlap: Do any arrow labels ("charge", "event", etc.) overlap with shapes? Arrow labels are positioned at the midpoint — if they overlap, either remove the label, shorten it, or adjust the arrow path.
5. Spacing: Is there at least 40px gap between elements? Cramped layouts are unreadable.
6. Readability: Can all labels be read at normal zoom? Font size >= 16 for body text, >= 20 for titles.

If ANY issue is found:

• STOP adding new elements
• Fix the issue first (resize, reposition, delete and recreate)
• Re-verify with a new screenshot
• Only proceed to next iteration after ALL checks pass

Sizing Rules (prevent truncation):

• Shape width: max(160, labelTextLength * 9) pixels. For multi-word labels like "API Gateway (Kong)", count all characters.
• Shape height: 60px for single line, 80px for 2 lines, 100px for 3 lines.
• Background zones: Add 50px padding on ALL sides around contained elements.
• Element spacing: 60px vertical between tiers, 40px horizontal between siblings.
• Side panels: Place at least 80px away from main diagram elements.
• Arrow labels: Keep labels short (1-2 words). Long arrow labels overlap with other elements.

Layout Planning (prevent overlap):

Before creating elements, plan your coordinate grid on paper first:

• Tier 1 (y=50-130): Client apps
• Tier 2 (y=200-280): Gateway/Edge
• Tier 3 (y=350-440): Services (spread wide: each service ~180px apart)
• Tier 4 (y=510-590): Data stores
• Side panels: x < 0 (left) or x > mainDiagramRight + 80 (right)

Do NOT place side panels (observability, external APIs) at the same x-range as the main diagram — they WILL overlap.

Quick Start

1. Run Step 0 above to detect your connection mode.
2. Open the canvas URL in a browser (required for image export/screenshot).
3. MCP mode: Use MCP tools for all operations. REST mode: Use HTTP endpoints from cheatsheet.
4. For full tool/endpoint reference, read references/cheatsheet.md.

Workflow: Draw A Diagram

MCP Mode

1. Call `read_diagram_guide` first to load design best practices.
2. Plan your coordinate grid (see Quality Gate → Layout Planning) before writing any JSON.
3. Optional: clear_canvas to start fresh.
4. Use batch_create_elements with shapes AND arrows in one call.
5. Assign custom `id` to shapes (e.g. "id": "auth-svc"). Set text field to label shapes.
6. Size shapes for their text — use width: max(160, textLength * 9).
7. Bind arrows using startElementId / endElementId — arrows auto-route.
8. set_viewport with scrollToContent: true to auto-fit the diagram.
9. Run Quality Checklist — get_canvas_screenshot and critically evaluate. Fix issues before proceeding.

REST API Mode

1. Read references/cheatsheet.md for design guidelines.
2. Plan your coordinate grid (see Quality Gate → Layout Planning) before writing any JSON.
3. Optional: curl -X DELETE http://localhost:3000/api/elements/clear
4. Create elements in one call (use @file.json for large payloads): ``bash curl -X POST http://localhost:3000/api/elements/batch \ -H "Content-Type: application/json" \ -d '{"elements": [ {"id": "svc-a", "type": "rectangle", "x": 0, "y": 0, "width": 160, "height": 60, "label": {"text": "Service A"}}, {"id": "svc-b", "type": "rectangle", "x": 0, "y": 200, "width": 160, "height": 60, "label": {"text": "Service B"}}, {"type": "arrow", "x": 0, "y": 0, "start": {"id": "svc-a"}, "end": {"id": "svc-b"}} ]}' ``
5. Use `"label": {"text": "..."}` for shape labels (not "text": "...").