excalidraw

Excalidraw Diagrams

You create hand-drawn visual explanations — the whiteboard sketch a senior engineer draws while explaining something. Not "a flowchart": a picture that makes someone understand.

Diagrams ARGUE, they don't display. Every element earns its place by contributing to an argument about how something works. The shape of the diagram should BE the meaning.

The bar, before you deliver:

• 10s / 2min test — a glance gives the main idea; two minutes of study gives the details.
• Isomorphism test — delete all text mentally: does the structure alone still communicate the concept? If not, redesign.
• Education test — does a reader LEARN something concrete, or did you just label boxes?
• Understanding per square inch — every choice maximizes how much the reader understands, how fast. Complexity is allowed only when it buys easier understanding, never to look thorough.

---

1. Workflow (always, in order)

1. UNDERSTAND the subject first — see the subject playbook (§2). Codebase → Grep/Read the real names. Paper → get the method right. Decision/pipeline from this conversation → mine the chat for the actual options, constraints, and conclusions discussed. Real names and real facts, never placeholders — "stripe-webhook → payments.events" teaches; "Service A → Service B" doesn't. If a key fact is uncertain, ask instead of inventing.
2. SCOPE & DEPTH — two dials, decided up front:
   • Size: would this need >12 major elements, multiple subsystems, or multiple zoom levels? → decomposition applies (§10).
   • Depth: walkthrough / balanced / reference (§3). When the request is non-trivial and the user hasn't implied the answers, ask one AskUserQuestion call covering what's genuinely unclear (≤2 questions: depth, and split-into-views if size triggered). If intent is obvious — "quick sketch" → reference-ish, "explain this to me / to a junior" → walkthrough — don't ask, infer.
3. PLAN before any JSON (think, briefly): one flow axis · which visual pattern per concept (§7) · the ONE hero element · which 2–3 semantic colors · what to show rather than label · where annotations go (per depth).
4. AUTHOR excalidraw/<name>.excalidraw (create the folder in the project root; kebab-case name). Build in z-order: zones → shapes → standalone text → bound text & arrows (array order = stacking order). Use the helpers (§4) for bound text and arrows — they compute the fiddly geometry.
5. CHECK — run excal.py check (§4) → fix every warning.
6. RENDER — run excal.py render (§4) → then Read the PNG. Actually look at it.
7. AUDIT the image against the checklist (§8), fix the JSON, re-render. Typically 2–3 passes. You cannot judge a diagram from JSON alone.
8. DELIVER — tell the user: the .png (embed-ready), the .excalidraw (drag onto excalidraw.com to edit), and offer a share link (excal.py share). The user's feedback in chat continues the loop — treat every comment as another audit pass.

---

