Create Excalidraw diagrams that argue visually — turn ideas and code into visual arguments. Trigger on draw, diagram, visualize, chart, map out, flowchart, architecture, sequence diagram, mind map, ER diagram, class diagram, state diagram, gantt, floor plan, apartment, office layout, sketch, or any request to visually represent information.
Generate diagrams that argue visually, not just display information. A diagram is a visual argument that shows relationships, causality, and flow that words alone cannot express. The shape should BE the meaning.
excalibrain capabilities:
Read these as needed — they are the ground truth for specifics:
| File | When to read |
|---|---|
references/color-palette.md | Before every diagram — all hex values live here |
references/diagram-type-rubric.md | Type selection — which diagram type to use when |
references/patterns.md | Visual pattern library with examples |
references/layout-rules.md | Layout rules + coordinate templates |
references/graph-json-format.md | Dagre graph JSON input format (architecture, state, mindmap) |
references/diagram-recipes/<type>.md | Before generating — complete examples per type |
Available recipes: flowchart.md, sequence.md, mindmap.md, class-diagram.md, state-diagram.md, er-diagram.md, gantt.md, architecture.md, floor-plan.md
Before creating anything, ask: did I already generate a diagram in this conversation?
Check for an active canvas:
.excalidraw file created or modified earlier in this conversation?If YES to any two of the above → merge, don't create a new file.
canvas-inspect.js on the existing file to find bounds and free space--merge <existing.excalidraw> --position <x>,<y> when generating the new sectionIf NO → proceed normally (new standalone file).
Signals that break continuity (create a new file):
This rule applies even when the diagram type changes (wireframe → sequence, architecture → ER). Different types on the same topic belong on the same canvas — they argue different facets of the same system.
Choose the diagram type that best argues the content — NOT the default flowchart.
Read references/diagram-type-rubric.md to pick the right type. Ask yourself: is this about components and relationships (architecture), process with decisions (flowchart), timing between services (sequence), lifecycle states (state diagram), concept hierarchy (mindmap), or data model (ER)? The type shapes the visual argument — a flowchart argues about process, an architecture diagram argues about structure, a sequence diagram argues about timing.
Present the user with your choice:
"I'll generate a [type] diagram for this. Here are the available themes:"
| Theme | Look |
|---|---|
default | Hand-drawn Excalidraw style (Virgil font, slight roughness) |
clean | Professional, precise lines (monospace font, no roughness) |
dark | Dark background with vibrant colors |
blueprint | Technical blueprint style (dark blue/white) |
"Want me to use the default theme, or would you prefer a different one?"
If the user doesn't specify or says to proceed, use default. If the user specifies a theme, pass --theme <name> to both dagre-layout.js and mermaid-convert.js.
Type selection: Read references/diagram-type-rubric.md. If the user's request clearly matches one type, state it and proceed. If ambiguous, ask which type they prefer.
Codebase task (documenting a repo, explaining a system):
Multiple diagrams in one request:
Conceptual task (blog post, report, explanation):
Parallelize with Step 2 — read references/diagram-recipes/<type>.md AND references/color-palette.md in the same turn.
Choose the path based on diagram type. Check references/diagram-type-rubric.md for the tool path column — it tells you which tool to use for each type.
If continuing a canvas (Step 0 said merge): append --merge <canvas.excalidraw> --position <x>,<y> to any tool command below. The --position coordinates come from canvas-inspect.js free-space output. Always write output back to the same canvas file.
Dagre path (flowchart, architecture, state, mindmap) — PRIMARY:
.json file (see references/graph-json-format.md for full format)references/diagram-recipes/<type>.md — it has the JSON template, color conventions, and best practicesstyle.roughness or style.fontFamily in graph JSON unless the user explicitly asks — let the theme control thesenode ${CLAUDE_PLUGIN_ROOT}/tools/dagre-layout.js graph.json [--theme <name>] --output diagram.excalidraw.excalidraw file with orthogonal arrows, auto-sized nodes, and bound textMermaid path (sequence, class, ER) — for types where mermaid's specialized layout is better:
.mmd filestyle ENTITY fill:#hex,stroke:#hex for colored entitiesnode ${CLAUDE_PLUGIN_ROOT}/tools/mermaid-convert.js input.mmd [--theme <name>] --output diagram.excalidraw.excalidraw file with vector elementsGantt path (gantt charts, project timelines, sprint schedules):
.json file (see references/diagram-recipes/gantt.md for full format)tasks (id, label, start, duration, fill, stroke) and optional dependenciesnode ${CLAUDE_PLUGIN_ROOT}/tools/gantt-layout.js gantt.json [--theme <name>] --output diagram.excalidrawDagre path (architecture, state, mindmap):
.json file (see references/graph-json-format.md for full format)style.roughness or style.fontFamily in graph JSON unless the user explicitly asks for a clean/technical look — let the theme control thesenode ${CLAUDE_PLUGIN_ROOT}/tools/dagre-layout.js graph.json [--theme <name>] --output diagram.excalidraw.excalidraw file with bound arrows and auto-sized nodesPrimitives path (floor plans, spatial layouts):
references/diagram-recipes/floor-plan.md — it has the full type registry, scale table, and door sizing rules.json file. All furniture types require the furniture: prefix (e.g., furniture:bed, not bed)width ≤ 50 px (40 px standard). Check swing arc clearance against nearby furniturefill, stroke, and labelColor to rooms for color codingdimension lines outside the floor plan perimeter and a label titlenode ${CLAUDE_PLUGIN_ROOT}/tools/primitives.js input.json --output floor-plan.excalidrawCompose path (no recipe fits — weekend trips, seating charts, comparison tables, custom layouts): Don't try to manually place 50 elements with x,y coordinates. Instead, decompose the problem:
x = col * width + gap)Direct path (truly freeform — rare):
.excalidraw JSON directly following Excalidraw's element formatnode ${CLAUDE_PLUGIN_ROOT}/tools/export.js diagram.excalidraw --format png --output diagram.png
Read the PNG with the Read tool. Check:
If any item fails: fix the input, regenerate, re-export. Max 3 iterations.
Save .excalidraw + optional PNG/SVG to:
docs/diagrams/ if it exists → or current directoryReturn markdown embed: 
Output format by context:
| Context | Format |
|---|---|
| Markdown doc, README, blog post | PNG |
| Web project (HTML/CSS/JS) | SVG |
| User says "I want to edit it" | .excalidraw |
| User specifies a format | User's choice |
The Isomorphism Test: Remove all text. Does the structure alone communicate the concept? If not, redesign.
The Education Test: Could someone learn something concrete from this diagram — actual formats, real event names, how things actually connect — or does it just label boxes?
Not every piece of text needs a shape around it. Default to free-floating text. Add containers only when:
Target: fewer than 30% of text elements inside containers.
| Bad (Displaying) | Good (Arguing) |
|---|---|
| 5 equal boxes with generic labels | Each concept shaped to mirror its behavior |
| Uniform card grid | Structure matches conceptual structure |
| "API" → "Database" → "Client" | Real service names + actual request/response formats |
| Same container style everywhere | Distinct visual vocabulary per concept type |
| Arrows all look the same | Color-coded arrows encoding relationship type |
Simple / Conceptual — abstract shapes, clean labels. For mental models, overviews.
Comprehensive / Technical — concrete examples, real data, code snippets. For real systems, architectures, tutorials.
If comprehensive: research the actual specs before drawing. Look up real event names, API formats, method signatures. Generic placeholders make diagrams useless.
Each major concept should use a different visual pattern. Full examples in references/patterns.md.
| If the concept... | Use this pattern |
|---|---|
| Spawns multiple outputs | Fan-out (radial arrows from center) |
| Combines inputs into one | Convergence (arrows merging to a point) |
| Has levels / hierarchy | Tree (lines + free-floating text) |
| Is a sequence of steps | Timeline (line + dot markers + labels) |
| Loops or improves | Cycle (arrows returning to start) |
| Groups related components | Swim lanes (zone backgrounds) |
| Transforms input to output | Assembly line (before → process → after) |
| Has many typed subtypes | Hub-and-spoke (center + spokes) |
| Compares two options | Side-by-side (parallel columns) |
| Artifact type | When to use |
|---|---|
| Code snippet | APIs, integrations, how-to |
| Data / JSON payload | Message formats, schemas |
| Event sequence | Protocols, lifecycles |
| Real API / method names | SDK usage, endpoints |
For dagre path: use dark-background nodes (fill: "#1e293b", textColor: "#e2e8f0") with monospace font.
Level 1 — Summary strip: Simplified overview at top/bottom showing the full flow. Level 2 — Section boundaries: Labelled, colored zone backgrounds. Level 3 — Detail inside sections: Evidence artifacts, code snippets, real data.