v1.1.0 to v1.1.0

---

name: excalidraw

description: "MANDATORY prerequisite for ALL Excalidraw MCP tool usage. Read BEFORE calling any Excalidraw tool (batch_create_elements, create_element, update_element, etc.). Without the sizing formulas, two-batch ordering (shapes-then-arrows), compact legends, domain styling presets, and write-check-review cycle in this skill, diagrams have invisible arrows, truncated text, and inconsistent colors. Use whenever the user asks to draw, sketch, visualize, or diagram anything technical - system architecture, microservices topology, C4 diagrams, data pipelines / ETL flows / lakehouse, sequence diagrams, ER diagrams, deployment / Kubernetes diagrams, network topology, flowcharts, decision trees. Includes ready-to-apply color palettes for software engineering, system architecture, and data solutions."

license: MIT

metadata:

author: vanducng

version: "1.1.0"

---

# Excalidraw - Technical Diagram Skill

## Step 0 - Detect Connection

Check **in order**:

1. **MCP server**: tools prefixed `mcp__excalidraw-mcp__*` (e.g. `batch_create_elements`, `describe_scene`) available → use MCP mode. This is the default for this user.

2. **REST fallback**: only if MCP missing - `curl -s $EXPRESS_SERVER_URL/health` returns `{"status":"ok"}`.

3. **Nothing** → auto-bootstrap the MCP config (see below), then tell user to reconnect the MCP so it registers. Do not fake output.

### Auto-bootstrap `.mcp.json`

When neither the MCP tools nor the REST fallback are available:

1. Resolve **project root**: `git rev-parse --show-toplevel` (fallback to CWD if not a git repo). Inside a git worktree this correctly returns the worktree itself - `.mcp.json` must live at the working root the session runs in, so the MCP registers for that session.

2. Derive **project name** = `basename` of the project root.

3. If `<project_root>/.mcp.json` does **not** exist, create it with this exact template (substitute `<project_name>`):

```json

{

"mcpServers": {

"excalidraw-mcp": {

"type": "http",

"headers": {

"Authorization": "Bearer ${EXCALIDRAW_MCP_TOKEN}",

"X-Tenant-Id": "<project_name>"

}

}

}

}

```

4. If `.mcp.json` already exists, **merge** - add the `excalidraw-mcp` entry under `mcpServers` without clobbering other servers. Skip if `excalidraw-mcp` already present.

Never write the bootstrap file outside the resolved project root, and never echo the token value.

## Step 1 - Tenant & Project Setup

The remote Excalidraw MCP is multi-tenant. Tenant is selected via the `X-Tenant-Id` header (configured in `.mcp.json`) or via tools.

Before any drawing:

1. `list_tenants` - confirm active tenant

2. `list_projects` - confirm active project; `switch_project` with `createName` if a fresh canvas is wanted

3. `describe_scene` - read existing diagram zones + suggested next placement coordinates

**Never** call `clear_canvas` unless the user explicitly says wipe. Place new diagrams spatially offset (≥300px) from existing ones.

## Core Principles (Read Before Any Diagram)

### 1. Write → Check → Review → Fix (Mandatory Loop)

```

WRITE batch → set_viewport(scrollToContent: true) → screenshot

→ REVIEW against Quality Checklist → FIX issues → re-screenshot

→ only proceed when all checks pass

```

### 2. Use `batch_create_elements` - Not `create_from_mermaid`

`create_from_mermaid` produces overlapping text and broken layouts. Use it only as a quick preview, never for final output. For quality, always plan coordinates and call `batch_create_elements`.

### 3. Two Batches: Shapes First, Arrows Second

Arrow binding (`startElementId`/`endElementId`) requires shapes to exist already. Mixing in one batch causes binding errors.

### 4. `roughness: 0` for Technical Diagrams

Excalidraw defaults to hand-drawn (roughness > 0). For professional system / data / architecture diagrams, set `roughness: 0` on every element. Use `strokeWidth: 2` for arrows.

### 5. Multi-Diagram Canvas

Never clear canvas between diagrams. Place side-by-side or stacked with ≥300px gap. Add a title text element (fontSize 24-28) above each. Group with `group_elements` so `describe_scene` reports it as a named zone.

### 6. Add a Compact Legend When It Clarifies

## Sizing Rules (Prevents Truncation)

Excalidraw's font is ~30% wider than typical sans-serif. Use these formulas:

| Shape | Width | Height | fontSize |

|-------|-------|--------|----------|

| Rectangle | `max(200, chars * 11)` | 70 (1 line) / 80 (2) / 100 (3) | 16-20 |

