excalidraw-mermaid

What this skill does

# Excalidraw-Mermaid Drawer

Specialist for producing Mermaid source that survives Excalidraw's
`@excalidraw/mermaid-to-excalidraw` converter without surprises. Default
posture is *be opinionated*: pick the right diagram type for the intent,
use shapes that round-trip well, quote everything that could be ambiguous,
and hand the user something they can paste once and ship.

The two most important rules of this skill:

> **Rule #1 — Visual clarity beats completeness.** A diagram with 8
> uncluttered nodes is worth ten times a diagram with 25 cramped ones.
> If the user has to squint or trace edges with their finger, the
> diagram has failed. Prefer fewer nodes, shorter labels, more
> whitespace, and splitting into multiple diagrams over packing
> everything into one canvas.

> **Rule #2 — Excalidraw supports a subset of Mermaid.** Authoring
> Mermaid that renders in mermaid.live but breaks in Excalidraw is the
> failure mode to avoid. Pick from the supported subset every time.

These two rules win against any other temptation in this document.
When they conflict with anything below, follow them anyway.

---

## Mental model — your Mermaid is a starting point, not the final art

The Excalidraw diagrams that look great — hatched colored fills,
role-coded entity colors, edge annotations in red, callout labels
floating next to boundaries — are **not** one-shot Mermaid output.
They are:

1. A **clean Mermaid** authored with the rules in this skill.
2. Pasted into Excalidraw via "Mermaid to Excalidraw".
3. **Polished by hand inside Excalidraw**: filling subgraph
   backgrounds, recoloring shapes by role, repositioning labels.

Your job in this skill is **step 1**. Optimize the Mermaid so that
step 3 takes one minute, not ten. That means:

- Use subgraphs to mark groups → user fills them with color later.
- Lay out nodes so the user doesn't have to reflow.
- Keep labels short enough that Excalidraw doesn't wrap them mid-word.
- Don't try to encode color or annotations in Mermaid (it'll be stripped).

When the user sees your Mermaid result and asks "how do I make it
pretty?" — that's the expected workflow, not a failure. Walk them
through the polish steps if asked.

---

## Visual clarity rules (these override every other guidance)

These come from the typical Mermaid-to-Excalidraw failure modes —
crossing edges, mid-word wraps, undifferentiated node soup. Follow
all of them.

### 1. Label length: ≤ 20 characters per line, ≤ 2 lines

Excalidraw auto-sizes nodes to fit, but its wrap heuristic is poor.
A 40-character label becomes a node that's either huge or wraps in
the middle of a word.

```
GOOD:  A["CheckLatest"]
       B["parseINI"]
       (two nodes, edge labeled "calls")

BAD:   A["CheckLatest<br/>parseINI<br/>Version = primary.patch"]
       (three lines, will wrap mid-word in many excalidraw versions)
```

When you need to convey multi-step behavior inside one logical
unit, **split into multiple nodes** or move detail to edge labels.

### 2. Never use `<br/>` for line breaks

`<br/>` is in the Mermaid spec but inconsistent in
mermaid-to-excalidraw. Some versions render the literal text
"<br/>" inside the node.

If a label genuinely needs two lines, write it as a single short
phrase and let Excalidraw auto-wrap. If that doesn't work, **split
into multiple nodes** connected by edges. Never bet on `<br/>`.

### 3. Place external systems adjacent to their callers

If `CheckLatest` calls `AU CDN`, put `AU CDN` next to `CheckLatest`
in the source order so the layout engine keeps them close. If
`UpdateInPlace` also calls `AU CDN`, the cleanest structure is one
of:

```
flowchart LR
    %% External on the right, flow on the left
    subgraph Flow["UpdateInPlace"]
        direction TB
        Step1 --> Step2 --> Step3
    end

    AU[("AU CDN")]
    Step1 -. "GET /server.ini" .-> AU
    Step3 -. "GET zips" .-> AU
```

This puts the external system on the right and the flow on the
left — the user can recolor the subgraph and the layout stays
clean.

### 4. Subgraphs are how you tell the user "color this"

A subgraph is a hint to the user: "this whole region is a logical
unit, fill it with a background color in Excalidraw". Always:

- Give the subgraph an explicit ID and quoted label
- Set an explicit `direction TB` or `LR`
- Put only logically-related nodes inside

```
subgraph Server["Scan-Server (Go process)"]
    direction TB
    gRPC["gRPC :50051"]
    HTTP["HTTP :8080"]
    Logic["Business logic"]
    gRPC --> Logic
    HTTP --> Logic
end
```

Don't subgraph for purely visual reasons. Don't nest subgraphs
more than one level deep — excalidraw's layout breaks.

### 5. Minimize edge crossings

Reorder nodes in your source until the most important arrows go in
one consistent direction (top-to-bottom for `TD`, left-to-right
for `LR`). If two edges *must* cross, make one of them dotted
(`-.->`) so the eye separates them.

If a "return to caller" arrow would cross the entire diagram,
*do not draw it*. The implicit return is fine — the next node in
flow tells the reader execution continued.

### 6. One color theme suggestion per diagram

Don't try to convey colors in Mermaid (you can't reliably). But
**leave structural breadcrumbs** that imply where color should go:

- Subgraphs → fill backgrounds
- External systems (cylinder shape `[(...)]`) → distinct color
- Decision diamonds → another color
- Entry/exit (pill shape `([...])`) → another color

The user sees 4 visual categories in the source and applies 4
colors in Excalidraw. That's the unspoken contract.

### 7. Max 12 nodes for "narrative" diagrams, 25 for "reference" diagrams

If you're showing a process flow that the reader will follow with
their eye, 12 nodes is already a lot. If you're showing a
reference (system overview, schema), 25 is the ceiling.

Beyond those numbers, **split into multiple diagrams**:

- One overview ("here are the major components")
- One per zoom-in ("here's what happens inside Component X")

### 8. Whitespace is your friend — leave gaps in source

Mermaid ignores blank lines for layout, but Excalidraw's converter
sometimes uses them as section hints. Even when it doesn't, blank
lines make the *source* readable so you can spot crossings before
you ship.

```
flowchart TD
    Client --> LB
    LB --> Web

    Web --> Cache
    Web --> DB

    Cache -.-> Origin
```

---

## When to invoke

Trigger phrases include:

- "draw this as mermaid" / "make a mermaid diagram"
- "give me a diagram I can paste into excalidraw"
- "flowchart for X" / "sequence diagram of Y" / "architecture diagram"
- "draw the flow" / "diagram this"
- Any time the user asks for a diagram and excalidraw is the rendering target

Also invoke proactively when the user has just described a system or flow
in prose and a visual would obviously help. Confirm the rendering target
(excalidraw vs. mermaid.live vs. github markdown) before producing output
if it isn't already clear — the constraints differ.

---

## Step 0 — Pick the right diagram type

Excalidraw's mermaid integration supports only a handful of diagram
types well. Pick from this list and nothing else:

| Diagram type     | Excalidraw support | When to use                                          |
| ---------------- | ------------------ | ---------------------------------------------------- |
| `flowchart`      | **excellent**      | Default. Process flow, data flow, architecture, decision trees |
| `sequenceDiagram`| **excellent**      | Time-ordered interactions between actors / services  |
| `classDiagram`   | **good**           | OO models, type hierarchies, schema relationships    |

Avoid the rest — they render badly or not at all in Excalidraw at the time of writing:

| Diagram type           | Issue in Excalidraw                                  |
| ---------------------- | ---------------------------------------------------- |
| `stateDiagram-v2`      | Layout breaks; nested states drop                    |
| `erDiagram`            | Crow's-foot n