Excalidraw Diagrams

/excalidraw

Work with Excalidraw diagrams (.excalidraw / .excalidraw.json). Ask the user to paste or upload the diagram file when operating on an existing one; deliver new or modified diagrams as complete JSON chat artifacts the user can open at excalidraw.com or save as a .excalidraw file.

Understanding the Format (Why Discipline Matters)

Excalidraw files are JSON with high token cost but low information density:

• Each shape has 20+ properties (x, y, width, height, strokeColor, seed, version, etc.)
• Most properties are visual metadata (positioning, styling, roughness)
• Actual content is the text labels and element relationships (<10% of the file)
• Signal-to-noise ratio is extremely low; a 14-element diagram can be ~600 lines, a 79-element diagram ~3,000 lines

Consequences for how you work:

• When ANALYZING a diagram, extract only text elements and relationships; never echo raw JSON or verbose element details back to the user.
• When MODIFYING, change only the elements involved; do not restyle or renumber untouched elements.
• When CREATING, keep the element count purposeful; every box costs hundreds of tokens.
• Token cost comes from volume, not complexity -- "the JSON is straightforward" is not a reason to dump it into the conversation.

When to Use

Trigger on ANY of these:

• The user pastes or uploads a .excalidraw or .excalidraw.json file
• Requests like "explain/update/create diagram", "show architecture", "visualize flow" with a hand-drawn/whiteboard aesthetic
• Mentions of "flowchart", "architecture diagram", "Excalidraw file"
• Architecture/design documentation tasks involving visual artifacts

For text-based diagrams embeddable in Markdown, use mermaid-diagrams instead.

Operation Playbooks

Read/Understand

Task: Extract and explain the components in the pasted .excalidraw JSON

Approach:
1. Parse the JSON the user provided
2. Extract only text elements (ignore positioning/styling)
3. Identify relationships between components (arrows: startBinding/endBinding element IDs)
4. Summarize architecture/flow

Return:
- List of components/services with descriptions
- Connection/dependency relationships
- Key insights about the architecture
- DO NOT return raw JSON or verbose element details

Modify

Task: Add [component] connected to [existing-component]

Approach:
1. Scan the provided file to identify existing elements
2. Find [existing-component] and its position
3. Create new element JSON for [component] with a fresh unique id, sensible x/y
   near the related element, and styling consistent with neighbors
4. Add arrow elements with startBinding/endBinding referencing the element ids
5. Deliver the complete updated file as a downloadable/pastable artifact

Return:
- The full updated JSON artifact
- A short note: what changed, position of the new element, ids created

Create

Task: Create a new Excalidraw diagram showing [description]

Approach:
1. Design the layout for [number] components (grid or layered flow; leave
   generous spacing, ~100px+ between boxes)
2. Create rectangle elements with bound text labels
3. Add arrows showing relationships
4. Use consistent styling (colors, fonts, strokeWidth)
5. Wrap in the standard envelope:
   {"type": "excalidraw", "version": 2, "source": "...", "elements": [...],
    "appState": {"viewBackgroundColor": "#ffffff"}, "files": {}}

Return:
- The complete JSON artifact ready to save as diagram.excalidraw
- A one-paragraph summary of the components included

Compare

Task: Compare architecture approaches in two pasted diagrams

Approach:
1. Parse both files
2. Extract text labels from each
3. Identify structural differences
4. Compare component relationships

Return:
- Key differences in architecture
- Components unique to each approach
- Relationship/flow differences
- DO NOT return full element details from both files

Quick Reference

Red Flags -- Stop and Refocus

Catch yourself about to:

• Quote large blocks of element JSON while "explaining" a diagram
• Restate positioning/styling metadata the user did not ask about
• Rebuild an entire file when only one element changed (for large files, you may instead deliver just the new/changed elements with exact insertion instructions)
• Compare diagrams by dumping both side-by-side

All of these mean: extract the text labels and relationships, work on those, and keep the raw JSON confined to the deliverable artifact.

The Iron Law

Raw Excalidraw JSON belongs in the deliverable artifact, never in the explanation. Summaries are text; diagrams are files.

Usage

/excalidraw $ARGUMENTS