Excalidraw System

A Claude Code skill for working with Excalidraw files and integrating Excalidraw diagramming into development workflows. Focuses on programmatic creation and manipulation of Excalidraw diagrams, efficient context management for large files, and subagent delegation patterns for processing Excalidraw JSON.

When to Use This Skill

Choose Excalidraw System when:

• You need to create or modify Excalidraw diagrams programmatically
• You want to integrate Excalidraw into your documentation workflow
• You need to process large Excalidraw files without consuming excessive context
• You want to convert between Excalidraw and other diagram formats
• You're building tools that generate visual diagrams in Excalidraw format

Consider alternatives when:

• You need SVG or Canvas drawing tools (use a draw framework skill)
• You want C4 architecture diagrams (use a C4 platform skill)
• You need general-purpose diagramming (use a diagramming skill)

Quick Start

Copy
# Install the skill
claude install excalidraw-system

# Create a diagram from description
claude "Create an Excalidraw diagram showing a microservices architecture with 4 services, an API gateway, and a message queue"

# Convert existing content
claude "Convert this Mermaid flowchart to an Excalidraw diagram: [paste mermaid code]"

# Process existing files
claude "Read the architecture.excalidraw file and list all the components and their connections"

Core Concepts

Excalidraw File Structure

Copy
{
  "type": "excalidraw",
  "version": 2,
  "elements": [
    {
      "type": "rectangle",
      "x": 100, "y": 100,
      "width": 200, "height": 80,
      "strokeColor": "#1e1e1e",
      "backgroundColor": "#a5d8ff",
      "fillStyle": "solid",
      "strokeWidth": 2,
      "roundness": { "type": 3 },
      "boundElements": [
        { "id": "text-id", "type": "text" },
        { "id": "arrow-id", "type": "arrow" }
      ]
    }
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  }
}

Element Types

Type	Use Case	Key Properties
rectangle	Boxes, containers	x, y, width, height, roundness
ellipse	Circles, nodes	x, y, width, height
diamond	Decision points	x, y, width, height
line	Connections (non-arrow)	points array
arrow	Directional connections	points, startBinding, endBinding
text	Labels, descriptions	text, fontSize, fontFamily
freedraw	Freehand sketches	points array
image	Embedded images	fileId references

Subagent Delegation Pattern

Main Agent → NEVER reads .excalidraw files directly
           → Delegates to subagent with specific task

Why: Excalidraw JSON has high token cost but low information density.
A 100-element diagram can be 50K+ tokens of JSON.

Delegation pattern:
1. Main agent identifies the task (add element, extract info, modify)
2. Spawns subagent with focused instructions
3. Subagent reads the file, performs the task, returns summary
4. Main agent uses the summary without consuming the raw JSON

Configuration

Parameter	Type	Default	Description
default_style	string	"hand-drawn"	Style: hand-drawn (Excalidraw default), architect (clean lines)
grid_size	number	20	Grid spacing in pixels
auto_layout	boolean	true	Automatically position elements
color_scheme	string	"default"	Colors: default, monochrome, pastel, vibrant
export_format	string	"excalidraw"	Export: excalidraw, svg, png

Best Practices

1. Delegate file reading to subagents — Excalidraw files are JSON-heavy with low information density. A 100-element diagram can be 50,000+ tokens. Always process them in a subagent to protect your main context window.

2. Use bound elements for labels — Attach text to shapes using boundElements rather than positioning text manually. Bound text moves with the shape and stays centered automatically.

3. Group related elements — Use the groupIds property to logically group elements that belong together. This allows users to move and select them as a unit in the Excalidraw editor.

4. Set consistent styling — Define a style palette (colors, stroke widths, font sizes) and apply it consistently. Excalidraw's hand-drawn aesthetic looks best with a limited color palette and consistent element sizes.

5. Auto-layout with grid alignment — When generating diagrams programmatically, snap elements to a grid (20px or 40px increments). This creates a clean, professional look that's easy to edit manually afterward.

Common Issues

Generated diagram elements overlap — Calculate positions programmatically based on element sizes plus spacing. Use a simple grid or tree layout algorithm to space elements before writing the JSON.

Arrow bindings not connecting properly — Set both startBinding and endBinding with the correct element IDs, and ensure the bound elements have matching entries in their boundElements array. Bindings are bidirectional.

File is too large for context — Use the subagent delegation pattern. Extract only the information you need (element types, text content, connections) rather than processing the full JSON. Consider building a summary tool that extracts a readable description from the Excalidraw JSON.