Excalidraw Diagram Generation

Workflow

1. Write excalidraw JSON to <name>.excalidraw
2. Render: uv run python -m excalidraw <name>.excalidraw -o <name>.png
3. For multiple diagrams, use: uv run python -m excalidraw --batch *.excalidraw --outdir rendered/

File Structure

{
  "type": "excalidraw",
  "version": 2,
  "source": "claude",
  "elements": [...],
  "appState": {
    "viewBackgroundColor": "#ffffff"
  }
}

Available Shapes

• rectangle, ellipse, diamond, line, arrow, freedraw, text

Shape Properties

{
  "id": "unique_id",
  "type": "rectangle",
  "x": 100,
  "y": 100,
  "width": 150,
  "height": 80,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "#a5d8ff",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 0
}

Text Elements

{
  "id": "label1",
  "type": "text",
  "x": 110,
  "y": 110,
  "width": 130,
  "height": 60,
  "text": "Multi-line\ntext here",
  "fontSize": 16,
  "fontFamily": 5,
  "textAlign": "center",
  "strokeColor": "#1e1e1e"
}

fontFamily: 1=hand-drawn, 2=normal, 5=monospace (use for technical diagrams)

Arrow/Line Elements

{
  "id": "arrow1",
  "type": "arrow",
  "x": 100,
  "y": 100,
  "width": 0,
  "height": 50,
  "strokeColor": "#1971c2",
  "strokeWidth": 2,
  "roughness": 0,
  "points": [[0, 0], [0, 50]]
}

Dashed Frames

{
  "id": "frame1",
  "type": "rectangle",
  "strokeColor": "#2f9e44",
  "backgroundColor": "transparent",
  "strokeStyle": "dashed",
  "roughness": 0
}

Color Palette

Spacing Guidelines

• Title fontSize: 28-36
• Section headers: 20-24
• Body text: 12-16
• Minimum padding inside boxes: 10px
• Gap between sections: 20-30px
• Dashed frame padding: 20px inside content

Arrow Labeling Rules

1. Arrows point AT things, not along them - perpendicular to target
2. Arrow tip touches the target
3. Text and arrow must not overlap

Iteration Log

1. fontFamily: Use 5 (monospace) for technical diagrams, not 1 (hand-drawn).
2. Text in shapes: Create separate text elements inside boxes for reliable rendering.
3. roughness: Set to 0 for clean technical diagrams.
4. Unsupported types: The renderer now fails explicitly on unsupported element types instead of dropping them silently.