Excalidraw Diagram

Purpose

This skill creates diagrams using the Excalidraw format — a JSON-based drawing format rendered by the Excalidraw library and its integrations. The output has a distinctive hand-drawn, whiteboard aesthetic that is ideal for architecture sketches, concept maps, brainstorming visuals, and informal system diagrams.

Unlike Mermaid which produces precise, flow-based diagrams from DSL text, Excalidraw uses geometric primitives (rectangles, ellipses, arrows, text, lines) laid out on a freeform canvas. The hand-drawn style makes it suitable for early-stage thinking, workshop facilitation, and documentation where the informal look communicates "this is a sketch, not a specification."

In Obsidian, Excalidraw files are supported via the Excalidraw plugin by Zsolt Viczian, which renders .excalidraw files natively and allows embedding them in notes.

When to Use

Invoke this skill when:

• The user explicitly asks for an Excalidraw diagram
• The user wants a "sketch-style" or "whiteboard" diagram
• The user says "draw this informally" or "make it look hand-drawn"
• The user needs a system architecture or C4-style diagram with an informal aesthetic
• The user wants a concept map or mind map with free positioning (not the rigid Mermaid mindmap syntax)
• The user is working in Obsidian and wants to embed a whiteboard-style drawing
• The user wants a diagram exported as .excalidraw file or embedded in a Markdown note

Do NOT use this skill when:

