excalidraw-diagram

name	excalidraw-diagram
description	Generate Excalidraw diagrams from text descriptions. Use when creating flowcharts, mind maps, hierarchies, timelines, comparisons, relationship maps, matrices, or freeform diagrams. Outputs Obsidian-compatible .excalidraw.md files.
allowed-tools	Read, Write, Glob, Grep

Excalidraw Diagram Generator

Generate visual diagrams from text content as Obsidian-compatible .excalidraw.md files with embedded Excalidraw JSON.

When to Use This Skill

Activate when:

• User asks to create a diagram, chart, flowchart, or visual
• User mentions "diagrama", "fluxo", "mapa mental", "excalidraw", "timeline", "hierarquia"
• User wants to visualize a process, architecture, relationships, or structure
• User asks to diagram something from existing documentation

Workflow

1. Analyze content — Identify concepts, relationships, hierarchies, and flow
2. Select diagram type — Choose from 8 types based on content structure
3. Generate JSON — Build valid Excalidraw element array
4. Write file — Save as .excalidraw.md in Obsidian format

Diagram Types

Type	When to Use	Key Elements
Flowchart	Sequential processes, workflows	Rectangles + arrows, left-to-right or top-to-bottom
Mind Map	Concept expansion, brainstorming	Central node + radiating branches
Hierarchy	Org charts, taxonomies, tree structures	Parent-child rectangles, top-down
Relationship	Entity interactions, system dependencies	Nodes + bidirectional connectors
Comparison	Multi-option analysis, pros/cons	Side-by-side columns or grouped boxes
Timeline	Chronological events, roadmaps	Horizontal line + milestone markers
Matrix	2D classification, quadrants	Grid layout with labeled axes
Freeform	Unstructured layouts, mixed visuals	Free positioning, mixed elements

Output Format

File Structure (Obsidian .excalidraw.md)

---

excalidraw-plugin: parsed
tags: [excalidraw]

---
==⚠  Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠== You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'


# Excalidraw Data

