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:
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:
- Diagram type: flowchart, relationship, mind map, architecture, sequence, ER, class, swimlane, data flow
- Key elements: entities, steps, concepts
- 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:
| Role |
Color |
| Primary entities |
#a5d8ff (light blue) |
| Process steps |
#b2f2bb (light green) |
| Important/central |
#ffd43b (yellow) |
| Warnings/errors |
#ffc9c9 (light red) |
| Default stroke |
#1e1e1e |
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:
- The exported image file (PNG or SVG)
- The source
.excalidraw file (for future editing)
- 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
| User Intent |
Type |
Keywords |
| Sequential process |
Flowchart |
"workflow", "process", "steps" |
| Entity connections |
Relationship |
"relationship", "dependencies" |
| Concept hierarchy |
Mind Map |
"mind map", "concepts", "ideas" |
| System components |
Architecture |
"architecture", "system", "modules" |
| Data movement |
Data Flow (DFD) |
"data flow", "data processing" |
| Cross-functional |
Swimlane |
"business process", "actors" |
| OOP design |
Class Diagram |
"class", "inheritance", "OOP" |
| Message flow |
Sequence |
"sequence", "interaction", "timeline" |
| Database design |
ER Diagram |
"database", "entity", "data model" |
Error Handling
| Issue |
Solution |
| kroki.io unreachable |
Check internet; output .excalidraw only, inform user to export manually |
| fonttools/brotli not installed |
Run pip install fonttools brotli; falls back to Chrome or system fonts |
| CJK text shows as boxes |
Use fontFamily: 5 so kroki embeds Xiaolai; ensure fonttools+brotli installed for text-to-path |
| Elements overlap |
Increase spacing; use 200-300px horizontal gap |
| Too many elements |
Break into multiple diagrams; suggest high-level + detail views |
PNG Backend Priority
| Backend |
Hand-drawn English |
Hand-drawn CJK |
Notes |
| text-to-path + resvg |
✅ Excalifont |
✅ Xiaolai |
Recommended. Extracts woff2 glyphs via fonttools, converts <text> → <path>. Fast, no browser. |
| Chrome headless |
✅ Excalifont |
✅ Xiaolai |
Fallback. Renders @font-face natively but heavy (~500MB). |
| resvg (no fonttools) |
❌ System font |
❌ System font |
Last resort. Ignores @font-face, uses system fonts. |
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
1---2name: excalidraw-export3description: "Generate Excalidraw diagrams and export to PNG/SVG images. Use when asked to 'create a diagram', 'draw a flowchart', 'visualize architecture', 'make a mind map', 'generate excalidraw', 'export diagram to png', 'diagram to image'. Supports flowcharts, relationship diagrams, mind maps, architecture diagrams, sequence diagrams, ER diagrams, and more. End-to-end: natural language -> .excalidraw JSON -> PNG/SVG image. Trigger: 'excalidraw', 'diagram', 'flowchart', 'visualize', 'architecture diagram', '画图', '流程图', '架构图', '思维导图', '导出图片'."4metadata:5 source: https://skillmd.com/skills/psylch/excalidraw-export6---78# Excalidraw Export910Generate Excalidraw diagrams from natural language and export them as PNG/SVG images, end-to-end.1112## Language1314**Match user's language**: Respond in the same language the user uses.1516## End-to-End Workflow1718Progress:19- [ ] Step 1: Understand the request20- [ ] Step 2: Generate .excalidraw JSON21- [ ] Step 3: Export to PNG/SVG22- [ ] Step 4: Deliver result2324## Prerequisites2526On first use, run the setup script to check dependencies:2728```bash29bash <SKILL_DIR>/scripts/setup.sh30```3132Required:33- Python 3.8+34- `resvg` (`brew install resvg`) — fast SVG-to-PNG rasterizer35- `fonttools` + `brotli` (`pip install fonttools brotli`) — extracts embedded hand-drawn fonts from SVG and converts `<text>` to `<path>`, preserving Excalifont + Xiaolai without a browser36- Internet access (uses kroki.io for rendering)3738Optional fallback:39- Google Chrome — used as fallback if resvg/fonttools unavailable4041If only SVG output is needed, no extra tools are required.4243Run preflight to verify all dependencies programmatically:4445```bash46python3 <SKILL_DIR>/scripts/export.py --preflight47```4849### Step 1: Understand the Request5051Determine:521. **Diagram type**: flowchart, relationship, mind map, architecture, sequence, ER, class, swimlane, data flow532. **Key elements**: entities, steps, concepts543. **Relationships**: flow direction, connections, hierarchy5556### Step 2: Generate .excalidraw JSON5758Create a valid `.excalidraw` file following the schema. Read the reference docs for details:5960- Read `<SKILL_DIR>/references/excalidraw-schema.md` for the JSON schema61- Read `<SKILL_DIR>/references/element-types.md` for element specifications6263**Critical rules:**64- 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.65- `fontFamily: 1` (Virgil) is **deprecated** — kroki will NOT embed Xiaolai for it, causing CJK to fall back to system fonts66- Only use `fontFamily: 3` (Cascadia) for code identifiers / monospace text67- All IDs must be unique68- Keep element count under 20 for clarity69- Use consistent spacing: 200-300px horizontal, 100-150px vertical7071**Color palette:**72| Role | Color |73|------|-------|74| Primary entities | `#a5d8ff` (light blue) |75| Process steps | `#b2f2bb` (light green) |76| Important/central | `#ffd43b` (yellow) |77| Warnings/errors | `#ffc9c9` (light red) |78| Default stroke | `#1e1e1e` |7980**File structure:**81```json82{83 "type": "excalidraw",84 "version": 2,85 "source": "https://excalidraw.com",86 "elements": [],87 "appState": {88 "viewBackgroundColor": "#ffffff",89 "gridSize": 2090 },91 "files": {}92}93```9495Save the file as `<descriptive-name>.excalidraw`.9697### Step 3: Export to PNG/SVG9899Run the export script to convert the .excalidraw file to an image:100101```bash102# Export to PNG (default, 2x resolution for retina)103python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw104105# Export to SVG106python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw -f svg107108# Export both PNG and SVG109python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw -f png -f svg110111# Custom output path112python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw -o output.png113114# Higher resolution (3x)115python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw --scale 3116117# Dark theme118python3 <SKILL_DIR>/scripts/export.py <file>.excalidraw --dark119```120121### Step 4: Deliver Result122123Always provide:1241. The exported image file (PNG or SVG)1252. The source `.excalidraw` file (for future editing)1263. Brief summary of what was created127128**Example delivery:**129```130Created: system-architecture.png (86 KB)131Source: system-architecture.excalidraw132Type: Architecture diagram133Elements: 8 rectangles, 7 arrows, 1 title134135The .excalidraw file can be edited at https://excalidraw.com or with the VS Code Excalidraw extension.136```137138## Diagram Type Guide139140| User Intent | Type | Keywords |141|-------------|------|----------|142| Sequential process | Flowchart | "workflow", "process", "steps" |143| Entity connections | Relationship | "relationship", "dependencies" |144| Concept hierarchy | Mind Map | "mind map", "concepts", "ideas" |145| System components | Architecture | "architecture", "system", "modules" |146| Data movement | Data Flow (DFD) | "data flow", "data processing" |147| Cross-functional | Swimlane | "business process", "actors" |148| OOP design | Class Diagram | "class", "inheritance", "OOP" |149| Message flow | Sequence | "sequence", "interaction", "timeline" |150| Database design | ER Diagram | "database", "entity", "data model" |151152## Error Handling153154| Issue | Solution |155|-------|----------|156| kroki.io unreachable | Check internet; output .excalidraw only, inform user to export manually |157| fonttools/brotli not installed | Run `pip install fonttools brotli`; falls back to Chrome or system fonts |158| CJK text shows as boxes | Use `fontFamily: 5` so kroki embeds Xiaolai; ensure fonttools+brotli installed for text-to-path |159| Elements overlap | Increase spacing; use 200-300px horizontal gap |160| Too many elements | Break into multiple diagrams; suggest high-level + detail views |161162## PNG Backend Priority163164| Backend | Hand-drawn English | Hand-drawn CJK | Notes |165|---------|---|---|---|166| text-to-path + resvg | ✅ Excalifont | ✅ Xiaolai | Recommended. Extracts woff2 glyphs via fonttools, converts `<text>` → `<path>`. Fast, no browser. |167| Chrome headless | ✅ Excalifont | ✅ Xiaolai | Fallback. Renders @font-face natively but heavy (~500MB). |168| resvg (no fonttools) | ❌ System font | ❌ System font | Last resort. Ignores @font-face, uses system fonts. |169170## Limitations171172- Requires internet access (kroki.io for SVG rendering)173- Maximum recommended: 20 elements per diagram174- No embedded image support in auto-generation175- Hand-drawn roughness uses default settings