home / skills / jiatastic / open-python-skills / excalidraw-ai
This skill generates Excalidraw-compatible diagrams by emitting exact JSON using the Excalidraw schema, enabling precise architecture visuals without templates.
npx playbooks add skill jiatastic/open-python-skills --skill excalidraw-aiReview the files below or copy the command above to add this skill to your agents.
---
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:
```json
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [ /* array of element objects */ ],
"appState": {
"viewBackgroundColor": "#ffffff",
"gridSize": null
},
"files": {}
}
```
### Element Types
#### Rectangle
```json
{
"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
```json
{
"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
```json
{
"id": "unique-id-3",
"type": "diamond",
"x": 100,
"y": 100,
"width": 120,
"height": 120,
"strokeColor": "#dc2626",
"backgroundColor": "#fee2e2",
"fillStyle": "solid"
}
```
#### Text
```json
{
"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
```json
{
"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
```json
{
"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
```json
{
"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](https://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
This skill generates professional Excalidraw diagrams by producing Excalidraw JSON directly. It supplies the JSON schema reference, element property guidance, color palettes, layout rules, and ready-to-use icon libraries so an AI agent can build diagrams autonomously without templates. Use it to programmatically compose architecture diagrams, flowcharts, mind maps, and system visuals with pixel-level control.
The skill outputs a complete Excalidraw JSON object containing elements, appState, and files. It knows element types (rectangle, ellipse, diamond, text, arrow, line), required properties (position, size, colors, styles), library components, and binding rules for connections. Agents embed library items, compute positions using layout guidelines, generate unique IDs and seeds, and return a .excalidraw/.json payload ready for import or export to PNG/SVG.
What file formats can I export?
Return a .excalidraw or .json payload that can be imported into Excalidraw; Excalidraw can export PNG/SVG.
How do I keep arrows attached when moving shapes?
Use startBinding and endBinding referencing elementId, set focus and gap values, and include stable groupIds when needed.
Can I reuse icon libraries?
Yes. Parse the .excalidrawlib arrays, adjust positions, and merge their element arrays into your diagram's elements.