name: excalidraw-ai
description: >
Create professional Excalidraw diagrams by generating JSON directly.
This skill provides the Excalidraw JSON schema reference and professional icon libraries
for AI agents to autonomously create diagrams without templates.

excalidraw-ai

Generate Excalidraw diagrams by writing JSON directly. No templates needed - you have full control over every element.

When to Use This Skill

Use this skill when you need to:
- Create architecture diagrams, flowcharts, or mind maps
- Visualize system designs, data flows, or processes
- Generate diagrams from code analysis or documentation
- Create custom diagrams with precise control over layout and styling

Excalidraw JSON Schema

An Excalidraw file is a JSON object with this structure:

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

Element Types

Rectangle

{
  "id": "unique-id-1",
  "type": "rectangle",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 100,
  "strokeColor": "#1971c2",
  "backgroundColor": "#a5d8ff",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "angle": 0,
  "seed": 12345,
  "isDeleted": false
}

Ellipse

{
  "id": "unique-id-2",
  "type": "ellipse",
  "x": 100,
  "y": 100,
  "width": 150,
  "height": 100,
  "strokeColor": "#7c3aed",
  "backgroundColor": "#ede9fe",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "roughness": 1
}

Diamond

{
  "id": "unique-id-3",
  "type": "diamond",
  "x": 100,
  "y": 100,
  "width": 120,
  "height": 120,
  "strokeColor": "#dc2626",
  "backgroundColor": "#fee2e2",
  "fillStyle": "solid"
}

Text

{
  "id": "unique-id-4",
  "type": "text",
  "x": 110,
  "y": 140,
  "width": 180,
  "height": 25,
  "text": "Your Label Here",
  "fontSize": 20,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "middle",
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent"
}

Arrow

{
  "id": "unique-id-5",
  "type": "arrow",
  "x": 300,
  "y": 150,
  "width": 100,
  "height": 50,
  "strokeColor": "#1971c2",
  "strokeWidth": 2,
  "points": [[0, 0], [100, 50]],
  "startBinding": {
    "elementId": "source-element-id",
    "focus": 0.5,
    "gap": 5
  },
  "endBinding": {
    "elementId": "target-element-id",
    "focus": 0.5,
    "gap": 5
  },
  "startArrowhead": null,
  "endArrowhead": "arrow"
}

Line

{
  "id": "unique-id-6",
  "type": "line",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 0,
  "strokeColor": "#868e96",
  "strokeWidth": 1,
  "points": [[0, 0], [200, 0]],
  "startArrowhead": null,
  "endArrowhead": null
}

Element Properties Reference

Text Properties

Arrow Properties

Color Palette Reference

Component-Based Colors (Recommended for Architecture Diagrams)

Theme Colors

Modern (Default)
- Primary: #1971c2 / #e7f5ff
- Neutral: #64748b / #f1f5f9

Sketchy (Hand-drawn)
- Primary: #495057 / #f8f9fa
- Use roughness: 2 and fontFamily: 3

Technical
- Primary: #2f9e44 / #ebfbee
- Use strokeStyle: "dashed" for connections

Icon Libraries (305 Components Total)

Professional icons are available in .excalidrawlib files in the assets/ directory:

Using Library Components

Library files contain element arrays that can be embedded directly into your diagram. Each library item is an array of Excalidraw elements that form a component.

To use: Parse the library JSON, find the component you need, adjust positions, and include in your diagram's elements array.

Layout Guidelines

Architecture Diagram Layout

Organize components in layers (top to bottom):

Layer 1: Client/External (y: 100)
Layer 2: Edge/CDN (y: 280)
Layer 3: Gateway/Load Balancer (y: 460)
Layer 4: Services (y: 640)
Layer 5: Data/Cache (y: 820)
Layer 6: Infrastructure (y: 1000)

Spacing recommendations:
- Horizontal spacing between components: 240px
- Vertical spacing between layers: 180px
- Component width: 180-220px
- Component height: 80-100px

Flowchart Layout

Arrange left-to-right or top-to-bottom:
- Step spacing: 200px
- Use rectangles for processes
- Use diamonds for decisions
- Use ellipses for start/end

Mind Map Layout

Radial layout from center:
- Center node at (400, 300)
- Child nodes at radius 250px
- Distribute evenly using angle calculations

Complete Example

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    {
      "id": "api-gateway",
      "type": "rectangle",
      "x": 100,
      "y": 100,
      "width": 180,
      "height": 80,
      "strokeColor": "#475569",
      "backgroundColor": "#f1f5f9",
      "fillStyle": "solid",
      "strokeWidth": 2,
      "roughness": 0,
      "opacity": 100,
      "groupIds": ["group-1"],
      "seed": 1234
    },
    {
      "id": "api-gateway-label",
      "type": "text",
      "x": 140,
      "y": 130,
      "width": 100,
      "height": 25,
      "text": "API Gateway",
      "fontSize": 16,
      "fontFamily": 1,
      "textAlign": "center",
      "strokeColor": "#1e1e1e",
      "groupIds": ["group-1"]
    },
    {
      "id": "redis",
      "type": "diamond",
      "x": 100,
      "y": 280,
      "width": 180,
      "height": 100,
      "strokeColor": "#dc2626",
      "backgroundColor": "#fee2e2",
      "fillStyle": "solid",
      "strokeWidth": 2,
      "roughness": 0,
      "seed": 5678
    },
    {
      "id": "redis-label",
      "type": "text",
      "x": 155,
      "y": 320,
      "width": 70,
      "height": 20,
      "text": "Redis",
      "fontSize": 16,
      "fontFamily": 1,
      "textAlign": "center",
      "strokeColor": "#1e1e1e"
    },
    {
      "id": "arrow-1",
      "type": "arrow",
      "x": 190,
      "y": 180,
      "width": 0,
      "height": 100,
      "strokeColor": "#64748b",
      "strokeWidth": 2,
      "points": [[0, 0], [0, 100]],
      "startBinding": {"elementId": "api-gateway", "focus": 0.5, "gap": 5},
      "endBinding": {"elementId": "redis", "focus": 0.5, "gap": 5},
      "endArrowhead": "arrow"
    }
  ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  },
  "files": {}
}

Output

Save your diagram as a .excalidraw or .json file. It can be:
- Imported directly into excalidraw.com
- Embedded in documentation or web apps
- Converted to PNG/SVG using Excalidraw's export features

Tips for AI Agents

1. Generate unique IDs: Use UUIDs or sequential IDs for each element
2. Group related elements: Use groupIds to keep shapes and their labels together
3. Use bindings for arrows: Connect arrows to elements using startBinding and endBinding
4. Apply consistent styling: Use the color palette for component types
5. Calculate text positions: Center text within shapes by adjusting x/y based on text length
6. Set seed values: Use seed: hash(id) for consistent hand-drawn rendering