Excalidraw Diagram Generator

Generate beautiful hand-drawn style diagrams rendered as PNG images.

Workflow

1. Generate JSON — Write Excalidraw element array based on what the user wants
2. Save to file — Write JSON to /tmp/<name>.excalidraw
3. Render — node ~/clawd/skills/excalidraw/scripts/render.js /tmp/<name>.excalidraw /tmp/<name>.png
4. Deliver based on context:

If chatting (Telegram/Discord/Slack/etc):

Send the PNG directly in chat via message tool:

message(action="send", filePath="/tmp/<name>.png", caption="Description")

NEVER create a separate .excalidraw file for the user. Always render to PNG and send inline.

If creating a Google Doc:

1. Upload PNG to Google Drive
2. Insert image INTO the document using Docs API
3. Do NOT create a separate file or link - embed the image directly

If user explicitly asks for the .excalidraw file:

Only then provide the raw .excalidraw JSON file for editing in Excalidraw app.

Quick Reference

node <skill_dir>/scripts/render.js input.excalidraw output.png

Element Types

Styling (all shapes)

{
  "strokeColor": "#1e1e1e",
  "backgroundColor": "#a5d8ff",
  "fillStyle": "hachure",
  "strokeWidth": 2,
  "roughness": 1,
  "strokeStyle": "solid"
}

fillStyle: hachure (diagonal lines), cross-hatch, solid roughness: 0=clean, 1=hand-drawn (default), 2=very sketchy

Arrow Binding (IMPORTANT)

Always use from/to bindings for arrows. The renderer auto-calculates edge intersection points — no manual coordinate math needed.

Simple arrow (straight, between two shapes)

{"type":"arrow","id":"a1","from":"box1","to":"box2","strokeColor":"#1e1e1e","strokeWidth":2,"roughness":1}

That's it. No x, y, or points needed. The renderer computes start/end at shape edges.

Multi-segment arrow (routed path with waypoints)

For arrows that need to go around obstacles, use absolutePoints with intermediate waypoints:

{
  "type":"arrow","id":"a2","from":"box3","to":"box1",
  "absolutePoints": true,
  "points": [[375,500],[30,500],[30,127],[60,127]],
  "strokeColor":"#1e1e1e","strokeWidth":2,"roughness":1
}

• First point = near source shape edge (will snap to actual edge)
• Last point = near target shape edge (will snap to actual edge)
• Middle points = absolute waypoint coordinates for routing

Arrow labels

Place a separate text element near the arrow midpoint:

{"type":"text","id":"label","x":215,"y":98,"width":85,"height":16,"text":"sends data","fontSize":10,"fontFamily":1,"strokeColor":"#868e96"}

Arrow styles

• "strokeStyle":"dashed" — dashed line
• "startArrowhead": true — bidirectional arrow

Template: Flowchart with Bindings

{
  "type": "excalidraw",
  "version": 2,
  "elements": [
    {"type":"rectangle","id":"start","x":150,"y":50,"width":180,"height":60,"strokeColor":"#1e1e1e","backgroundColor":"#b2f2bb","fillStyle":"hachure","strokeWidth":2,"roughness":1},
    {"type":"text","id":"t1","x":200,"y":65,"width":80,"height":30,"text":"Start","fontSize":20,"fontFamily":1,"strokeColor":"#1e1e1e"},

    {"type":"arrow","id":"a1","from":"start","to":"decision","strokeColor":"#1e1e1e","strokeWidth":2,"roughness":1},

    {"type":"diamond","id":"decision","x":140,"y":170,"width":200,"height":120,"strokeColor":"#1e1e1e","backgroundColor":"#ffec99","fillStyle":"hachure","strokeWidth":2,"roughness":1},
    {"type":"text","id":"t2","x":185,"y":215,"width":110,"height":30,"text":"Condition?","fontSize":18,"fontFamily":1,"strokeColor":"#1e1e1e","textAlign":"center"},

    {"type":"arrow","id":"a2","from":"decision","to":"process","strokeColor":"#1e1e1e","strokeWidth":2,"roughness":1},

    {"type":"rectangle","id":"process","x":150,"y":350,"width":180,"height":60,"strokeColor":"#1e1e1e","backgroundColor":"#a5d8ff","fillStyle":"hachure","strokeWidth":2,"roughness":1},
    {"type":"text","id":"t3","x":190,"y":365,"width":100,"height":30,"text":"Process","fontSize":20,"fontFamily":1,"strokeColor":"#1e1e1e"}
  ]
}

Layout Guidelines

• Node size: 140-200 × 50-70 px
• Diamond: 180-200 × 100-120 px (taller for text)
• Vertical spacing: 60-100 px between nodes
• Horizontal spacing: 80-120 px between nodes
• Text: Position inside shape manually (offset ~15-30px from top-left of shape)
• Arrow labels: Place as separate text elements near midpoint of arrow path

Color Palette

Fills: #a5d8ff (blue), #b2f2bb (green), #ffec99 (yellow), #ffc9c9 (red), #d0bfff (purple), #f3d9fa (pink), #fff4e6 (cream) Strokes: #1e1e1e (dark), #1971c2 (blue), #2f9e44 (green), #e8590c (orange), #862e9c (purple) Labels: #868e96 (gray, for annotations)

Tips

• Every element needs a unique id (required for binding!)
• Use from/to on arrows — don't calculate coordinates manually
• roughness:0 for clean diagrams, 1 for sketchy feel
• Text fontFamily:1 for hand-drawn, 3 for code
• Group related elements spatially, color-code by type
• For nested layouts, use a large background rectangle as a container