# Draw Excalidraw Diagram

> Use when someone asks to draw a diagram, make an Excalidraw diagram, or build an editable diagram. Default for all diagram requests.

- **Type:** Skill
- **Install:** `agentstack add skill-jiplet-transformation-os-utility-draw-excalidraw-diagram`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Jiplet](https://agentstack.voostack.com/s/jiplet)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Jiplet](https://github.com/Jiplet)
- **Source:** https://github.com/Jiplet/transformation-os/tree/main/skills/utility/utility-draw-excalidraw-diagram

## Install

```sh
agentstack add skill-jiplet-transformation-os-utility-draw-excalidraw-diagram
```

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

## About

## Workflow

### Step 1: Understand the request
Before generating anything, make sure you know:
- What concept or system are they diagramming?
- What are the major components or sections?
- What is the flow or relationship between them?

If the request is vague (e.g., "make a diagram of Docker"), ask 1-2 clarifying questions:
- What specific aspect? (architecture, networking, volumes, etc.)
- What level of detail? (high-level overview vs. detailed internals)

### Step 2: Research if needed
If you're not confident about the technical accuracy of the concept, research it before diagramming. Verify:
- Correct component names and relationships
- Proper hierarchy and nesting
- Accurate data flow direction

### Step 3: Plan the layout
Before writing any JSON, sketch the layout mentally:
- What are the major sections? (left-to-right or top-to-bottom)
- What is nested inside what?
- What arrows connect what?

Write down the section plan:
```
[Section A: w=170] --40px gap-- [Section B: w=170] --40px gap-- [Section C: w=640]
```

### Step 4: Generate elements
Build elements in order:
1. Outer boxes / containers first
2. Section header text
3. Nested elements (top to bottom within each section)
4. Arrows and arrow labels last

### Step 5: Save and deliver
1. Save to `[concept-slug].excalidraw` in the current directory
2. Show the full JSON in a code block so the user can copy it directly
3. Briefly describe what the diagram shows and what each color zone represents
4. Tell the user how to use the file:

> **How to view and edit your diagram:**
> - Go to excalidraw.com (free, no account needed)
> - Option A: Click the menu (top-left hamburger icon) > "Open" > select the `.excalidraw` file
> - Option B: Copy the JSON code block above, open excalidraw.com, and paste it with Ctrl+V / Cmd+V
> - Every element is fully editable -- drag to move, grab handles to resize, double-click to edit text

### Step 6: Handle feedback
If the user asks for changes:
- Shifting an element = update x/y on that element + all elements that depend on it
- Changing text = update both `text` and `originalText` fields
- Adding a zone = assign it a new color from the palette, keep spacing consistent
- If a diagram gets complex (20+ elements), build it section by section to avoid coordinate errors

---

## Critical Rule: Text Contrast

Text inside colored shapes must be readable. Use `#1e1e1e` (near-black) or `#343a40` (dark charcoal) for all text inside filled shapes. Never use the zone's stroke color for text sitting on that zone's background (e.g., yellow text on a yellow card is unreadable). Reserve the zone's strokeColor for shape borders and arrows only.

---

## Design Principles

**Color tells the story:** One color per logical zone. Everything in the "input" zone is blue. Everything in the "output" zone is green. The viewer should understand structure before reading a word.

**Nesting shows containment:** If X lives inside Y, X's box is drawn inside Y's box with consistent padding. Coordinates are absolute, not relative: `child_x = parent_x + padding`.

**Labels are short:** 2-5 words per label. Longer explanations become annotations with smaller fontSize and muted color (`#868e96`).

**White space is structure:** 15px minimum gap between siblings. 40px minimum between major sections.

**Arrows carry intent:** Color arrows to match purpose. Label every non-obvious arrow.

**Consistency:** If one panel uses bullet points (`•  `), every other multi-line description on the diagram uses bullets too. Don't mix bulleted lists with raw line-break paragraphs across cards. Same for numbered lists, dashes, indentation. Pick one style per diagram and stick to it.

**Professional tone:** Phrase objectives, descriptions, and gotchas in neutral business language. Don't name individuals when describing tasks ("Lift Alex's logic out of his head", "Sarah owns this in her brain"). Use "Document the existing logic", "Capture the current approach", "Existing rules are not yet documented" instead. Names are fine in attribution lines (e.g. "Open Questions for Alex") but not inside task phrasing.

---

## Layout System

Always plan coordinates before writing JSON.

1. Identify major sections (left-to-right or top-to-bottom)
2. Assign fixed width and starting x to each section
3. Calculate gaps: 40-60px between major sections, 15-25px between siblings
4. Work top-to-bottom within sections: `next_y = current_y + current_height + gap`

**Padding rules:**
- Outer box to inner label: 8-10px top offset
- Outer box to nested box: 10-15px offset on all sides
- Sibling elements: 10-15px gap

**Text width trick:** Set text width = parent box width. Text centers automatically when `textAlign: "center"`.

**Arrow labels:** Position as separate text elements, 20-25px above the arrow's midpoint y, with width and x matching the arrow.

**Coordinate math example:**
```
Section A: x=30,  w=170  -> right edge = 200
Gap:                        40px
Section B: x=240, w=170  -> right edge = 410
Gap:                        40px
Section C: x=450, w=600  -> right edge = 1050
```

---

## Color System

| Zone | Use for | strokeColor | backgroundColor |
|------|---------|-------------|-----------------|
| Blue | Input, source, external services | `#1971c2` | `#e7f5ff` |
| Yellow | Processing, transformation | `#f59f00` | `#fff9db` |
| Green | Output, containers, success | `#2f9e44` | `#d3f9d8` |
| Purple | Shared layers, infrastructure | `#862e9c` | `#f3d9fa` |
| Red | Host OS, warnings, errors | `#c92a2a` | `#ffe3e3` |
| Gray | Hardware, neutral containers | `#495057` | `#f8f9fa` |

For nested elements, vary the fill intensity:
- Outer: lightest (e.g., `#d3f9d8`)
- Inner: medium (e.g., `#8ce99a`)
- Deep inner: light-medium (e.g., `#b2f2bb`)

---

## Typography Scale

**HARD RULE — never use the handwriting font (Virgil, fontFamily 1).** It looks unprofessional and is not acceptable for any programme output (exec, internal, or working). Default `fontFamily: 2` (Helvetica) for every text element. Use `fontFamily: 3` (Cascadia) only for code-style labels. Never `fontFamily: 1`.

Apply the same rule to `roughness`: use `0` (smooth) by default. The "hand-drawn" rough strokes pair with the handwriting font to create the same unprofessional look. Only deviate (`roughness: 1`) for an explicit, casual brainstorm context Jacob has confirmed.

| Role | fontSize | fontFamily |
|------|----------|------------|
| Diagram title | 28-32 | 2 (Helvetica) |
| Section header | 18-22 | 2 |
| Element label | 15-17 | 2 |
| Annotation | 13-14 | 2 |
| Small note | 11-12 | 2 |
| Code label | 13-15 | 3 (Cascadia) |

Text width = parent box width. Text x/y offset ~8-10px from box x/y for padding.

---

## Element Schema

Every element needs these base fields. Do not omit any.

### Base fields (all types)
```json
{
  "id": "unique-string",
  "type": "rectangle|ellipse|diamond|arrow|line|text|freedraw",
  "x": 0, "y": 0,
  "width": 100, "height": 50,
  "angle": 0,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "frameId": null,
  "roundness": null,
  "boundElements": [],
  "updated": 1,
  "link": null,
  "locked": false
}
```

### Text fields (add to base)
```json
{
  "text": "Label text",
  "fontSize": 16,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "top",
  "containerId": null,
  "originalText": "Label text",
  "lineHeight": 1.25
}
```

### Arrow fields (add to base)
```json
{
  "points": [[0, 0], [100, 0]],
  "lastCommittedPoint": null,
  "startBinding": null,
  "endBinding": null,
  "startArrowhead": null,
  "endArrowhead": "arrow"
}
```

### Key values
- **fontFamily:** 2 = Helvetica (DEFAULT — always use), 3 = Cascadia (monospace, code labels only). **Never use 1 (Virgil / handwritten) — banned for professional output.**
- **roughness:** 0 = smooth (DEFAULT — always use). Never 1 or 2 unless Jacob has explicitly confirmed a casual / sketchy context.
- **fillStyle:** `"solid"` for clean diagrams (DEFAULT). Never `"hachure"` — pairs with the rough/handwritten look we are avoiding.
- **roundness:** `null` = sharp corners, `{"type": 3}` = rounded rectangles, `{"type": 2}` = curved arrows
- **strokeStyle:** `"solid"`, `"dashed"` (optional connections), `"dotted"`

---

## Common Patterns

### Labeled box
```
[Rect: x, y, w, h]
[Title text: x, y+10, w, fontSize=18]
[Subtitle: x, y+38, w, fontSize=14, strokeColor=#868e96]
```

### Nested container
```
[Host rect: x=0, y=0, w=640, h=500]
[Host label: x=0, y=10, w=640]
[Item 1: x=15, y=50, w=190, h=200]
[Item 2: x=225, y=50, w=190, h=200]
[Item 3: x=435, y=50, w=190, h=200]
```

### Arrow with label
```
[Arrow: x=start_x, y=mid_y, width=gap_width, points=[[0,0],[gap_width,0]]]
[Label: x=start_x, y=mid_y-25, width=gap_width, textAlign=center]
```

---

## JSON Wrapper

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

## Source & license

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

- **Author:** [Jiplet](https://github.com/Jiplet)
- **Source:** [Jiplet/transformation-os](https://github.com/Jiplet/transformation-os)
- **License:** MIT

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-jiplet-transformation-os-utility-draw-excalidraw-diagram
- Seller: https://agentstack.voostack.com/s/jiplet
- 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%.