Excalidraw Diagram Generator

Create complete, valid .excalidraw.json files that users can directly open at excalidraw.com.

Core Capabilities

Diagram types supported:

Flowcharts - Process flows, decision trees, workflows
Architecture Diagrams - System architectures, network topologies, component diagrams
UML Diagrams - Class diagrams, sequence diagrams, use case diagrams
Mind Maps - Hierarchical concept maps, brainstorming diagrams

Two visual styles:

Professional Mode (default): Clean, polished diagrams for technical documentation
Hand-drawn Mode: Sketch-style diagrams for brainstorming and informal use

Quick Reference

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:

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

Element	Width	Height	Use Case
Small box	120	60	Labels, simple steps
Standard box	160	80	Process steps
Large box	200	100	Detailed nodes
Wide box	240	80	Long text
Diamond	100	100	Decision points
Circle	80	80	Start/End nodes

Text Calculations (CRITICAL)

Text Height Formula

textHeight = fontSize × lineHeight × numberOfLines
           = fontSize × 1.25 × numberOfLines

Examples:
- 1 line, fontSize 20: 20 × 1.25 × 1 = 25px
- 3 lines, fontSize 14: 14 × 1.25 × 3 = 52.5px ≈ 53px
- 12 lines, fontSize 15: 15 × 1.25 × 12 = 225px

Text Centering Formula

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

Text Size Reference

Font Size	Char Width	Line Height	Use
11	~6px	15px	Labels, annotations
12	~7px	16px	Secondary text
14	~8px	18px	Body text
16	~9px	20px	Primary text
18	~10px	24px	Headings
20	~11px	26px	Titles
28	~16px	35px	Icons/Emoji

Estimate text_width: char_count × char_width

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

UML Class Diagram Container Height

containerHeight = headerHeight + attributesHeight + methodsHeight + padding

Where:
- headerHeight = classNameTextHeight + topPadding (typically 15px + 15px = 30px)
- attributesHeight = fontSize × 1.25 × numberOfAttributes + 10px
- methodsHeight = fontSize × 1.25 × numberOfMethods + 10px

Example (12 attributes, 10 methods, fontSize 15):
- Header: 20 + 15 = 35px
- Attributes: 15 × 1.25 × 12 + 10 = 235px
- Methods: 15 × 1.25 × 10 + 10 ≈ 198px
- Total: 35 + 10 + 235 + 10 + 198 = 488px (round to 500px)

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]]

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
  ]

Z-Order (Element Array Order)

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

Correct order:

Background shapes (containers, frames)
Connection lines/arrows
Foreground shapes (nodes, boxes)
Text labels
Icons/overlays

Visual Styles

Professional Mode (Default)

Use for: Architecture diagrams, UML, technical docs, formal presentations

{
  "roughness": 0,
  "fillStyle": "solid",
  "strokeWidth": 2,
  "fontFamily": 2
}

Colors (light backgrounds for readability):

Purpose	Background
Primary	`#e7f5ff`
Success	`#ebfbee`
Warning	`#fff9db`
Accent	`#f3f0ff`
Secondary	`#fff4e6`

Hand-drawn Mode

Use for: Brainstorming, sketches, informal sharing

{
  "roughness": 1,
  "fillStyle": "hachure",
  "strokeWidth": 2,
  "fontFamily": 1
}

Colors (medium saturation):

Purpose	Background
Primary	`#a5d8ff`
Success	`#b2f2bb`
Warning	`#ffec99`
Error	`#ffc9c9`
Accent	`#d0bfff`
Secondary	`#ffd8a8`

Stroke color: #1e1e1e (dark gray, softer than pure black)

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"

Workflow

Step 1: Identify Diagram Type

Match the request to a diagram type:

Flowchart: Process flows, algorithms, decision trees, workflows
Architecture: System designs, microservices, cloud infrastructure
UML Class: Object-oriented design, class hierarchies, relationships
Mind Map: Brainstorming, concept hierarchies, topic exploration

Step 2: Use Templates as Foundation

Templates in assets/:

flowchart-template.json
architecture-template.json
uml-class-template.json
mindmap-template.json

Usage:

Read the appropriate template
Modify IDs, text, positions, colors
Add/remove elements as needed
Ensure all IDs are unique

Step 3: Generate Elements

Key element types:

rectangle - Boxes, containers, processes
ellipse - Start/end nodes, databases
diamond - Decisions, conditional branches
arrow / line - Connections, flows
text - Labels, descriptions

Step 4: Calculate Layout

Use the grid system and text centering formulas above.

Layout strategies:

Flowcharts: Top-to-bottom, centered alignment
Architecture: Left-to-right for flow, grouped by layer
UML Class: Use container height formula; prevent text overflow
Mind Maps: Radial from center, balanced branches

Step 5: Style and Polish

Choose visual style (Professional or Hand-drawn)
Apply consistent colors from the palette
Ensure adequate spacing (80-100px between elements)

Step 6: Save to File

Always save directly as .excalidraw.json (no code blocks).

Write complete JSON to file
Name descriptively (e.g., user-login-flow.excalidraw.json)
Save to current directory unless specified otherwise

After saving, provide:

Confirmation with file path
Brief description of diagram structure
Instructions: "Open at excalidraw.com → Menu → Open"

Common Patterns

Pattern 1: Sequential Flow

For A → B → C processes:

Place elements vertically with 120px gaps
Use rectangles for processes, ellipses for start/end
Connect with arrows (endArrowhead: "arrow")
Center-align all elements

Pattern 2: Decision Tree

For conditional branches:

Use diamond for decision nodes
Branch arrows left/right or up/down
Add text labels on arrows ("Yes", "No")
Rejoin paths when appropriate

Pattern 3: Hierarchical Structure

For layered architectures:

Group elements by layer (horizontal rows)
Use different colors per layer
Vertical arrows show dependencies
Consistent element sizes within layers

Pattern 4: Radial Mind Map

For concept exploration:

Central node (ellipse) in middle
Lines radiate outward
Different colors per branch
Rectangles for sub-topics

Positioning Checklist

Before generating:

Define grid: START_X, START_Y, COLUMN_WIDTH, ROW_HEIGHT
List all elements with row/column positions
Calculate exact x,y using formulas
Calculate text positions using centering formula
Calculate arrow start points and relative endpoints
Order elements correctly for z-order
Assign unique IDs and incrementing seeds

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
  }
]

Tips for Quality Diagrams

Unique IDs: Generate random 8-16 character IDs for each element
Consistent spacing: Follow spacing guidelines strictly
Color harmony: Use the recommended color palette
Text sizing: Match text width to container width with padding
Arrow connections: Position arrow start/end points precisely
Version numbers: Use random integers for versionNonce and seed

Handling Complex Requests

For large or complex diagrams:

Start simple: Create core structure first
Iterate: Add details progressively
Group logically: Use visual grouping (colors, spacing)
Limit complexity: Suggest breaking into multiple diagrams if needed
Maintain readability: Ensure text doesn't overlap, adequate spacing

Resources

assets/

Templates for common diagram types:

flowchart-template.json
architecture-template.json
uml-class-template.json
mindmap-template.json

references/

excalidraw-format.md - Complete JSON format specification
elements.md - Element types and properties
processing-loop-template.md - Processing loop example

excalidraw-generator