excalidraw

Excalidraw Diagram Generator

Generate Excalidraw diagrams programmatically using Python. Produces professional-looking, editable .excalidraw files instead of ASCII art.

Output format: .excalidraw JSON files that can be:

• Opened at https://excalidraw.com (drag and drop the file)
• Edited in VS Code with the Excalidraw extension
• Exported to SVG/PNG for embedding in documentation

Token cost note: Excalidraw JSON is verbose (4,000-22,000+ tokens per file). Delegate diagram generation to subagents when context is tight.

Quick Start

Method 1: Direct Python Script (Recommended)

Write a Python script using the generator library and run it:

#!/usr/bin/env python3
import sys, os
sys.path.insert(0, os.path.expanduser("~/.claude/plugins/duet/skills/excalidraw/scripts"))
from excalidraw_generator import Diagram, Flowchart, ArchitectureDiagram

# Create your diagram
d = Diagram()
box1 = d.box(100, 100, "Step 1", color="blue")
box2 = d.box(300, 100, "Step 2", color="green")
d.arrow_between(box1, box2, "next")
d.save("my_diagram.excalidraw")

Run with:

python3 /path/to/your_script.py

Method 2: Inline Python Execution

python3 -c "
import sys, os
sys.path.insert(0, os.path.expanduser('~/.claude/plugins/duet/skills/excalidraw/scripts'))
from excalidraw_generator import Diagram

d = Diagram()
a = d.box(100, 100, 'Hello', color='blue')
b = d.box(300, 100, 'World', color='green')
d.arrow_between(a, b)
d.save('hello.excalidraw')
print('Created: hello.excalidraw')
"

---

API Reference

Diagram Class

The base class for all diagrams.

from excalidraw_generator import Diagram

d = Diagram(background="#ffffff")  # white background

Methods

box(x, y, label, width=150, height=60, color="blue", shape="rectangle", font_size=18)

Create a labeled shape. Returns an Element for connecting.

• x, y: Position (top-left corner)
• label: Text to display
• color: "blue", "green", "red", "yellow", "orange", "violet", "cyan", "teal", "gray", "black"
• shape: "rectangle", "ellipse", "diamond"

box1 = d.box(100, 100, "Process A", color="blue")
box2 = d.box(100, 200, "Decision?", color="yellow", shape="diamond")

text_box(x, y, content, font_size=20, color="black")

Create standalone text.

d.text_box(100, 50, "System Architecture", font_size=28, color="black")

arrow_between(source, target, label=None, color="black", from_side="auto", to_side="auto")

Draw an arrow between two elements.

• from_side, to_side: "auto", "left", "right", "top", "bottom"

d.arrow_between(box1, box2, "sends data")
d.arrow_between(box1, box3, from_side="bottom", to_side="top")

line_between(source, target, color="black")

Draw a line (no arrowhead) between elements.

save(path)

Save the diagram. Extension .excalidraw added if not present.

d.save("output/my_diagram")  # Creates output/my_diagram.excalidraw

---

Flowchart Class

Specialized for flowcharts with automatic positioning.

from excalidraw_generator import Flowchart

fc = Flowchart(direction="vertical", spacing=80)

fc.start("Begin")
fc.process("p1", "Process Data")
fc.decision("d1", "Valid?")
fc.process("p2", "Save")
fc.end("Done")

fc.connect("__start__", "p1")
fc.connect("p1", "d1")
fc.connect("d1", "p2", label="Yes")
fc.connect("d1", "__end__", label="No")

fc.save("flowchart.excalidraw")

Methods

• start(label="Start") - Green ellipse
• end(label="End") - Red ellipse
• process(node_id, label, color="blue") - Blue rectangle
• decision(node_id, label, color="yellow") - Yellow diamond
• node(node_id, label, shape, color, width, height) - Generic node
• connect(from_id, to_id, label=None) - Arrow between nodes
• position_at(x, y) - Set position for next node

---

AutoLayoutFlowchart Class

