---

name: excalidraw-architect description: Choose and compose the right Excalidraw diagram - architecture, flowchart, sequence, state, ER, swimlane, process, timeline, quadrant, pyramid, venn, loop, gantt, bar, line, scatter, and more - using the excalidraw-architect-mcp server. Use whenever a reader would learn more from a picture than from prose, or when asked to draw, diagram, chart, or visualize a system, process, or dataset. license: MIT

Excalidraw Architect

The MCP server renders. This skill decides what to render and how much.

Picking the wrong diagram type is the most common way a diagram fails. A cross-functional process drawn as a flowchart loses the handoffs that were the entire point. A ranking drawn as a bar chart loses the ranking.

---

1. Before you draw

Ask: would the reader learn more from this than from a well-written paragraph or a three-column table? If no, write the paragraph.

Don't draw for:

• A list of things → bullets or a table.
• A simple before/after → a two-column table.
• One shape → just write the sentence.

---

2. The two rules that carry most of the quality

Density target: ~4/10. Enough to be complete, not so dense it needs its own legend. Above nine nodes it is usually two diagrams — draw an overview and a detail. Two nodes that always travel together are one node.

Accent is reserved. Every spec accepts "focal": true on its elements. Mark one or two — the thing you want looked at first. Marking five spends the signal and leaves the reader with no entry point. Most elements should be unmarked; that is what makes the marked one work.

A third, quieter rule: every connection should carry information. If the relationship is already obvious from the layout, delete the line.

---

3. Picking a type

If you're showing…	Use	Not when
Components and the connections between them	architecture	(graph type — pass nodes + connections)
Decision logic with branches	flowchart	(graph type — pass nodes + connections)
Parent -> children: taxonomies, file hierarchies, decision breakdowns.	tree	Use org_chart for people or teams; use nested when containment is the point.
Human, team, or agent ownership: reporting lines, escalation, routing.	org_chart	Not for system components -- that is architecture.
States, transitions, and guards. Order lifecycles, retry machines, approval flows.	state	Not for time-ordered messages between actors -- that is sequence.
Hierarchy by containment or scope: bounded contexts, module trees, org scopes.	nested	Beyond three levels of nesting, split into an overview plus a detail diagram.
Stacked abstraction levels where each layer sits on the one below.	layers	If the layers exchange traffic in both directions, use architecture instead.
Multi-tier data storage with quality levels: bronze/silver/gold, raw/curated/serving.	medallion	Use data_flow when the emphasis is who does what rather than where data rests.
Entities, their fields, and relationships. Data models and schema documentation.	er	Above ~8 entities, split by bounded context.
End-to-end stack drawn inside one named boundary (a cluster, an account, a VPC).	high_level	Use architecture when the boundary is not the point.
Legacy landscape grouped by phase or department; the 'before' state.	it_state	Use architecture for a target-state design.
Cross-functional process where step ownership matters. Handoffs are the story.	swimlane	If every step has the same owner, use flowchart.
Multi-actor sequential workflow drawn as vertical actor columns with data handoffs.	process	Use swimlane for horizontal lanes and a wider flow.
A pipeline where each stage is tagged with the role that owns it.	data_flow	Use medallion when storage tiers, not roles, are the subject.
Integration topology of a platform: sources -> core -> consumers.	dp_integration	Use architecture when the core needs to be decomposed in detail.
Time-ordered messages between actors: API traces, protocols, incident replays.	sequence	Never draw a message arrow that points backwards in time; use state for lifecycles.
Events positioned in time along a single axis. Roadmaps, incident chronologies.	timeline	Use gantt when items have duration rather than a single instant.
Two-axis positioning and prioritization. Add quadrant_labels for a consultant 2x2.	quadrant	Use scatter when the axes carry real units rather than relative position.
Ranked hierarchy (mode='pyramid') or conversion drop-off (mode='funnel').	pyramid	Use bar when the values matter more than the ranking.
Overlap between two or three sets, where the intersection is the insight.	venn	Four or more sets is unreadable -- use a table.
A reinforcing cycle; add a hub for shared state the stations write back to.	loop	Use process when the flow has a real beginning and end.
Tasks and phases with duration on a timeline. Shows overlap and parallel tracks.	gantt	Above ~12 tasks, collapse to a phase-level view.
Quantitative comparison across categories. Multiple series render as grouped bars.	bar	Use line when the x axis is continuous time.
Continuous trends over an ordered axis. Capped at 15 points per series.	line	Use bar for a handful of discrete categories.
Distribution and correlation between two continuous variables.	scatter	Use quadrant when position is relative judgement rather than measurement.

Rules of thumb:

• If a three-column table says the same thing, use the table.
• Combining two types? Pick the dominant axis. Don't hybridize grammars.
• Past the density budget? Split into overview + detail.

---

4. Calling the tools

list_diagram_types()            # the table above, from the server
get_diagram_schema("sequence")  # exact spec shape for one type
create_diagram(output_path="./x.excalidraw", diagram_type="sequence", spec={...})

architecture and flowchart are graph types and take nodes + connections instead of a spec. Everything else takes diagram_type + spec.

Every spec accepts optional title and subtitle.

Editing. Call get_diagram_info(path) to read the stored spec, then:

modify_diagram(path, [{"op": "update_spec", "patch": {"title": "New title"}}])

The patch is deep-merged. Lists are replaced wholesale — to change one tier, send the whole tiers list.

Exporting. export_diagram(path, "./x.svg") for SVG; PNG needs the optional cairosvg extra.

See references/types.md for the full spec shape and a worked example of every type.

---

5. Anti-patterns

Anti-pattern	Why it fails
Accent on five nodes	Destroys the signal it exists to carry.
A step drawn across two lanes	Pick one owner; ambiguity is the opposite of the point.
A sequence message pointing upward	Reverses time. Never correct.
Fifteen nodes in one diagram	Past the budget — split it.
A chart with 50 points	Sketchy strokes turn it into a seismograph. Downsample.
A table drawn as boxes	Excalidraw has no table primitive. Write the markdown table.
Generic labels ("Service A")	Name the real thing or delete the node.

---

6. What the renderer already handles

Don't work around these — they are done for you:

• Layout. Never pass coordinates. The engine places and routes everything.
• Chrome vs content. Axes, gridlines, and lane dividers render crisp; shapes and data marks render hand-drawn. That contrast is deliberate.
• Themes. default, dark, colorful. Accent and series ramps adapt.
• Bindings. Arrows stay attached when a node is dragged in Excalidraw.