Excalidraw Diagram Creator

Generate .excalidraw files — from quick flowcharts to comprehensive technical diagrams.

⚠️ Golden Rule

Every diagram MUST be rendered to PNG and visually inspected before delivery. Look at the actual image — check that text fits inside boxes, no elements overlap, arrows connect correctly, and spacing is balanced. Fix the JSON and re-render until it looks professional. See the Render & Validate section. No exceptions.

Depth Gate (Do This First)

Quick Path: CLI DSL Flowcharts

For straightforward flows, use @swiftlysingh/excalidraw-cli (installed locally by setup.sh):

excalidraw-cli create --inline "DSL" -o output.excalidraw

> Note: If excalidraw-cli is not in your PATH after setup, use:

> "$SKILL_DIR/.npm/node_modules/.bin/excalidraw-cli" or re-run setup.sh.

DSL Syntax

Directives: @direction LR|TB|RL|BT, @spacing 60

DSL Example

excalidraw-cli create --inline "$(cat <<'EOF'
@direction TB
(Start) -> [Receive Request] -> {Authenticated?}
{Authenticated?} -> "yes" -> [Process Request] -> (Success)
{Authenticated?} -> "no" -> [Return 401] -> (End)
EOF
)" -o auth-flow.excalidraw

CLI options: -d LR (direction), -s 80 (spacing), --format dot (DOT/Graphviz input).

After generation, always render and validate (see Render section below). Fix overlaps or clipping in the JSON if needed.

Full Path: Hand-Crafted JSON Diagrams

For comprehensive, professional diagrams. Read these references as needed:

• references/color-palette.md — All colors (read FIRST, every time)
• references/element-templates.md — Copy-paste JSON for each element type
• references/json-schema.md — Full property reference
• references/layout-rules.md — Anti-overlap spacing and text-sizing rules ⚠️ READ THIS

Design Process

1. Assess depth — simple/conceptual vs. comprehensive/technical
2. Research (technical diagrams) — look up real specs, event names, API formats
3. Map concepts to visual patterns — see Pattern Library below
4. Sketch mentally — trace how the eye moves through the diagram
5. Generate JSON section-by-section — see Large Diagram Strategy
6. Render & validate — MANDATORY loop (see below)

JSON Structure

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

Core Rules

• fontFamily: 3, roughness: 0, opacity: 100 on all elements
• text property = ONLY readable words (no markup)
• Size containers to fit text — see references/layout-rules.md
• Minimum 40px gap between elements — see references/layout-rules.md
• Default to free-floating text; use containers only when meaningful (<30% text in boxes)

Visual Pattern Library

Shape Meaning

Evidence Artifacts (Technical Diagrams)

Large Diagram Strategy

Build JSON one section at a time (Claude has ~32k token output limit):

1. Create base file + first section
2. Add one section per edit — use descriptive IDs ("trigger_rect", "auth_arrow")
3. Namespace seeds by section (100xxx, 200xxx, etc.)
4. Update cross-section bindings as you go
5. Review the whole before rendering

Multi-Zoom (Comprehensive Diagrams)

• Level 1 — Summary flow (simplified overview)
• Level 2 — Section boundaries (labeled regions)
• Level 3 — Detail (evidence artifacts, code snippets, real data)

Render & Validate (MANDATORY)

Every diagram must be rendered and visually inspected before delivery. This catches overlap, text clipping, and spacing issues that are invisible in JSON.

Render Command

cd ~/.openclaw/skills/excalidraw-diagram && uv run python render_excalidraw.py <path-to-file.excalidraw>

Outputs a PNG next to the .excalidraw file. Use the Read tool to view it.

First-Time Setup

cd ~/.openclaw/skills/excalidraw-diagram
bash setup.sh                              # builds local Excalidraw bundle (requires node/npm)
uv sync && uv run playwright install chromium

The Loop (repeat until professional)

1. Render the PNG
2. View the image with the Read tool — actually look at it
3. Inspect systematically:
• Does every label fit cleanly inside its box? (no clipping, no overflow)
• Are all boxes/shapes clearly separated? (no overlapping edges)
• Are arrows connecting the right elements without crossing through others?
• Is spacing even and consistent between similar elements?
• Is text large enough to read?
• Does the overall layout look balanced and professional?
4. Fix the JSON for every issue found — widen containers, adjust x/y, add arrow waypoints, increase gaps
5. Re-render and re-view — look at the new PNG
6. Repeat until every issue is resolved (typically 2-4 iterations, sometimes more)

Do not skip this loop. JSON coordinates are approximate — you will almost always find issues on the first render. The visual check IS the quality gate.

Stop When

• No text overflow or overlapping
• Arrows route cleanly
• Consistent spacing, balanced composition
• You'd show it without caveats

PNG & PDF Export

PNG (for Word, presentations, sharing)

The render script outputs high-res PNG (2x scale by default):

cd ~/.openclaw/skills/excalidraw-diagram && uv run python render_excalidraw.py diagram.excalidraw --output diagram.png --scale 3

Options: --scale 3 (3x for print), --width 2560 (wider viewport).

PDF (for documents, printing)

Convert PNG to PDF:

# ImageMagick (most common)
convert diagram.png -density 150 diagram.pdf

# Or with a white background and margins
convert diagram.png -gravity center -background white -extent 110%x110% -density 150 diagram.pdf

For multi-page or A4/Letter sizing:

convert diagram.png -resize 1800x -gravity center -background white \
  -extent 2100x2970 -units PixelsPerInch -density 254 diagram-a4.pdf

Quality Checklist

Layout & Overlap

• [ ] All text fits within containers (used layout-rules.md sizing formula)
• [ ] Minimum 40px gap between all elements
• [ ] Arrows don't cross through elements
• [ ] Even spacing between similar elements
• [ ] Balanced composition (no voids or overcrowding)

Visual

• [ ] roughness: 0, opacity: 100, fontFamily: 3 everywhere
• [ ] Colors from references/color-palette.md
• [ ] Text readable at export size
• [ ] Clear visual flow (eye path)

Technical (if applicable)

• [ ] Real specs/event names/API formats (not placeholders)
• [ ] Evidence artifacts included
• [ ] Multi-zoom levels present

Export

• [ ] Rendered to PNG and visually validated
• [ ] PNG/PDF delivered if user needs it