2. Subject playbook (it's not just code)

Subject	Approach
Codebase / system architecture	C4-ish views; identifiers Grep'd from the code; zones per deployment boundary
Research paper / ML method	Method pipeline input → stages → output; dims/equations as evidence panels (§7); training vs inference as separate flows or zones; results as a small comparison panel
A decision being discussed (in this chat)	Options as columns × criteria as aligned rows, or a decision tree; the chosen path highlighted with the accent color; arguments pulled from the conversation
Business / human process	Swimlanes: one horizontal zone per actor, time flowing L→R
Data model	ER diagram; crowfoot_* arrowheads; ≤8 entities per view
Incident, history, roadmap	Timeline pattern (§7) with phases as zones above/below the line
Comparison ("X vs Y")	Side-by-side panels with row-aligned aspects; differences accented, sameness greyed
Abstract concept / mental model	Free-form via the creativity engine (§7): metaphor, show-don't-tell

The conversation itself is a valid source — when the user says "diagram what we just decided", the content is the chat: extract the real options weighed, constraints named, and the conclusion. Confirm anything fuzzy rather than decorating a guess.

---

3. Explanation depth (the dial)

Same subject, three legitimate diagrams. Depth changes how much you explain — never how clearly.

• Walkthrough ("teach me") — for learning, onboarding, complex topics. Add: numbered step badges along the flow (18px circles, bold number, accent color) so there's an explicit reading order · a concrete example flowing through (real sample request/value/tensor shape in evidence panels) · asterisk callouts on every non-obvious term · a small legend · "gotcha" notes in grey where people get confused. Complexity grows by adding simple elements, never by densifying — if walkthrough extras push past the element budget, split into more views (§10) instead of crowding.
• Balanced (default) — labels everywhere, annotations only where something is non-obvious. Standard budgets.
• Reference ("clean") — structure + names, zero prose, tightest canvas. For readers who know the domain: docs embeds, slides, quick refreshers.

When torn between two depths, take the more explanatory one. A reader who understands fast forgives an extra annotation; one who's lost forgives nothing.

---

4. Files, elements, helpers

Skeleton (this is the whole file format):

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

Author terse elements — omit anything Excalidraw defaults on load (seed, version, versionNonce, updated, index, angle:0, isDeleted, groupIds:[], frameId, link, locked...). A shape needs only:

{"id":"api","type":"rectangle","x":300,"y":200,"width":180,"height":90,
 "strokeColor":"#1971c2","backgroundColor":"#a5d8ff","fillStyle":"solid",
 "strokeWidth":2,"roughness":1,"roundness":{"type":3}}

{"id":"title","type":"text","x":280,"y":40,"width":340,"height":35,
 "text":"Payment Flow","fontSize":28,"fontFamily":5,"strokeColor":"#1e1e1e"}

• ids: short, descriptive, namespaced when sectioned (auth-db, auth-arrow-1). Never duplicated.
• Strict JSON — no comments, no trailing commas. Radians for angle.
• Snap x/y/width/height to the 20px grid; aligned elements share exact coordinates.
• Full field reference, per-type minimums, pitfalls: references/format.md.

Helper CLI — every command is uv run --python 3.12 "${CLAUDE_SKILL_DIR}/scripts/excal.py" <subcommand> ... (quote the path; works from any cwd; rewrites the file in place):

textbox <file> <containerId> "Label text"     centered bound text in a shape   [--size 16 --font 5 --color HEX]
connect <file> <fromId> <toId>                edge-to-edge arrow + bindings    [--label TXT --style dashed --elbow --color HEX --end-head triangle --from-side auto]
check   <file>                                geometric lint: overlaps, overflow, broken refs, floating arrows
render  <file>                                PNG preview                       [-o out.png --scale 2]
share   <file>                                encrypted upload → excalidraw.com link

Hand-author bound text / arrows only when you need something the helpers can't do — mechanics in references/arrows.md and references/format.md.

Setup hiccups: helpers need uv (brew install uv); the renderer needs system cairo once (brew install cairo / apt-get install libcairo2-dev). If rendering is impossible on this machine, keep authoring + check (still valid diagrams — you just lose the visual pass; say so to the user).

---

5. Layout rules

One flow axis per diagram. L→R for pipelines/processes/sequences; T→B for hierarchies/decisions; radial for hub-and-spoke. Never mix axes in one view.

Rank discipline (mental Sugiyama): rank = hops from the entry point. Same rank ⇒ same column (L→R) or row (T→B), sharing the exact coordinate. Reorder nodes within a rank to minimize arrow crossings — target zero crossings; feedback/return edges go dashed, routed around the outside.

Size = importance. Three tiers, one hero:

Tier	Size	Use
HERO	~300×150	THE thing the diagram is about — exactly one, given the most whitespace (≥200px isolation)
PRIMARY	~180×90	main flow participants
SECONDARY	~120×60	supporting pieces
marker	16–20	dots, ticks, step badges, connection points

Box size comes from its text: width ≥ longest-line-chars × fontSize × 0.6 + 30; height ≥ lines × fontSize × 1.25 + 30. (The textbox helper warns/grows for you.)

Spacing: ~40px between related elements; ≥2× that between groups. Crowding next to voids reads as broken — distribute.

Grouping = enclosure (the strongest visual cue). Zone recipe — draw FIRST (lowest z):

{"id":"zone-auth","type":"rectangle","x":260,"y":140,"width":520,"height":300,
 "strokeColor":"#868e96","backgroundColor":"transparent","strokeStyle":"dashed",
 "strokeWidth":1,"roughness":1,"roundness":{"type":3}}

plus a 14–16px UPPERCASE grey label inside top-left (x+15, y+12). 20px padding around children (+30 top for the label). Nesting ≤2 deep. Never use type:"frame" — invisible in local preview (§9).

≤20 elements per view. More → decompose (§10).

---

6. Style system

Semantic colors — dark stroke (shade idx4) paired with light fill (idx1) of the SAME hue:

Role	Stroke	Fill
neutral / default	#1e1e1e	transparent
primary / data flow	#1971c2	#a5d8ff
process / success	#2f9e44	#b2f2bb
storage / state	#e8590c	#ffd8a8
error / critical	#e03131	#ffc9c9
AI / special	#6741d9	#d0bfff
decision / warning	#f08c00	#ffec99
secondary / annotation	#868e96	#f8f9fa

Rules: ≤3 semantic hues + neutrals per diagram (add a small legend if ≥3 carry meaning) · 60-30-10 balance — the most saturated color on ≤10% of elements (your focal accent) · color encodes meaning, never decoration · full 12-hue ramp + cloud-vendor palettes (AWS orange etc.): references/style.md.

Typography (4 levels, consistent):

• Title 28–36px — fontFamily:5 (or 7 for display) — no box around titles
• Section 20px · Body/labels 16px · Annotations 14px in grey #868e96
• Minimum 14px, always. Code/identifiers → fontFamily:8. No emoji (won't render).

Texture: one roughness for the whole diagram — 1 (default sketch) or 0 (precise/technical). strokeWidth 2 default, 1 for fine structure lines, 4 only for the hero's emphasis. Line semantics: solid=sync/primary flow · dashed=async/optional/zones · dotted=weak reference. Arrowheads: arrow flow (default) · triangle inheritance/strong typed · bar terminator · circle connection · crowfoot_one/crowfoot_many/crowfoot_one_or_many ER cardinality. Opacity 20–40 for translucent overlap/highlight layers.

---

7. Creativity mandates (the anti-boxes-and-arrows engine)

Each major concept gets a DIFFERENT visual treatment. Uniform same-size box grids are a failure mode. Map concepts to patterns:

Concept	Pattern
one-to-many	fan-out: arrows radiating to a spread of targets
many-to-one	funnel/convergence
hierarchy	tree of lines + free text (not nested boxes)
cycle / retry	circular arrow loop
transformation	assembly line: in → process → out
multiplicity ("many X")	offset stack: 3 copies at +8x/+4y, fading opacity
same thing over time	copies linked by dotted lines
overlap / intersection	overlapping translucent ellipses
timeline	horizontal line + dot markers + free text above/below
layers	stacked full-width rounded rects

Show, don't tell. For anything hard to caption, ask "how could I SHOW this?" — a queue is a long rect with small rects inside it; a shard is a cylinder split by lines; a stream is a dashed arrow with little squares riding it. Full recipe library: references/patterns.md.

Text is seasoning, not structure. The drawing explains; words only name. If a region makes sense only because of a sentence sitting next to it, that region is undrawn — replace the sentence with a visual device before reaching for prose:

• mechanism → a tiny inset drawing of it (a slot being filled, a piece moving)
• condition/choice → an actual branch · quantity → a bar or stack · change → a small before→after pair
• emphasis → size/weight/color contrast, never the word "important" Rules: annotations ≤ 12 words each, visually attached to their target (adjacent, smaller, grey); never paragraphs on canvas (sole exception: evidence panels showing real artifacts); "box + explanatory caption" may appear a couple of times, but if it's the pattern of the diagram, redesign. Walkthrough depth (§3) means more visual scaffolding — badges, insets, example values — not longer captions.

Free text first. Default to free-floating text; box text only when the shape means something (a component, a store, a boundary) or must receive an arrow. Target: <30% of text elements live in containers. Lines beat boxes for structure (timelines, trees, dividers).

Annotation layers (what makes it feel like notes, not a chart):

• Asterisk pattern: term* then a smaller grey *explanation nearby.
• Evidence artifacts: a dark panel (#1e293b bg) with 14px fontFamily:8 code/payload text in #b2f2bb — show the REAL event/payload/equation/tensor shape.
• Tiny grey "why" notes (14px, #868e96) next to the thing they explain.
• Walkthrough depth (§3) adds: numbered step badges, an example value flowing through, a legend.

---

8. Render loop (mandatory — you cannot judge a diagram from JSON)

After check passes: render, Read the PNG, audit:

1. Text clipped, overflowing, or cramped in any shape?
2. Any two elements overlapping that shouldn't?
3. Arrows: touching their endpoints' edges? crossing through shapes? spaghetti?
4. Any label floating with an unclear owner?
5. Spacing: crowded region next to a void? misaligned rows/columns?
6. Everything readable? (≥14px; render --scale 3 to verify tight cases)
7. Composition balanced? ONE clear focal point?
8. Eye-flow follows the actual order of the system? Isomorphism holds?
9. Colors semantic + consistent? Sufficient contrast?
10. Does the structure lie about anything? (wrong direction, false grouping, missing critical path)
11. Depth honored? (walkthrough: could a newcomer follow the numbered path? reference: any prose left to cut?)
12. Squint test: imagine every word gone — does the picture still teach the core idea? Any region that's just box-plus-prose? Redraw it visually (§7), don't re-caption it.

Common fixes: widen box / re-run textbox · shift x/y on the 20-grid · re-run connect after moving shapes (arrows don't follow automatically) · add a waypoint to route an arrow around an obstacle · move a label next to its owner · resize to restore hierarchy.

Stop when you'd show it without caveats — usually 2–3 passes. Then deliver; the user's chat feedback drives further passes.

---

9. Local-preview quirks (PNG renderer vs excalidraw.com)

The bundled renderer is fast and faithful for layout QA, with known gaps — author around them:

• type:"frame" renders nothing → always use zone rectangles (§5). Frames are fine on the web, but you'd be blind locally.
• fillStyle:"hachure"/"cross-hatch" render solid locally (correct on web). Don't rely on texture to encode meaning.
• Arrows draw their literal points — no auto-rerouting. connect computes edge-to-edge geometry; re-run it after moving endpoints' shapes.
• Bound text renders at its literal x/y — textbox pre-centers it. Don't hand-place bound text without the centering math.
• PNG output only. Fonts preview as Virgil/JetBrainsMono; excalidraw.com shows the true Excalifont/Nunito/etc. (metrics are close).

---

10. Decomposition (big subjects → linked views)

Trigger (from §1.2): >12 major elements / multiple subsystems / multiple zoom levels → offer the user (in the same AskUserQuestion as the depth dial when both trigger):

(A) one high-level overview · (B) a deep-dive of one component · (C) both — overview + a detail file per component

For (C), C4-style: excalidraw/<system>-overview.excalidraw (what talks to what, no internals) + excalidraw/<component>-detail.excalidraw per component (internals + immediate neighbors as greyed, dashed, 50-opacity context anchors at the edges). Keep names IDENTICAL across files. Overview boxes with a detail file get a 14px grey → see <component>-detail note. Every file: title + one-line grey subtitle. Run the full check+render loop per file. Works for non-code too (paper → method overview + per-stage detail; process → end-to-end + per-actor detail). Full protocol: references/decomposition.md.

---

11. Editing existing diagrams

Read the file first. Preserve the author's ids, palette, and style — match it, don't impose yours. After edits: check, re-connect any arrows whose endpoints moved, render, view. Append new elements at the right z-position (zones near the front of the array, arrows/text at the end).

---

Final gate

Before delivering, confirm: unique ids · strict JSON · one flow axis · one focal point · ≤3 semantic hues, same-hue stroke/fill pairs · <30% boxed text · all text ≥14px · annotations ≤12 words and no canvas paragraphs · squint test passes (structure teaches without the words) · no frame elements · depth honored (§3) · check clean · you looked at the final PNG and would show it without caveats.