excalidraw

name	excalidraw
description	Create and edit Excalidraw diagrams programmatically. Use when the user asks to create diagrams, flowcharts, architecture diagrams, wireframes, or any visual drawings in Excalidraw format (.excalidraw files).

Excalidraw Diagram Creation

This skill enables you to create beautiful, hand-drawn style diagrams in the Excalidraw JSON format.

File Format Overview

Excalidraw files (.excalidraw) are JSON with this structure:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

Quick Start - Creating Elements

Every element needs at minimum: type, id, x, y, and styling properties.

Minimal Rectangle

{
  "type": "rectangle",
  "id": "rect-1",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 100,
  "angle": 0,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "seed": 1234,
  "version": 1,
  "versionNonce": 1234,
  "isDeleted": false,
  "groupIds": [],
  "boundElements": null,
  "link": null,
  "locked": false,
  "roundness": { "type": 3 }
}

Text Element

{
  "type": "text",
  "id": "text-1",
  "x": 120,
  "y": 130,
  "width": 160,
  "height": 25,
  "text": "Hello World",
  "fontSize": 20,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "middle",
  "angle": 0,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "seed": 5678,
  "version": 1,
  "versionNonce": 5678,
  "isDeleted": false,
  "groupIds": [],
  "boundElements": null,
  "link": null,
  "locked": false,
  "containerId": null,
  "originalText": "Hello World",
  "autoResize": true,
  "lineHeight": 1.25
}

Arrow Element

{
  "type": "arrow",
  "id": "arrow-1",
  "x": 300,
  "y": 150,
  "width": 100,
  "height": 0,
  "points": [[0, 0], [100, 0]],
  "startArrowhead": null,
  "endArrowhead": "arrow",
  "startBinding": null,
  "endBinding": null,
  "angle": 0,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "seed": 9012,
  "version": 1,
  "versionNonce": 9012,
  "isDeleted": false,
  "groupIds": [],
  "boundElements": null,
  "link": null,
  "locked": false
}

Element Types

Type	Use For
rectangle	Boxes, containers, cards
ellipse	Circles, ovals, nodes
diamond	Decision points, conditions
text	Labels, descriptions
arrow	Connections, flow direction
line	Connectors without arrowheads
freedraw	Hand-drawn paths
image	Embedded images
frame	Grouping/framing elements

Color Palette (Recommended)

Backgrounds

• #a5d8ff - Light blue
• #b2f2bb - Light green
• #ffec99 - Light yellow
• #ffc9c9 - Light red/pink
• #e9ecef - Light gray
• #d0bfff - Light purple
• #99e9f2 - Light cyan

Strokes

• #1e1e1e - Default black
• #1971c2 - Blue
• #2f9e44 - Green
• #f08c00 - Orange
• #e03131 - Red
• #9c36b5 - Purple

Styling Properties

Property	Values	Description
fillStyle	"solid", "hachure", "cross-hatch"	Fill pattern
strokeWidth	1, 2, 4	Line thickness
strokeStyle	"solid", "dashed", "dotted"	Line style
roughness	0, 1, 2	Hand-drawn feel (0=smooth, 2=rough)
opacity	0-100	Transparency
roundness	{ "type": 3 }	Rounded corners

Connecting Elements with Arrows

To connect shapes with arrows, use bindings:

{
  "type": "arrow",
  "id": "arrow-1",
  "startBinding": {
    "elementId": "rect-1",
    "focus": 0,
    "gap": 5
  },
  "endBinding": {
    "elementId": "rect-2",
    "focus": 0,
    "gap": 5
  },
  "points": [[0, 0], [200, 0]]
}

Also add boundElements to the connected shapes:

{
  "type": "rectangle",
  "id": "rect-1",
  "boundElements": [{ "id": "arrow-1", "type": "arrow" }]
}

Font Families

Value	Font
1	Hand-drawn (Virgil)
2	Normal (Helvetica)
3	Code (Cascadia)

Best Practices

1. Generate unique IDs - Use descriptive prefixes like rect-1, arrow-2, text-header
2. Use random seeds - Each element needs a unique seed for consistent rendering
3. Space elements well - Leave 50-100px between elements
4. Align elements - Use consistent x/y coordinates for visual alignment
5. Group related items - Use matching groupIds arrays
6. Use the color palette - Stick to Excalidraw's built-in colors for consistency

Diagram Types You Can Create

Type	Description
Flowcharts	Process flows, algorithms, decision trees
Sequence Diagrams	API calls, user interactions, message flows
Architecture Diagrams	System design, microservices, infrastructure
Mind Maps	Brainstorming, concept mapping, idea organization
Data Flow Diagrams	Data movement, system analysis
ERD	Database schemas, entity relationships
Wireframes	UI mockups, layout sketches

Reference Documentation

• diagram-patterns.md - Professional patterns for each diagram type (flowcharts, sequence diagrams, mind maps, architecture, etc.)
• examples.md - Complete working JSON examples you can use as templates
• element-reference.md - Full property reference for all element types
• best-practices.md - Design tips, color theory, typography guidelines

Quick Tips for Beautiful Diagrams

1. Use roughness: 0 for formal/technical diagrams, roughness: 1 for friendly sketches
2. Use fontFamily: 2 (Helvetica) for professional look, fontFamily: 1 (Virgil) only when casual look is requested
3. Consistent spacing - 100px between major elements, 50px for related items
4. Color semantics - Blue for info/input, Green for success/data, Yellow for decisions, Red for errors
5. Arrow conventions - Solid for actions, Dashed for responses/async