• The user wants precise, structured flowcharts with clear graph routing — use mermaid-diagram instead
• The user wants a structured knowledge graph layout in Obsidian — use obsidian-canvas instead
• The user asks for a "professional" or "polished" diagram (Excalidraw's hand-drawn look is intentionally informal)
• The user wants to embed code blocks or data-driven diagrams

Excalidraw Output Formats

Diagram Types

Systems architecture

Boxes representing services/components connected with labeled arrows. Uses color to group related components (e.g., blue for frontend, green for backend, orange for external).

Concept map / mind map

Central concept with radiating branches. Each branch is a related idea. Uses curved arrows and freeform text nodes.

User flow / journey

Horizontal swim lanes for actors. Steps flow left to right. Decision points use diamond shapes.

C4-style sketch

Four levels: System Context → Container → Component → Code. Each level drawn as nested boxes with arrows for interactions.

Sequence sketch

Actors as columns, time flowing downward. Message arrows between columns with labels.

Workflow

Step 1: Identify the Diagram Type and Content

From the user's request, determine:

1. Diagram type from the list above
2. Main components — the nodes/entities in the diagram
3. Relationships — how components connect (and the labels on connections)
4. Layout preference — horizontal flow, vertical hierarchy, radial, or freeform

If the user's request is vague ("draw our system"), ask one clarifying question:

• "What are the main components to include?"
• "Should this be a sketch of the overall architecture, or a sequence of interactions?"

Step 2: Design the Layout

Plan the component positions before writing the Excalidraw JSON:

• Architecture diagrams: Group related components into clusters. Place external systems at the edges. Group by layer (frontend → backend → data → external).
• Concept maps: Place the central concept in the middle. Branch outward with related concepts at a radius of 200-300 units.
• User flows: Use horizontal layout. Actors as column headers at the top. Steps flow left to right.
• C4 sketches: Use nested rectangles. Outer box = system, inner boxes = containers, innermost = components.

Color guidelines:

• Blue (#1971c2 / fill #d0ebff) — user-facing or frontend components
• Green (#2f9e44 / fill #d3f9d8) — backend or processing components
• Orange (#e8590c / fill #ffe8cc) — external systems or third-party services
• Purple (#862e9c / fill #f3d9fa) — data storage or databases
• Gray (#495057 / fill #f1f3f5) — infrastructure or platform components

Step 3: Generate the Excalidraw JSON

Excalidraw diagrams are JSON objects with an elements array. Each element is a shape with position, size, style, and content properties.

Element schema:

{
  "type": "rectangle",
  "id": "unique-id",
  "x": 100,
  "y": 200,
  "width": 160,
  "height": 80,
  "strokeColor": "#1971c2",
  "backgroundColor": "#d0ebff",
  "fillStyle": "hachure",
  "strokeWidth": 2,
  "roughness": 1,
  "opacity": 100,
  "text": "Component Name",
  "fontSize": 16,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "middle"
}

Shape types:

• rectangle — boxes for components and systems
• ellipse — circles/ovals for actors or rounded shapes
• diamond — decision points
• arrow — directed connections between components
• line — undirected connections
• text — standalone labels

Arrow element:

{
  "type": "arrow",
  "id": "arrow-1",
  "x": 260,
  "y": 240,
  "width": 140,
  "height": 0,
  "points": [[0, 0], [140, 0]],
  "startBinding": {"elementId": "source-id", "gap": 5, "focus": 0},
  "endBinding": {"elementId": "target-id", "gap": 5, "focus": 0},
  "strokeColor": "#343a40",
  "strokeWidth": 2,
  "roughness": 1
}

Full Excalidraw file structure:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": {
    "gridSize": null,
    "viewBackgroundColor": "#ffffff"
  }
}

Step 4: Output the Diagram

For standalone .excalidraw file output: Output the complete JSON block in a fenced code block labeled json. Instruct the user to save it as DiagramName.excalidraw.

For Obsidian embed: Wrap the JSON in an Obsidian Excalidraw note format — a Markdown file with an excalidraw-plugin: parsed frontmatter and the JSON embedded in a code fence:

---
excalidraw-plugin: parsed
tags:
  - excalidraw
---

```json
{
  "type": "excalidraw",
  ...
}
```

Save as DiagramName.excalidraw.md in the vault. Embed in any note with ![[DiagramName.excalidraw.md]].

For animated SVG: Note that animated export requires the Obsidian Excalidraw plugin's export command — it cannot be generated as pure JSON. Guide the user through: Design view → ⋮ menu → Export as animated SVG.

Step 5: Provide Rendering Instructions

After the output, explain how to use it:

• Obsidian: Install the Excalidraw plugin by Zsolt Viczian. Save the file with .excalidraw.md extension. Open in Obsidian to see the rendered diagram. Embed with ![[filename.excalidraw.md]].
• Excalidraw.com: Go to excalidraw.com → ☰ Open → paste JSON.
• VS Code: Install the "Excalidraw" VS Code extension to render .excalidraw files.

Design Principles

Clarity over complexity:

• Limit to 10-15 elements per diagram. Larger diagrams should be split.
• Every arrow must have a label if the relationship is not obvious.
• Avoid crossing arrows where possible — reroute elements to minimize crossings.

Grouping by color:

• Use the color scheme consistently: blue = frontend, green = backend, orange = external.
• Add a legend box at the bottom right when using 3+ colors.

Typography:

• Use fontFamily: 1 (the hand-drawn font) for titles and labels.
• Keep label text short: 3-5 words maximum per element.
• Use ALL_CAPS or Title Case for component names, sentence case for descriptions.

Spacing:

• Maintain at least 40px gap between elements to prevent crowding.
• Grid spacing of 20px keeps elements visually aligned without rigid structure.
• Arrow labels should be positioned midpoint between source and target.

Critical Rules

NEVER:

• Output partial JSON that is not valid Excalidraw format
• Use element IDs that are duplicated — every ID must be unique
• Reference an element in a binding that does not exist in the elements array
• Include CJK characters, non-ASCII text, or language-specific content in labels
• Use more than 20 elements without suggesting the diagram be split
• Output a Mermaid block when the user asked for Excalidraw

ALWAYS:

• Use the roughness: 1 property for the hand-drawn aesthetic
• Assign unique, descriptive IDs (e.g., frontend-ui, api-gateway, user-db)
• Include a label on every arrow
• Output valid JSON that can be pasted directly into Excalidraw or saved as a file
• Note which Obsidian plugin is required (Excalidraw by Zsolt Viczian)

Example Usage

Example 1: Three-tier web architecture

User: "Draw a simple three-tier web architecture: browser, API server, and database."

Produces: An Excalidraw JSON with three boxes (Browser in blue, API Server in green, Database in purple) connected by two labeled arrows (HTTP Request/Response, SQL Query/Result). Grid layout, left to right.

Example 2: Concept map for product strategy

User: "Create a concept map where Product Strategy is the center, connected to: Vision, ICP, Positioning, Pricing, GTM, and Roadmap."

Produces: A radial layout with "Product Strategy" as a central ellipse and six boxes arranged around it, each connected with an arrow. Consistent spacing (~250px radius), short labels.

Example 3: User registration flow

User: "Sketch a user registration flow: User fills form → Validate email → Check if email exists → (Yes) Show error → (No) Hash password → Save to DB → Send confirmation."

Produces: A left-to-right flowchart with rectangles for process steps, a diamond for the decision point, two branches (Yes to error box, No continuing the flow), and end at "Send confirmation."

Example 4: C4 Context diagram

User: "Draw a C4 context diagram for our SaaS application. Users interact with our Web App. The Web App calls our Payment Provider and sends emails via our Email Service."

Produces: A C4-style sketch with User as a person icon (ellipse), Web App as the central rectangle, and two external system boxes (Payment Provider, Email Service) at the right edge. Labeled arrows for each interaction.

Example 5: Team structure org chart

User: "Quick org chart sketch: CPO at top, under CPO are PM Lead and Design Lead, under PM Lead are three PMs, under Design Lead are two Designers."

Produces: A top-down tree with seven total boxes, connected by hierarchical lines, using gray for the org structure coloring and clear label names.