## Text Elements
%%
## Drawing
```json
{EXCALIDRAW_JSON}

%%

### JSON Root Structure

```json
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://github.com/zsviczian/obsidian-excalidraw-plugin",
  "elements": [],
  "appState": {
    "gridSize": null,
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

Design Rules

Color Palette

Role	Color	Hex
Titles / primary stroke	Deep blue	#1e40af
Secondary elements / accent stroke	Bright blue	#3b82f6
Body text / neutral stroke	Gray	#374151
Emphasis / highlights	Gold	#f59e0b
Primary fill (light)	Light blue	#dbeafe
Secondary fill (light)	Light gold	#fef3c7
Neutral fill	Light gray	#f3f4f6
Success / positive	Green	#059669
Success fill	Light green	#d1fae5
Warning / attention	Orange	#d97706
Error / negative	Red	#dc2626
Error fill	Light red	#fee2e2
Default stroke (connectors)	Dark gray	#1e1e1e
Background	White	#ffffff

Typography

• Font family: 1 (Excalifont — hand-drawn style)
• Title: fontSize: 28, strokeColor: "#1e40af"
• Subtitle / section header: fontSize: 20, strokeColor: "#3b82f6"
• Body text: fontSize: 16, strokeColor: "#374151"
• Small labels: fontSize: 14, strokeColor: "#374151"
• Line height: 1.25 for all text
• textAlign: "center" for bound text, "left" for standalone
• No emojis in diagram elements

Canvas

• Target area: 0–1200 x 0–800 pixels
• Leave 40px margin from edges
• Minimum 20px gap between elements

Element Reference

Common Properties (all elements)

{
  "id": "unique-string",
  "type": "rectangle",
  "x": 0,
  "y": 0,
  "width": 200,
  "height": 100,
  "angle": 0,
  "strokeColor": "#1e40af",
  "backgroundColor": "#dbeafe",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "frameId": null,
  "index": "a0",
  "roundness": { "type": 3 },
  "seed": 1001,
  "version": 1,
  "versionNonce": 500100,
  "isDeleted": false,
  "boundElements": null,
  "updated": 1,
  "link": null,
  "locked": false
}

Shapes

Rectangle — Main container for content boxes, process steps, cards.

{
  "type": "rectangle",
  "roundness": { "type": 3 },
  "boundElements": [
    { "type": "text", "id": "text-id" }
  ]
}

Ellipse — Used for start/end nodes, emphasis circles.

{
  "type": "ellipse",
  "roundness": { "type": 2 }
}

Diamond — Decision points, conditional branches.

{
  "type": "diamond",
  "roundness": { "type": 2 }
}

Text

Standalone text (titles, labels):

{
  "type": "text",
  "text": "Title Text",
  "rawText": "Title Text",
  "originalText": "Title Text",
  "fontSize": 28,
  "fontFamily": 1,
  "textAlign": "left",
  "verticalAlign": "top",
  "containerId": null,
  "autoResize": true,
  "lineHeight": 1.25
}

Bound text (text inside a shape):

{
  "type": "text",
  "text": "Step 1",
  "rawText": "Step 1",
  "originalText": "Step 1",
  "fontSize": 16,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "middle",
  "containerId": "parent-shape-id",
  "autoResize": true,
  "lineHeight": 1.25
}

Binding rules:

1. Set text containerId to the shape's id
2. Add { "type": "text", "id": "text-id" } to the shape's boundElements array
3. Position text x/y inside the shape bounds (Obsidian auto-centers, but provide reasonable coords)
4. Text width and height should fit within the container

Arrows and Lines

Arrow (directional connector):

{
  "type": "arrow",
  "points": [[0, 0], [150, 0]],
  "lastCommittedPoint": [150, 0],
  "startBinding": {
    "elementId": "source-shape-id",
    "focus": 0,
    "gap": 1,
    "fixedPoint": null
  },
  "endBinding": {
    "elementId": "target-shape-id",
    "focus": 0,
    "gap": 1,
    "fixedPoint": null
  },
  "startArrowhead": null,
  "endArrowhead": "arrow",
  "elbowed": false
}

Line (non-directional connector):

{
  "type": "line",
  "points": [[0, 0], [100, 0]],
  "lastCommittedPoint": [100, 0],
  "startBinding": null,
  "endBinding": null,
  "startArrowhead": null,
  "endArrowhead": null
}

Binding rules for arrows:

1. First point MUST be [0, 0]
2. Arrow x, y = position of the start point in canvas coordinates
3. Set startBinding.elementId and endBinding.elementId to connect shapes
4. Add { "type": "arrow", "id": "arrow-id" } to both shapes' boundElements
5. focus: -1 to 1 — position along the target edge (0 = center)
6. gap: distance from shape edge (use 1)

Index Values

Each element needs a unique index string for ordering. Use alphabetical indexing:

• "a0", "a1", "a2", ... "a9", "aA", "aB", ...

Seed and Version

• seed: Use incrementing integers starting from 1000 (e.g., 1000, 1001, 1002)
• version: Always 1 for new diagrams
• versionNonce: Use seed * 100 for simplicity

Layout Patterns

Flowchart (left-to-right)

[Step 1] ---> [Step 2] ---> [Step 3]
                |
                v
            <Decision>
              /    \
         [Yes]    [No]

• Rectangles: width: 180, height: 80
• Horizontal gap: 80px (arrow space)
• Vertical gap: 60px for branches
• Diamonds for decisions: width: 140, height: 100

Mind Map (radial)

           [Branch 1]
              |
[Branch 4] - [CENTER] - [Branch 2]
              |
           [Branch 3]

• Center node: width: 200, height: 80, deep blue stroke + fill
• Branch nodes: width: 160, height: 60, bright blue stroke
• Leaf nodes: width: 140, height: 50, gray stroke
• Radial spacing: 200-250px from center

Hierarchy (top-down tree)

         [Root]
        /      \
   [Child 1]  [Child 2]
    /    \
[Leaf] [Leaf]

• Vertical level gap: 100px
• Horizontal sibling gap: 40px
• Center children under parents

Timeline (horizontal)

  |        |         |        |
[E1]     [E2]      [E3]     [E4]
  |        |         |        |
  2024     2025      2026     2027

• Horizontal line: full width at y=400
• Event markers: rectangles above/below the line (alternating)
• Date labels below each marker
• Spacing: 250px between events

Comparison (columns)

  [Option A]    [Option B]    [Option C]
  ┌────────┐   ┌────────┐   ┌────────┐
  │ Point 1│   │ Point 1│   │ Point 1│
  │ Point 2│   │ Point 2│   │ Point 2│
  │ Point 3│   │ Point 3│   │ Point 3│
  └────────┘   └────────┘   └────────┘

• Column width: 300px
• Column gap: 40px
• Header rectangles: accent color
• Content rectangles: neutral fill

Matrix (2x2 quadrant)

        High
    ┌────┬────┐
    │ Q1 │ Q2 │
    ├────┼────┤
    │ Q3 │ Q4 │
    └────┴────┘
  Low          High

• Quadrant size: 400x300 each
• Axis labels as standalone text
• Items positioned within quadrants

File Naming and Location

Default location

3-resources/diagrams/[topic]-[type].excalidraw.md

Project-specific

1-projects/[project-name]/[topic]-[type].excalidraw.md

Naming convention

• Lowercase, hyphen-separated
• Pattern: [descriptive-topic]-[diagram-type].excalidraw.md
• Examples:
  • user-onboarding-flowchart.excalidraw.md
  • product-architecture-hierarchy.excalidraw.md
  • q1-roadmap-timeline.excalidraw.md
  • pricing-models-comparison.excalidraw.md

Quality Checklist

Before saving, verify:

• All element IDs are unique strings
• All text elements have text, rawText, and originalText fields
• Bound text has containerId set and container has matching boundElements
• Arrow first point is [0, 0]
• Arrow bindings reference valid element IDs
• Shapes with bound arrows list them in boundElements
• Elements fit within 1200x800 canvas
• Font family is 1 for all text
• Colors use the defined palette
• Index values are unique and sequential
• File has correct Obsidian frontmatter and wrapper
• JSON is valid and properly escaped

Post-Generation Message

After saving the file, tell the user:

1. File path where the diagram was saved
2. Diagram type that was used
3. Number of elements generated
4. Instruction: "Open in Obsidian and switch to Excalidraw view to see the diagram"