Excalidraw Render

Other

Create professional Excalidraw diagrams — flowcharts, architecture diagrams, workflows, systems, processes, or concepts. Use when user asks to "create a diagram", "draw a flowchart", "visualize a process", "make a flow diagram", "architecture diagram", "excalidraw", "technical diagram", or discusses workflow/process visualization. Supports quick DSL-based flowcharts and comprehensive hand-crafted JSON diagrams. Built-in PNG rendering and PDF export.

Install

openclaw skills install @scottgl9/excalidraw-render

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)

Need	Approach	Time
Simple flowchart, decision tree, linear process	Quick Path — CLI DSL	~1 min
Architecture, multi-zoom technical, evidence artifacts	Full Path — hand-crafted JSON	~10 min

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

Syntax	Shape	Use For
`[Label]`	Rectangle	Process steps
`{Label?}`	Diamond	Decisions
`(Label)`	Ellipse	Start/End
`[[Label]]`	Database	Data storage
`->`	Arrow	Connection
`-> "text" ->`	Labeled arrow	Conditional
`-->`	Dashed arrow	Optional path

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

Assess depth — simple/conceptual vs. comprehensive/technical
Research (technical diagrams) — look up real specs, event names, API formats
Map concepts to visual patterns — see Pattern Library below
Sketch mentally — trace how the eye moves through the diagram
Generate JSON section-by-section — see Large Diagram Strategy
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

Concept Behavior	Pattern
One source → many outputs	Fan-out (radial arrows from center)
Many inputs → one output	Convergence (arrows merging)
Hierarchy/nesting	Tree (lines + free-floating text)
Sequence of steps	Timeline (line + dots + labels)
Feedback loop	Spiral/Cycle (arrow returning to start)
Abstract state	Cloud (overlapping ellipses)
Transformation	Assembly line (before → process → after)
Comparison	Side-by-side (parallel structures)
Phase changes	Gap/Break (visual whitespace)

Shape Meaning

Concept	Shape
Labels, descriptions	Free-floating text (no container)
Timeline markers	Small ellipse (12px)
Start/trigger	Ellipse
End/output	Ellipse
Decision	Diamond
Process/action	Rectangle

Evidence Artifacts (Technical Diagrams)

Artifact	Rendering
Code snippets	Dark rect (`#1e293b`) + syntax-colored text
JSON/data	Dark rect (`#1e293b`) + green text (`#22c55e`)
Event sequences	Timeline (line + dots + labels)
UI mockups	Nested rectangles

Large Diagram Strategy

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

Create base file + first section
Add one section per edit — use descriptive IDs ("trigger_rect", "auth_arrow")
Namespace seeds by section (100xxx, 200xxx, etc.)
Update cross-section bindings as you go
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)

Render the PNG
View the image with the Read tool — actually look at it
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?
Fix the JSON for every issue found — widen containers, adjust x/y, add arrow waypoints, increase gaps
Re-render and re-view — look at the new PNG
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