excalidraw

# Excalidraw Diagrams

## Overview

Generate `.excalidraw` JSON files and export to PNG/SVG.

**Two export options:**
- **Kroki API** (`curl`) — zero install, SVG output only
- **excalidraw-brute-export-cli** — local Firefox-based, PNG + SVG

**Supported formats:** PNG (local CLI only), SVG (both options). PDF is NOT supported.

## When to Use

**Explicit triggers:** user says "画图", "diagram", "visualize", "flowchart", "draw", "架构图", "流程图"

**Proactive triggers:**
- Explaining a system with 3+ interacting components
- Describing a multi-step process or decision tree
- Comparing architectures or approaches side by side

**Skip when:** a simple list or table suffices, or user is in a quick Q&A flow

**When NOT to use it — route elsewhere:**
- Polished, precise diagrams, strict UML, or branded vendor icons → **drawio**.
- Diagrams-as-code in git, auto-laid-out from text → **mermaid** (general) or **plantuml** (UML).
- An infinite-canvas whiteboard or programmatic freehand strokes → **tldraw**.

## Prerequisites

### Option A: Kroki API (recommended — zero install, SVG only)

```bash
# Just needs curl (pre-installed on macOS/Linux/Windows Git Bash)
curl --version
```

No additional setup. SVG rendered via `https://kroki.io`.

### Option B: Local CLI (required for PNG)

The CLI uses **Firefox** (not Chromium). Check and install:

```bash
npm install -g excalidraw-brute-export-cli
npx playwright install firefox
```

**macOS patch (one-time, required):**
```bash
CLI_MAIN=$(npm root -g)/excalidraw-brute-export-cli/src/main.js
sed -i '' 's/keyboard.press("Control+O")/keyboard.press("Meta+O")/' "$CLI_MAIN"
sed -i '' 's/keyboard.press("Control+Shift+E")/keyboard.press("Meta+Shift+E")/' "$CLI_MAIN"
```

**Windows/Linux:** No patch needed.

## Workflow

1. **Check deps** — use Kroki (curl) for SVG; use local CLI for PNG
2. **Plan** — pick the visual metaphor (see **Relationship-to-layout map**), then the diagram type and color palette
3. **Generate** — write `.excalidraw` JSON file (section-by-section for large diagrams)
4. **Export** — run Kroki or CLI command
5. **Verify the render** — view the exported PNG, fix any defects, re-export (see **Verify the Render**)
6. **Review loop** — show the image to the user, apply the minimal `.excalidraw` edit per request, re-export until approved (see **Review Loop**)
7. **Report** — tell user the output file path

## Design Principles

### Default style

- `roughness: 0` — clean, modern look for all technical diagrams (use `1` only when user requests hand-drawn/casual style)
- `fontFamily: 2` (Helvetica) — professional look; use `1` (Virgil) only for casual/sketch style, `3` (Cascadia) for code snippets
- `fillStyle: "solid"` — default fill

### Containers: prefer typography over boxes

A box around every label makes a diagram look like a wireframe. The cleanest Excalidraw diagrams use **free-floating text and lines** for structure and reserve filled boxes for things that are genuinely *components*.

- **Default to no container** — use a standalone `text` element unless the box earns its place.
- **Add a box only when** the element is a real system component, an arrow binds to it, the shape itself carries meaning (decision diamond, start/end ellipse), or it groups a zone.
- Aim for **under ~30% of text elements inside boxes.**
- For timelines, trees, and hierarchies, use a **line/connector + free-floating labels**, not a stack of rectangles. Size, weight, and color create hierarchy without boxes.

### Font size hierarchy

| Level | Size | Use for |
|-------|------|---------|
| Title | 28px | Diagram title |
| Header | 24px | Section/group headers |
| Label | 20px | Primary element labels |
| Description | 16px | Secondary text, descriptions |
| Note | 14px | Annotations, fine print |

### Color palette

Follow the **60-30-10 rule**: 60% whitespace/neutral, 30% primary accent, 10% highlight.

**Semantic fill colors** (use with `strokeColor` one shade darker):

| Category | Fill | Stroke | Use for |
|----------|------|--------|---------|
| Primary / Input | `#dbeafe` | `#1e40af` | Entry points, APIs, user-facing |
| Success / Data | `#dcfce7` | `#166534` | Data stores, success states |
| Warning / Decision | `#fef9c3` | `#854d0e` | Decision points, conditions |
| Error / Critical | `#fee2e2` | `#991b1b` | Errors, alerts, critical paths |
| External / Storage | `#f3e8ff` | `#6b21a8` | External services, databases, AI/ML |
| Process / Default | `#e0f2fe` | `#0369a1` | Standard process steps |
| Trigger / Start | `#fed7aa` | `#c2410c` | Start nodes, triggers, events |
| Neutral / Container | `#f1f5f9` | `#475569` | Groups, swimlanes, backgrounds |

**Text colors:**

| Level | Color |
|-------|-------|
| Title | `#1e293b` |
| Label | `#334155` |
| Description | `#64748b` |

**Rule: Do not invent new colors.** Pick from this palette.

### Arrow semantics

| Style | Meaning |
|-------|---------|
| Solid (`strokeStyle: "solid"`) | Primary flow, main path |
| Dashed (`"dashed"`) | Response, async, callback |
| Dotted (`"dotted"`) | Optional, reference, weak dependency |

## Excalidraw JSON Structure

### File skeleton

```json
{
  "type": "excalidraw",
  "version": 2,
  "source": "claude-code",
  "elements": [],
  "appState": { "viewBackgroundColor": "#ffffff" }
}
```

### Element types

| type      | use for                          |
|-----------|----------------------------------|
| rectangle | boxes, components, modules       |
| ellipse   | start/end nodes, databases       |
| diamond   | decision points                  |
| arrow     | directed connections             |
| line      | undirected connections           |
| text      | standalone labels                |

`image`, `frame`, and `embeddable` are **not covered** by this skill: `image` needs a separate `files` map plus a `fileId`, and frames/embeds render inconsistently through the export path. Stick to the six types above — and for ready-made icons built *from* these primitives, see **Community shape & i