# Excalidraw Generator

> Professional Excalidraw diagram generation expert that creates complete, valid .excalidraw.json files based on user descriptions. Use ONLY when users explicitly mention "Excalidraw" or request to create diagrams specifically with Excalidraw (e.g., "用 Excalidraw 画个流程图", "generate an Excalidraw diagram", "create Excalidraw file"). Do NOT trigger for generic diagram requests without Excalidraw menti…

- **Type:** Skill
- **Install:** `agentstack add skill-kv0906-pm-kit-excalidraw`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kv0906](https://agentstack.voostack.com/s/kv0906)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kv0906](https://github.com/kv0906)
- **Source:** https://github.com/kv0906/pm-kit/tree/main/.claude/skills/excalidraw
- **Website:** https://willtran.xyz

## Install

```sh
agentstack add skill-kv0906-pm-kit-excalidraw
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Excalidraw Diagram Generator

Create complete, valid `.excalidraw.json` files that users can directly open at excalidraw.com.

## Core Capabilities

Diagram types supported:
- **Flowcharts** - Process flows, decision trees, workflows
- **Architecture Diagrams** - System architectures, network topologies, component diagrams
- **UML Diagrams** - Class diagrams, sequence diagrams, use case diagrams
- **Mind Maps** - Hierarchical concept maps, brainstorming diagrams

**Two visual styles:**
- **Professional Mode** (default): Clean, polished diagrams for technical documentation
- **Hand-drawn Mode**: Sketch-style diagrams for brainstorming and informal use

---

## Quick Reference

### JSON Schema

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

### Coordinate System

- **Origin**: Top-left corner (0, 0)
- **X-axis**: Increases rightward
- **Y-axis**: Increases downward
- **Unit**: Pixels

### Grid-Based Layout System

Use a 20px grid for alignment:

```
GRID_UNIT = 20
COLUMN_WIDTH = 200    # Element + gap
ROW_HEIGHT = 150      # Element + gap

Position formula:
  x = START_X + (column * COLUMN_WIDTH)
  y = START_Y + (row * ROW_HEIGHT)

Recommended START_X = 50, START_Y = 100
```

### Standard Element Sizes

| Element | Width | Height | Use Case |
|---------|-------|--------|----------|
| Small box | 120 | 60 | Labels, simple steps |
| Standard box | 160 | 80 | Process steps |
| Large box | 200 | 100 | Detailed nodes |
| Wide box | 240 | 80 | Long text |
| Diamond | 100 | 100 | Decision points |
| Circle | 80 | 80 | Start/End nodes |

---

## Text Calculations (CRITICAL)

### Text Height Formula

```
textHeight = fontSize × lineHeight × numberOfLines
           = fontSize × 1.25 × numberOfLines

Examples:
- 1 line, fontSize 20: 20 × 1.25 × 1 = 25px
- 3 lines, fontSize 14: 14 × 1.25 × 3 = 52.5px ≈ 53px
- 12 lines, fontSize 15: 15 × 1.25 × 12 = 225px
```

### Text Centering Formula

```
text_x = shape_x + (shape_width - text_width) / 2
text_y = shape_y + (shape_height - text_height) / 2
```

### Text Size Reference

| Font Size | Char Width | Line Height | Use |
|-----------|------------|-------------|-----|
| 11 | ~6px | 15px | Labels, annotations |
| 12 | ~7px | 16px | Secondary text |
| 14 | ~8px | 18px | Body text |
| 16 | ~9px | 20px | Primary text |
| 18 | ~10px | 24px | Headings |
| 20 | ~11px | 26px | Titles |
| 28 | ~16px | 35px | Icons/Emoji |

**Estimate text_width**: `char_count × char_width`

### Centering Example

```
Shape: x=100, y=100, width=160, height=80
Text: "Process" (7 chars), fontSize=16

text_width = 7 × 9 = 63
text_height = 1 × 20 = 20
text_x = 100 + (160 - 63) / 2 = 148.5 ≈ 148
text_y = 100 + (80 - 20) / 2 = 130
```

### UML Class Diagram Container Height

```
containerHeight = headerHeight + attributesHeight + methodsHeight + padding

Where:
- headerHeight = classNameTextHeight + topPadding (typically 15px + 15px = 30px)
- attributesHeight = fontSize × 1.25 × numberOfAttributes + 10px
- methodsHeight = fontSize × 1.25 × numberOfMethods + 10px

Example (12 attributes, 10 methods, fontSize 15):
- Header: 20 + 15 = 35px
- Attributes: 15 × 1.25 × 12 + 10 = 235px
- Methods: 15 × 1.25 × 10 + 10 ≈ 198px
- Total: 35 + 10 + 235 + 10 + 198 = 488px (round to 500px)
```

---

## Arrow Positioning

### Horizontal Arrow (Left to Right)

```
From shape at (x1, y1, w1, h1) to shape at (x2, y2, w2, h2):

arrow_x = x1 + w1           # Right edge of source
arrow_y = y1 + h1/2         # Vertical center
gap = x2 - (x1 + w1)        # Space between shapes
points = [[0, 0], [gap, 0]]
```

### Vertical Arrow (Top to Bottom)

```
arrow_x = x1 + w1/2         # Horizontal center
arrow_y = y1 + h1           # Bottom edge of source
gap = y2 - (y1 + h1)
points = [[0, 0], [0, gap]]
```

### Feedback Loop (Return Arrow)

```
From bottom-right back to left:
  Start: (800, 400)
  points=[
    [0, 0],        # Start
    [0, 80],       # Down
    [-400, 80],    # Left
    [-400, -150]   # Up to target
  ]
```

---

## Z-Order (Element Array Order)

Elements render in array order. First = back, last = front.

**Correct order:**
1. Background shapes (containers, frames)
2. Connection lines/arrows
3. Foreground shapes (nodes, boxes)
4. Text labels
5. Icons/overlays

---

## Visual Styles

### Professional Mode (Default)

**Use for:** Architecture diagrams, UML, technical docs, formal presentations

```json
{
  "roughness": 0,
  "fillStyle": "solid",
  "strokeWidth": 2,
  "fontFamily": 2
}
```

**Colors (light backgrounds for readability):**
| Purpose | Background |
|---------|------------|
| Primary | `#e7f5ff` |
| Success | `#ebfbee` |
| Warning | `#fff9db` |
| Accent | `#f3f0ff` |
| Secondary | `#fff4e6` |

### Hand-drawn Mode

**Use for:** Brainstorming, sketches, informal sharing

```json
{
  "roughness": 1,
  "fillStyle": "hachure",
  "strokeWidth": 2,
  "fontFamily": 1
}
```

**Colors (medium saturation):**
| Purpose | Background |
|---------|------------|
| Primary | `#a5d8ff` |
| Success | `#b2f2bb` |
| Warning | `#ffec99` |
| Error | `#ffc9c9` |
| Accent | `#d0bfff` |
| Secondary | `#ffd8a8` |

**Stroke color:** `#1e1e1e` (dark gray, softer than pure black)

---

## Element Types

### Common Properties (required for all)

```json
{
  "id": "unique-id",
  "type": "rectangle",
  "x": 100,
  "y": 100,
  "width": 160,
  "height": 80,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "roughness": 1,
  "opacity": 100,
  "angle": 0,
  "seed": 100,
  "version": 1,
  "isDeleted": false,
  "boundElements": null,
  "link": null,
  "locked": false
}
```

### Type-Specific Properties

**Rectangle**: Add `"roundness": {"type": 3}` for rounded corners

**Text**:
```json
{
  "type": "text",
  "text": "Content\nLine 2",
  "fontSize": 16,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "middle"
}
```
- fontFamily: 1=Virgil (hand), 2=Helvetica, 3=Cascadia (mono)

**Arrow/Line**:
```json
{
  "type": "arrow",
  "points": [[0, 0], [100, 0]],
  "startArrowhead": null,
  "endArrowhead": "arrow"
}
```
- Points are relative to element's x,y
- Arrowheads: `null`, `"arrow"`, `"bar"`, `"dot"`, `"triangle"`

---

## Workflow

### Step 1: Identify Diagram Type

Match the request to a diagram type:
- **Flowchart**: Process flows, algorithms, decision trees, workflows
- **Architecture**: System designs, microservices, cloud infrastructure
- **UML Class**: Object-oriented design, class hierarchies, relationships
- **Mind Map**: Brainstorming, concept hierarchies, topic exploration

### Step 2: Use Templates as Foundation

Templates in `assets/`:
- `flowchart-template.json`
- `architecture-template.json`
- `uml-class-template.json`
- `mindmap-template.json`

**Usage:**
1. Read the appropriate template
2. Modify IDs, text, positions, colors
3. Add/remove elements as needed
4. Ensure all IDs are unique

### Step 3: Generate Elements

Key element types:
- `rectangle` - Boxes, containers, processes
- `ellipse` - Start/end nodes, databases
- `diamond` - Decisions, conditional branches
- `arrow` / `line` - Connections, flows
- `text` - Labels, descriptions

### Step 4: Calculate Layout

Use the grid system and text centering formulas above.

**Layout strategies:**
- **Flowcharts**: Top-to-bottom, centered alignment
- **Architecture**: Left-to-right for flow, grouped by layer
- **UML Class**: Use container height formula; prevent text overflow
- **Mind Maps**: Radial from center, balanced branches

### Step 5: Style and Polish

1. Choose visual style (Professional or Hand-drawn)
2. Apply consistent colors from the palette
3. Ensure adequate spacing (80-100px between elements)

### Step 6: Save to File

**Always save directly as `.excalidraw.json`** (no code blocks).

1. Write complete JSON to file
2. Name descriptively (e.g., `user-login-flow.excalidraw.json`)
3. Save to current directory unless specified otherwise

**After saving, provide:**
1. Confirmation with file path
2. Brief description of diagram structure
3. Instructions: "Open at excalidraw.com → Menu → Open"

---

## Common Patterns

### Pattern 1: Sequential Flow

For A → B → C processes:
1. Place elements vertically with 120px gaps
2. Use rectangles for processes, ellipses for start/end
3. Connect with arrows (endArrowhead: "arrow")
4. Center-align all elements

### Pattern 2: Decision Tree

For conditional branches:
1. Use diamond for decision nodes
2. Branch arrows left/right or up/down
3. Add text labels on arrows ("Yes", "No")
4. Rejoin paths when appropriate

### Pattern 3: Hierarchical Structure

For layered architectures:
1. Group elements by layer (horizontal rows)
2. Use different colors per layer
3. Vertical arrows show dependencies
4. Consistent element sizes within layers

### Pattern 4: Radial Mind Map

For concept exploration:
1. Central node (ellipse) in middle
2. Lines radiate outward
3. Different colors per branch
4. Rectangles for sub-topics

---

## Positioning Checklist

Before generating:
1. Define grid: START_X, START_Y, COLUMN_WIDTH, ROW_HEIGHT
2. List all elements with row/column positions
3. Calculate exact x,y using formulas
4. Calculate text positions using centering formula
5. Calculate arrow start points and relative endpoints
6. Order elements correctly for z-order
7. Assign unique IDs and incrementing seeds

---

## Complete Node Example

```json
[
  {
    "id": "node1-box",
    "type": "rectangle",
    "x": 100, "y": 100, "width": 160, "height": 80,
    "strokeColor": "#1971c2",
    "backgroundColor": "#a5d8ff",
    "fillStyle": "solid",
    "strokeWidth": 2,
    "roughness": 1,
    "opacity": 100,
    "angle": 0,
    "seed": 100,
    "version": 1,
    "isDeleted": false,
    "boundElements": [{"id": "arrow1", "type": "arrow"}],
    "roundness": {"type": 3},
    "link": null,
    "locked": false
  },
  {
    "id": "node1-text",
    "type": "text",
    "x": 130, "y": 130,
    "width": 100, "height": 20,
    "text": "Process Step",
    "fontSize": 16,
    "fontFamily": 1,
    "textAlign": "center",
    "verticalAlign": "middle",
    "strokeColor": "#1e1e1e",
    "backgroundColor": "transparent",
    "fillStyle": "solid",
    "strokeWidth": 1,
    "roughness": 1,
    "opacity": 100,
    "angle": 0,
    "seed": 101,
    "version": 1,
    "isDeleted": false,
    "boundElements": null,
    "link": null,
    "locked": false
  }
]
```

---

## Tips for Quality Diagrams

1. **Unique IDs**: Generate random 8-16 character IDs for each element
2. **Consistent spacing**: Follow spacing guidelines strictly
3. **Color harmony**: Use the recommended color palette
4. **Text sizing**: Match text width to container width with padding
5. **Arrow connections**: Position arrow start/end points precisely
6. **Version numbers**: Use random integers for versionNonce and seed

## Handling Complex Requests

For large or complex diagrams:
1. **Start simple**: Create core structure first
2. **Iterate**: Add details progressively
3. **Group logically**: Use visual grouping (colors, spacing)
4. **Limit complexity**: Suggest breaking into multiple diagrams if needed
5. **Maintain readability**: Ensure text doesn't overlap, adequate spacing

---

## Resources

### assets/
Templates for common diagram types:
- `flowchart-template.json`
- `architecture-template.json`
- `uml-class-template.json`
- `mindmap-template.json`

### references/
- `excalidraw-format.md` - Complete JSON format specification
- `elements.md` - Element types and properties
- `processing-loop-template.md` - Processing loop example

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kv0906](https://github.com/kv0906)
- **Source:** [kv0906/pm-kit](https://github.com/kv0906/pm-kit)
- **License:** MIT
- **Homepage:** https://willtran.xyz

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kv0906-pm-kit-excalidraw
- Seller: https://agentstack.voostack.com/s/kv0906
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.