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.

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:
5. Comprehensive/Technical Diagrams are needed when:
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:
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:
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:
24. Use free-floating text when:
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:
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