Excalidraw

Excalidraw Diagram Generation

Generate .excalidraw JSON files that open directly in Excalidraw. These diagrams have a distinctive hand-drawn aesthetic.

Quick Start

Minimal valid file:

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

Workflow

1. Identify diagram type (flowchart, architecture, sequence, mind map, wireframe, org chart)
2. Plan element layout with consistent spacing (use 20px grid)
3. Generate elements with unique IDs and proper bindings
4. Write complete JSON to .excalidraw file

Element Patterns

Shape with Label

Always bind text to container bidirectionally:

// Rectangle
{
  "type": "rectangle",
  "id": "box_1",
  "x": 100, "y": 100, "width": 150, "height": 60,
  "backgroundColor": "#a5d8ff",
  "boundElements": [{ "id": "text_1", "type": "text" }],
  ...baseProps
}
// Bound text
{
  "type": "text",
  "id": "text_1",
  "containerId": "box_1",
  "textAlign": "center",
  "verticalAlign": "middle",
  ...textProps
}

Connected Arrow

Update both arrow and shapes:

// Arrow
{
  "type": "arrow",
  "id": "arrow_1",
  "points": [[0, 0], [150, 0]],
  "startBinding": { "elementId": "box_1", "fixedPoint": [1.0, 0.5001], "mode": "orbit" },
  "endBinding": { "elementId": "box_2", "fixedPoint": [0.0, 0.5001], "mode": "orbit" },
  "endArrowhead": "arrow",
  ...baseProps
}
// Both shapes need boundElements updated
"boundElements": [{ "id": "arrow_1", "type": "arrow" }]

Diagram-Specific Patterns

Flowchart: Ellipse (start/end), Rectangle (process), Diamond (decision), vertical flow with 70px gaps

Sequence Diagram: Rectangles (actors) at top, dashed vertical lines (lifelines), horizontal arrows (messages)

Architecture: Rectangles with rounded corners, group related components, use frames for boundaries

Mind Map: Central ellipse, radiating lines to topic rectangles, organic layout

Org Chart: Rectangles with hierarchy, lines (not arrows) for connections

Wireframe: Rectangles for UI sections, text placeholders, simple shapes for buttons/forms

Critical Rules

1. Bidirectional bindings - When arrow connects to shape, update BOTH:

   • Arrow's startBinding/endBinding
   • Shape's boundElements array

2. fixedPoint precision - Use 0.5001 not 0.5 to avoid floating point issues

3. Unique IDs - Every element needs unique id

4. Calculate width/height for lines/arrows from points array

5. Required base properties for every element:

   id, type, x, y, width, height, angle, strokeColor, backgroundColor,
   fillStyle, strokeWidth, strokeStyle, roughness, opacity, roundness,
   seed, version, versionNonce, isDeleted, updated, groupIds, frameId,
   boundElements, link, locked, index
   

Common Values

Colors:

• Stroke: #1e1e1e (black), #e03131 (red), #2f9e44 (green), #1971c2 (blue)
• Background: #a5d8ff (blue), #b2f2bb (green), #ffec99 (yellow), #ffc9c9 (red), #d0bfff (purple)

Defaults:

• strokeWidth: 2
• roughness: 1 (hand-drawn), 0 (smooth for text)
• opacity: 100
• fontFamily: 5 (Excalifont)
• fontSize: 20
• seed: any random integer
• version: 1, versionNonce: 0
• index: "a0", "a1", "a2"...

Element Types

When to Use Excalidraw

• Hand-drawn aesthetic desired
• Interactive diagram editing needed
• Whiteboard-style brainstorming
• Presentations and documentation with visual appeal
• When visual style matters more than precision
• Team collaboration on diagrams

Reference

See references/format-spec.md for complete element schemas, all property values, and detailed examples.