Excalidraw Diagram Builder

---
name: excalidraw-diagram-builder
description: Use when generating an Excalidraw whiteboard diagram from a natural-language description. Triggers on "Excalidraw", "whiteboard diagram", "sketch this architecture", or any request where the output should be a shareable file rather than an inline code-rendered diagram.
---

# Excalidraw Diagram Builder

Generate an Excalidraw diagram where the layout itself communicates the relationships, not just lists the components. If the spatial arrangement doesn't convey the logical structure, the diagram needs to be redesigned, not annotated.

## Required inputs

1. **The structure to diagram** — system components, process steps, concept map, team relationships
2. **The key relationships** — what is one-to-many, sequential, parallel, or shared-ownership?
3. **The primary path** (if applicable) — what's the main flow vs. secondary branches?
4. **The audience** — mixed engineer/non-engineer changes annotation density
5. **Brand palette** (optional) — hex values; if none, use the default sketch look (white fill, dark stroke)

## Layout principles — encode relationships, not categories

The spatial arrangement is the diagram's argument. Use these conventions consistently:

- **Fan-outs** — one parent, multiple children spread below or to the right: encodes one-to-many ownership
- **Linear chains** — left-to-right or top-to-bottom sequence with clear arrow directionality: encodes order
- **Overlapping boxes** — literal visual overlap: encodes shared ownership or joint responsibility
- **Proximity** — elements that belong together cluster; unrelated elements have visible whitespace between them
- **Arrow style** — solid arrows for primary/sync flows, dashed for secondary/async; label every arrow on an ambiguous branch

If the structure requires crossing arrows or double-back edges, split the diagram by concern rather than forcing everything into one view.

## Excalidraw JSON structure

An Excalidraw file is JSON with an `elements` array. Key fields per element:

- `type`: `"rectangle"`, `"ellipse"`, `"diamond"`, `"arrow"`, `"text"`, `"line"`
- `x`, `y`: top-left position in Excalidraw's coordinate space
- `width`, `height`: element dimensions
- `label.text`: the visible label for shape elements
- `strokeColor`, `backgroundColor`: hex strings

Shape conventions by semantic meaning:
- `"rectangle"` — services, components, process steps
- `"ellipse"` — external actors, users, third-party systems
- `"diamond"` — decision points
- `"text"` — evidence artifacts and annotation nodes placed near relevant elements

## Evidence artifacts as text nodes

Embed concrete evidence as `"text"` elements placed near the relevant element:

- API response JSON snippets near API gateway elements
- Error message strings near failure-path arrows
- Throughput estimates ("~50k events/day") next to queue nodes

These anchor the diagram to real system behavior and make it useful in debugging conversations, not just design reviews.

## Brand palette and color use

Color encodes category — use it for signal, not decoration:

- One `backgroundColor` per logical group (services, data stores, external systems)
- `strokeColor` one shade darker than `backgroundColor` for contrast
- 3–4 colors maximum; more than that obscures the grouping

If no palette is specified, use Excalidraw's default sketch aesthetic (white fill, dark stroke). This communicates that the diagram is intentionally informal — usually accurate for early architecture discussions.

## Visual validation (coleam00/excalidraw-diagram-skill)

Before handing off the file, run the Playwright validation hook to check:

- No unintentional element overlap (overlapping boxes only where shared-ownership layout is intended)
- All arrow endpoints connected to named elements
- All text labels visible and not clipped by element bounds

Layout defects that look correct in the JSON are often obvious once rendered at screen resolution.

## Excalidraw vs. Mermaid — rendering context decides

| Situation | Use |
|---|---|
| Embed in PR comment, GitHub wiki, or Notion | Mermaid |
| Share as a file or Excalidraw.com link | Excalidraw |
| Formal UML (class, sequence, ER) | Mermaid |
| Design review with mixed eng/non-eng audience | Excalidraw |
| Diagram in version control, needs to be text-diffable | Mermaid |

## Anti-patterns

- **Grid of boxes with no connections** — a grid of service names is a legend, not a diagram. Show the flows.
- **Arrow soup** — if every element connects to every other, split by concern (write path vs. read path, happy path vs. error path).
- **More than 12 elements** — Excalidraw's format invites addition. At 12+ elements, start a linked sub-diagram.
- **Colors for decoration** — every color encodes a group. If you're adding color to make the diagram look nicer, remove it.
- **No evidence artifacts** — a pure boxes-and-arrows sketch with no numbers, rates, or payload samples is speculation, not documentation.

## Output

Provide the complete Excalidraw JSON in a ```json code block, plus:
- A 2-line summary: what the diagram shows, and which layout choice encodes the most important relationship
- Filename recommendation (`<system>-<view>-<date>.excalidraw`)

If you split into multiple diagrams, label each one and name the boundary between them.