Excalidraw Diagram Generator

A skill for generating Excalidraw-format diagrams from natural language descriptions. This skill helps create visual representations of processes, systems, relationships, and ideas without manual drawing.

When to Use This Skill

Use this skill when users request:

- "Create a diagram showing..."
"Make a flowchart for..."
"Visualize the process of..."
"Draw the system architecture of..."
"Generate a mind map about..."
"Create an Excalidraw file for..."
"Show the relationship between..."
"Diagram the workflow of..."

Supported diagram types:

- 📊 Flowcharts: Sequential processes, workflows, decision trees
🔗 Relationship Diagrams: Entity relationships, system components, dependencies
🧠 Mind Maps: Concept hierarchies, brainstorming results, topic organization
🏗️ Architecture Diagrams: System design, module interactions, data flow
📈 Data Flow Diagrams (DFD): Data flow visualization, data transformation processes
🏊 Business Flow (Swimlane): Cross-functional workflows, actor-based process flows
📦 Class Diagrams: Object-oriented design, class structures and relationships
🔄 Sequence Diagrams: Object interactions over time, message flows
🗃️ ER Diagrams: Database entity relationships, data models

Prerequisites

- Clear description of what should be visualized
Identification of key entities, steps, or concepts
Understanding of relationships or flow between elements

Step-by-Step Workflow

Step 1: Understand the Request

Analyze the user's description to determine:

1. Diagram type (flowchart, relationship, mind map, architecture)
Key elements (entities, steps, concepts)
Relationships (flow, connections, hierarchy)
Complexity (number of elements)

Step 2: Choose the Appropriate Diagram Type

User Intent	Diagram Type	Example Keywords
Process flow, steps, procedures	Flowchart	"workflow", "process", "steps", "procedure"
Connections, dependencies, associations

Step 3: Extract Structured Information

For Flowcharts:

- List of sequential steps
Decision points (if any)
Start and end points

For Relationship Diagrams:

- Entities/nodes (name + optional description)
Relationships between entities (from → to, with label)

For Mind Maps:

- Central topic
Main branches (3-6 recommended)
Sub-topics for each branch (optional)

For Data Flow Diagrams (DFD):

- Data sources and destinations (external entities)
Processes (data transformations)
Data stores (databases, files)
Data flows (arrows showing data movement from left-to-right or from top-left to bottom-right)
Important: Do not represent process order, only data flow

For Business Flow (Swimlane):

- Actors/roles (departments, systems, people) - displayed as header columns
Process lanes (vertical lanes under each actor)
Process boxes (activities within each lane)
Flow arrows (connecting process boxes, including cross-lane handoffs)

For Class Diagrams:

