> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/coleam00/excalidraw-diagram-skill/llms.txt
> Use this file to discover all available pages before exploring further.

# Design Process

> The complete step-by-step workflow for creating effective Excalidraw diagrams that argue visually

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:

<CardGroup cols={2}>
  <Card title="Simple/Conceptual" icon="cloud">
    Abstract shapes, labels, relationships. Use for mental models and philosophies.
  </Card>

  <Card title="Comprehensive/Technical" icon="code">
    Concrete examples, code snippets, real data. Use for systems, architectures, and tutorials.
  </Card>
</CardGroup>

### 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

<Warning>
  **For technical diagrams, you MUST include evidence artifacts.** See the [Evidence Artifacts](/concepts/evidence-artifacts) page for details.
</Warning>

<Note>
  **If comprehensive**: Do research first. Look up actual specs, formats, event names, APIs.
</Note>

***

## Step 1: Understand Deeply

Read the content thoroughly. For each concept, ask:

<Steps>
  <Step title="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.
  </Step>

  <Step title="What relationships exist?">
    Identify connections, dependencies, and flows between concepts.
  </Step>

  <Step title="What's the core transformation?">
    Find the central flow or change that the diagram should illustrate.
  </Step>

  <Step title="What would someone need to SEE to understand this?">
    Think beyond text. What visual information makes the concept click?
  </Step>
</Steps>

***

## 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 outputs         | **Fan-out** (radial arrows from center)            |
| Combines inputs into one        | **Convergence** (funnel, arrows merging)           |
| Has hierarchy/nesting           | **Tree** (lines + free-floating text)              |
| Is a sequence of steps          | **Timeline** (line + dots + free-floating labels)  |
| Loops or improves continuously  | **Spiral/Cycle** (arrow returning to start)        |
| Is an abstract state or context | **Cloud** (overlapping ellipses)                   |
| Transforms input to output      | **Assembly line** (before → process → after)       |
| Compares two things             | **Side-by-side** (parallel with contrast)          |
| Separates into phases           | **Gap/Break** (visual separation between sections) |

<Tip>
  See the [Pattern Library](/methodology/pattern-library) for detailed examples and ASCII diagrams of each pattern.
</Tip>

### 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.**

<Warning>
  No uniform cards or grids. If every section looks the same, you're displaying, not arguing.
</Warning>

### Bad vs Good

| Bad (Displaying)              | Good (Arguing)                                     |
| ----------------------------- | -------------------------------------------------- |
| 5 equal boxes with labels     | Each concept has a shape that mirrors its behavior |
| Card grid layout              | Visual structure matches conceptual structure      |
| Icons decorating text         | Shapes that ARE the meaning                        |
| Same container for everything | Distinct visual vocabulary per concept             |

***

## Step 4: Sketch the Flow

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

<Steps>
  <Step title="Identify the entry point">
    Where does the viewer's eye land first? Usually top-left or the largest element.
  </Step>

  <Step title="Trace the primary path">
    What's the main visual journey through the diagram? There should be a clear narrative flow.
  </Step>

  <Step title="Check for dead ends">
    Are there isolated elements with no connections? Every element should relate to the story.
  </Step>

  <Step title="Verify hierarchy">
    Are the most important concepts visually dominant (larger, more isolated, more whitespace)?
  </Step>
</Steps>

### 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.

<Note>
  **For comprehensive or technical diagrams, you MUST build the JSON one section at a time.** See the [Large Diagram Strategy](/guides/large-diagrams) documentation for the complete workflow.
</Note>

### Section-by-Section Approach

<Steps>
  <Step title="Create the base file">
    Start with the JSON wrapper (`type`, `version`, `appState`, `files`) and the first section of elements.
  </Step>

  <Step title="Add one section per edit">
    Each section gets its own dedicated pass. Use descriptive string IDs (e.g., `"trigger_rect"`, `"arrow_fan_left"`).
  </Step>

  <Step title="Namespace seeds by section">
    Section 1 uses 100xxx, section 2 uses 200xxx, etc. to avoid collisions.
  </Step>

  <Step title="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>
</Steps>

***

## Step 6: Render & Validate (MANDATORY)

<Warning>
  You **MUST** run the render-view-fix loop until the diagram looks right. This is not optional.
</Warning>

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

```bash theme={null}
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:

<AccordionGroup>
  <Accordion title="Visual Structure Match">
    Does the visual structure match the conceptual structure you planned in Steps 1-4?
  </Accordion>

  <Accordion title="Pattern Fidelity">
    Does each section use the pattern you intended (fan-out, convergence, timeline, etc.)?
  </Accordion>

  <Accordion title="Eye Flow">
    Does the eye flow through the diagram in the order you designed?
  </Accordion>

  <Accordion title="Visual Hierarchy">
    Are hero elements dominant and supporting elements appropriately smaller?
  </Accordion>

  <Accordion title="Evidence Artifacts (Technical Diagrams)">
    Are code snippets and data examples readable and properly placed?
  </Accordion>
</AccordionGroup>

### 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

<Tip>
  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.
</Tip>

***

## Complete Process Summary

<Steps>
  <Step title="Assess Depth">
    Simple/conceptual or comprehensive/technical? Research if technical.
  </Step>

  <Step title="Understand Deeply">
    What does each concept DO? What relationships exist? What needs to be SEEN?
  </Step>

  <Step title="Map to Patterns">
    Match each concept's behavior to the right visual pattern (fan-out, convergence, timeline, etc.).
  </Step>

  <Step title="Ensure Variety">
    Each major concept uses a different visual pattern. No uniform grids.
  </Step>

  <Step title="Sketch Flow">
    Trace the visual path. Verify hierarchy and connections.
  </Step>

  <Step title="Generate JSON">
    Build section-by-section for comprehensive diagrams. Use descriptive IDs.
  </Step>

  <Step title="Render & Validate">
    Render → view → audit → fix → repeat until perfect.
  </Step>
</Steps>