Excalidraw Studio

Generate Excalidraw-format diagrams from natural language descriptions. Outputs .excalidraw JSON files that can be opened directly in Excalidraw (web, VS Code extension, or Obsidian plugin).

Workflow

UNDERSTAND → CHOOSE TYPE → EXTRACT → GENERATE → SAVE

Step 1: Understand the Request

Analyze the user's description to determine:

1. Diagram type — Use the decision matrix below
2. Key elements — Entities, steps, concepts, actors
3. Relationships — Flow direction, connections, hierarchy
4. Complexity — Number of elements (target: under 20 for clarity)

Step 2: Choose the Diagram Type and Visual Mode

Diagram type:

Visual mode — decide upfront and apply consistently to all elements:

Step 3: Extract Structured Information

Extract the key components based on diagram type. For each type, identify:

• Nodes/entities — What are the boxes/shapes?
• Connections — What connects to what, and with what label?
• Hierarchy — What contains what, what comes before what?
• Decision points — Where does the flow branch?

For detailed extraction guidelines per diagram type, read references/element-types.md.

Step 4: Generate the Excalidraw JSON

CRITICAL: Read references/excalidraw-schema.md before generating your first diagram. It contains the correct element format, text container model, and binding system.

Key rules for generation:

1. Text inside shapes — Use boundElements on the shape and a separate text element with containerId. Never use a label shorthand:

   [
     {
       "id": "step-1",
       "type": "rectangle",
       "x": 100, "y": 100, "width": 200, "height": 80,
       "boundElements": [{ "type": "text", "id": "text-step-1" }]
     },
     {
       "id": "text-step-1",
       "type": "text",
       "x": 130, "y": 128, "width": 140, "height": 24,
       "text": "My Step", "originalText": "My Step",
       "fontSize": 20, "fontFamily": 5,
       "textAlign": "center", "verticalAlign": "middle",
       "containerId": "step-1", "lineHeight": 1.25, "roundness": null
     }
   ]

2. Arrow labels — Also use boundElements + separate text element with containerId. Never use a label shorthand on arrows:

   [
     {
       "id": "arrow-1",
       "type": "arrow",
       "x": 100, "y": 150,
       "points": [[0, 0], [200, 0]],
       "boundElements": [{ "type": "text", "id": "text-arrow-1" }]
     },
     {
       "id": "text-arrow-1",
       "type": "text",
       "x": 160, "y": 132, "width": 80, "height": 18,
       "text": "sends data", "originalText": "sends data",
       "fontSize": 14, "fontFamily": 5,
       "textAlign": "center", "verticalAlign": "middle",
       "containerId": "arrow-1", "lineHeight": 1.25, "roundness": null
     }
   ]

3. Arrow bindings — Use startBinding/endBinding (not start/end). Connected shapes must list the arrow in their boundElements:

   {
     "id": "shape-1",
     "boundElements": [
       { "type": "text", "id": "text-shape-1" },
       { "type": "arrow", "id": "arrow-1" }
     ]
   }

   {
     "id": "arrow-1",
     "type": "arrow",
     "startBinding": { "elementId": "shape-1", "focus": 0, "gap": 1 },
     "endBinding": { "elementId": "shape-2", "focus": 0, "gap": 1 }
   }

4. Element order for z-index — Always declare shapes first, arrows second, text elements last. This guarantees text renders on top and is never obscured by arrows or other shapes.

5. Positioning — Use grid-aligned coordinates (multiples of 20px when gridSize: 20). Leave 200-300px horizontal gap, 100-150px vertical gap between elements.

6. Unique IDs — Every element must have a unique id. Use descriptive IDs like "step-1", "decision-valid", "arrow-1-to-2", "text-step-1".

7. Colors — Use a consistent palette:

   Role	Color	Hex
   Primary entities	Light blue	#a5d8ff
   Process steps	Light green	#b2f2bb
   Important/Central	Yellow	#ffd43b
   Warnings/Errors	Light red	#ffc9c9
   Secondary	Cyan	#96f2d7
   Default stroke	Dark	#1e1e1e

Step 5: Save and Present

1. Save as <descriptive-name>.excalidraw

2. Provide a summary:

   Created: user-workflow.excalidraw
   Type: Flowchart
   Elements: 7 shapes, 6 arrows, 1 title
   Total: 14 elements
   
   To view:
   1. Visit https://excalidraw.com → Open → drag and drop the file
   2. Or use the Excalidraw VS Code extension
   3. Or open in Obsidian with the Excalidraw plugin

