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:
- 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 |
Relationship Diagram |
"relationship", "connections", "dependencies", "structure" |
| Concept hierarchy, brainstorming |
Mind Map |
"mind map", "concepts", "ideas", "breakdown" |
| System design, components |
Architecture Diagram |
"architecture", "system", "components", "modules" |
| Data flow, transformation processes |
Data Flow Diagram (DFD) |
"data flow", "data processing", "data transformation" |
| Cross-functional processes, actor responsibilities |
Business Flow (Swimlane) |
"business process", "swimlane", "actors", "responsibilities" |
| Object-oriented design, class structures |
Class Diagram |
"class", "inheritance", "OOP", "object model" |
| Interaction sequences, message flows |
Sequence Diagram |
"sequence", "interaction", "messages", "timeline" |
| Database design, entity relationships |
ER Diagram |
"database", "entity", "relationship", "data model" |
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
ellipse: Alternative shapes for emphasis
diamond: Decision points
arrow: Directional connections
text: Labels and annotations
Key properties to set:
- Position:
x, y coordinates
- Size:
width, height
- Style:
strokeColor, backgroundColor, fillStyle
- 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:
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [
// Array of diagram elements
],
"appState": {
"viewBackgroundColor": "#ffffff",
"gridSize": 20
},
"files": {}
}
Step 6: Save and Provide Instructions
- Save as
<descriptive-name>.excalidraw
- Inform user how to open:
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
- Start positions: Center important elements, use consistent spacing
- Spacing:
- Horizontal gap: 200-300px between elements
- Vertical gap: 100-150px between rows
- Colors: Use consistent color scheme
- Primary elements: Light blue (
#a5d8ff)
- Secondary elements: Light green (
#b2f2bb)
- Important/Central: Yellow (
#ffd43b)
- Alerts/Warnings: Light red (
#ffc9c9)
- 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:
"Your request includes 15 components. For clarity, I recommend:
1. High-level architecture diagram (6 main components)
2. Detailed diagram for each subsystem
Would you like me to start with the high-level view?"
Example Prompts and Responses
Example 1: Simple Flowchart
User: "Create a flowchart for user registration"
Agent generates:
- Extract steps: "Enter email" → "Verify email" → "Set password" → "Complete"
- Create flowchart with 4 rectangles + 3 arrows
- Save as
user-registration-flow.excalidraw
Example 2: Relationship Diagram
User: "Diagram the relationship between User, Post, and Comment entities"
Agent generates:
- Entities: User, Post, Comment
- Relationships: User → Post ("creates"), User → Comment ("writes"), Post → Comment ("contains")
- Save as
user-content-relationships.excalidraw
Example 3: Mind Map
User: "Mind map about machine learning concepts"
Agent generates:
- Center: "Machine Learning"
- Branches: Supervised Learning, Unsupervised Learning, Reinforcement Learning, Deep Learning
- Sub-topics under each branch
- Save as
machine-learning-mindmap.excalidraw
Troubleshooting
| Issue |
Solution |
| Elements overlap |
Increase spacing between coordinates |
| Text doesn't fit in boxes |
Increase box width or reduce font size |
| Too many elements |
Break into multiple diagrams |
| Unclear layout |
Use grid layout (rows/columns) or radial layout (mind maps) |
| Colors inconsistent |
Define color palette upfront based on element types |
Advanced Techniques
Grid Layout (for Relationship Diagrams)
const columns = Math.ceil(Math.sqrt(entityCount));
const x = startX + (index % columns) * horizontalGap;
const y = startY + Math.floor(index / columns) * verticalGap;
Radial Layout (for Mind Maps)
const angle = (2 * Math.PI * index) / branchCount;
const x = centerX + radius * Math.cos(angle);
const y = centerY + radius * Math.sin(angle);
Auto-generated IDs
Use timestamp + random string for unique IDs:
const id = Date.now().toString(36) + Math.random().toString(36).substr(2);
Output Format
Always provide:
- ✅ Complete
.excalidraw JSON file
- 📊 Summary of what was created
- 📝 Element count
- 💡 Instructions for opening/editing
Example summary:
Created: user-workflow.excalidraw
Type: Flowchart
Elements: 7 rectangles, 6 arrows, 1 title text
Total: 14 elements
To view:
1. Visit https://excalidraw.com
2. Drag and drop user-workflow.excalidraw
3. Or use File → Open in Excalidraw VS Code extension
Validation Checklist
Before delivering the diagram:
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:
Check if library exists: Look for libraries/<library-name>/reference.md
If library exists: Proceed to use icons (see AI Assistant Workflow below)
If library does NOT exist: Respond with setup instructions:
To use [AWS/GCP/Azure/etc.] architecture icons, please follow these steps:
1. Visit https://libraries.excalidraw.com/
2. Search for "[AWS Architecture Icons/etc.]" and download the .excalidrawlib file
3. Create directory: skills/excalidraw-diagram-generator/libraries/[icon-set-name]/
4. Place the downloaded file in that directory
5. Run the splitter script:
python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/[icon-set-name]/
This will split the library into individual icon files for efficient use.
After setup is complete, I can create your diagram using the actual AWS/cloud icons.
Alternatively, I can create the diagram now using simple shapes (rectangles, ellipses)
which you can later replace with icons manually in Excalidraw.
User Setup Instructions (Detailed)
Step 1: Create Library Directory
mkdir -p skills/excalidraw-diagram-generator/libraries/aws-architecture-icons
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
python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
Step 5: Verify Setup
After running the script, verify the following structure exists:
skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
aws-architecture-icons.excalidrawlib (original)
reference.md (generated - icon lookup table)
icons/ (generated - individual icon files)
API-Gateway.json
CloudFront.json
EC2.json
Lambda.json
RDS.json
S3.json
...
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:
Create base diagram structure:
- Create
.excalidraw file with basic layout (title, boxes, regions)
- This establishes the canvas and overall structure
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:
# Add EC2 icon at position (400, 300) with label
python scripts/add-icon-to-diagram.py diagram.excalidraw EC2 400 300 --label "Web Server"
# Add VPC icon at position (200, 150)
python scripts/add-icon-to-diagram.py diagram.excalidraw VPC 200 150
# Add icon from different library
python scripts/add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \
--library-path libraries/gcp-icons --label "API Server"
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:
# Simple arrow from (300, 250) to (500, 300)
python scripts/add-arrow.py diagram.excalidraw 300 250 500 300
# Arrow with label
python scripts/add-arrow.py diagram.excalidraw 300 250 500 300 --label "HTTPS"
# Dashed arrow with custom color
python scripts/add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"
Workflow summary:
# Step 1: Create base diagram with title and structure
# (Create .excalidraw file with initial elements)
# Step 2: Add icons with labels
python scripts/add-icon-to-diagram.py my-diagram.excalidraw "Internet-gateway" 200 150 --label "Internet Gateway"
python scripts/add-icon-to-diagram.py my-diagram.excalidraw VPC 250 250
python scripts/add-icon-to-diagram.py my-diagram.excalidraw ELB 350 300 --label "Load Balancer"
python scripts/add-icon-to-diagram.py my-diagram.excalidraw EC2 450 350 --label "EC2 Instance"
python scripts/add-icon-to-diagram.py my-diagram.excalidraw RDS 550 400 --label "Database"
# Step 3: Add connecting arrows
python scripts/add-arrow.py my-diagram.excalidraw 250 200 300 250 # Internet → VPC
python scripts/add-arrow.py my-diagram.excalidraw 300 300 400 300 # VPC → ELB
python scripts/add-arrow.py my-diagram.excalidraw 400 330 500 350 # ELB → EC2
python scripts/add-arrow.py my-diagram.excalidraw 500 380 600 400 # EC2 → RDS
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:
Check for libraries:
List directory: skills/excalidraw-diagram-generator/libraries/
Look for subdirectories containing reference.md files
Read reference.md:
Open: libraries/<library-name>/reference.md
This is lightweight (typically <300 lines) and lists all available icons
Find relevant icons:
Search the reference.md table for icon names matching diagram needs
Example: For AWS diagram with EC2, S3, Lambda → Find "EC2", "S3", "Lambda" in table
Load specific icon data (WARNING: Large files):
Read ONLY the needed icon files:
- libraries/aws-architecture-icons/icons/EC2.json (200-300 lines)
- libraries/aws-architecture-icons/icons/S3.json (200-300 lines)
- libraries/aws-architecture-icons/icons/Lambda.json (200-300 lines)
Note: Each icon file is 200-1000 lines - this consumes significant tokens
Extract and transform elements:
Each icon JSON contains an "elements" array
Calculate bounding box (min_x, min_y, max_x, max_y)
Apply offset to all x/y coordinates
Generate new unique IDs for all elements
Update groupIds references
Copy transformed elements into your diagram
Position icons and add connections:
Adjust x/y coordinates to position icons correctly in the diagram
Update IDs to ensure uniqueness across diagram
Add connecting arrows and labels as needed
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):
# Step 1: Create base diagram file with title
# Create my-aws-diagram.excalidraw with basic structure (title, etc.)
# Step 2: Check icon availability
# Read: libraries/aws-architecture-icons/reference.md
# Confirm icons exist: Internet-gateway, VPC, ELB, EC2, RDS
# Step 3: Add icons with Python script
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw "Internet-gateway" 150 100 --label "Internet Gateway"
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw VPC 200 200
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw ELB 350 250 --label "Load Balancer"
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw EC2 500 300 --label "Web Server"
python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw RDS 650 350 --label "Database"
# Step 4: Add connecting arrows
python scripts/add-arrow.py my-aws-diagram.excalidraw 200 150 250 200 # Internet → VPC
python scripts/add-arrow.py my-aws-diagram.excalidraw 265 230 350 250 # VPC → ELB
python scripts/add-arrow.py my-aws-diagram.excalidraw 415 280 500 300 # ELB → EC2
python scripts/add-arrow.py my-aws-diagram.excalidraw 565 330 650 350 --label "SQL" --style dashed
# Result: Complete diagram with professional AWS icons, labels, and connections
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):
- 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
- 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
references/element-types.md - Detailed element type specifications
templates/flowchart-template.json - Basic flowchart starter
templates/relationship-template.json - Relationship diagram starter
templates/mindmap-template.json - Mind map starter
scripts/split-excalidraw-library.py - Tool to split .excalidrawlib files
scripts/README.md - Documentation for library tools
scripts/.gitignore - 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
1---2name: excalidraw-diagram-generator3description: 'Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, and system architecture diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw.'4metadata:5 source: https://skillmd.com/skills/github/excalidraw-diagram-generator6---78# Excalidraw Diagram Generator910A 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.1112## When to Use This Skill1314Use this skill when users request:1516- "Create a diagram showing..."17- "Make a flowchart for..."18- "Visualize the process of..."19- "Draw the system architecture of..."20- "Generate a mind map about..."21- "Create an Excalidraw file for..."22- "Show the relationship between..."23- "Diagram the workflow of..."2425**Supported diagram types:**26- 📊 **Flowcharts**: Sequential processes, workflows, decision trees27- 🔗 **Relationship Diagrams**: Entity relationships, system components, dependencies28- 🧠 **Mind Maps**: Concept hierarchies, brainstorming results, topic organization29- 🏗️ **Architecture Diagrams**: System design, module interactions, data flow30- 📈 **Data Flow Diagrams (DFD)**: Data flow visualization, data transformation processes31- 🏊 **Business Flow (Swimlane)**: Cross-functional workflows, actor-based process flows32- 📦 **Class Diagrams**: Object-oriented design, class structures and relationships33- 🔄 **Sequence Diagrams**: Object interactions over time, message flows34- 🗃️ **ER Diagrams**: Database entity relationships, data models3536## Prerequisites3738- Clear description of what should be visualized39- Identification of key entities, steps, or concepts40- Understanding of relationships or flow between elements4142## Step-by-Step Workflow4344### Step 1: Understand the Request4546Analyze the user's description to determine:471. **Diagram type** (flowchart, relationship, mind map, architecture)482. **Key elements** (entities, steps, concepts)493. **Relationships** (flow, connections, hierarchy)504. **Complexity** (number of elements)5152### Step 2: Choose the Appropriate Diagram Type5354| User Intent | Diagram Type | Example Keywords |55|-------------|--------------|------------------|56| Process flow, steps, procedures | **Flowchart** | "workflow", "process", "steps", "procedure" |57| Connections, dependencies, associations | **Relationship Diagram** | "relationship", "connections", "dependencies", "structure" |58| Concept hierarchy, brainstorming | **Mind Map** | "mind map", "concepts", "ideas", "breakdown" |59| System design, components | **Architecture Diagram** | "architecture", "system", "components", "modules" |60| Data flow, transformation processes | **Data Flow Diagram (DFD)** | "data flow", "data processing", "data transformation" |61| Cross-functional processes, actor responsibilities | **Business Flow (Swimlane)** | "business process", "swimlane", "actors", "responsibilities" |62| Object-oriented design, class structures | **Class Diagram** | "class", "inheritance", "OOP", "object model" |63| Interaction sequences, message flows | **Sequence Diagram** | "sequence", "interaction", "messages", "timeline" |64| Database design, entity relationships | **ER Diagram** | "database", "entity", "relationship", "data model" |6566### Step 3: Extract Structured Information6768**For Flowcharts:**69- List of sequential steps70- Decision points (if any)71- Start and end points7273**For Relationship Diagrams:**74- Entities/nodes (name + optional description)75- Relationships between entities (from → to, with label)7677**For Mind Maps:**78- Central topic79- Main branches (3-6 recommended)80- Sub-topics for each branch (optional)8182**For Data Flow Diagrams (DFD):**83- Data sources and destinations (external entities)84- Processes (data transformations)85- Data stores (databases, files)86- Data flows (arrows showing data movement from left-to-right or from top-left to bottom-right)87- **Important**: Do not represent process order, only data flow8889**For Business Flow (Swimlane):**90- Actors/roles (departments, systems, people) - displayed as header columns91- Process lanes (vertical lanes under each actor)92- Process boxes (activities within each lane)93- Flow arrows (connecting process boxes, including cross-lane handoffs)9495**For Class Diagrams:**96- Classes with names97- Attributes with visibility (+, -, #)98- Methods with visibility and parameters99- 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)100- Multiplicity notations (1, 0..1, 1..*, *)101102**For Sequence Diagrams:**103- Objects/actors (arranged horizontally at top)104- Lifelines (vertical lines from each object)105- Messages (horizontal arrows between lifelines)106- Synchronous messages (solid arrow), asynchronous messages (dashed arrow)107- Return values (dashed arrows)108- Activation boxes (rectangles on lifelines during execution)109- Time flows from top to bottom110111**For ER Diagrams:**112- Entities (rectangles with entity names)113- Attributes (listed inside entities)114- Primary keys (underlined or marked with PK)115- Foreign keys (marked with FK)116- Relationships (lines connecting entities)117- Cardinality: 1:1 (one-to-one), 1:N (one-to-many), N:M (many-to-many)118- Junction/associative entities for many-to-many relationships (dashed rectangles)119120### Step 4: Generate the Excalidraw JSON121122Create the `.excalidraw` file with appropriate elements:123124**Available element types:**125- `rectangle`: Boxes for entities, steps, concepts126- `ellipse`: Alternative shapes for emphasis127- `diamond`: Decision points128- `arrow`: Directional connections129- `text`: Labels and annotations130131**Key properties to set:**132- **Position**: `x`, `y` coordinates133- **Size**: `width`, `height`134- **Style**: `strokeColor`, `backgroundColor`, `fillStyle`135- **Font**: `fontFamily: 5` (Excalifont - **required for all text elements**)136- **Text**: Embedded text for labels137- **Connections**: `points` array for arrows138139**Important**: All text elements must use `fontFamily: 5` (Excalifont) for consistent visual appearance.140141### Step 5: Format the Output142143Structure the complete Excalidraw file:144145```json146{147 "type": "excalidraw",148 "version": 2,149 "source": "https://excalidraw.com",150 "elements": [151 // Array of diagram elements152 ],153 "appState": {154 "viewBackgroundColor": "#ffffff",155 "gridSize": 20156 },157 "files": {}158}159```160161### Step 6: Save and Provide Instructions1621631. Save as `<descriptive-name>.excalidraw`1642. Inform user how to open:165 - Visit https://excalidraw.com166 - Click "Open" or drag-and-drop the file167 - Or use Excalidraw VS Code extension168169## Best Practices170171### Element Count Guidelines172173| Diagram Type | Recommended Count | Maximum |174|--------------|-------------------|---------|175| Flowchart steps | 3-10 | 15 |176| Relationship entities | 3-8 | 12 |177| Mind map branches | 4-6 | 8 |178| Mind map sub-topics per branch | 2-4 | 6 |179180### Layout Tips1811821. **Start positions**: Center important elements, use consistent spacing1832. **Spacing**: 184 - Horizontal gap: 200-300px between elements185 - Vertical gap: 100-150px between rows1863. **Colors**: Use consistent color scheme187 - Primary elements: Light blue (`#a5d8ff`)188 - Secondary elements: Light green (`#b2f2bb`)189 - Important/Central: Yellow (`#ffd43b`)190 - Alerts/Warnings: Light red (`#ffc9c9`)1914. **Text sizing**: 16-24px for readability1925. **Font**: Always use `fontFamily: 5` (Excalifont) for all text elements1936. **Arrow style**: Use straight arrows for simple flows, curved for complex relationships194195### Complexity Management196197**If user request has too many elements:**198- Suggest breaking into multiple diagrams199- Focus on main elements first200- Offer to create detailed sub-diagrams201202**Example response:**203```204"Your request includes 15 components. For clarity, I recommend:2051. High-level architecture diagram (6 main components)2062. Detailed diagram for each subsystem207208Would you like me to start with the high-level view?"209```210211## Example Prompts and Responses212213### Example 1: Simple Flowchart214215**User:** "Create a flowchart for user registration"216217**Agent generates:**2181. Extract steps: "Enter email" → "Verify email" → "Set password" → "Complete"2192. Create flowchart with 4 rectangles + 3 arrows2203. Save as `user-registration-flow.excalidraw`221222### Example 2: Relationship Diagram223224**User:** "Diagram the relationship between User, Post, and Comment entities"225226**Agent generates:**2271. Entities: User, Post, Comment2282. Relationships: User → Post ("creates"), User → Comment ("writes"), Post → Comment ("contains")2293. Save as `user-content-relationships.excalidraw`230231### Example 3: Mind Map232233**User:** "Mind map about machine learning concepts"234235**Agent generates:**2361. Center: "Machine Learning"2372. Branches: Supervised Learning, Unsupervised Learning, Reinforcement Learning, Deep Learning2383. Sub-topics under each branch2394. Save as `machine-learning-mindmap.excalidraw`240241## Troubleshooting242243| Issue | Solution |244|-------|----------|245| Elements overlap | Increase spacing between coordinates |246| Text doesn't fit in boxes | Increase box width or reduce font size |247| Too many elements | Break into multiple diagrams |248| Unclear layout | Use grid layout (rows/columns) or radial layout (mind maps) |249| Colors inconsistent | Define color palette upfront based on element types |250251## Advanced Techniques252253### Grid Layout (for Relationship Diagrams)254```javascript255const columns = Math.ceil(Math.sqrt(entityCount));256const x = startX + (index % columns) * horizontalGap;257const y = startY + Math.floor(index / columns) * verticalGap;258```259260### Radial Layout (for Mind Maps)261```javascript262const angle = (2 * Math.PI * index) / branchCount;263const x = centerX + radius * Math.cos(angle);264const y = centerY + radius * Math.sin(angle);265```266267### Auto-generated IDs268Use timestamp + random string for unique IDs:269```javascript270const id = Date.now().toString(36) + Math.random().toString(36).substr(2);271```272273## Output Format274275Always provide:2761. ✅ Complete `.excalidraw` JSON file2772. 📊 Summary of what was created2783. 📝 Element count2794. 💡 Instructions for opening/editing280281**Example summary:**282```283Created: user-workflow.excalidraw284Type: Flowchart285Elements: 7 rectangles, 6 arrows, 1 title text286Total: 14 elements287288To view:2891. Visit https://excalidraw.com2902. Drag and drop user-workflow.excalidraw2913. Or use File → Open in Excalidraw VS Code extension292```293294## Validation Checklist295296Before delivering the diagram:297- [ ] All elements have unique IDs298- [ ] Coordinates prevent overlapping299- [ ] Text is readable (font size 16+)300- [ ] **All text elements use `fontFamily: 5` (Excalifont)**301- [ ] Arrows connect logically302- [ ] Colors follow consistent scheme303- [ ] File is valid JSON304- [ ] Element count is reasonable (<20 for clarity)305306## Icon Libraries (Optional Enhancement)307308For 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.309310### When User Requests Icons311312**If user asks for AWS/cloud architecture diagrams or mentions wanting to use specific icons:**3133141. **Check if library exists**: Look for `libraries/<library-name>/reference.md`3152. **If library exists**: Proceed to use icons (see AI Assistant Workflow below)3163. **If library does NOT exist**: Respond with setup instructions:317318 ```319 To use [AWS/GCP/Azure/etc.] architecture icons, please follow these steps:320 321 1. Visit https://libraries.excalidraw.com/322 2. Search for "[AWS Architecture Icons/etc.]" and download the .excalidrawlib file323 3. Create directory: skills/excalidraw-diagram-generator/libraries/[icon-set-name]/324 4. Place the downloaded file in that directory325 5. Run the splitter script:326 python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/[icon-set-name]/327 328 This will split the library into individual icon files for efficient use.329 After setup is complete, I can create your diagram using the actual AWS/cloud icons.330 331 Alternatively, I can create the diagram now using simple shapes (rectangles, ellipses) 332 which you can later replace with icons manually in Excalidraw.333 ```334335### User Setup Instructions (Detailed)336337**Step 1: Create Library Directory**338```bash339mkdir -p skills/excalidraw-diagram-generator/libraries/aws-architecture-icons340```341342**Step 2: Download Library**343- Visit: https://libraries.excalidraw.com/344- Search for your desired icon set (e.g., "AWS Architecture Icons")345- Click download to get the `.excalidrawlib` file346- Example categories (availability varies; confirm on the site):347 - Cloud service icons348 - UI/Material icons349 - Flowchart symbols350351**Step 3: Place Library File**352- Rename the downloaded file to match the directory name (e.g., `aws-architecture-icons.excalidrawlib`)353- Move it to the directory created in Step 1354355**Step 4: Run Splitter Script**356```bash357python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/358```359360**Step 5: Verify Setup**361After running the script, verify the following structure exists:362```363skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/364 aws-architecture-icons.excalidrawlib (original)365 reference.md (generated - icon lookup table)366 icons/ (generated - individual icon files)367 API-Gateway.json368 CloudFront.json369 EC2.json370 Lambda.json371 RDS.json372 S3.json373 ...374```375376### AI Assistant Workflow377378**When icon libraries are available in `libraries/`:**379380**RECOMMENDED APPROACH: Use Python Scripts (Efficient & Reliable)**381382The repository includes Python scripts that handle icon integration automatically:3833841. **Create base diagram structure**:385 - Create `.excalidraw` file with basic layout (title, boxes, regions)386 - This establishes the canvas and overall structure3873882. **Add icons using Python script**:389 ```bash390 python skills/excalidraw-diagram-generator/scripts/add-icon-to-diagram.py \391 <diagram-path> <icon-name> <x> <y> [--label "Text"] [--library-path PATH]392 ```393 - Edit via `.excalidraw.edit` is enabled by default to avoid overwrite issues; pass `--no-use-edit-suffix` to disable.394 395 **Examples**:396 ```bash397 # Add EC2 icon at position (400, 300) with label398 python scripts/add-icon-to-diagram.py diagram.excalidraw EC2 400 300 --label "Web Server"399 400 # Add VPC icon at position (200, 150)401 python scripts/add-icon-to-diagram.py diagram.excalidraw VPC 200 150402 403 # Add icon from different library404 python scripts/add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \405 --library-path libraries/gcp-icons --label "API Server"406 ```4074083. **Add connecting arrows**:409 ```bash410 python skills/excalidraw-diagram-generator/scripts/add-arrow.py \411 <diagram-path> <from-x> <from-y> <to-x> <to-y> [--label "Text"] [--style solid|dashed|dotted] [--color HEX]412 ```413 - Edit via `.excalidraw.edit` is enabled by default to avoid overwrite issues; pass `--no-use-edit-suffix` to disable.414 415 **Examples**:416 ```bash417 # Simple arrow from (300, 250) to (500, 300)418 python scripts/add-arrow.py diagram.excalidraw 300 250 500 300419 420 # Arrow with label421 python scripts/add-arrow.py diagram.excalidraw 300 250 500 300 --label "HTTPS"422 423 # Dashed arrow with custom color424 python scripts/add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"425 ```4264274. **Workflow summary**:428 ```bash429 # Step 1: Create base diagram with title and structure430 # (Create .excalidraw file with initial elements)431 432 # Step 2: Add icons with labels433 python scripts/add-icon-to-diagram.py my-diagram.excalidraw "Internet-gateway" 200 150 --label "Internet Gateway"434 python scripts/add-icon-to-diagram.py my-diagram.excalidraw VPC 250 250435 python scripts/add-icon-to-diagram.py my-diagram.excalidraw ELB 350 300 --label "Load Balancer"436 python scripts/add-icon-to-diagram.py my-diagram.excalidraw EC2 450 350 --label "EC2 Instance"437 python scripts/add-icon-to-diagram.py my-diagram.excalidraw RDS 550 400 --label "Database"438 439 # Step 3: Add connecting arrows440 python scripts/add-arrow.py my-diagram.excalidraw 250 200 300 250 # Internet → VPC441 python scripts/add-arrow.py my-diagram.excalidraw 300 300 400 300 # VPC → ELB442 python scripts/add-arrow.py my-diagram.excalidraw 400 330 500 350 # ELB → EC2443 python scripts/add-arrow.py my-diagram.excalidraw 500 380 600 400 # EC2 → RDS444 ```445446**Benefits of Python Script Approach**:447- ✅ **No token consumption**: Icon JSON data (200-1000 lines each) never enters AI context448- ✅ **Accurate transformations**: Coordinate calculations handled deterministically449- ✅ **ID management**: Automatic UUID generation prevents conflicts450- ✅ **Reliable**: No risk of coordinate miscalculation or ID collision451- ✅ **Fast**: Direct file manipulation, no parsing overhead452- ✅ **Reusable**: Works with any Excalidraw library you provide453454**ALTERNATIVE: Manual Icon Integration (Not Recommended)**455456Only use this if Python scripts are unavailable:4574581. **Check for libraries**: 459 ```460 List directory: skills/excalidraw-diagram-generator/libraries/461 Look for subdirectories containing reference.md files462 ```4634642. **Read reference.md**:465 ```466 Open: libraries/<library-name>/reference.md467 This is lightweight (typically <300 lines) and lists all available icons468 ```4694703. **Find relevant icons**:471 ```472 Search the reference.md table for icon names matching diagram needs473 Example: For AWS diagram with EC2, S3, Lambda → Find "EC2", "S3", "Lambda" in table474 ```4754764. **Load specific icon data** (WARNING: Large files):477 ```478 Read ONLY the needed icon files:479 - libraries/aws-architecture-icons/icons/EC2.json (200-300 lines)480 - libraries/aws-architecture-icons/icons/S3.json (200-300 lines)481 - libraries/aws-architecture-icons/icons/Lambda.json (200-300 lines)482 Note: Each icon file is 200-1000 lines - this consumes significant tokens483 ```4844855. **Extract and transform elements**:486 ```487 Each icon JSON contains an "elements" array488 Calculate bounding box (min_x, min_y, max_x, max_y)489 Apply offset to all x/y coordinates490 Generate new unique IDs for all elements491 Update groupIds references492 Copy transformed elements into your diagram493 ```4944956. **Position icons and add connections**:496 ```497 Adjust x/y coordinates to position icons correctly in the diagram498 Update IDs to ensure uniqueness across diagram499 Add connecting arrows and labels as needed500 ```501502**Manual Integration Challenges**:503- ⚠️ High token consumption (200-1000 lines per icon × number of icons)504- ⚠️ Complex coordinate transformation calculations505- ⚠️ Risk of ID collision if not handled carefully506- ⚠️ Time-consuming for diagrams with many icons507508### Example: Creating AWS Diagram with Icons509510**Request**: "Create an AWS architecture diagram with Internet Gateway, VPC, ELB, EC2, and RDS"511512**Recommended Workflow (using Python scripts)**:513**Request**: "Create an AWS architecture diagram with Internet Gateway, VPC, ELB, EC2, and RDS"514515**Recommended Workflow (using Python scripts)**:516517```bash518# Step 1: Create base diagram file with title519# Create my-aws-diagram.excalidraw with basic structure (title, etc.)520521# Step 2: Check icon availability522# Read: libraries/aws-architecture-icons/reference.md523# Confirm icons exist: Internet-gateway, VPC, ELB, EC2, RDS524525# Step 3: Add icons with Python script526python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw "Internet-gateway" 150 100 --label "Internet Gateway"527python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw VPC 200 200528python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw ELB 350 250 --label "Load Balancer"529python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw EC2 500 300 --label "Web Server"530python scripts/add-icon-to-diagram.py my-aws-diagram.excalidraw RDS 650 350 --label "Database"531532# Step 4: Add connecting arrows533python scripts/add-arrow.py my-aws-diagram.excalidraw 200 150 250 200 # Internet → VPC534python scripts/add-arrow.py my-aws-diagram.excalidraw 265 230 350 250 # VPC → ELB535python scripts/add-arrow.py my-aws-diagram.excalidraw 415 280 500 300 # ELB → EC2536python scripts/add-arrow.py my-aws-diagram.excalidraw 565 330 650 350 --label "SQL" --style dashed537538# Result: Complete diagram with professional AWS icons, labels, and connections539```540541**Benefits**:542- No manual coordinate calculation543- No token consumption for icon data544- Deterministic, reliable results545- Easy to iterate and adjust positions546547**Alternative Workflow (manual, if scripts unavailable)**:5481. Check: `libraries/aws-architecture-icons/reference.md` exists → Yes5492. Read reference.md → Find entries for Internet-gateway, VPC, ELB, EC2, RDS5503. Load:551 - `icons/Internet-gateway.json` (298 lines)552 - `icons/VPC.json` (550 lines)553 - `icons/ELB.json` (363 lines)554 - `icons/EC2.json` (231 lines) 555 - `icons/RDS.json` (similar size)556 **Total: ~2000+ lines of JSON to process**5574. Extract elements from each JSON5585. Calculate bounding boxes and offsets for each icon5596. Transform all coordinates (x, y) for positioning5607. Generate unique IDs for all elements5618. Add arrows showing data flow5629. Add text labels56310. Generate final `.excalidraw` file564565**Challenges with manual approach**:566- High token consumption (~2000-5000 lines)567- Complex coordinate math568- Risk of ID conflicts569570### Supported Icon Libraries (Examples — verify availability)571572- This workflow works with any valid `.excalidrawlib` file you provide.573- Examples of library categories you may find on https://libraries.excalidraw.com/:574 - Cloud service icons575 - Kubernetes / infrastructure icons576 - UI / Material icons577 - Flowchart / diagram symbols578 - Network diagram icons579- Availability and naming can change; verify exact library names on the site before use.580581### Fallback: No Icons Available582583**If no icon libraries are set up:**584- Create diagrams using basic shapes (rectangles, ellipses, arrows)585- Use color coding and text labels to distinguish components586- Inform user they can add icons later or set up libraries for future diagrams587- The diagram will still be functional and clear, just less visually polished588589## References590591See bundled references for:592- `references/excalidraw-schema.md` - Complete Excalidraw JSON schema593- `references/element-types.md` - Detailed element type specifications594- `templates/flowchart-template.json` - Basic flowchart starter595- `templates/relationship-template.json` - Relationship diagram starter596- `templates/mindmap-template.json` - Mind map starter597- `scripts/split-excalidraw-library.py` - Tool to split `.excalidrawlib` files598- `scripts/README.md` - Documentation for library tools599- `scripts/.gitignore` - Prevents local Python artifacts from being committed600601## Limitations602603- Complex curves are simplified to straight/basic curved lines604- Hand-drawn roughness is set to default (1)605- No embedded images support in auto-generation606- Maximum recommended elements: 20 per diagram607- No automatic collision detection (use spacing guidelines)608609## Future Enhancements610611Potential improvements:612- Auto-layout optimization algorithms613- Import from Mermaid/PlantUML syntax614- Template library expansion615- Interactive editing after generation