Skip to main content
Follow this process before generating any JSON. Rushing into implementation without planning leads to diagrams that display rather than argue.

​
Step 0: Assess Depth Required

Before anything else, determine if this diagram needs to be:

Simple/Conceptual

Abstract shapes, labels, relationships. Use for mental models and philosophies.

Comprehensive/Technical

Concrete examples, code snippets, real data. Use for systems, architectures, and tutorials.

​
Simple/Conceptual Diagrams

Use abstract shapes when:
  • Explaining a mental model or philosophy
  • The audience doesn’t need technical specifics
  • The concept IS the abstraction (e.g., “separation of concerns”)

​
Comprehensive/Technical Diagrams

Use concrete examples when:
  • Diagramming a real system, protocol, or architecture
  • The diagram will be used to teach or explain (e.g., YouTube video)
  • The audience needs to understand what things actually look like
  • You’re showing how multiple technologies integrate
For technical diagrams, you MUST include evidence artifacts. See the Evidence Artifacts page for details.
If comprehensive: Do research first. Look up actual specs, formats, event names, APIs.

​
Step 1: Understand Deeply

Read the content thoroughly. For each concept, ask:
1

What does this concept DO?

Focus on behavior, not just definitions. “What IS it” leads to static labels; “What does it DO” leads to dynamic visual patterns.
2

What relationships exist?

Identify connections, dependencies, and flows between concepts.
3

What's the core transformation?

Find the central flow or change that the diagram should illustrate.
4

What would someone need to SEE to understand this?

Think beyond text. What visual information makes the concept click?

​
Step 2: Map Concepts to Patterns

For each concept, find the visual pattern that mirrors its behavior:
If the concept…Use this pattern
Spawns multiple outputsFan-out (radial arrows from center)
Combines inputs into oneConvergence (funnel, arrows merging)
Has hierarchy/nestingTree (lines + free-floating text)
Is a sequence of stepsTimeline (line + dots + free-floating labels)
Loops or improves continuouslySpiral/Cycle (arrow returning to start)
Is an abstract state or contextCloud (overlapping ellipses)
Transforms input to outputAssembly line (before → process → after)
Compares two thingsSide-by-side (parallel with contrast)
Separates into phasesGap/Break (visual separation between sections)
See the Pattern Library for detailed examples and ASCII diagrams of each pattern.

​
Example: Mapping a Streaming Protocol

If you’re diagramming a protocol that:
  • Starts with a connection request (single trigger)
  • Streams multiple events over time (sequence)
  • Each event triggers different handlers (fan-out)
  • Results aggregate into final state (convergence)
Your visual strategy should use:
  • Ellipse for the connection trigger
  • Timeline for the event sequence
  • Fan-out for event → handler relationships
  • Convergence for handlers → final state

​
Step 3: Ensure Variety

For multi-concept diagrams: each major concept must use a different visual pattern.
No uniform cards or grids. If every section looks the same, you’re displaying, not arguing.

​
Bad vs Good

Bad (Displaying)Good (Arguing)
5 equal boxes with labelsEach concept has a shape that mirrors its behavior
Card grid layoutVisual structure matches conceptual structure
Icons decorating textShapes that ARE the meaning
Same container for everythingDistinct visual vocabulary per concept

​
Step 4: Sketch the Flow

Before generating JSON, mentally trace how the eye moves through the diagram.
1

Identify the entry point

Where does the viewer’s eye land first? Usually top-left or the largest element.
2

Trace the primary path

What’s the main visual journey through the diagram? There should be a clear narrative flow.
3

Check for dead ends

Are there isolated elements with no connections? Every element should relate to the story.
4

Verify hierarchy

Are the most important concepts visually dominant (larger, more isolated, more whitespace)?

​
Flow Direction Guidelines

  • Left → Right: Standard for sequences, processes, pipelines
  • Top → Bottom: Good for hierarchies, timelines, cascading flows
  • Radial (center → out): Perfect for fan-out, hub-and-spoke, central triggers
  • Circular: For loops, cycles, iterative processes

​
Step 5: Generate JSON

Only now create the Excalidraw elements.
For comprehensive or technical diagrams, you MUST build the JSON one section at a time. See the Large Diagram Strategy documentation for the complete workflow.

​
Section-by-Section Approach

1

Create the base file

Start with the JSON wrapper (type, version, appState, files) and the first section of elements.
2

Add one section per edit

Each section gets its own dedicated pass. Use descriptive string IDs (e.g., "trigger_rect", "arrow_fan_left").
3

Namespace seeds by section

Section 1 uses 100xxx, section 2 uses 200xxx, etc. to avoid collisions.
4

Update cross-section bindings

When a new section’s element needs to bind to a previous section, edit the earlier element’s boundElements array.

​
Step 6: Render & Validate (MANDATORY)

You MUST run the render-view-fix loop until the diagram looks right. This is not optional.
After generating or editing the Excalidraw JSON, you cannot judge quality from JSON alone. You must:
  1. Render to PNG using the render script
  2. View the image using the Read tool
  3. Audit against your vision (Steps 1-4)
  4. Check for visual defects
  5. Fix issues in the JSON
  6. Re-render and repeat until perfect

​
The Render Command

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

​
Audit Checklist

Before looking for bugs, compare the rendered result to your original design:
Does the visual structure match the conceptual structure you planned in Steps 1-4?
Does each section use the pattern you intended (fan-out, convergence, timeline, etc.)?
Does the eye flow through the diagram in the order you designed?
Are hero elements dominant and supporting elements appropriately smaller?
Are code snippets and data examples readable and properly placed?

​
Visual Defect Checklist

  • Text clipped by or overflowing its container
  • Text or shapes overlapping other elements
  • Arrows crossing through elements instead of routing around them
  • Arrows landing on the wrong element or pointing into empty space
  • Labels floating ambiguously (not clearly anchored)
  • Uneven spacing between elements that should be evenly spaced
  • Sections with too much whitespace next to cramped sections
  • Text too small to read at the rendered size
  • Overall composition feels lopsided or unbalanced

​
Common Fixes

  • Widen containers when text is clipped
  • Adjust x/y coordinates to fix spacing and alignment
  • Add waypoints to arrow points arrays to route around elements
  • Reposition labels closer to the element they describe
  • Resize elements to rebalance visual weight across sections

​
When to Stop

The loop is done when:
  • The rendered diagram matches the conceptual design from your planning steps
  • No text is clipped, overlapping, or unreadable
  • Arrows route cleanly and connect to the right elements
  • Spacing is consistent and the composition is balanced
  • You’d be comfortable showing it to someone without caveats
Typically takes 2-4 iterations. Don’t stop after one pass just because there are no critical bugs — if the composition could be better, improve it.

​
Complete Process Summary

1

Assess Depth

Simple/conceptual or comprehensive/technical? Research if technical.
2

Understand Deeply

What does each concept DO? What relationships exist? What needs to be SEEN?
3

Map to Patterns

Match each concept’s behavior to the right visual pattern (fan-out, convergence, timeline, etc.).
4

Ensure Variety

Each major concept uses a different visual pattern. No uniform grids.
5

Sketch Flow

Trace the visual path. Verify hierarchy and connections.
6

Generate JSON

Build section-by-section for comprehensive diagrams. Use descriptive IDs.
7

Render & Validate

Render → view → audit → fix → repeat until perfect.

Build docs developers (and LLMs) love

Get started for freeTalk to us