Skip to main content
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.
1
Step 1: Assess Depth Required
2
Before designing anything, determine what level of detail your diagram needs:
3
Simple/Conceptual Diagrams are appropriate when:
4
  • Explaining a mental model or philosophy
  • The audience doesn’t need technical specifics
  • The concept IS the abstraction (e.g., “separation of concerns”)
    • 5
    Comprehensive/Technical Diagrams are needed when:
    6
  • 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
    • 7
    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.
    8
    Step 2: Research (For Technical Diagrams)
    9
    If you’re creating a technical diagram, research the actual specifications before drawing anything:
    10
  • Look up the actual JSON/data formats
  • Find the real event names, method names, or API endpoints
  • Understand how the pieces actually connect
  • Use real terminology, not generic placeholders
    • 11
    Bad example: “Protocol” → “Frontend”
    Good example: “AG-UI streams events (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)” → “CopilotKit renders via createA2UIMessageRenderer()”
    12
    Research makes diagrams both accurate and educational.
    13
    Step 3: Understand Deeply
    14
    Read the content you’re visualizing. For each concept, ask:
    15
  • 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)
    • 16
    Step 4: Map Concepts to Visual Patterns
    17
    For each concept, choose a visual pattern that mirrors its behavior:
    18
    If the concept…Use this patternSpawns 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 + 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)
    19
    For multi-concept diagrams, each major concept must use a different visual pattern. No uniform cards or grids.
    20
    Step 5: Plan Container Usage
    21
    Not every piece of text needs a shape around it. Default to free-floating text. Add containers only when they serve a purpose:
    22
    Use a container when:
    23
  • 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
    • 24
    Use free-floating text when:
    25
  • 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
    • 26
    Goal: Aim for less than 30% of text elements to be inside containers.
    27
    Step 6: Generate the JSON
    28
    Now create the Excalidraw elements:
    29
  • Read the color palette at ~/.claude/skills/excalidraw-diagram/references/color-palette.md
  • Use element templates from ~/.claude/skills/excalidraw-diagram/references/element-templates.md
  • For large diagrams, build section-by-section (see Large Diagrams guide)
  • Use descriptive IDs like "trigger_rect" or "arrow_fan_left" for readability
    • 30
    Basic Structure
    {
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    // Your elements here
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}
    Example Element
    {
  "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"
}
    31
    Step 7: Render & Validate (MANDATORY)
    32
    You cannot judge a diagram from JSON alone. After generating the JSON, you must run the render-view-fix loop until it looks right.
    33
    See the Render & Validate guide for the complete process.

    ​
    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

    Large Diagrams

    Learn the section-by-section strategy for comprehensive diagrams

    Render & Validate

    Master the mandatory render-view-fix loop

    Customization

    Customize colors and brand styles for your diagrams

    Visual Patterns

    Explore all available visual patterns

    Build docs developers (and LLMs) love

    Get started for freeTalk to us