For complex flowcharts with automatic hierarchical layout. Requires grandalf package (pip install grandalf).

from excalidraw_generator import AutoLayoutFlowchart, DiagramStyle, FlowchartStyle, LayoutConfig

fc = AutoLayoutFlowchart(
    diagram_style=DiagramStyle(roughness=0),
    flowchart_style=FlowchartStyle(decision_color="orange"),
    layout_config=LayoutConfig(vertical_spacing=100, horizontal_spacing=80)
)

fc.add_node("start", "Start", shape="ellipse", color="green", node_type="terminal")
fc.add_node("process1", "Validate Input", node_type="process")
fc.add_node("check", "Is Valid?", shape="diamond", color="yellow", node_type="decision")
fc.add_node("success", "Process Data", node_type="process")
fc.add_node("error", "Show Error", color="red", node_type="process")
fc.add_node("end", "End", shape="ellipse", color="red", node_type="terminal")

fc.add_edge("start", "process1")
fc.add_edge("process1", "check")
fc.add_edge("check", "success", label="Yes")
fc.add_edge("check", "error", label="No")
fc.add_edge("success", "end")
fc.add_edge("error", "process1", label="Retry")

result = fc.compute_layout(two_column=True, target_aspect_ratio=0.8)
fc.save("auto_flowchart.excalidraw")

---

ArchitectureDiagram Class

For system architecture diagrams.

from excalidraw_generator import ArchitectureDiagram

arch = ArchitectureDiagram()

arch.user("user", "User", x=100, y=200)
arch.component("frontend", "React App", x=250, y=200, color="blue")
arch.service("api", "API Gateway", x=450, y=200, color="violet")
arch.database("db", "PostgreSQL", x=650, y=200, color="green")

arch.connect("user", "frontend", "HTTPS")
arch.connect("frontend", "api", "REST")
arch.connect("api", "db", "SQL")

arch.save("architecture.excalidraw")

Methods

• component(id, label, x, y, width=150, height=80, color="blue")
• database(id, label, x, y, color="green") - Ellipse shape
• service(id, label, x, y, color="violet")
• user(id, label="User", x=100, y=100) - Gray ellipse
• connect(from_id, to_id, label=None, bidirectional=False)

---

Configuration & Styling

DiagramStyle - Global Appearance

from excalidraw_generator import Diagram, DiagramStyle

d = Diagram(diagram_style=DiagramStyle(
    roughness=0,              # 0=clean, 1=hand-drawn, 2=rough sketch
    stroke_style="solid",     # "solid", "dashed", "dotted"
    stroke_width=2,           # Line thickness (1-4)
    color_scheme="corporate"  # Named color scheme
))

Roughness levels:

• 0 - Architect: Clean, precise lines
• 1 - Artist: Normal hand-drawn look (default)
• 2 - Cartoonist: Rough, sketchy appearance

Color Schemes

d = Diagram(diagram_style=DiagramStyle(color_scheme="vibrant"))

primary = d.scheme_color("primary")
secondary = d.scheme_color("secondary")
accent = d.scheme_color("accent")
warning = d.scheme_color("warning")
danger = d.scheme_color("danger")
neutral = d.scheme_color("neutral")

Scheme	Primary	Secondary	Accent	Warning	Danger
default	blue	green	violet	yellow	red
monochrome	black	gray	gray	gray	black
corporate	blue	teal	violet	orange	red
vibrant	violet	cyan	orange	yellow	red
earth	teal	green	orange	yellow	red

Color Reference

Color	Stroke Hex	Use For
blue	#1971c2	Primary components
green	#2f9e44	Success, databases
red	#e03131	Errors, end states
yellow	#f08c00	Warnings, decisions
orange	#e8590c	Highlights
violet	#6741d9	Services
cyan	#0c8599	Network
teal	#099268	Secondary
gray	#868e96	Users, actors
black	#1e1e1e	Text, arrows

---

Complete Examples

Example 1: Simple Flow

import sys, os
sys.path.insert(0, os.path.expanduser("~/.claude/plugins/duet/skills/excalidraw/scripts"))
from excalidraw_generator import Diagram

