Excalidraw

Excalidraw Diagram Generator

Generate hand-drawn Excalidraw diagrams and save them as .excalidraw files.

Workflow

1. Read colors.md from this skill directory to get the current color theme
2. Decide if the diagram benefits from icons (see Icons section below)
3. If yes, read icons.md from this skill directory for icon recipes
4. Plan the diagram: elements, layout, colors, labels, arrows, and icon placements
5. Spawn a subagent (Task tool, subagent_type: "general-purpose") with:
   • The full element format reference below
   • The colors from colors.md
   • Icon recipes from icons.md (if applicable)
   • A detailed description of the diagram to draw (element positions, labels, connections, colors, icon placements)
   • The output file path (ask the user or default to diagram.excalidraw in the current directory)
6. The subagent produces the JSON elements array and writes the .excalidraw file
7. Tell the user the output path — they can open it at excalidraw.com or in VS Code with the Excalidraw extension

Icons (Optional)

Include icons when:

• Architecture diagrams with distinct component types (frontend, API, database, cache, etc.)
• Nodes that would otherwise all look like identical rectangles
• The user explicitly asks for icons or visual distinction

Skip icons when:

• Simple flowcharts or sequence diagrams where shape/color already conveys meaning
• Wireframes or UI mockups
• Very small diagrams (fewer than 4 nodes)

When using icons, describe each icon placement in the subagent prompt: which icon type, where it goes (inline in a shape or standalone), and the base coordinates.

Subagent Prompt Template

Include everything between the --- markers in the subagent prompt:

You are an Excalidraw JSON generator. Your job is to produce a valid .excalidraw file.

Output Format

Write a JSON file with this envelope structure:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [ ... ],
  "appState": {
    "gridSize": null,
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

Element Format

Required Fields (all elements)

type, id (unique string), x, y, width, height

Defaults (skip these)

strokeColor="#1e1e1e", backgroundColor="transparent", fillStyle="solid", strokeWidth=2, roughness=1, opacity=100

Element Types

Rectangle: { "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }

• roundness: { "type": 3 } for rounded corners
• backgroundColor: "#a5d8ff", fillStyle: "solid" for filled

Ellipse: { "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }

Diamond: { "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }

Labeled shape (PREFERRED): Add label to any shape for auto-centered text. { "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80, "label": { "text": "Hello", "fontSize": 20 } }

• Works on rectangle, ellipse, diamond

Labeled arrow: "label": { "text": "connects" } on an arrow element.

Standalone text (titles, annotations only): { "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20 }

• x is the LEFT edge. To center at cx: set x = cx - (text.length × fontSize × 0.5) / 2

Arrow: { "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0, "points": [[0,0],[200,0]], "endArrowhead": "arrow" }

• points: [dx, dy] offsets from element x,y
• endArrowhead: null | "arrow" | "bar" | "dot" | "triangle"

Arrow Bindings

"startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] } fixedPoint: top=[0.5,0], bottom=[0.5,1], left=[0,0.5], right=[1,0.5]

Sizing Rules

Font sizes:

• Minimum fontSize: 16 for body text, labels
• Minimum fontSize: 20 for titles and headings
• Minimum fontSize: 14 for secondary annotations only (sparingly)
• NEVER use fontSize below 14

Element sizing:

• Minimum shape size: 120×60 for labeled rectangles/ellipses
• Leave 20-30px gaps between elements minimum
• Prefer fewer, larger elements over many tiny ones

Canvas layout:

• Plan layout to fit roughly 800×600 for standard diagrams
• Leave padding around edges (start content at x:50-100, y:50-100)

Drawing Order

• Array order = z-order (first = back, last = front)
• Background zones first, then shapes, then text/labels, then arrows
• Icons and decorative art/illustrations LAST

Group IDs (for icons)

• Each icon is made of multiple primitive elements that share a groupIds entry
• Convention: "groupIds": ["ico_{type}_{n}"] — e.g., ["ico_database_1"], ["ico_cloud_2"]
• All parts of one icon get the same groupId so they move/select together
• Icon parts use strokeWidth: 1 (thinner than normal shapes)

Rules

• Do NOT use emoji in text — they don't render in Excalidraw's Virgil font
• Make sure text is readable (never use same text color as background)
• Use colors consistently — one fill per semantic role
• Check that elements don't overlap unintentionally
• Arrow labels need space — keep labels short or make arrows wider
• Center titles relative to the diagram content

Quick Example

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    {"type":"rectangle","id":"b1","x":100,"y":100,"width":200,"height":100,"roundness":{"type":3},"backgroundColor":"#a5d8ff","fillStyle":"solid","label":{"text":"Start","fontSize":20}},
    {"type":"rectangle","id":"b2","x":450,"y":100,"width":200,"height":100,"roundness":{"type":3},"backgroundColor":"#b2f2bb","fillStyle":"solid","label":{"text":"End","fontSize":20}},
    {"type":"arrow","id":"a1","x":300,"y":150,"width":150,"height":0,"points":[[0,0],[150,0]],"endArrowhead":"arrow","startBinding":{"elementId":"b1","fixedPoint":[1,0.5]},"endBinding":{"elementId":"b2","fixedPoint":[0,0.5]}}
  ],
  "appState": {"gridSize":null,"viewBackgroundColor":"#ffffff"},
  "files": {}
}

After the format reference, append:

• The colors from colors.md
• The icon recipes from icons.md (if the diagram uses icons)
• Your detailed diagram description (including icon placements if applicable)
• The output file path
• "Write the .excalidraw file using the Write tool. Output ONLY the file — no explanation needed."

Full Examples

See reference.md in this skill directory for complete diagram examples (photosynthesis, storyboard, etc.). Include relevant examples in the subagent prompt when the user's request is similar.