diagram-router

Diagram Router

Select the best output format and diagram type for the user's request, then delegate to the format-specific skill.

Step 1: Did the User Specify a Format?

If the user explicitly requests a format, use it:

• "Draw this in SVG" / "as SVG" / "raw SVG" --> svg skill
• "Mermaid diagram" / "in mermaid" / "as mermaid" --> mermaid skill
• "Excalidraw" / "whiteboard style" / "hand-drawn" --> excalidraw skill
• "D2 diagram" / "in d2" --> d2 skill

If they specified a format, skip to Step 3.

Step 2: Select Format from Context

Default: SVG. Always. SVG produces the highest visual quality, handles every diagram type, and renders everywhere (browsers, GitHub, docs, presentations). Only route away from SVG when the user explicitly names another format.

Context Signal	Format	Why
No specific signal	SVG	Best quality, most flexible, browser-native
"For the README" / "in markdown" / "GitHub"	SVG	GitHub renders SVG natively. Quality matters.
"Quick" / "simple" / "basic"	SVG	Still SVG -- it handles simple diagrams well too
User explicitly says "mermaid"	Mermaid	They asked for it
User explicitly says "excalidraw" / "whiteboard" / "sketch" / "hand-drawn"	Excalidraw	Hand-drawn aesthetic, saves .excalidraw file
User explicitly says "d2"	D2	They asked for it

The rule is simple: SVG unless the user says otherwise. The user can always convert later ("convert that to mermaid", "make that an excalidraw", etc.).

Step 3: Select Diagram Type

If the user described what they want to visualize but did not name a diagram type, infer it:

What They Described	Diagram Type
System components, layers, platform	Layered architecture
Service communication, API calls, request flow	Sequence diagram
Steps in a process, pipeline, workflow	Flowchart
Who handles each step, team responsibilities	Swimlane
Object lifecycle, status transitions	State machine
Database tables and relationships	ER diagram
Module/package dependencies	Dependency graph
Option A vs option B, before/after	Comparison (side-by-side)
Project phases, milestones, releases	Timeline / Gantt
Security boundaries, attack surface	Threat model / DFD
Topics and subtopics, brainstorm	Mind map
Central service with consumers	Hub and spoke
Set overlaps, shared characteristics	Venn diagram
Decision logic, branching conditions	Decision tree
Volume distribution, traffic flow	Sankey diagram
Team structure, hierarchy	Org chart / tree
Cloud infrastructure, network topology	Network diagram
How software maps to infrastructure	Deployment diagram

If ambiguous, briefly confirm with the user: "This sounds like a [type] -- does that match what you have in mind?"

Step 4: Delegate

Load the selected format skill and follow its workflow:

• SVG: Consult the svg skill and its references (svg-design-system.md, layout-patterns.md)
• Mermaid: Consult the mermaid skill
• Excalidraw: Consult the excalidraw skill
• D2: Consult the d2 skill

Always consult the design-system skill for color, composition, and quality rules regardless of format.

Step 5: Handle Conversion Requests

Users frequently want to convert between formats or extract styles. Common patterns:

Format conversion:

• "Convert that SVG to mermaid" --> Read the SVG, extract the structure, generate equivalent Mermaid syntax
• "Can we make that a D2 file instead?" --> Read the source, translate to D2's container/connection syntax
• "Export that as Excalidraw" --> Rebuild using Excalidraw JSON elements + MCP tools

Style extraction from images:

• "Here's a screenshot of a diagram style I like -- make ours look like that" --> Analyze the image for color palette, layout style, typography, element shapes, then apply those visual choices to the content
• "Match the style of this existing diagram" --> Extract design tokens (colors, border radius, spacing, font sizes) and apply to new content

Cross-format iteration:

• User starts with SVG for quality, later asks for Mermaid for embedding in docs
• User starts with Excalidraw for brainstorming, later asks for SVG for the final polished version
• User provides a hand-drawn sketch or screenshot and asks for a clean version

When converting, preserve:

1. All content -- labels, relationships, grouping
2. Semantic meaning -- which elements are primary/secondary, flow direction
3. Design intent -- colors, emphasis, hierarchy (adapt to target format's capabilities)

Accept that some fidelity is lost when converting to simpler formats (SVG to Mermaid loses custom positioning and gradients). Mention this to the user.