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

# Creating Diagrams

> End-to-end workflow from concept to finished diagram

This guide walks you through the complete process of creating an Excalidraw diagram using this skill—from understanding your content to delivering a polished visual.

## Overview

Creating a diagram isn't just about drawing shapes. It's about **arguing visually**—showing relationships, causality, and flow that words alone can't express. Follow this workflow to ensure your diagrams teach and communicate effectively.

<Steps>
  ### Step 1: Assess Depth Required

  Before designing anything, determine what level of detail your diagram needs:

  **Simple/Conceptual Diagrams** are appropriate 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** are needed 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

  <Tip>
    For technical diagrams, you **must include evidence artifacts**—code snippets, real data formats, actual event names. This is what makes the diagram educational rather than just decorative.
  </Tip>

  ### Step 2: Research (For Technical Diagrams)

  If you're creating a technical diagram, research the actual specifications **before drawing anything**:

  1. Look up the actual JSON/data formats
  2. Find the real event names, method names, or API endpoints
  3. Understand how the pieces actually connect
  4. Use real terminology, not generic placeholders

  **Bad example:** "Protocol" → "Frontend"\
  **Good example:** "AG-UI streams events (RUN\_STARTED, STATE\_DELTA, A2UI\_UPDATE)" → "CopilotKit renders via createA2UIMessageRenderer()"

  Research makes diagrams both accurate **and** educational.

  ### Step 3: Understand Deeply

  Read the content you're visualizing. For each concept, ask:

  * What does this concept **DO**? (not what IS it)
  * What relationships exist between concepts?
  * What's the core transformation or flow?
  * What would someone need to **SEE** to understand this? (not just read about)

  ### Step 4: Map Concepts to Visual Patterns

  For each concept, choose a 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 + 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) |

  <Warning>
    For multi-concept diagrams, each major concept must use a **different visual pattern**. No uniform cards or grids.
  </Warning>

  ### Step 5: Plan Container Usage

  Not every piece of text needs a shape around it. Default to free-floating text. Add containers only when they serve a purpose:

  **Use a container when:**

  * It's the focal point of a section
  * It needs visual grouping with other elements
  * Arrows need to connect to it
  * The shape itself carries meaning (decision diamond, etc.)
  * It represents a distinct "thing" in the system

  **Use free-floating text when:**

  * It's a label or description
  * It's supporting detail or metadata
  * Typography alone creates sufficient hierarchy
  * It's a section title, subtitle, or annotation

  **Goal:** Aim for less than 30% of text elements to be inside containers.

  ### Step 6: Generate the JSON

  Now create the Excalidraw elements:

  1. **Read the color palette** at `~/.claude/skills/excalidraw-diagram/references/color-palette.md`
  2. **Use element templates** from `~/.claude/skills/excalidraw-diagram/references/element-templates.md`
  3. **For large diagrams**, build section-by-section (see [Large Diagrams guide](/guides/large-diagrams))
  4. **Use descriptive IDs** like `"trigger_rect"` or `"arrow_fan_left"` for readability

  <CodeGroup>
    ```json Basic Structure theme={null}
    {
      "type": "excalidraw",
      "version": 2,
      "source": "https://excalidraw.com",
      "elements": [
        // Your elements here
      ],
      "appState": {
        "viewBackgroundColor": "#ffffff",
        "gridSize": 20
      },
      "files": {}
    }
    ```

    ```json Example Element theme={null}
    {
      "id": "start_ellipse",
      "type": "ellipse",
      "x": 100,
      "y": 100,
      "width": 180,
      "height": 90,
      "angle": 0,
      "strokeColor": "#c2410c",
      "backgroundColor": "#fed7aa",
      "fillStyle": "solid",
      "strokeWidth": 2,
      "roughness": 0,
      "opacity": 100,
      "seed": 100001,
      "text": "Start",
      "fontSize": 16,
      "fontFamily": 3,
      "textAlign": "center",
      "verticalAlign": "middle"
    }
    ```
  </CodeGroup>

  ### Step 7: Render & Validate (MANDATORY)

  You cannot judge a diagram from JSON alone. After generating the JSON, you **must** run the render-view-fix loop until it looks right.

  See the [Render & Validate guide](/guides/render-validate) for the complete process.
</Steps>

## Quality Checklist

Before considering your diagram complete, verify:

### For Technical Diagrams

* ✅ Research done: actual specs, formats, event names looked up
* ✅ Evidence artifacts: code snippets, JSON examples, or real data included
* ✅ Multi-zoom: has summary flow + section boundaries + detail
* ✅ Concrete over abstract: real content shown, not just labeled boxes
* ✅ Educational value: someone could learn something concrete from this

### For All Diagrams

* ✅ Isomorphism: each visual structure mirrors its concept's behavior
* ✅ Argument: diagram SHOWS something text alone couldn't
* ✅ Variety: each major concept uses a different visual pattern
* ✅ Minimal containers: less than 30% of text elements are in boxes
* ✅ Connections: every relationship has an arrow or line
* ✅ Flow: clear visual path for the eye to follow
* ✅ Rendered & validated: PNG generated, visually inspected, issues fixed

## Next Steps

<CardGroup cols={2}>
  <Card title="Large Diagrams" icon="diagram-project" href="/guides/large-diagrams">
    Learn the section-by-section strategy for comprehensive diagrams
  </Card>

  <Card title="Render & Validate" icon="eye" href="/guides/render-validate">
    Master the mandatory render-view-fix loop
  </Card>

  <Card title="Customization" icon="palette" href="/guides/customization">
    Customize colors and brand styles for your diagrams
  </Card>

  <Card title="Visual Patterns" icon="shapes" href="/methodology/pattern-library">
    Explore all available visual patterns
  </Card>
</CardGroup>