Excalidraw Diagram Generator

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

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": {}
}

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

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

Complexity management

Procedure

1. Understand the request: determine diagram type, key elements, relationships, and complexity.
2. Choose the appropriate diagram type from the selection table.
3. Extract structured information: steps, decisions, entities, branches, actors, classes, lifelines, data stores, or cardinalities.
4. Use bundled templates when they match the requested type; otherwise build JSON from scratch using the schema rules.
5. Generate the .excalidraw file with unique IDs, non-overlapping coordinates, consistent colors, readable text, and logical arrows.
6. 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

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

• The chosen diagram type matches the user's intent and extracted structure.
• The file is valid JSON with type, version, source, elements, appState, and files.
• All elements have unique IDs and coordinates prevent overlap.
• All text elements use fontFamily: 5 and readable fontSize.
• Arrows connect logically and labels match relationships or flow.
• Colors follow a consistent scheme and element count is reasonable.
• The output includes the .excalidraw file, summary, element count, and opening instructions.

References

• Excalidraw