name: excalidraw
description: Create Excalidraw diagrams as JSON files for flowcharts, user journeys, system architectures, wireframes, and visual documentation. Use when the user asks to create diagrams, flowcharts, visual representations, architecture diagrams, mind maps, or any Excalidraw-compatible visualizations. Outputs .excalidraw.json files that can be opened in excalidraw.com or any Excalidraw-compatible app.

Excalidraw Diagram Generator

Create Excalidraw-compatible JSON diagrams. Output .excalidraw.json files.

JSON Schema

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

Coordinate System

• Origin: Top-left corner (0, 0)
• X-axis: Increases rightward
• Y-axis: Increases downward
• Unit: Pixels

Grid-Based Layout System

Use a 20px grid for alignment. Standard positions:

GRID_UNIT = 20
COLUMN_WIDTH = 200    # Element + gap
ROW_HEIGHT = 150      # Element + gap

Position formula:
  x = START_X + (column * COLUMN_WIDTH)
  y = START_Y + (row * ROW_HEIGHT)

Recommended START_X = 50, START_Y = 100

Standard Element Sizes

Text Centering Formula

CRITICAL: To center text inside a shape:

text_x = shape_x + (shape_width - text_width) / 2
text_y = shape_y + (shape_height - text_height) / 2

Text Size Reference

Estimate text_width: char_count * char_width
Estimate text_height: line_count * line_height

Centering Example

Shape: x=100, y=100, width=160, height=80
Text: "Process" (7 chars), fontSize=16

text_width = 7 * 9 = 63
text_height = 1 * 20 = 20
text_x = 100 + (160 - 63) / 2 = 148.5 ≈ 148
text_y = 100 + (80 - 20) / 2 = 130

Element Types

Common Properties (required for all)

{
  "id": "unique-id",
  "type": "rectangle",
  "x": 100,
  "y": 100,
  "width": 160,
  "height": 80,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "roughness": 1,
  "opacity": 100,
  "angle": 0,
  "seed": 100,
  "version": 1,
  "isDeleted": false,
  "boundElements": null,
  "link": null,
  "locked": false
}

Type-Specific Properties

Rectangle: Add "roundness": {"type": 3} for rounded corners

Text:

{
  "type": "text",
  "text": "Content\nLine 2",
  "fontSize": 16,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "middle"
}

• fontFamily: 1=Virgil (hand), 2=Helvetica, 3=Cascadia (mono)

Arrow/Line:

{
  "type": "arrow",
  "points": [[0, 0], [100, 0]],
  "startArrowhead": null,
  "endArrowhead": "arrow"
}

• Points are relative to element's x,y
• Arrowheads: null, "arrow", "bar", "dot", "triangle"

Arrow Positioning

Horizontal Arrow (Left to Right)

From shape at (x1, y1, w1, h1) to shape at (x2, y2, w2, h2):

arrow_x = x1 + w1           # Right edge of source
arrow_y = y1 + h1/2         # Vertical center
gap = x2 - (x1 + w1)        # Space between shapes
points = [[0, 0], [gap, 0]]

Vertical Arrow (Top to Bottom)

arrow_x = x1 + w1/2         # Horizontal center
arrow_y = y1 + h1           # Bottom edge of source
gap = y2 - (y1 + h1)
points = [[0, 0], [0, gap]]

Diagonal/Curved Arrow

points = [[0, 0], [dx/2, dy], [dx, dy]]  # Curved path

Color Palette

Z-Order (Element Array Order)

Elements render in array order. First = back, last = front.

Correct order:
1. Background shapes (containers, frames)
2. Connection lines/arrows
3. Foreground shapes (nodes, boxes)
4. Text labels
5. Icons/overlays

Layout Patterns

Horizontal Flow (Left to Right)

COL_GAP = 60  # Gap between elements

Element 1: x=50,  y=100, w=160, h=80
Arrow 1:   x=210, y=140, points=[[0,0],[60,0]]
Element 2: x=270, y=100, w=160, h=80
Arrow 2:   x=430, y=140, points=[[0,0],[60,0]]
Element 3: x=490, y=100, w=160, h=80

Vertical Flow (Top to Bottom)

ROW_GAP = 50

Element 1: x=100, y=50,  w=160, h=80
Arrow 1:   x=180, y=130, points=[[0,0],[0,50]]
Element 2: x=100, y=180, w=160, h=80

Decision Branch (Diamond)

Diamond:    x=300, y=200, w=100, h=100
Center:     (350, 250)

Yes path (up-right):
  arrow_x=350, arrow_y=200
  points=[[0,0], [0,-50], [100,-50]]

No path (down-right):
  arrow_x=350, arrow_y=300
  points=[[0,0], [0,50], [100,50]]

Feedback Loop (Return Arrow)

From bottom-right back to left:
  Start: (800, 400)
  points=[
    [0, 0],        # Start
    [0, 80],       # Down
    [-400, 80],    # Left
    [-400, -150]   # Up to target
  ]

Complete Node Example

[
  {
    "id": "node1-box",
    "type": "rectangle",
    "x": 100, "y": 100, "width": 160, "height": 80,
    "strokeColor": "#1971c2",
    "backgroundColor": "#a5d8ff",
    "fillStyle": "solid",
    "strokeWidth": 2,
    "roughness": 1,
    "opacity": 100,
    "angle": 0,
    "seed": 100,
    "version": 1,
    "isDeleted": false,
    "boundElements": [{"id": "arrow1", "type": "arrow"}],
    "roundness": {"type": 3},
    "link": null,
    "locked": false
  },
  {
    "id": "node1-text",
    "type": "text",
    "x": 130, "y": 130,
    "width": 100, "height": 20,
    "text": "Process Step",
    "fontSize": 16,
    "fontFamily": 1,
    "textAlign": "center",
    "verticalAlign": "middle",
    "strokeColor": "#1e1e1e",
    "backgroundColor": "transparent",
    "fillStyle": "solid",
    "strokeWidth": 1,
    "roughness": 1,
    "opacity": 100,
    "angle": 0,
    "seed": 101,
    "version": 1,
    "isDeleted": false,
    "boundElements": null,
    "link": null,
    "locked": false
  }
]

Positioning Checklist

Before generating:
1. ☐ Define grid: START_X, START_Y, COLUMN_WIDTH, ROW_HEIGHT
2. ☐ List all elements with row/column positions
3. ☐ Calculate exact x,y using formulas
4. ☐ Calculate text positions using centering formula
5. ☐ Calculate arrow start points and relative endpoints
6. ☐ Order elements correctly for z-order
7. ☐ Assign unique IDs and incrementing seeds

Templates

• Basic flowchart: assets/flowchart-template.excalidraw.json
• Processing loop: references/processing-loop-template.md
• Element specs: references/elements.md

Output

1. Save as .excalidraw.json
2. Copy to /mnt/user-data/outputs/
3. Tell user: "Open at excalidraw.com → Menu → Open"