# Excalidraw Diagram

> Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts as beautiful, structured diagrams.

- Skill: `skizha/excalidraw-diagram` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add skizha/excalidraw-diagram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/skizha/excalidraw-diagram/raw
- Safety review: WARNING
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: skizha (https://skillmd.com/u/skizha)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/skizha/excalidraw-diagram

---


# Excalidraw Diagram Creator

Generate `.excalidraw` JSON files that **argue visually** — shapes that mirror their meaning, not just labelled boxes.

**Two tests every diagram must pass:**
- **Isomorphism**: remove all text — does the structure still communicate the concept?
- **Education**: does it teach concrete details, or just label things?

---

## Step 0 — Assess Depth

- **Simple/Conceptual**: abstract shapes and labels (mental models, overviews)
- **Comprehensive/Technical**: real data formats, actual API/event names, code snippets

For technical diagrams: **research the actual specs first** (real event names, JSON formats, method names — not generic placeholders).

## Step 1 — Map Concepts to Patterns

See `references/diagram-patterns.md` for the full pattern library (fan-out, convergence, timeline, assembly line, etc.) and evidence artifact types.

## Step 2 — Plan Layout

Before writing JSON, sketch mentally:
- Entry and exit points
- Major sections (assign non-overlapping coordinate regions, e.g. Section A: x 0–800, Section B: x 900–1700)
- Where evidence artifacts live
- Arrow flow and reading direction (top→bottom or left→right)

## Step 3 — Generate JSON

**Wrapper:**
```json
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": { "viewBackgroundColor": "#ffffff", "gridSize": null },
  "files": {}
}
```

- Element reference (templates, sizing, coordinates) → `references/element-templates.md`
- Colors → `references/color-palette.md` (single source of truth)
- Use meaningful IDs (`auth-box`, `api-arrow-1`), never `elem1`
- For large diagrams: build section-by-section, not all at once

**Key defaults:** `roughness: 0`, `opacity: 100`, `fontFamily: 3` (monospace) on all elements.

## Step 4 — Render

```bash
cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <file.excalidraw>
```

**First-time setup** (from the `references/` directory):

Option A — with `uv` (recommended):
```bash
# Install uv if needed:
#   Windows:  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
#   macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
uv run playwright install chromium
```

Option B — with pip (no uv needed):
```bash
pip install playwright
playwright install chromium
# Then run directly: python render_excalidraw.py <file.excalidraw>
```

## Step 5 — Validate & Iterate

Fix and re-render (expect 2–4 iterations). Check:
- **Isomorphism**: structure communicates without text
- **Education**: teaches concrete details, not just labels
- Text fully visible, no clipping; no unintentional overlaps
- Arrows route cleanly; evidence artifacts present in technical diagrams