Excalidraw Export

Generate Excalidraw diagrams from natural language and export them as PNG/SVG images, end-to-end.

Language

Match user's language: Respond in the same language the user uses.

End-to-End Workflow

Progress:

• Step 1: Understand the request
• Step 2: Generate .excalidraw JSON
• Step 3: Export to PNG/SVG
• Step 4: Deliver result

Prerequisites

On first use, run the setup script to check dependencies:

bash <SKILL_DIR>/scripts/setup.sh

Required:

• Python 3.8+
• resvg (brew install resvg) — fast SVG-to-PNG rasterizer
• fonttools + brotli (pip install fonttools brotli) — extracts embedded hand-drawn fonts from SVG and converts <text> to <path>, preserving Excalifont + Xiaolai without a browser
• Internet access (uses kroki.io for rendering)

Optional fallback:

• Google Chrome — used as fallback if resvg/fonttools unavailable

If only SVG output is needed, no extra tools are required.

Run preflight to verify all dependencies programmatically:

python3 <SKILL_DIR>/scripts/export.py --preflight

Step 1: Understand the Request

Determine:

1. Diagram type: flowchart, relationship, mind map, architecture, sequence, ER, class, swimlane, data flow
2. Key elements: entities, steps, concepts
3. Relationships: flow direction, connections, hierarchy

Step 2: Generate .excalidraw JSON

Create a valid .excalidraw file following the schema. Read the reference docs for details:

• Read <SKILL_DIR>/references/excalidraw-schema.md for the JSON schema
• Read <SKILL_DIR>/references/element-types.md for element specifications

Critical rules:

• All text elements MUST use fontFamily: 5 (Excalifont) for the hand-drawn style. This is excalidraw's current default font. kroki.io will auto-embed Excalifont (hand-drawn Latin) + Xiaolai (hand-drawn CJK) as woff2. The export script extracts these glyphs and converts <text> to <path>, so resvg renders the hand-drawn fonts perfectly without a browser.
• fontFamily: 1 (Virgil) is deprecated — kroki will NOT embed Xiaolai for it, causing CJK to fall back to system fonts
• Only use fontFamily: 3 (Cascadia) for code identifiers / monospace text
• All IDs must be unique
• Keep element count under 20 for clarity
• Use consistent spacing: 200-300px horizontal, 100-150px vertical

Color palette:

File structure:

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

Save the file as <descriptive-name>.excalidraw.

Step 3: Export to PNG/SVG

Run the export script to convert the .excalidraw file to an image:

# Export to PNG (default, 2x resolution for retina)
python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw

# Export to SVG
python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw -f svg

# Export both PNG and SVG
python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw -f png -f svg

# Custom output path
python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw -o output.png

# Higher resolution (3x)
python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw --scale 3

# Dark theme
python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw --dark

Step 4: Deliver Result

Always provide:

1. The exported image file (PNG or SVG)
2. The source .excalidraw file (for future editing)
3. Brief summary of what was created

Example delivery:

Created: system-architecture.png (86 KB)
Source:  system-architecture.excalidraw
Type:    Architecture diagram
Elements: 8 rectangles, 7 arrows, 1 title

The .excalidraw file can be edited at https://excalidraw.com or with the VS Code Excalidraw extension.

Diagram Type Guide

Error Handling

PNG Backend Priority

Limitations

• Requires internet access (kroki.io for SVG rendering)
• Maximum recommended: 20 elements per diagram
• No embedded image support in auto-generation
• Hand-drawn roughness uses default settings