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

> Choose the right diagram type by matching content to semantic patterns and selecting a visual layout. This guide helps you find the perfect diagram for your needs.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-19

---

**You choose the right diagram type by first matching your content to a semantic pattern in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), then selecting a visual layout from the [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) |
| Legacy IT landscape (before/after) | **IT current-state** | [`type-it-state.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-it-state.md) |
| Decision logic with branches | **Flowchart** | [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) |
| Time-ordered messages between actors | **Sequence** | [`type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sequence.md) |
| States & transitions | **State machine** | [`type-state.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-state.md) |
| Entities, fields & relationships | **ER / data model** | [`type-er.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-er.md) |
| Events positioned on a timeline | **Timeline** | [`type-timeline.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-timeline.md) |
| Cross-functional hand-offs | **Swimlane** | [`type-swimlane.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-swimlane.md) |
| Two-axis positioning / prioritisation | **Quadrant** | [`type-quadrant.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-quadrant.md) |
| Multi-criteria scoring | **Radar / Spider** | [`type-radar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-radar.md) |
| Reinforcing cycle or flywheel | **Loop** | [`type-loop.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-loop.md) |
| Hierarchy by containment | **Nested** | [`type-nested.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-nested.md) |
| Parent → children relationships | **Tree** | [`type-tree.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-tree.md) |
| Ownership / reporting structure | **Org chart** | [`type-org-chart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-org-chart.md) |
| Stacked abstraction levels | **Layer stack** | [`type-layers.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-layers.md) |
| Set overlap | **Venn** | [`type-venn.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-venn.md) |
| Ranked hierarchy or funnel | **Pyramid / Funnel** | [`type-pyramid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-pyramid.md) |
| Quantitative comparison (bars) | **Bar chart** | [`type-bar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-bar.md) |
| Part-of-whole area encoding | **Treemap** | [`type-treemap.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-treemap.md) |
| Continuous trends (lines) | **Line chart** | [`type-line.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-line.md) |
| Tasks & phases on a timeline | **Gantt** | [`type-gantt.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-gantt.md) |
| Distribution & correlation | **Scatter plot** | [`type-scatter.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-scatter.md) |
| End-to-end data stack | **High-Level** | [`type-high-level.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-high-level.md) |
| Multi-actor sequential workflow | **Process** | [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md) |
| Multi-tier storage architecture | **Medallion** | [`type-medallion.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-medallion.md) |
| Role-scoped data flow | **Data flow** | [`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md) |
| Data platform integration topology | **DP integration** | [`type-dp-integration.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-dp-integration.md) |
| Per-role access matrix | **DP security matrix** | [`type-dp-security-matrix.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-dp-security-matrix.md) |
| Quantity splitting/merging | **Sankey** | [`type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sankey.md) |
| Root-cause analysis | **Fishbone** | [`type-fishbone.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-fishbone.md) |
| Value chain / evolution | **Wardley map** | [`type-wardley.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-wardley.md) |
| Work-in-progress board | **Kanban** | [`type-kanban.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-kanban.md) |
| User journey & experience | **User journey** | [`type-journey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-journey.md) |
| Deployment topology | **Deployment** | [`type-deployment.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-deployment.md) |
| Dependency graph | **Dependency graph** | [`type-dependency.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-dependency.md) |
| UML class diagram | **UML class** | [`type-uml-class.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-uml-class.md) |
| Narrative backbone & releases | **Story map** | [`type-story-map.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-story-map.md) |
| Physical database schema | **Database schema** | [`type-db-schema.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) for motion) have been loaded.

## Code Examples

These examples show how the decision process looks in practice.

### Simple Architecture Request

```text

# 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

```text

# 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

```bash

# 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

```bash

# 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

```python

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)
- **Semantic-pattern reference** – [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)
- **Animation contract (optional motion)** – [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md)
- **Import-drawio procedure** – [`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md)
- **Import-mermaid procedure** – [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py)

## Summary

- **Choose the right diagram type** by running behaviour before layout: first check [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), then the visual-type guide in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) or [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) alongside the chosen type reference. The result is a step-by-step HTML diagram with playback controls.