d = Diagram()
d.text_box(200, 30, "Data Processing Pipeline", font_size=24)

input_box = d.box(100, 100, "Input", color="gray")
process = d.box(300, 100, "Process", color="blue")
output = d.box(500, 100, "Output", color="green")

d.arrow_between(input_box, process, "raw data")
d.arrow_between(process, output, "results")

d.save("pipeline.excalidraw")

Example 2: Decision Flowchart

import sys, os
sys.path.insert(0, os.path.expanduser("~/.claude/plugins/duet/skills/excalidraw/scripts"))
from excalidraw_generator import Flowchart

fc = Flowchart(direction="vertical", spacing=100)

fc.start("User Request")
fc.process("auth", "Authenticate")
fc.decision("valid", "Valid Token?")

fc.position_at(300, 340)
fc.process("proc", "Process Request")
fc.process("resp", "Return Response")

fc.position_at(100, 340)
fc.process("err", "Return 401")

fc.connect("__start__", "auth")
fc.connect("auth", "valid")
fc.connect("valid", "proc", "Yes")
fc.connect("valid", "err", "No")
fc.connect("proc", "resp")

fc.save("auth_flow.excalidraw")

Example 3: Microservices Architecture

import sys, os
sys.path.insert(0, os.path.expanduser("~/.claude/plugins/duet/skills/excalidraw/scripts"))
from excalidraw_generator import ArchitectureDiagram

arch = ArchitectureDiagram()

arch.user("client", "Client", x=400, y=50)
arch.service("gateway", "API Gateway", x=350, y=180, color="violet")

arch.service("auth", "Auth Service", x=100, y=350, color="blue")
arch.service("users", "User Service", x=300, y=350, color="blue")
arch.service("orders", "Order Service", x=500, y=350, color="blue")
arch.service("notify", "Notification", x=700, y=350, color="cyan")

arch.database("authdb", "Auth DB", x=100, y=500, color="green")
arch.database("userdb", "User DB", x=300, y=500, color="green")
arch.database("orderdb", "Order DB", x=500, y=500, color="green")

arch.component("queue", "Message Queue", x=600, y=450, color="orange")

arch.connect("client", "gateway", "HTTPS")
arch.connect("gateway", "auth", "gRPC")
arch.connect("gateway", "users", "gRPC")
arch.connect("gateway", "orders", "gRPC")
arch.connect("auth", "authdb", "SQL")
arch.connect("users", "userdb", "SQL")
arch.connect("orders", "orderdb", "SQL")
arch.connect("orders", "queue", "publish")
arch.connect("queue", "notify", "subscribe")

arch.save("microservices.excalidraw")

---

Viewing the Output

After generating a .excalidraw file:

1. Excalidraw.com: Go to https://excalidraw.com and drag the file onto the canvas
2. VS Code: Install the "Excalidraw" extension, then open the file
3. CLI: Use open filename.excalidraw on macOS

Exporting to PNG

# First time setup
cd ~/.claude/plugins/duet/skills/excalidraw/scripts
npm install
npx playwright install chromium

# Export
node ~/.claude/plugins/duet/skills/excalidraw/scripts/export_playwright.js diagram.excalidraw output.png

Tips

1. Positioning: Use a grid system. Start shapes at multiples of 50 or 100 for alignment
2. Spacing: Leave 50-100px between elements for clean arrows
3. Labels: Keep labels short (2-3 words). Use text boxes for longer descriptions
4. Colors: Use consistent colors for similar components (all databases green, all services blue)
5. Layout patterns:
   • Horizontal flow: x increases, y constant
   • Vertical flow: y increases, x constant
   • Grid: Combine both for complex diagrams
6. After generation: Open in Excalidraw to fine-tune positions and add hand-drawn elements

See Also

• /mermaid - For inline documentation diagrams that render natively on GitHub
• /design - Design thinking applies to diagram composition and layout
• /prose - Diagram labels benefit from the same concision rules as prose