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)#

NeedApproachTimeSimple flowchart, decision tree, linear processQuick Path — CLI DSL1 minArchitecture, multi-zoom technical, evidence artifactsFull Path — hand-crafted JSON10 min

---

Quick Path: CLI DSL Flowcharts#

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

bash

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#

SyntaxShapeUse For[Label]RectangleProcess steps{Label?}DiamondDecisions(Label)EllipseStart/End[[Label]]DatabaseData storage->ArrowConnection-> "text" ->Labeled arrowConditional-->Dashed arrowOptional path

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

DSL Example#

bash

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#

json

{
  "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 BehaviorPatternOne source → many outputsFan-out (radial arrows from center)Many inputs → one outputConvergence (arrows merging)Hierarchy/nestingTree (lines + free-floating text)Sequence of stepsTimeline (line + dots + labels)Feedback loopSpiral/Cycle (arrow returning to start)Abstract stateCloud (overlapping ellipses)TransformationAssembly line (before → process → after)ComparisonSide-by-side (parallel structures)Phase changesGap/Break (visual whitespace)

Shape Meaning#

ConceptShapeLabels, descriptionsFree-floating text (no container)Timeline markersSmall ellipse (12px)Start/triggerEllipseEnd/outputEllipseDecisionDiamondProcess/actionRectangle

Evidence Artifacts (Technical Diagrams)#

ArtifactRenderingCode snippetsDark rect ( #1e293b) + syntax-colored textJSON/dataDark rect ( #1e293b) + green text ( #22c55e)Event sequencesTimeline (line + dots + labels)UI mockupsNested rectangles

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#

bash

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#

bash

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):

bash

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:

bash

# 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:

bash

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