Excalidraw

Excalidraw Diagrams

Overview

Generate .excalidraw JSON files and export to PNG/SVG.

Two export options:

• Kroki API (curl) — zero install, SVG output only
• excalidraw-brute-export-cli — local Firefox-based, PNG + SVG

Supported formats: PNG (local CLI only), SVG (both options). PDF is NOT supported.

When to Use

Explicit triggers: user says "画图", "diagram", "visualize", "flowchart", "draw", "架构图", "流程图"

Proactive triggers:

• Explaining a system with 3+ interacting components
• Describing a multi-step process or decision tree
• Comparing architectures or approaches side by side

Skip when: a simple list or table suffices, or user is in a quick Q&A flow

When NOT to use it — route elsewhere:

• Polished, precise diagrams, strict UML, or branded vendor icons → drawio.
• Diagrams-as-code in git, auto-laid-out from text → mermaid (general) or plantuml (UML).
• An infinite-canvas whiteboard or programmatic freehand strokes → tldraw.

Prerequisites

Option A: Kroki API (recommended — zero install, SVG only)

# Just needs curl (pre-installed on macOS/Linux/Windows Git Bash)
curl --version

No additional setup. SVG rendered via https://kroki.io.

Option B: Local CLI (required for PNG)

The CLI uses Firefox (not Chromium). Check and install:

npm install -g excalidraw-brute-export-cli
npx playwright install firefox

macOS patch (one-time, required):

CLI_MAIN=$(npm root -g)/excalidraw-brute-export-cli/src/main.js
sed -i '' 's/keyboard.press("Control+O")/keyboard.press("Meta+O")/' "$CLI_MAIN"
sed -i '' 's/keyboard.press("Control+Shift+E")/keyboard.press("Meta+Shift+E")/' "$CLI_MAIN"

Windows/Linux: No patch needed.

Workflow

1. Check deps — use Kroki (curl) for SVG; use local CLI for PNG
2. Plan — pick the visual metaphor (see Relationship-to-layout map), then the diagram type and color palette
3. Generate — write .excalidraw JSON file (section-by-section for large diagrams)
4. Export — run Kroki or CLI command
5. Verify the render — view the exported PNG, fix any defects, re-export (see Verify the Render)
6. Review loop — show the image to the user, apply the minimal .excalidraw edit per request, re-export until approved (see Review Loop)
7. Report — tell user the output file path

Design Principles

Default style

• roughness: 0 — clean, modern look for all technical diagrams (use 1 only when user requests hand-drawn/casual style)
• fontFamily: 2 (Helvetica) — professional look; use 1 (Virgil) only for casual/sketch style, 3 (Cascadia) for code snippets
• fillStyle: "solid" — default fill

Containers: prefer typography over boxes

A box around every label makes a diagram look like a wireframe. The cleanest Excalidraw diagrams use free-floating text and lines for structure and reserve filled boxes for things that are genuinely components.

• Default to no container — use a standalone text element unless the box earns its place.
• Add a box only when the element is a real system component, an arrow binds to it, the shape itself carries meaning (decision diamond, start/end ellipse), or it groups a zone.
• Aim for under ~30% of text elements inside boxes.
• For timelines, trees, and hierarchies, use a line/connector + free-floating labels, not a stack of rectangles. Size, weight, and color create hierarchy without boxes.

Font size hierarchy

Color palette

Follow the 60-30-10 rule: 60% whitespace/neutral, 30% primary accent, 10% highlight.

Semantic fill colors (use with strokeColor one shade darker):

Text colors:

Rule: Do not invent new colors. Pick from this palette.

Arrow semantics

Excalidraw JSON Structure

File skeleton

{
  "type": "excalidraw",
  "version": 2,
  "source": "claude-code",
  "elements": [],
  "appState": { "viewBackgroundColor": "#ffffff" }
}

Element types

image, frame, and embeddable are not covered by this skill: image needs a separate files map plus a fileId, and frames/embeds render inconsistently through the export path. Stick to the six types above — and for ready-made icons built from these primitives, see Community shape & icon libraries below.

Community shape & icon libraries

Need a real AWS / Azure / GCP / network / UML / BPMN icon instead of a plain box? The Excalidraw community libraries (200+ .excalidrawlib files) are built almost entirely from the same vector primitives above — so their items render through Kroki and the local CLI with no image element and no files map. Use the helper in scripts/excalidraw_lib.py:

# 1. Find a library (matches name / description / item names)
python scripts/excalidraw_lib.py search aws

# 2. List its items (index, name, element count; flags any image-based item)
python scripts/excalidraw_lib.py items slobodan/aws-serverless.excalidrawlib

# 3. Build your base scene first, then drop an item in at (x, y). IDs are
#    namespaced and coordinates translated, so it merges without collisions:
python scripts/excalidraw_lib.py merge scene.excalidraw \
    slobodan/aws-serverless.excalidrawlib 0 455 257 --scale 0.9 --prefix lambda

Rules:

• Vector only. merge refuses any item containing an image element (won't render via the export path); items flags them up front.
• Use sparingly. An icon is just a labeled node — keep the design system's spacing, labels, and arrow semantics. Icons accent a diagram; they don't replace it.
• Arrows don't bind to library groups — draw connectors with explicit edge-to-edge points (bindings don't affect the static export anyway).
• Libraries are MIT-licensed; a courtesy credit is welcome, not required.
• Still run Verify the Render afterward — icon bounding boxes vary, so check alignment and spacing.

Element sizing

Calculate element width from label text to prevent truncation:

Latin text:  width = max(160, charCount * 9)
CJK text:   width = max(160, charCount * 18)
Mixed text:  estimate each character individually, sum up