How to Choose the Right Diagram Type for Your Needs: A Complete Guide

You choose the right diagram type by first matching your content to a semantic pattern in semantic-patterns.md, then selecting a visual layout from the SKILL.md visual-type guide based on what you are actually showing.

Selecting the correct visual representation prevents miscommunication and keeps stakeholders aligned. In the cathrynlavery/diagram-design repository, the diagram-design skill enforces a deterministic, two-step workflow that balances behaviour (semantic meaning) and layout (visual structure) to help you choose the right diagram type every time.

The Two-Step Decision Process

The diagram-design skill resolves every request through a rigid decision pipeline that runs behaviour before layout.

Step 1 – Identify the Semantic Pattern

When your content involves state, policy, security, or workflow semantics, the skill loads skills/diagram-design/references/semantic-patterns.md and matches your trigger. Valid triggers include patterns such as fan-in queue, stage framework, or secure paved road. The selected pattern supplies the behavioural vocabulary and may add primitive annotations like callouts or motion that the final output must include.

Step 2 – Pick the Visual Type

Once the pattern is fixed, or if no semantic pattern applies, the skill consults the visual-type guide in skills/diagram-design/SKILL.md (section 8.1). This guide maps what you are showing to a specific diagram type and its corresponding reference file in skills/diagram-design/references/.

Visual Type Reference Guide

The table below lists every supported mapping from concept to diagram type as implemented in the repository.

What you're showing…	Recommended type	Reference file
System components & connections	Architecture	type-architecture.md
Legacy IT landscape (before/after)	IT current-state	type-it-state.md
Decision logic with branches	Flowchart	type-flowchart.md
Time-ordered messages between actors	Sequence	type-sequence.md
States & transitions	State machine	type-state.md
Entities, fields & relationships	ER / data model	type-er.md
Events positioned on a timeline	Timeline	type-timeline.md
Cross-functional hand-offs	Swimlane	type-swimlane.md
Two-axis positioning / prioritisation	Quadrant	type-quadrant.md
Multi-criteria scoring	Radar / Spider	type-radar.md
Reinforcing cycle or flywheel	Loop	type-loop.md
Hierarchy by containment	Nested	type-nested.md
Parent → children relationships	Tree	type-tree.md
Ownership / reporting structure	Org chart	type-org-chart.md
Stacked abstraction levels	Layer stack	type-layers.md
Set overlap	Venn	type-venn.md
Ranked hierarchy or funnel	Pyramid / Funnel	type-pyramid.md
Quantitative comparison (bars)	Bar chart	type-bar.md
Part-of-whole area encoding	Treemap	type-treemap.md
Continuous trends (lines)	Line chart	type-line.md
Tasks & phases on a timeline	Gantt	type-gantt.md
Distribution & correlation	Scatter plot	type-scatter.md
End-to-end data stack	High-Level	type-high-level.md
Multi-actor sequential workflow	Process	type-process.md
Multi-tier storage architecture	Medallion	type-medallion.md
Role-scoped data flow	Data flow	type-data-flow.md
Data platform integration topology	DP integration	type-dp-integration.md
Per-role access matrix	DP security matrix	type-dp-security-matrix.md
Quantity splitting/merging	Sankey	type-sankey.md
Root-cause analysis	Fishbone	type-fishbone.md
Value chain / evolution	Wardley map	type-wardley.md
Work-in-progress board	Kanban	type-kanban.md
User journey & experience	User journey	type-journey.md
Deployment topology	Deployment	type-deployment.md
Dependency graph	Dependency graph	type-dependency.md
UML class diagram	UML class	type-uml-class.md
Narrative backbone & releases	Story map	type-story-map.md
Physical database schema	Database schema	type-db-schema.md

How to Choose the Right Diagram Type in Practice

Follow this four-step workflow to finalise your choice.