- Classes with names
Attributes with visibility (+, -, #)
Methods with visibility and parameters
Relationships: inheritance (solid line + white triangle), implementation (dashed line + white triangle), association (solid line), dependency (dashed line), aggregation (solid line + white diamond), composition (solid line + filled diamond)
Multiplicity notations (1, 0..1, 1.., )

For Sequence Diagrams:

- Objects/actors (arranged horizontally at top)
Lifelines (vertical lines from each object)
Messages (horizontal arrows between lifelines)
Synchronous messages (solid arrow), asynchronous messages (dashed arrow)
Return values (dashed arrows)
Activation boxes (rectangles on lifelines during execution)
Time flows from top to bottom

For ER Diagrams:

- Entities (rectangles with entity names)
Attributes (listed inside entities)
Primary keys (underlined or marked with PK)
Foreign keys (marked with FK)
Relationships (lines connecting entities)
Cardinality: 1:1 (one-to-one), 1:N (one-to-many), N:M (many-to-many)
Junction/associative entities for many-to-many relationships (dashed rectangles)

Step 4: Generate the Excalidraw JSON

Create the .excalidraw file with appropriate elements:

Available element types:

- rectangle: Boxes for entities, steps, concepts
INLINECODE2: Alternative shapes for emphasis
INLINECODE3: Decision points
INLINECODE4: Directional connections
INLINECODE5: Labels and annotations

Key properties to set:

- Position: x, y coordinates
Size: width, INLINECODE9
Style: strokeColor, backgroundColor, INLINECODE12
Font: fontFamily: 5 (Excalifont - required for all text elements)
Text: Embedded text for labels
Connections: points array for arrows

Important: All text elements must use fontFamily: 5 (Excalifont) for consistent visual appearance.

Step 5: Format the Output

Structure the complete Excalidraw file:

CODEBLOCK0

Step 6: Save and Provide Instructions

1. Save as INLINECODE16
Inform user how to open:

- Visit https://excalidraw.com - Click "Open" or drag-and-drop the file - Or use Excalidraw VS Code extension

Best Practices

Element Count Guidelines

Diagram Type	Recommended Count	Maximum
Flowchart steps	3-10	15
Relationship entities

3-8 | 12 | | Mind map branches | 4-6 | 8 | | Mind map sub-topics per branch | 2-4 | 6 |

Layout Tips

1. Start positions: Center important elements, use consistent spacing
Spacing:

- Horizontal gap: 200-300px between elements - Vertical gap: 100-150px between rows

3. Colors: Use consistent color scheme

- Primary elements: Light blue (#a5d8ff) - Secondary elements: Light green (#b2f2bb) - Important/Central: Yellow (#ffd43b) - Alerts/Warnings: Light red (#ffc9c9)

4. Text sizing: 16-24px for readability
Font: Always use fontFamily: 5 (Excalifont) for all text elements
Arrow style: Use straight arrows for simple flows, curved for complex relationships

Complexity Management

If user request has too many elements:

- Suggest breaking into multiple diagrams
Focus on main elements first
Offer to create detailed sub-diagrams

Example response:
CODEBLOCK1

Example Prompts and Responses

Example 1: Simple Flowchart

User: "Create a flowchart for user registration"

Agent generates:

1. Extract steps: "Enter email" → "Verify email" → "Set password" → "Complete"
Create flowchart with 4 rectangles + 3 arrows
Save as INLINECODE22

Example 2: Relationship Diagram

User: "Diagram the relationship between User, Post, and Comment entities"

Agent generates:

1. Entities: User, Post, Comment
Relationships: User → Post ("creates"), User → Comment ("writes"), Post → Comment ("contains")
Save as INLINECODE23

Example 3: Mind Map

User: "Mind map about machine learning concepts"

Agent generates:

1. Center: "Machine Learning"
Branches: Supervised Learning, Unsupervised Learning, Reinforcement Learning, Deep Learning
Sub-topics under each branch
Save as INLINECODE24

Troubleshooting

Issue	Solution
Elements overlap	Increase spacing between coordinates
Text doesn't fit in boxes

Advanced Techniques

Grid Layout (for Relationship Diagrams)

CODEBLOCK2

Radial Layout (for Mind Maps)

CODEBLOCK3

Auto-generated IDs

Use timestamp + random string for unique IDs: CODEBLOCK4

Output Format

Always provide:

1. ✅ Complete .excalidraw JSON file
📊 Summary of what was created
📝 Element count
💡 Instructions for opening/editing

Example summary:
CODEBLOCK5

Validation Checklist

Before delivering the diagram:

- [ ] All elements have unique IDs
[ ] Coordinates prevent overlapping
[ ] Text is readable (font size 16+)
[ ] All text elements use fontFamily: 5 (Excalifont)
[ ] Arrows connect logically
[ ] Colors follow consistent scheme
[ ] File is valid JSON
[ ] Element count is reasonable (<20 for clarity)

Icon Libraries (Optional Enhancement)

For specialized diagrams (e.g., AWS/GCP/Azure architecture diagrams), you can use pre-made icon libraries from Excalidraw. This provides professional, standardized icons instead of basic shapes.

When User Requests Icons

If user asks for AWS/cloud architecture diagrams or mentions wanting to use specific icons:

1. Check if library exists: Look for INLINECODE27
If library exists: Proceed to use icons (see AI Assistant Workflow below)
If library does NOT exist: Respond with setup instructions:

CODEBLOCK6

User Setup Instructions (Detailed)

Step 1: Create Library Directory
CODEBLOCK7

Step 2: Download Library

- Visit: https://libraries.excalidraw.com/
Search for your desired icon set (e.g., "AWS Architecture Icons")
Click download to get the .excalidrawlib file
Example categories (availability varies; confirm on the site):

- Cloud service icons
- UI/Material icons
- Flowchart symbols

Step 3: Place Library File

- Rename the downloaded file to match the directory name (e.g., aws-architecture-icons.excalidrawlib)
Move it to the directory created in Step 1

Step 4: Run Splitter Script
CODEBLOCK8

Step 5: Verify Setup
After running the script, verify the following structure exists:
CODEBLOCK9

AI Assistant Workflow

When icon libraries are available in libraries/:

RECOMMENDED APPROACH: Use Python Scripts (Efficient & Reliable)

The repository includes Python scripts that handle icon integration automatically:

1. Create base diagram structure:

- Create .excalidraw file with basic layout (title, boxes, regions) - This establishes the canvas and overall structure

2. Add icons using Python script:

   python skills/excalidraw-diagram-generator/scripts/add-icon-to-diagram.py \
     <diagram-path> <icon-name> <x> <y> [--label "Text"] [--library-path PATH]

- Edit via .excalidraw.edit is enabled by default to avoid overwrite issues; pass --no-use-edit-suffix to disable.

Examples:
CODEBLOCK11

3. Add connecting arrows:

   python skills/excalidraw-diagram-generator/scripts/add-arrow.py \
     <diagram-path> <from-x> <from-y> <to-x> <to-y> [--label "Text"] [--style solid|dashed|dotted] [--color HEX]

- Edit via .excalidraw.edit is enabled by default to avoid overwrite issues; pass --no-use-edit-suffix to disable.

Examples:
CODEBLOCK13

4. Workflow summary:

CODEBLOCK14

Benefits of Python Script Approach:

- ✅ No token consumption: Icon JSON data (200-1000 lines each) never enters AI context
✅ Accurate transformations: Coordinate calculations handled deterministically
✅ ID management: Automatic UUID generation prevents conflicts
✅ Reliable: No risk of coordinate miscalculation or ID collision
✅ Fast: Direct file manipulation, no parsing overhead
✅ Reusable: Works with any Excalidraw library you provide

ALTERNATIVE: Manual Icon Integration (Not Recommended)

Only use this if Python scripts are unavailable:

1. Check for libraries:

CODEBLOCK15

2. Read reference.md:

CODEBLOCK16

3. Find relevant icons:

CODEBLOCK17

4. Load specific icon data (WARNING: Large files):

CODEBLOCK18

5. Extract and transform elements:

CODEBLOCK19

6. Position icons and add connections:

CODEBLOCK20

Manual Integration Challenges:

- ⚠️ High token consumption (200-1000 lines per icon × number of icons)
⚠️ Complex coordinate transformation calculations
⚠️ Risk of ID collision if not handled carefully
⚠️ Time-consuming for diagrams with many icons

Example: Creating AWS Diagram with Icons

Request: "Create an AWS architecture diagram with Internet Gateway, VPC, ELB, EC2, and RDS"

Recommended Workflow (using Python scripts):
Request: "Create an AWS architecture diagram with Internet Gateway, VPC, ELB, EC2, and RDS"

Recommended Workflow (using Python scripts):

CODEBLOCK21

Benefits:

- No manual coordinate calculation
No token consumption for icon data
Deterministic, reliable results
Easy to iterate and adjust positions

Alternative Workflow (manual, if scripts unavailable):

1. Check: libraries/aws-architecture-icons/reference.md exists → Yes
Read reference.md → Find entries for Internet-gateway, VPC, ELB, EC2, RDS
Load:

- icons/Internet-gateway.json (298 lines)
- icons/VPC.json (550 lines)
- icons/ELB.json (363 lines)
- icons/EC2.json (231 lines)
- icons/RDS.json (similar size)
Total: ~2000+ lines of JSON to process

4. Extract elements from each JSON
Calculate bounding boxes and offsets for each icon
Transform all coordinates (x, y) for positioning
Generate unique IDs for all elements
Add arrows showing data flow
Add text labels
Generate final .excalidraw file

Challenges with manual approach:

- High token consumption (~2000-5000 lines)
Complex coordinate math
Risk of ID conflicts

Supported Icon Libraries (Examples — verify availability)

- This workflow works with any valid .excalidrawlib file you provide.
Examples of library categories you may find on https://libraries.excalidraw.com/:

- Cloud service icons - Kubernetes / infrastructure icons - UI / Material icons - Flowchart / diagram symbols - Network diagram icons

- Availability and naming can change; verify exact library names on the site before use.

Fallback: No Icons Available

If no icon libraries are set up:

- Create diagrams using basic shapes (rectangles, ellipses, arrows)
Use color coding and text labels to distinguish components
Inform user they can add icons later or set up libraries for future diagrams
The diagram will still be functional and clear, just less visually polished

References

See bundled references for:

- references/excalidraw-schema.md - Complete Excalidraw JSON schema
INLINECODE45 - Detailed element type specifications
INLINECODE46 - Basic flowchart starter
INLINECODE47 - Relationship diagram starter
INLINECODE48 - Mind map starter
INLINECODE49 - Tool to split .excalidrawlib files
INLINECODE51 - Documentation for library tools
INLINECODE52 - Prevents local Python artifacts from being committed

Limitations

- Complex curves are simplified to straight/basic curved lines
Hand-drawn roughness is set to default (1)
No embedded images support in auto-generation
Maximum recommended elements: 20 per diagram
No automatic collision detection (use spacing guidelines)

Future Enhancements

Potential improvements:

- Auto-layout optimization algorithms
Import from Mermaid/PlantUML syntax
Template library expansion
Interactive editing after generation

Excalidraw 图表生成器

一个根据自然语言描述生成 Excalidraw 格式图表的技能。此技能帮助创建流程、系统、关系和想法的可视化表示，无需手动绘制。

何时使用此技能

当用户请求以下内容时使用此技能：

- 创建一个图表显示...
制作一个关于...的流程图
可视化...的过程
绘制...的系统架构
生成一个关于...的思维导图
创建一个关于...的 Excalidraw 文件
展示...之间的关系
绘制...的工作流程

支持的图表类型：

- 📊 流程图：顺序流程、工作流、决策树
🔗 关系图：实体关系、系统组件、依赖关系
🧠 思维导图：概念层级、头脑风暴结果、主题组织
🏗️ 架构图：系统设计、模块交互、数据流
📈 数据流图 (DFD)：数据流可视化、数据转换过程
🏊 业务流程图 (泳道图)：跨职能工作流、基于角色的流程
📦 类图：面向对象设计、类结构和关系
🔄 时序图：对象随时间变化的交互、消息流
🗃️ ER 图：数据库实体关系、数据模型

先决条件

- 清晰描述需要可视化的内容
识别关键实体、步骤或概念
理解元素之间的关系或流程

分步工作流程

第1步：理解请求

分析用户的描述以确定：

1. 图表类型（流程图、关系图、思维导图、架构图）
关键元素（实体、步骤、概念）
关系（流程、连接、层级）
复杂度（元素数量）

第2步：选择合适的图表类型

用户意图	图表类型	示例关键词
流程、步骤、程序	流程图	工作流、流程、步骤、程序
连接、依赖、关联

第3步：提取结构化信息

对于流程图：

- 顺序步骤列表
决策点（如果有）
起点和终点

对于关系图：

- 实体/节点（名称 + 可选描述）
实体之间的关系（从 → 到，带标签）

对于思维导图：

- 中心主题
主要分支（建议3-6个）
每个分支的子主题（可选）

对于数据流图 (DFD)：

- 数据源和目标（外部实体）
处理过程（数据转换）
数据存储（数据库、文件）
数据流（箭头显示数据从左到右或从左上到右下的移动）
重要：不表示处理顺序，仅表示数据流

对于业务流程图 (泳道图)：

- 角色/参与者（部门、系统、人员）- 显示为标题列
流程泳道（每个参与者下的垂直泳道）
流程框（每个泳道内的活动）
流程箭头（连接流程框，包括跨泳道交接）

对于类图：

- 带名称的类
带可见性的属性（+、-、#）
带可见性和参数的方法
关系：继承（实线 + 白色三角形）、实现（虚线 + 白色三角形）、关联（实线）、依赖（虚线）、聚合（实线 + 白色菱形）、组合（实线 + 实心菱形）
多重性标注（1、0..1、1..、）

对于时序图：

- 对象/角色（水平排列在顶部）
生命线（每个对象的垂直线）
消息（生命线之间的水平箭头）
同步消息（实线箭头）、异步消息（虚线箭头）
返回值（虚线箭头）
激活框（执行期间生命线上的矩形）
时间从上到下流动

对于ER图：

- 实体（带实体名称的矩形）
属性（列在实体内部）
主键（下划线或标记为PK）
外键（标记为FK）
关系（连接实体的线）
基数：1:1（一对一）、1:N（一对多）、N:M（多对多）
多对多关系的连接/关联实体（虚线矩形）

第4步：生成 Excalidraw JSON

创建包含适当元素的 .excalidraw 文件：

可用的元素类型：

- rectangle：用于实体、步骤、概念的框
ellipse：用于强调的替代形状
diamond：决策点
arrow：方向性连接
text：标签和注释

要设置的关键属性：

- 位置：x、y 坐标
大小：width、height
样式：strokeColor、backgroundColor、fillStyle
字体：fontFamily: 5（Excalifont - 所有文本元素必需）
文本：标签的嵌入文本
连接：箭头的 points 数组

重要：所有文本元素必须使用 fontFamily: 5（Excalifont）以保持一致的视觉外观。

第5步：格式化输出

构建完整的 Excalidraw 文件：

json
{
type: excalidraw,
version: 2,
source: https://excalidraw.com,
elements: [
// 图表元素数组
],
appState: {
viewBackgroundColor: #ffffff,
gridSize: 20
},
files: {}
}

第6步：保存并提供说明

1. 保存为 <描述性名称>.excalidraw
告知用户如何打开：

- 访问 https://excalidraw.com - 点击打开或拖放文件 - 或使用 Excalidraw VS Code 扩展

最佳实践

元素数量指南

图表类型	推荐数量	最大数量
流程图步骤	3-10	15
关系实体

3-8 | 12 | | 思维导图分支 | 4-6 | 8 | | 每个分支的子主题 | 2-4 | 6 |

布局技巧

1. 起始位置：居中重要元素，使用一致的间距
间距：

- 水平间距：元素之间200-300px - 垂直间距：行之间100-150px

3. 颜色：使用一致的配色方案

- 主要元素：浅蓝色（#a5d8ff） - 次要元素：浅绿色（#b2f2bb） - 重要/中心：黄色（#ffd43b） - 警报/警告：浅红色（#ffc9c9）

4. 文本大小：16-24px 以确保可读性
字体：所有文本元素始终使用 fontFamily: 5（Excalifont）
箭头样式：简单流程使用直线箭头，复杂关系使用曲线箭头

复杂度管理

如果用户请求包含太多元素：

- 建议拆分为多个图表
先关注主要元素
提供创建详细子图表的选项

示例响应：

您的请求包含15个组件。为了清晰起见，我建议：

1. 高层架构图（6个主要组件）
每个子系统的详细图表

您希望我先从高层视图开始吗？

示例提示和响应

示例1：简单流程图

用户： 创建一个用户注册的流程图

代理生成：

1. 提取步骤：输入邮箱 → 验证邮箱 → 设置密码 → 完成

excalidraw-diagram-generatorExcalidraw图表生成器