Excalidraw diagram generator
Turn a natural-language diagram request into a valid Excalidraw JSON file by choosing the right diagram type, extracting nodes and relationships, laying out elements, and saving a .excalidraw artifact the user can open directly.
When to invoke
- "Create a diagram showing this workflow."
- "Make a flowchart for the registration process."
- "Draw the system architecture as an Excalidraw file."
- "Generate a mind map about these concepts."
- "Show the relationship between these entities."
Prerequisites and context
- Require a clear description of what should be visualized, including key entities, steps, concepts, relationships, and flow.
- If the request has too many elements, propose multiple diagrams before generating a crowded file.
- Save output as
<descriptive-name>.excalidraw; users can open it at https://excalidraw.com by drag-and-drop, File → Open, or the Excalidraw VS Code extension.
Diagram selection
| User intent |
Diagram type |
Extract |
| Workflow, process, steps, procedure, decision tree |
Flowchart |
Start, end, sequential steps, decision points. |
| Relationship, connections, dependencies, structure |
Relationship Diagram |
Entities/nodes and labeled relationships from → to. |
| Mind map, concepts, ideas, breakdown |
Mind Map |
Central topic, 3-6 main branches, optional sub-topics. |
| Architecture, system, components, modules |
Architecture Diagram |
Components, interfaces, boundaries, data/control flow. |
| Data flow, data processing, data transformation |
Data Flow Diagram (DFD) |
External entities, processes, data stores, and data flows; do not represent process order. |
| Business process, swimlane, actors, responsibilities |
Business Flow (Swimlane) |
Actor columns, process lanes, activities, cross-lane handoffs. |
| Class, inheritance, OOP, object model |
Class Diagram |
Classes, attributes, methods, visibility, relationships, multiplicity. |
| Sequence, interaction, messages, timeline |
Sequence Diagram |
Objects/actors, lifelines, messages, return values, activation boxes; time flows top to bottom. |
| Database, entity, relationship, data model |
ER Diagram |
Entities, attributes, primary keys, foreign keys, cardinality, junction entities. |
Excalidraw JSON rules
Generate complete JSON with type: "excalidraw", version: 2, source: "https://excalidraw.com", an elements array, appState.viewBackgroundColor: "#ffffff", appState.gridSize: 20, and files: {}.
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [],
"appState": { "viewBackgroundColor": "#ffffff", "gridSize": 20 },
"files": {}
}
| Element type |
Use it for |
Required properties |
rectangle |
Entities, steps, concepts, swimlane activities, classes |
id, x, y, width, height, strokeColor, backgroundColor, fillStyle. |
ellipse |
Alternative emphasis or boundary shapes |
Same core position, size, and style properties. |
diamond |
Decision points |
Enough width for text and outgoing labels. |
arrow |
Directional connections |
points array and logical start/end placement. |
text |
Labels and annotations |
fontFamily: 5 for Excalifont, readable fontSize, and embedded text. |
All text elements must use fontFamily: 5 (Excalifont). Use timestamp plus random suffix IDs such as Date.now().toString(36) + Math.random().toString(36).substr(2).
Layout rules
| Rule |
Value |
| Horizontal gap |
200-300px between elements. |
| Vertical gap |
100-150px between rows. |
| Text size |
16-24px; never below 16px for normal labels. |
| Primary color |
Light blue #a5d8ff. |
| Secondary color |
Light green #b2f2bb. |
| Central/important color |
Yellow #ffd43b. |
| Alert/warning color |
Light red #ffc9c9. |
| Roughness |
Default 1. |
| Recommended maximum |
Fewer than 20 elements for clarity. |
Use straight arrows for simple flows and curved arrows only for complex relationships. For relationship diagrams, use grid layout:
const columns = Math.ceil(Math.sqrt(entityCount));
const x = startX + (index % columns) * horizontalGap;
const y = startY + Math.floor(index / columns) * verticalGap;
For mind maps, use radial layout:
const angle = (2 * Math.PI * index) / branchCount;
const x = centerX + radius * Math.cos(angle);
const y = centerY + radius * Math.sin(angle);
Diagram-specific notation
| Type |
Required conventions |
| Flowcharts |
Rectangles for steps, diamonds for decisions, arrows for sequence, explicit start and end. |
| Data Flow Diagrams (DFD) |
Data sources and destinations, processes, data stores, arrows showing data movement left-to-right or top-left to bottom-right; no process-order semantics. |
| Business Flow (Swimlane) |
Actors/roles as header columns, vertical lanes, process boxes inside lanes, arrows for cross-lane handoffs. |
| Class Diagrams |
Visibility +, -, #; inheritance uses solid line plus white triangle; implementation dashed line plus white triangle; association solid line; dependency dashed line; aggregation solid line plus white diamond; composition solid line plus filled diamond; multiplicity 1, 0..1, 1..*, *. |
| Sequence Diagrams |
Actors horizontally at top, vertical lifelines, synchronous solid arrows, asynchronous dashed arrows, return values dashed arrows, activation boxes. |
| ER Diagrams |
Entities as rectangles, attributes inside, primary keys marked PK, foreign keys marked FK, relationships with 1:1, 1:N, N:M, and junction/associative entities for many-to-many relationships. |
Complexity management
| Problem |
Response |
| More than 15 flowchart steps |
Split into high-level and detailed flowcharts. |
| More than 12 relationship entities |
Create a high-level relationship diagram first, then subsystem diagrams. |
| More than 8 mind-map branches or 6 sub-topics per branch |
Trim to primary concepts and offer follow-up diagrams. |
| User includes 15 components |
Recommend a high-level architecture diagram with 6 main components plus detailed subsystem diagrams. |
| Request needs icons |
Read references/icon-libraries.md and use the icon-library workflow. |
Procedure
- Understand the request: determine diagram type, key elements, relationships, and complexity.
- Choose the appropriate diagram type from the selection table.
- Extract structured information: steps, decisions, entities, branches, actors, classes, lifelines, data stores, or cardinalities.
- Use bundled templates when they match the requested type; otherwise build JSON from scratch using the schema rules.
- Generate the
.excalidraw file with unique IDs, non-overlapping coordinates, consistent colors, readable text, and logical arrows.
- Validate JSON syntax and element count, then provide a concise summary and opening instructions.
Progressive disclosure and bundled resources
Read bundled resources only when needed:
references/excalidraw-schema.md: complete Excalidraw JSON schema.references/element-types.md: detailed element type specifications.references/icon-libraries.md: Excalidraw icon libraries and optional icon loading.templates/flowchart-template.excalidraw: basic flowchart starter.templates/relationship-template.excalidraw: relationship diagram starter.templates/mindmap-template.excalidraw: mind map starter.templates/data-flow-diagram-template.excalidraw: DFD starter.templates/business-flow-swimlane-template.excalidraw: swimlane starter.templates/class-diagram-template.excalidraw: class diagram starter.templates/sequence-diagram-template.excalidraw: sequence diagram starter.templates/er-diagram-template.excalidraw: ER diagram starter.scripts/split-excalidraw-library.py: split .excalidrawlib files.scripts/add-icon-to-diagram.py: add an icon to a diagram.scripts/add-arrow.py: add arrows programmatically.scripts/README.md: documentation for library tools.scripts/.gitignore: prevents local Python artifacts from being committed.
Limits
- Complex curves are simplified to straight or basic curved lines.
- Embedded images are not generated automatically; use imports or icon-library resources when needed.
- No automatic collision detection exists, so apply spacing and validation manually.
- Mermaid or PlantUML import and auto-layout optimization are future enhancements, not current required output.
Troubleshooting
| Issue |
Solution |
| Elements overlap |
Increase coordinate spacing or switch to grid/radial layout. |
| Text doesn't fit in boxes |
Increase box width or reduce font size while staying readable. |
| Too many elements |
Break into multiple diagrams. |
| Unclear layout |
Use rows/columns for relationships or radial layout for mind maps. |
| Colors inconsistent |
Define the palette upfront by element type. |
Naming and compatibility notes
Preserve common example filenames and legacy template references when mapping older requests: user-registration-flow, user-registration-flow.excalidraw, user-content-relationships, user-content-relationships.excalidraw, machine-learning-mindmap, machine-learning-mindmap.excalidraw, user-workflow, templates/flowchart-template.json, templates/relationship-template.json, and templates/mindmap-template.json. Current bundled templates use .excalidraw; do not create new .json templates unless the user asks.
Style names must remain understandable to agents translating older examples: Important/Central, Alerts/Warnings, actor-based process flows, Junction/associative entities, one-to-one, one-to-many, sub-diagrams, auto-generation, opening/editing, straight/basic curved lines, Mermaid/PlantUML future import, and core element keys width, height, strokeColor, backgroundColor, and fillStyle.
Output template
## Excalidraw diagram result - <diagram name>
**Status:** created | needs clarification | blocked
**File:** `<descriptive-name>.excalidraw`
**Type:** Flowchart | Relationship Diagram | Mind Map | Architecture Diagram | Data Flow Diagram (DFD) | Business Flow (Swimlane) | Class Diagram | Sequence Diagram | ER Diagram
**Elements:** `<count>` total (`<rectangles>` rectangles, `<arrows>` arrows, `<text>` text)
### Created structure
- <main nodes or sections>
- <relationships or flow>
### To view
1. Visit https://excalidraw.com
2. Drag and drop `<descriptive-name>.excalidraw`
3. Or use File → Open in the Excalidraw VS Code extension
Quality gate
References
1---2name: excalidraw-diagram-generator-33description: Generate valid .excalidraw JSON diagrams from natural language descriptions, including flowcharts, relationship diagrams, mind maps, architecture diagrams, DFDs, swimlanes, class diagrams, sequence diagrams, and ER diagrams. Use when asked to create a diagram, make a flowchart, visualize a process, draw a system architecture, create a mind map, show relationships, or generate an Excalidraw file.4---56<!-- Generated from harness/github-copilot/plugins/diagram-authoring/skills/excalidraw-diagram-generator/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Excalidraw diagram generator910Turn a natural-language diagram request into a valid Excalidraw JSON file by choosing the right diagram type, extracting nodes and relationships, laying out elements, and saving a `.excalidraw` artifact the user can open directly.1112## When to invoke1314- "Create a diagram showing this workflow."15- "Make a flowchart for the registration process."16- "Draw the system architecture as an Excalidraw file."17- "Generate a mind map about these concepts."18- "Show the relationship between these entities."1920## Prerequisites and context2122- Require a clear description of what should be visualized, including key entities, steps, concepts, relationships, and flow.23- If the request has too many elements, propose multiple diagrams before generating a crowded file.24- Save output as `<descriptive-name>.excalidraw`; users can open it at https://excalidraw.com by drag-and-drop, File → Open, or the Excalidraw VS Code extension.2526## Diagram selection2728| User intent | Diagram type | Extract |29| --- | --- | --- |30| Workflow, process, steps, procedure, decision tree | Flowchart | Start, end, sequential steps, decision points. |31| Relationship, connections, dependencies, structure | Relationship Diagram | Entities/nodes and labeled relationships from → to. |32| Mind map, concepts, ideas, breakdown | Mind Map | Central topic, 3-6 main branches, optional sub-topics. |33| Architecture, system, components, modules | Architecture Diagram | Components, interfaces, boundaries, data/control flow. |34| Data flow, data processing, data transformation | Data Flow Diagram (DFD) | External entities, processes, data stores, and data flows; do not represent process order. |35| Business process, swimlane, actors, responsibilities | Business Flow (Swimlane) | Actor columns, process lanes, activities, cross-lane handoffs. |36| Class, inheritance, OOP, object model | Class Diagram | Classes, attributes, methods, visibility, relationships, multiplicity. |37| Sequence, interaction, messages, timeline | Sequence Diagram | Objects/actors, lifelines, messages, return values, activation boxes; time flows top to bottom. |38| Database, entity, relationship, data model | ER Diagram | Entities, attributes, primary keys, foreign keys, cardinality, junction entities. |3940## Excalidraw JSON rules4142Generate complete JSON with `type: "excalidraw"`, `version: 2`, `source: "https://excalidraw.com"`, an `elements` array, `appState.viewBackgroundColor: "#ffffff"`, `appState.gridSize: 20`, and `files: {}`.4344```json45{46 "type": "excalidraw",47 "version": 2,48 "source": "https://excalidraw.com",49 "elements": [],50 "appState": { "viewBackgroundColor": "#ffffff", "gridSize": 20 },51 "files": {}52}53```5455| Element type | Use it for | Required properties |56| --- | --- | --- |57| `rectangle` | Entities, steps, concepts, swimlane activities, classes | `id`, `x`, `y`, `width`, `height`, `strokeColor`, `backgroundColor`, `fillStyle`. |58| `ellipse` | Alternative emphasis or boundary shapes | Same core position, size, and style properties. |59| `diamond` | Decision points | Enough width for text and outgoing labels. |60| `arrow` | Directional connections | `points` array and logical start/end placement. |61| `text` | Labels and annotations | `fontFamily: 5` for Excalifont, readable `fontSize`, and embedded `text`. |6263All text elements must use `fontFamily: 5` (Excalifont). Use timestamp plus random suffix IDs such as `Date.now().toString(36) + Math.random().toString(36).substr(2)`.6465## Layout rules6667| Rule | Value |68| --- | --- |69| Horizontal gap | `200-300px` between elements. |70| Vertical gap | `100-150px` between rows. |71| Text size | `16-24px`; never below `16px` for normal labels. |72| Primary color | Light blue `#a5d8ff`. |73| Secondary color | Light green `#b2f2bb`. |74| Central/important color | Yellow `#ffd43b`. |75| Alert/warning color | Light red `#ffc9c9`. |76| Roughness | Default `1`. |77| Recommended maximum | Fewer than `20` elements for clarity. |7879Use straight arrows for simple flows and curved arrows only for complex relationships. For relationship diagrams, use grid layout:8081```javascript82const columns = Math.ceil(Math.sqrt(entityCount));83const x = startX + (index % columns) * horizontalGap;84const y = startY + Math.floor(index / columns) * verticalGap;85```8687For mind maps, use radial layout:8889```javascript90const angle = (2 * Math.PI * index) / branchCount;91const x = centerX + radius * Math.cos(angle);92const y = centerY + radius * Math.sin(angle);93```9495## Diagram-specific notation9697| Type | Required conventions |98| --- | --- |99| Flowcharts | Rectangles for steps, diamonds for decisions, arrows for sequence, explicit start and end. |100| Data Flow Diagrams (DFD) | Data sources and destinations, processes, data stores, arrows showing data movement left-to-right or top-left to bottom-right; no process-order semantics. |101| Business Flow (Swimlane) | Actors/roles as header columns, vertical lanes, process boxes inside lanes, arrows for cross-lane handoffs. |102| Class Diagrams | Visibility `+`, `-`, `#`; inheritance uses solid line plus white triangle; implementation dashed line plus white triangle; association solid line; dependency dashed line; aggregation solid line plus white diamond; composition solid line plus filled diamond; multiplicity `1`, `0..1`, `1..*`, `*`. |103| Sequence Diagrams | Actors horizontally at top, vertical lifelines, synchronous solid arrows, asynchronous dashed arrows, return values dashed arrows, activation boxes. |104| ER Diagrams | Entities as rectangles, attributes inside, primary keys marked `PK`, foreign keys marked `FK`, relationships with `1:1`, `1:N`, `N:M`, and junction/associative entities for many-to-many relationships. |105106## Complexity management107108| Problem | Response |109| --- | --- |110| More than 15 flowchart steps | Split into high-level and detailed flowcharts. |111| More than 12 relationship entities | Create a high-level relationship diagram first, then subsystem diagrams. |112| More than 8 mind-map branches or 6 sub-topics per branch | Trim to primary concepts and offer follow-up diagrams. |113| User includes 15 components | Recommend a high-level architecture diagram with 6 main components plus detailed subsystem diagrams. |114| Request needs icons | Read `references/icon-libraries.md` and use the icon-library workflow. |115116## Procedure1171181. Understand the request: determine diagram type, key elements, relationships, and complexity.1192. Choose the appropriate diagram type from the selection table.1203. Extract structured information: steps, decisions, entities, branches, actors, classes, lifelines, data stores, or cardinalities.1214. Use bundled templates when they match the requested type; otherwise build JSON from scratch using the schema rules.1225. Generate the `.excalidraw` file with unique IDs, non-overlapping coordinates, consistent colors, readable text, and logical arrows.1236. Validate JSON syntax and element count, then provide a concise summary and opening instructions.124125## Progressive disclosure and bundled resources126127Read bundled resources only when needed:128129- `references/excalidraw-schema.md`: complete Excalidraw JSON schema.130- `references/element-types.md`: detailed element type specifications.131- `references/icon-libraries.md`: Excalidraw icon libraries and optional icon loading.132- `templates/flowchart-template.excalidraw`: basic flowchart starter.133- `templates/relationship-template.excalidraw`: relationship diagram starter.134- `templates/mindmap-template.excalidraw`: mind map starter.135- `templates/data-flow-diagram-template.excalidraw`: DFD starter.136- `templates/business-flow-swimlane-template.excalidraw`: swimlane starter.137- `templates/class-diagram-template.excalidraw`: class diagram starter.138- `templates/sequence-diagram-template.excalidraw`: sequence diagram starter.139- `templates/er-diagram-template.excalidraw`: ER diagram starter.140- `scripts/split-excalidraw-library.py`: split `.excalidrawlib` files.141- `scripts/add-icon-to-diagram.py`: add an icon to a diagram.142- `scripts/add-arrow.py`: add arrows programmatically.143- `scripts/README.md`: documentation for library tools.144- `scripts/.gitignore`: prevents local Python artifacts from being committed.145146## Limits147148- Complex curves are simplified to straight or basic curved lines.149- Embedded images are not generated automatically; use imports or icon-library resources when needed.150- No automatic collision detection exists, so apply spacing and validation manually.151- Mermaid or PlantUML import and auto-layout optimization are future enhancements, not current required output.152153## Troubleshooting154155| Issue | Solution |156| --- | --- |157| Elements overlap | Increase coordinate spacing or switch to grid/radial layout. |158| Text doesn't fit in boxes | Increase box width or reduce font size while staying readable. |159| Too many elements | Break into multiple diagrams. |160| Unclear layout | Use rows/columns for relationships or radial layout for mind maps. |161| Colors inconsistent | Define the palette upfront by element type. |162163## Naming and compatibility notes164165Preserve common example filenames and legacy template references when mapping older requests: user-registration-flow, `user-registration-flow.excalidraw`, user-content-relationships, `user-content-relationships.excalidraw`, machine-learning-mindmap, `machine-learning-mindmap.excalidraw`, user-workflow, templates/flowchart-template.json, templates/relationship-template.json, and `templates/mindmap-template.json`. Current bundled templates use `.excalidraw`; do not create new `.json` templates unless the user asks.166167Style names must remain understandable to agents translating older examples: Important/Central, Alerts/Warnings, actor-based process flows, Junction/associative entities, one-to-one, one-to-many, sub-diagrams, auto-generation, opening/editing, straight/basic curved lines, Mermaid/PlantUML future import, and core element keys `width`, `height`, `strokeColor`, `backgroundColor`, and `fillStyle`.168169## Output template170171```markdown172## Excalidraw diagram result - <diagram name>173174**Status:** created | needs clarification | blocked175**File:** `<descriptive-name>.excalidraw`176**Type:** Flowchart | Relationship Diagram | Mind Map | Architecture Diagram | Data Flow Diagram (DFD) | Business Flow (Swimlane) | Class Diagram | Sequence Diagram | ER Diagram177**Elements:** `<count>` total (`<rectangles>` rectangles, `<arrows>` arrows, `<text>` text)178179### Created structure180- <main nodes or sections>181- <relationships or flow>182183### To view1841. Visit https://excalidraw.com1852. Drag and drop `<descriptive-name>.excalidraw`1863. Or use File → Open in the Excalidraw VS Code extension187```188189## Quality gate190191- [ ] The chosen diagram type matches the user's intent and extracted structure.192- [ ] The file is valid JSON with `type`, `version`, `source`, `elements`, `appState`, and `files`.193- [ ] All elements have unique IDs and coordinates prevent overlap.194- [ ] All text elements use `fontFamily: 5` and readable `fontSize`.195- [ ] Arrows connect logically and labels match relationships or flow.196- [ ] Colors follow a consistent scheme and element count is reasonable.197- [ ] The output includes the `.excalidraw` file, summary, element count, and opening instructions.198199## References200201- [Excalidraw](https://excalidraw.com)
paulasilvatech