1. Ask the “what am I showing?” question – Write down the primary concept (architecture, timeline, hierarchy, etc.).
2. Match it to the table above – The first row that fits determines the visual type and the type-*.md file to load.
3. Check the complexity budget – Review the limits in skills/diagram-design/SKILL.md (section 6.3). If you exceed the maximum nodes or arrows, split the diagram or lower the detail level from faithful → balanced → simplified.
4. Confirm with the pre-output checklist – Run the taste gate to verify the chosen type, size preset, and any semantic pattern files (semantic-patterns.md, animation.md for motion) have been loaded.

Code Examples

These examples show how the decision process looks in practice.

Simple Architecture Request

# 1️⃣ Simple request – Claude Code or Pi

You: "Make me an architecture diagram of my web app: frontend, backend, Postgres, Redis."
Agent: → loads SKILL.md → selects Architecture → loads type-architecture.md → renders HTML

Semantic Pattern First

# 2️⃣ Using a semantic pattern first

You: "Show the fan-in queue for my data pipeline."
Agent: → loads semantic-patterns.md → picks Fan-in queue / bottleneck
       → maps to Data flow → loads type-data-flow.md → renders

Import an Existing Mermaid File

# 3️⃣ Importing an existing Mermaid file and forcing a specific type

/pi> /import-mermaid my-pipeline.mmd --diagram=all --size=slide-16x9 --detail=simplified

# The skill extracts the IR, then for each block it:

#   - decides the best visual type (e.g., Flowchart)

#   - applies the slide-16x9 size preset

#   - limits nodes to ≤12 (balanced) → simplified detail

Add Optional Motion

# 4️⃣ Adding optional motion

/pi> /diagram-design:make sequence diagram of OAuth flow --motion=step

# Loads type-sequence.md + animation.md; produces a step-by-step HTML with controls.

Run the Built-In Self-Check

# 5️⃣ Running the built-in self-check after generation

python3 skills/diagram-design/scripts/self_check.py my-diagram.html

# Prints "OK" if all accessibility, connector, and layout rules pass.

Key Files and References

The following files drive the entire decision pipeline.

• Skill manifest & visual-type guide – skills/diagram-design/SKILL.md
• Semantic-pattern reference – skills/diagram-design/references/semantic-patterns.md
• Individual diagram-type specifications – skills/diagram-design/references/type-*.md (38 files)
• Style guide (colors, typography) – skills/diagram-design/references/style-guide.md
• Animation contract (optional motion) – skills/diagram-design/references/animation.md
• Import-drawio procedure – skills/diagram-design/references/import-drawio.md
• Import-mermaid procedure – skills/diagram-design/references/import-mermaid.md
• Template variants (light, dark, full) – skills/diagram-design/assets/template*.html
• Self-check script (CI & local validation) – skills/diagram-design/scripts/self_check.py

Summary

• Choose the right diagram type by running behaviour before layout: first check semantic-patterns.md, then the visual-type guide in SKILL.md.
• Every concept maps to a dedicated type-*.md reference file that defines the rendering rules for that visual form.
• Enforce the complexity budget from SKILL.md (section 6.3) to keep diagrams readable; downgrade detail or split the canvas when limits are exceeded.
• Always run the pre-output checklist (taste gate) and validate with self_check.py before publishing.

Frequently Asked Questions

What is the first step when I need to choose the right diagram type?

The first step is to determine whether your content matches a semantic pattern—such as a fan-in queue, stage framework, or secure paved road—by checking skills/diagram-design/references/semantic-patterns.md. If a pattern applies, it defines the behavioural vocabulary before you ever select a visual layout.

Where does the diagram-design skill store its visual-type mappings?

All mappings live in the visual-type guide inside skills/diagram-design/SKILL.md (section 8.1). Each type links to a dedicated reference file in skills/diagram-design/references/, such as type-architecture.md or type-flowchart.md.

How should I reduce complexity if my diagram has too many nodes?

Consult the complexity budget in skills/diagram-design/SKILL.md (section 6.3); if you exceed the limits, split the diagram or lower the detail level from faithful to balanced or simplified. This keeps the output readable and within the layout constraints.

Can I generate animated or interactive diagrams?

Yes. You can request optional motion by passing a --motion=step flag, which causes the skill to load skills/diagram-design/references/animation.md alongside the chosen type reference. The result is a step-by-step HTML diagram with playback controls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}