excalidraw-ai Skill | Agent Skills

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

| Property | Type | Description | |----------|------|-------------| | id | string | Unique identifier (use UUID or similar) | | type | string | rectangle, ellipse, diamond, text, arrow, line | | x, y | number | Position coordinates | | width, height | number | Dimensions | | strokeColor | string | Border/stroke color (hex) | | backgroundColor | string | Fill color (hex) or "transparent" | | fillStyle | string | "solid", "hachure", "cross-hatch" | | strokeWidth | number | Line thickness (1, 2, 4) | | strokeStyle | string | "solid", "dashed", "dotted" | | roughness | number | 0 = sharp, 1 = normal, 2 = sketchy | | opacity | number | 0-100 | | angle | number | Rotation in radians | | groupIds | array | Group element IDs together | | seed | number | Random seed for hand-drawn effect |

Text Properties

| Property | Type | Description | |----------|------|-------------| | text | string | The text content | | fontSize | number | Font size in pixels | | fontFamily | number | 1 = Virgil (hand-drawn), 2 = Helvetica, 3 = Cascadia | | textAlign | string | "left", "center", "right" | | verticalAlign | string | "top", "middle" |

Arrow Properties

| Property | Type | Description | |----------|------|-------------| | points | array | Array of [x, y] coordinates relative to element origin | | startBinding | object | Connection to source element | | endBinding | object | Connection to target element | | startArrowhead | string | null, "arrow", "bar", "dot", "triangle" | | endArrowhead | string | null, "arrow", "bar", "dot", "triangle" |

Color Palette Reference

Component-Based Colors (Recommended for Architecture Diagrams)

| Component Type | Stroke | Background | Use For | |----------------|--------|------------|---------| | Database | #7c3aed | #ede9fe | PostgreSQL, MySQL, MongoDB | | Cache | #dc2626 | #fee2e2 | Redis, Memcached | | Queue | #16a34a | #dcfce7 | Kafka, RabbitMQ, SQS | | Load Balancer | #0891b2 | #cffafe | Nginx, HAProxy, ALB | | Gateway | #475569 | #f1f5f9 | API Gateway, Kong | | CDN | #06b6d4 | #e0f2fe | CloudFront, Fastly | | Auth | #e11d48 | #ffe4e6 | OAuth, IAM, Cognito | | Storage | #d97706 | #fef3c7 | S3, Blob Storage | | Service | #2563eb | #dbeafe | Backend services, APIs | | Container | #0284c7 | #bae6fd | Docker, Kubernetes | | Function | #f59e0b | #fef3c7 | Lambda, Serverless | | Monitoring | #84cc16 | #ecfccb | Prometheus, Grafana | | Web App | #4f46e5 | #e0e7ff | React, Vue, Frontend | | Mobile | #6366f1 | #eef2ff | iOS, Android |

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:

| Library | Components | Content | |---------|------------|---------| | aws-architecture-icons.excalidrawlib | 248 | AWS service icons (Lambda, S3, EC2, RDS, DynamoDB, SQS, etc.) | | system-design.excalidrawlib | 24 | System design elements (server, database, storage, etc.) | | drwnio.excalidrawlib | 18 | Draw.io style icons | | system-design-template.excalidrawlib | 8 | Pre-built templates (steps, flow, db, etc.) | | software-architecture.excalidrawlib | 7 | Software architecture components |

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

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

Agent Skills: excalidraw-ai

Install this agent skill to your local

Skill Files