Excalibraindraw

Available recipes: flowchart.md, sequence.md, mindmap.md, class-diagram.md, state-diagram.md, er-diagram.md, gantt.md, architecture.md, floor-plan.md

Workflow

0. Canvas continuity check (do this FIRST)

Before creating anything, ask: did I already generate a diagram in this conversation?

Check for an active canvas:

1. Was a .excalidraw file created or modified earlier in this conversation?
2. Is the new request topically related to that file? (Same system, same feature, different perspective — e.g., wireframe then sequence diagram, architecture then ER diagram, floor plan then furniture detail)
3. Does the user reference the prior diagram? ("this", "that", "the same", "for this screen", "behind this", etc.)

If YES to any two of the above → merge, don't create a new file.

• Run canvas-inspect.js on the existing file to find bounds and free space
• Use --merge <existing.excalidraw> --position <x>,<y> when generating the new section
• Place the new section below or to the right of existing content (leave ≥80px gap)
• Add a section title label above the new content to separate it visually

If NO → proceed normally (new standalone file).

Signals that break continuity (create a new file):

• User explicitly asks for a "new diagram" or "separate file"
• Topic is completely unrelated to the prior diagram
• User names a different output 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.

1. Type & theme selection

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:"

"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.

2. Content sourcing

Codebase task (documenting a repo, explaining a system):

• Parallelize file reads — identify all relevant source files first, then read them all in a single turn using multiple parallel Read tool calls.
• Present a brief bullet summary: "Here's what I found: [nodes + relationships]"
• Wait for user confirmation before generating (max 3 rounds; proceed after 3 or if user says "go ahead")

Multiple diagrams in one request:

• Generate all diagrams in parallel using sub-agents — each diagram is fully independent

Conceptual task (blog post, report, explanation):

• Derive structure from the user's message and any open documents
• No confirmation needed — proceed directly

3. Read the recipe + color palette

Parallelize with Step 2 — read references/diagram-recipes/<type>.md AND references/color-palette.md in the same turn.

4. Generate

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:

1. Write graph JSON to a .json file (see references/graph-json-format.md for full format)
2. Read the type-specific recipe from references/diagram-recipes/<type>.md — it has the JSON template, color conventions, and best practices
3. Do NOT override style.roughness or style.fontFamily in graph JSON unless the user explicitly asks — let the theme control these
4. Run: node ${CLAUDE_PLUGIN_ROOT}/tools/dagre-layout.js graph.json [--theme <name>] --output diagram.excalidraw
5. Output is a fully-positioned .excalidraw file with orthogonal arrows, auto-sized nodes, and bound text

Mermaid path (sequence, class, ER) — for types where mermaid's specialized layout is better:

1. Write the Mermaid syntax to a .mmd file
2. ER diagrams: Use style ENTITY fill:#hex,stroke:#hex for colored entities
3. Run: node ${CLAUDE_PLUGIN_ROOT}/tools/mermaid-convert.js input.mmd [--theme <name>] --output diagram.excalidraw
4. Output is a native .excalidraw file with vector elements
5. Do NOT use mermaid for flowcharts — use dagre instead. Mermaid flowcharts break on fan-in/fan-out patterns (>10 nodes).

Gantt path (gantt charts, project timelines, sprint schedules):

1. Write Gantt JSON to a .json file (see references/diagram-recipes/gantt.md for full format)
2. The JSON uses a Gantt-specific format with tasks (id, label, start, duration, fill, stroke) and optional dependencies
3. Run: node ${CLAUDE_PLUGIN_ROOT}/tools/gantt-layout.js gantt.json [--theme <name>] --output diagram.excalidraw
4. Output is a proper Gantt chart with horizontal time axis, parallel task bars, grid lines, and dependency arrows

Dagre path (architecture, state, mindmap):