| Diamond (text uses ~50% of bbox - **double**) | `max(400, longestLine * 18)` | `max(160, lines * 50)` | 16 |

| Ellipse (text ~60% of bbox) | `max(280, chars * 14)` | `max(65, lines * 35)` | 16-18 |

| Title text | - | - | 24-28 |

## Arrow Visibility (Prevents Invisible Arrows)

Bound arrows shrink to `gap_between_shapes - 16` (8px binding padding each side). Below 80px, arrows vanish.

| Direction | Min gap | Recommended |

|-----------|---------|-------------|

| Vertical | 80px | **120px** |

| Horizontal | 100px | **140px** |

```

gap = nextShape.y - (currentShape.y + currentShape.height)

```

## Domain Styling Presets

### Active Color Budget

Use at most **5 active semantic colors** in any one diagram. Similar components share one color family: all internal services together, all data stores together, all compute/jobs together, all external systems together, all security/blocked paths together.

Treat long preset tables as menus, not a requirement to use every color. If the diagram needs more than five meanings, keep the color and vary shape, stroke style, arrow width, grouping boundary, or label. Neutral gray boundaries/backgrounds and black/white text do not count against the 5-color budget.

## Quality Checklist

After every batch, verify ALL:

| Check | Look For | Fix |

|-------|----------|-----|

| Truncation | Labels cut off, especially in diamonds | Increase width using formulas above |

| Invisible arrows | Connections you cannot trace | Increase gap to ≥120px vertical |

| Arrow label collision | YES/NO labels overlap shapes | Shorten label or widen gap |

| Element overlap | Shapes share space | Reposition with proper spacing |

| Readability | Text legible at 50-70% zoom | Bump fontSize to ≥16 |

| Color consistency | Colors match a single domain preset | Re-pick from one table above |

| Color budget | More than 5 active semantic colors in one diagram | Merge similar components; use shape/stroke/labels for extra meaning |

| Stroke + fill contrast | Light fill + dark stroke (or inverse) | Use the pairs in tables - never light fill + light stroke |

| Legend clarity | Needed semantics absent, or legend lists everything | Add 3-5 used meanings only, or remove if redundant |

If any check fails: STOP. Use `update_element` or delete + recreate. Re-screenshot. Only proceed when all checks pass.

## Standard Workflow

```

1. describe_scene # see existing

2. Plan: list elements, layout direction, IDs, coordinates

3. Pick a domain preset (architecture/cloud/data/UML/deployment)

4. batch_create_elements: shapes (Batch 1)

5. batch_create_elements: arrows (Batch 2)

6. Add compact legend if trigger conditions apply

7. group_elements # group new diagram

8. set_viewport(scrollToContent: true)

9. Screenshot → Quality Checklist → fix → repeat

```

## Anti-Patterns (Avoid)

| Mistake | Why it fails | Do this |

|---------|--------------|---------|

| Mixing C4 levels in one view | suggests false relationships | one diagram per level (Context, Container, Component) |

| Unlabeled arrows | ambiguous: sync? async? what data? | label every arrow with what + how |

| Labeling shape by tech only ("Lambda") | diagram describes infra, not domain | name first: `CheckoutHandler [Lambda]` |

| Master diagram showing all levels | illegible | split by concern (data flow / deployment / security) |

When exporting through `export_scene` or `export_to_image`, write finalized images into the injected `Visuals:` path (it resolves under the umbrella even from a worktree, so exports survive `worktree clean`); fall back to a temp dir only when no `Visuals:` path was injected. Then hand off an openable output location:

- Clickable absolute file link: `[diagram.png](/absolute/path/to/diagram.png)`

- Plain browser URI when useful: `file:///absolute/path/to/diagram.png`

- Remote share URL from `export_to_excalidraw_url`, if generated

Never report only `diagram.png` or another basename; include the canvas URL plus the file path/URI for every finalized exported file.

## Element Creation Cheat Notes

- Always assign a custom `id` to each shape so arrows can bind via `startElementId` / `endElementId`.

- For shape labels (rectangles, diamonds, ellipses): set `text` directly on the element - MCP auto-creates the bound text child.

- Curved arrows: `roundness: { type: 2 }` plus 3+ `points`.

- Elbowed arrows: `elbowed: true`.

- Dashed stroke: `strokeStyle: "dashed"`. Dotted: `strokeStyle: "dotted"`.

- Translucent zone backgrounds: `backgroundColor: "#e9ecef"`, `opacity: 30`.

- Compact legend: small swatch rectangles or 80px mini-lines with short labels; group legend elements with the diagram.

## References

When in doubt, re-read the preset table for your domain before drawing. Color and shape consistency matters more than how many shapes you draw.