Templates

Pre-built templates are available in assets/ for quick starting points. Use these when the diagram type matches — they provide correct structure and styling:

Read a template when creating that diagram type for the first time. Use its structure as a base, then modify elements to match the user's request.

Icon Libraries

For professional architecture diagrams with service icons (AWS, GCP, Azure, etc.), icon libraries can be set up. Read references/icon-libraries.md when:

• User requests an AWS/cloud architecture diagram
• User mentions wanting specific service icons
• You need to check if icon libraries are available

Best Practices

Element Count

If the user's request exceeds maximum, suggest breaking into multiple diagrams:

"Your request includes 15 components. For clarity, I recommend: (1) High-level architecture diagram with 6 main components, (2) Detailed sub-diagrams for each subsystem. Want me to start with the high-level view?"

Layout

• Flow direction: Left-to-right for processes, top-to-bottom for hierarchies
• Spacing: 200-300px horizontal, 100-150px vertical between elements
• Grid alignment: Position on multiples of 20px for clean alignment
• Margins: Minimum 50px from canvas edge
• Text sizing: 28-36px titles, 18-22px labels, 14-16px annotations
• Font: Use fontFamily: 5 (Excalifont) for hand-drawn consistency. Fallback to 1 (Virgil) if 5 is not supported.
• Background zones: For architecture diagrams, add semi-transparent dashed zone rectangles (opacity: 35, strokeStyle: "dashed", roughness: 0) as the first elements in the array to create visual grouping regions. See references/excalidraw-schema.md → Background Zones.
• Element order: zones first → shapes → arrows → text elements (ensures correct z-index and text always renders on top)

Common Mistakes to Avoid

• ❌ Using label: { text: "..." } shorthand on shapes or arrows — not supported by the Excalidraw parser
• ❌ Putting text directly on shape elements without containerId
• ❌ Using start/end for arrow bindings — use startBinding/endBinding with elementId/focus/gap
• ❌ Forgetting to add arrows to their connected shapes' boundElements arrays
• ❌ Omitting originalText, lineHeight, autoResize, or backgroundColor: "transparent" from text elements inside containers
• ❌ Omitting required base properties (angle, strokeStyle, opacity, groupIds, frameId, index, isDeleted, seed, version, versionNonce, updated, link, locked) — elements will not render
• ❌ Missing "files": {} at the top level of the JSON
• ❌ Using roundness: { "type": 3 } on ellipses — ellipses must use roundness: null
• ❌ Missing lastCommittedPoint, startArrowhead, endArrowhead on arrows
• ❌ Declaring text elements before arrows — text renders underneath and gets obscured
• ❌ Floating arrows without bindings (won't move with shapes)
• ❌ Overlapping elements (increase spacing)
• ❌ Inconsistent color usage (define palette upfront)
• ❌ Too many elements on one diagram (break into sub-diagrams)

Validation Checklist

Before delivering the diagram, verify:

• All elements have unique IDs
• Every element has ALL required base properties: angle, strokeStyle, opacity, groupIds, frameId, index, isDeleted, link, locked, seed, version, versionNonce, updated
• index values are assigned in order ("a0", "a1", …) with text elements getting higher values than shapes/arrows
• Top-level JSON includes "files": {}
• Shapes with text use boundElements + separate text element with containerId
• Text elements inside containers have containerId, originalText, lineHeight: 1.25, autoResize: true, roundness: null, backgroundColor: "transparent"
• Arrows use startBinding/endBinding (with elementId, focus, gap) when connecting shapes, plus lastCommittedPoint: null, startArrowhead: null, endArrowhead: "arrow"
• Connected shapes list the arrow in their boundElements arrays
• Element order: shapes → arrows → text elements (text always on top)
• Ellipses use roundness: null (not { "type": 3 })
• Coordinates prevent overlapping (check spacing)
• Text is readable (font size 16+)
• Colors follow consistent scheme
• File is valid JSON
• Element count is reasonable (<20 for clarity)

Troubleshooting

Limitations

• Complex curves are simplified to straight/basic curved lines
• Hand-drawn roughness is set to default (1)
• No embedded images in auto-generation (use icon libraries for service icons)
• Maximum recommended: 20 elements per diagram for clarity
• No automatic collision detection — use spacing guidelines