1. Write graph JSON to a .json file (see references/graph-json-format.md for full format)
2. Do NOT override style.roughness or style.fontFamily in graph JSON unless the user explicitly asks for a clean/technical look — let the theme control these
3. Run: node ${CLAUDE_PLUGIN_ROOT}/tools/dagre-layout.js graph.json [--theme <name>] --output diagram.excalidraw
4. Output is a fully-positioned .excalidraw file with bound arrows and auto-sized nodes

Primitives path (floor plans, spatial layouts):

1. Read references/diagram-recipes/floor-plan.md — it has the full type registry, scale table, and door sizing rules
2. Write primitives JSON to a .json file. All furniture types require the furniture: prefix (e.g., furniture:bed, not bed)
3. Use door width ≤ 50 px (40 px standard). Check swing arc clearance against nearby furniture
4. Pass fill, stroke, and labelColor to rooms for color coding
5. Add dimension lines outside the floor plan perimeter and a label title
6. Run: node ${CLAUDE_PLUGIN_ROOT}/tools/primitives.js input.json --output floor-plan.excalidraw

Compose 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:

1. Identify the spatial structure — is it a graph (nodes + connections)? A grid? A timeline? A radial layout?
2. Use the right tool for that structure:
   • Graph/topology → dagre (model locations as nodes, routes as edges)
   • Grid/spatial → primitives.js (calculate grid positions: x = col * width + gap)
   • Timeline → gantt-layout.js
   • Hybrid → combine tools, merge onto same canvas
3. Only fall back to raw .excalidraw JSON when no tool handles the structure at all

Direct path (truly freeform — rare):

1. Write .excalidraw JSON directly following Excalidraw's element format
2. Last resort only — the compose path above handles most "unconventional" diagrams better

5. Validate (mandatory)

node ${CLAUDE_PLUGIN_ROOT}/tools/export.js diagram.excalidraw --format png --output diagram.png

Read the PNG with the Read tool. Check:

• All nodes labeled and readable
• No label text overlapping node borders or other nodes
• All expected connections present
• Arrow directions correct
• Color coding consistent with color-palette.md
• Structure passes isomorphism test (remove text — does shape alone communicate?)

If any item fails: fix the input, regenerate, re-export. Max 3 iterations.

6. Output

Save .excalidraw + optional PNG/SVG to:

• Same directory as the doc being written → or docs/diagrams/ if it exists → or current directory

Return markdown embed: ![<Type> diagram showing <brief description>](<relative-path>)

Output format by context:

Core Philosophy

Diagrams Should ARGUE, Not DISPLAY

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?

Container Discipline

Not every piece of text needs a shape around it. Default to free-floating text. Add containers only when:

• Arrows need to connect to the element
• The shape itself carries meaning (decision diamond, start ellipse, etc.)
• Visual grouping with a background zone is needed

Target: fewer than 30% of text elements inside containers.

Bad vs Good

Depth Assessment (Do This First)

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.

Visual Patterns

Each major concept should use a different visual pattern. Full examples in references/patterns.md.

Evidence Artifacts (Technical Diagrams)

For dagre path: use dark-background nodes (fill: "#1e293b", textColor: "#e2e8f0") with monospace font.

Multi-Zoom Architecture (Comprehensive Diagrams)

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.

Quality Checklist

Philosophy

• Isomorphism test passes — structure alone communicates the concept
• No uniform card grids — each major concept uses a different visual pattern
• < 30% of text elements inside containers

Depth & Evidence

• Real terminology used — no generic placeholders
• Evidence artifacts present for technical diagrams
• Multi-zoom structure for complex diagrams

Layout

• All labels fit their containers
• Zone backgrounds drawn before nodes (dagre handles this)
• No cross-lane long diagonals
• Font sizes ≥ 12
• Arrow styles differentiate relationship types

Connections

• Every relationship has an arrow
• Arrow colors from color-palette.md
• Bidirectional arrows used where appropriate

After Render

• No text overflow or truncation
• Arrows land on correct elements
• All text legible at export size
• Composition balanced