Excalidraw Diagram Generator

Generate .excalidraw JSON files in Jack's brand style (roughness: 1, Nunito, 7-color semantic palette, Excalidraw frames for grouping). Every diagram is rendered to PNG and visually validated via a Playwright render-view-fix loop before delivery.

File Index — READ ALL OF THESE BEFORE GENERATING

Before writing any JSON, read every references/*.md file below. They are small, and the rules interact — arrow x,y lives in arrows.md, but the whitespace rules in brand-style.md determine where those coordinates should be; the validation checklist in validation.md catches the silent-binding failures hinted at in element-templates.md. Round-1 agents who skipped files produced broken arrows and wrong-sized boxes for rules that were documented.

Quick Start

1. Ask the user for missing info (type, complexity, subsystems) — see Required Information.
2. Read every references/*.md file. Do not skip any. Rules interact across files, and the most common round-1 failures were documented rules that were never loaded.
3. Plan sections first (Step 0). The layout decision determines whether the diagram will work.
4. Generate JSON. For 30+ element diagrams, build one frame per edit (section-by-section).
5. Render the PNG (scripts/render_excalidraw.py) and look at it.
6. Iterate 2–4 times fixing anything the render shows that the JSON didn't.

Required Information

Ensure you have:

1. Diagram type: process (workflow, timeline, steps) OR architecture (components, services, infrastructure).
2. Complexity: simple (5–10 elements) / medium (15–25) / complex (30+).
3. Components and how they connect.
4. Subsystems (if 2+): each becomes a frame. For each frame, list which other frames it sends arrows to.

Ask the user:

To create your diagram, I need:
1. Process or architecture?
2. Complexity: simple (5–10 boxes), medium (15–25), complex (30+)?
3. Main components / steps?
4. If multiple subsystems: what are the frames, and which connect to which?

See references/prompt-templates.md for structured prompt templates users can copy.

Workflow

Step 0: Plan Sections First

For any diagram with ≥ 8 elements or 2+ subsystems. The single most important step.

1. Consider a flow direction (soft preference, not a rule):
   • Timelines, chronological sequences, phased rollouts usually read better left-to-right.
   • Network traffic, technical request/response sequences, pipeline stages often lean top-to-bottom.
   • Holding one direction per diagram tends to look cleaner, but mix if there's a good reason (loops, callbacks, sidebars).
2. Pick a visual pattern that matches the argument the diagram makes (see references/visual-patterns.md): assembly line, timeline, fan-out, convergence, hub with spokes, tree, side-by-side, gap, loop, cloud.
3. List subsystems — each becomes a frame. For each frame, note which other frames it exchanges arrows with, and which edge each cross-frame arrow exits from.
4. Sketch the frame layout mentally or on paper. Every cross-frame arrow should have a direct path (one or two bends, midpoint-routed) that does NOT cross a third frame.
5. Check the signs the layout is wrong (references/section-layout.md):
   • Two frames that exchange many arrows are > 1 frame-width apart.
   • An arrow from A to C passes through B's bounding box.
   • An arrow would need 4+ waypoints to reach its target.
   • Frames < 150px apart with arrows squeezing between.

Fix by moving frames, not by adding arrow waypoints. Arrow JSON is determined by layout.

Step 1: Read ALL References

Read every references/*.md listed in the File Index at the top of this document. Short files, interacting rules — skipping any one of them is the main cause of round-1 failures (invisible arrows, wrong-size boxes, missing legends, broken bindings).

Step 2: Study 2–3 canonical examples (MANDATORY)

Not optional. Pick the 2–3 examples whose patterns most resemble what you're building and view both the .png and the .excalidraw JSON for each. The PNG shows the intended visual; the JSON shows the exact coordinates, frame sizes, and arrow routing Jack uses. You cannot match Jack's style without seeing it.

Step 3: Generate JSON

Standard defaults:

• backgroundColor: "transparent", strokeWidth: 2, fontFamily: 5, roughness: 1
• Box 200×100 default, ~100px between rows AND between columns (constant rhythm — see brand-style.md measured ranges)
• Labeled shape = TWO elements (shape with boundElements + text with containerId)
• Arrows: elbowed: true, max 4 points, midpoint-routed, stroke = source element's semantic color

Write the .excalidraw file directly. Do not generate helper/build scripts (.py, .js, etc.) unless the user explicitly asks for a reusable generator or asks you to modify an existing helper.

For complex diagrams (30+ elements): build one frame per edit. Namespace element IDs per section (e.g. s1_*, s2_*) or seeds per section (100xxx, 200xxx). Add cross-section arrows last, once all frames are placed.

Step 4: Run the render

uv run <skill-dir>/scripts/render_excalidraw.py path/to/diagram.excalidraw

<skill-dir> is wherever this SKILL.md lives, for example .claude/skills/excalidraw or ~/.agents/skills/excalidraw. First run on a machine: uv run --with playwright playwright install chromium downloads the browser. Never create a .venv inside the skill folder.

Step 5: View the PNG (MANDATORY)

Read the resulting .png and check:

• Arrows: any arrow crossing through shapes or third frames? Do arrows land on the correct edge?
• Text: clipped, overflowing a container, or overlapping another element?
• Alignment: same-row elements share Y + height? same-column elements share X + width?
• Spacing: < 150px cramps between frames? > 400px dead whitespace?
• Frames: subsystems read as visually distinct groups?
• Legend: if multiple colors, is there a legend in the top-left?

On large/tall diagrams, mis-bound connectors and label overlaps are often invisible at full-diagram zoom. Crop zoomed regions of the PNG (e.g. PIL Image.crop(...)) and view those crops to confirm each arrow lands on its box edge and labels don't collide — don't trust the full thumbnail alone for binding QA.

Step 6: Fix & re-render (loop 2–4 times)

If anything is wrong, edit the JSON and re-render.

If an arrow crosses a third frame, the fix is Step 0 (re-plan the section layout), not a new arrow JSON.

Do not ship a diagram you haven't looked at.

Step 7: Technical validation

See references/validation.md — run through the JSON-level checklist (IDs unique, arrows bound both ends, text containerId matches shape boundElements, no diamonds, etc.).

Before committing, optionally run:

python scripts/cleanup_excalidraw.py path/to/diagram.excalidraw    # strip isDeleted
python scripts/optimize_excalidraw.py path/to/diagram.excalidraw   # strip auto-regen metadata (-20 to -50%)

Critical Rules

1. Whitespace is pretty. Jack's canonical diagrams run 10–27% shape area / 73–90% whitespace (measured across all 6 examples). Default box 200×100. ~100px inter-box rhythm is constant (row gaps AND column gaps). Frame padding flexes with content: ~80–100px L/R when airy, 20–60px when content is verbose (see multi-frame-process, prompts-to-harness). Top padding always ~20px (frame name sits there). One idea per box. No embedded code-snippet callouts. No subheads inside frames. No captions below boxes unless the label truly can't fit the meaning. Reduce before you add. See references/brand-style.md § "Whitespace is pretty" for the full measured ranges.
2. One box size per diagram. Pick a standard (usually 200×100, or ~170×75 for dense 4+-column row-grids) and use it for every content box. Don't vary box size to fit a label — tighten the label. Exceptions are meaningful and few: legend swatches are smaller, a container/region shape can be bigger if it represents something fundamentally different. Consistency = readability.
3. Plan sections first (Step 0). Everything else depends on this.
4. Follow the prompt literally. Don't add column headers, subheads, or explanatory sub-boxes unless the prompt explicitly lists them. Don't expand (xN) labels into N boxes — it's one box with an annotation (see brand-style.md).
5. Labels need TWO elements: shape with boundElements: [{id, type:"text"}] + text with containerId: shapeId.
6. Arrows: elbowed: true + fixedPoint bindings + 2–4 point paths. Max 4 points. Midpoint-routed. x, y = absolute canvas coord of the first point (source-edge anchor). See arrows.md Hard Rules.
7. Register every arrow on BOTH endpoints. Append {id: arrowId, type: "arrow"} to source shape's and destination shape's boundElements. Missing this silently breaks bindings.
8. If an arrow needs 5+ waypoints, move a frame — don't add waypoints.
9. Never use diamonds. Arrow bindings break on diamond shapes. Use rectangles.
10. Container discipline: default to no container. Aim for < 30% of text elements inside boxes. Prefer free-floating text + lines for section titles, annotations. Rectangles are for structural components, not every label.
11. Legend top-left when 2+ semantic colors used; per-frame mini-legend top-right when multiple frames share the same palette.
12. Frame, not dashed rectangle, for subsystem grouping. Children set frameId.
13. Rounded corners by default (roundness: {"type": 3}). Sharp only for flagged container/boundary shapes.
14. Render before shipping. No unlooked-at diagrams.
15. No helper-file detours by default. When the deliverable is a diagram, create the .excalidraw file itself. Do not create .py/.js builder files unless the user explicitly asks for one.

Visual Pattern Library (one-line summaries)

Full details in references/visual-patterns.md.

Scripts Reference

All scripts live in scripts/. Run from the skill root.

First-run setup (only for render_excalidraw.py): the script carries inline uv metadata, so uv run installs the Playwright package into uv's cache automatically. Download the browser once per machine:

uv run --with playwright playwright install chromium

Troubleshooting / Alternate Export

The default scripts/render_excalidraw.py produces PNG via Chromium. If it fails or you need SVG output / dark-mode / batch export, fall back to excalidraw-brute-export-cli. In particular, if Chromium hangs with Page.wait_for_function: Timeout 30000ms exceeded, don't keep retrying it — go straight to the brute-export fallback, which is reliable:

# From any directory — global install, no hard-coded path:
npx -y excalidraw-brute-export-cli -i path/to/diagram.excalidraw -o path/to/out.png -f png -s 2 -b true

Flags: -f png|svg, -s 1|2|3 (scale), -b true|false (white background), -d true|false (dark mode). First-run: npx playwright install firefox (once per machine).

This is a fallback — Cole's render_excalidraw.py is the default for everything the skill generates.

(File Index moved to the top of this document — skim it there.)