# How to Choose Between the 27 Visual Types in Diagram Design: A Complete Guide

> Explore the 27 visual types in diagram design to find the perfect fit for your data. Learn when to use each type for hierarchy, flow, state, or analytical relationships.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: tutorial
- Published: 2026-08-15

---

**The 27 visual types in Diagram Design are immutable grammar specifications—ranging from Tree and Flowchart to Radar and DP Security Matrix—each mapped to specific semantic patterns like hierarchy, sequence, or comparison; you choose based on whether your primary data represents structure, flow, state, or analytical relationships.**

The `cathrynlavery/diagram-design` repository maintains a **stable set of 27 visual-type grammars** that define how SVG diagrams render static or animated structures. According to [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), these types are not user-extensible; the CI script [`scripts/verify-semantics-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantics-motion.py) enforces this 27-type budget to ensure diagram portability. Each type is documented in a dedicated reference file under `skills/diagram-design/references/type-*.md` and selected via a two-step workflow: first identify the semantic pattern, then map to the nearest visual type.

## How the Selection Workflow Works

The selection process is rigidly defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) section 3 (Selection). You must identify the **semantic pattern** first—such as *queue*, *policy trace*, or *risk*—using [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md). Only after establishing the semantic intent do you map to the nearest visual type.

This prevents visual misalignment. For example, both **Swimlane** and **Data Flow** handle multi-actor processes, but Swimlane emphasizes the *owner* of each step while Data Flow emphasizes the *payload transformation* across roles.

## Hierarchy and Structure

Use these four types when your primary concern is parent-child relationships, containment, or tiered classification.

### Tree

**Tree** renders a hierarchical indented list perfect for deep parent-child chains like file systems or taxonomy trees. It prioritizes depth over breadth.

Choose **Tree** when vertical depth matters more than horizontal expansion.

```yaml
type: tree
root: "Company"
children:
  - {name: "Engineering", children: ["Backend","Frontend"]}
  - {name: "Product"}

```

Reference: [`skills/diagram-design/references/type-tree.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-tree.md)

### Org-Chart

**Org-Chart** displays boxes linked in a tree of responsibility, specifically designed for corporate reporting lines.

Use this for classic corporate hierarchies where boxes represent roles and lines represent authority.

```yaml
type: org-chart
root: "CEO"
reports:
  - {name: "CTO", reports: ["Eng Lead","Ops Lead"]}

```

### Nested

**Nested** draws boxes within boxes to illustrate containment boundaries, such as security zones or deployment layers.

Choose **Nested** when *nesting* itself conveys the primary architectural meaning rather than flow or sequence.

```yaml
type: nested
boxes:
  - {label: "Outer", children: [{label: "Inner"}]}

```

### Pyramid

**Pyramid** creates tiered stacked blocks that illustrate decreasing size or importance, such as budget allocation or maturity levels.

Use this for top-heavy visuals showing hierarchical levels that narrow toward the top.

```yaml
type: pyramid
levels: ["Vision","Strategy","Execution"]

```

## Process and Flow

These six types handle movement, decision logic, and cross-functional workflows.

### Flowchart

**Flowchart** represents branching logic with decision nodes and arrows, ideal for if/else business processes.

Choose **Flowchart** when the primary shape is **decision-based flow** rather than simple sequential steps.

```yaml
type: flowchart
steps:
  - {label: "Start"}
  - {label: "Decision", decision: true}
  - {label: "End"}

```

### Process

**Process** displays stacked steps with optional lanes, detailing ordered stages where each step is a *service* rather than a role.

Pick **Process** when the workflow’s **service stages** dominate, such as ETL pipelines or CI stages.

```yaml
type: process
steps:
  - {label: "Ingest"}
  - {label: "Transform"}
  - {label: "Load"}

```

### Swimlane

**Swimlane** maps horizontal lanes with vertical steps, where each lane represents an owner (e.g., HR, Engineering).

Prefer **Swimlane** when the *owner* of each step is the primary axis of interest, not just the sequence.

```yaml
type: swimlane
lanes: [{name: "Front-end"}, {name: "Back-end"}]
steps: [{label: "Design"}, {label: "Build"}, {label: "Deploy"}]
nodes:
  - {lane: "Front-end", step: 0, title: "Mockups"}
  - {lane: "Back-end", step: 1, title: "API"}

```

### Data Flow

**Data Flow** visualizes how data moves through a pipeline across organizational roles, similar to Swimlane but emphasizing **payload transformation**.

Use **Data Flow** when tracking how data changes state as it moves between teams or systems.

```yaml
type: data-flow
lanes:
  - {name: ["DATA","ADMINS"], key:"ADM"}
steps:
  - {number:"01", label:"COLLECT"}
nodes:
  - {lane:"ADM", step:0, title:"Setup"}

```

### Sequence

**Sequence** places actors on the left with vertical descending messages, classic for API calls or system interactions.

Choose **Sequence** when time and specific participants matter, and you need to show ordered interactions between distinct actors.

```yaml
type: sequence
actors: ["Client", "Server"]
messages:
  - {from: "Client", to: "Server", label: "GET /api"}

```

### Loop

**Loop** renders circular flow with back-edges to stress repeatable cycles like CI/CD or control systems.

Pick **Loop** when the diagram must emphasize a **repeatable cycle** or feedback mechanism rather than linear progression.

```yaml
type: loop
steps: ["Start","Process","Check","Return"]

```

## Time and Scheduling

These three types handle chronological data and temporal planning.

### Timeline

**Timeline** draws a horizontal axis with events, perfect for roadmaps, changelogs, or incident histories.

Use **Timeline** for linear historical visualization where points occur along a single chronological axis.

```yaml
type: timeline
events:
  - {date: "2024-01-01", label: "Launch"}
  - {date: "2024-03-15", label: "Feature X"}

```

### Gantt

**Gantt** renders bars across a timeline for project management, showing task dependencies and schedules.

Choose **Gantt** for classic project-management views where duration and dependencies are critical.

```yaml
type: gantt
tasks:
  - {label: "Design", start: "2024-01-01", end: "2024-01-10"}

```

### Line

**Line** creates simple trend charts with optional series, ideal for time-series metrics.

Use **Line** for straightforward metric plotting over a continuous axis without categorical grouping.

```yaml
type: line
series:
  - {label: "Prod", points: [{x:0,y:10},{x:1,y:12}]}

```

## Comparison and Analysis

These five types visualize set relationships, multi-dimensional data, and categorical comparisons.

### Venn

**Venn** draws overlapping circles to compare sets with shared members, such as feature overlap or audience segments.

Use **Venn** when you need classic set-intersection illustration with visual overlap representing shared attributes.

```yaml
type: venn
sets:
  - {name: "A", items: ["a","b","c"]}
  - {name: "B", items: ["b","c","d"]}

```

### Scatter

**Scatter** plots XY coordinates to reveal correlations or clusters in metric-versus-metric data.

Choose **Scatter** for data-driven visualizations where spatial relationships encode meaning and trend lines are optional.

```yaml
type: scatter
points:
  - {x: 10, y: 20, label: "A"}
  - {x: 30, y: 40, label: "B"}

```

### Radar

**Radar** displays radial axes with polygon overlays, useful for comparing multi-dimensional scores like product capabilities.

Pick **Radar** when you need a "spider-web" view comparing several quantitative dimensions simultaneously.

```yaml
type: radar
axes: ["Cost","Speed","Quality"]
values: [3,5,4]

```

### Quadrant

**Quadrant** positions items on a two-axis grid (e.g., risk vs. value) with bubbles.

Use **Quadrant** for strategic prioritization grids or market-position plots requiring orthogonal scales.

```yaml
type: quadrant
xLabel: "Impact"
yLabel: "Effort"
items:
  - {x: 8, y: 2, label: "Feature A"}

```

### Bar

**Bar** renders categorical comparisons as simple bars, ideal for counts or percentages across discrete groups.

Choose **Bar** for straightforward value comparison where the category matters more than the trend.

```yaml
type: bar
bars:
  - {label:"Q1", value:120}
  - {label:"Q2", value:150}

```

## System Architecture

These six types visualize infrastructure, platform layers, and high-level component arrangements.

### Architecture

**Architecture** draws boxes with arcs and optional hop-over lines for complex component relationships.

Use **Architecture** when you need free-form component layout with explicit routing conventions for crossing lines.

```yaml
type: architecture
components:
  - {name:"API", x:100, y:200}
connections:
  - {from:"API", to:"DB"}

```

### Layers

**Layers** displays stacked horizontal bands representing concerns like OSI network layers or security stacks.

Choose **Layers** when each horizontal band represents a distinct **concern layer** in a vertical stack.

```yaml
type: layers
layers:
  - {name: "Presentation"}
  - {name: "Business"}
  - {name: "Data"}

```

### Medallion

**Medallion** renders arches connecting a central hub to peripheral nodes, named after the data-lake medallion architecture (bronze, silver, gold).

Use **Medallion** for hub-spoke patterns where the central core is the focal point of the architecture.

```yaml
type: medallion
hub: "Lake"
spokes: ["Raw","Clean","Curated"]

```

### High-Level

**High-Level** uses phase chevrons and deployment boundaries to show end-to-end data stacks from ingest to visualization.

Pick **High-Level** for architecture overviews where phases, clusters, and cross-cutting concerns matter more than individual components.

```yaml
type: high-level
phases:
  - {name: "Ingest", components: ["Kafka","S3"]}

```

### DP Integration

**DP Integration** (Data Platform Integration) uses a standard three-row shape to show integration points like Trino or Airflow within a data platform.

Use **DP Integration** for canonical data-platform integration diagrams following the three-row convention.

```yaml
type: dp-integration
layers:
  - {name: "Ingest", nodes:["Kafka","S3"]}

```

### IT State

**IT State** renders horizontal bands with footers but no connectors, summarizing cross-cutting platform services like logging and auth.

Choose **IT State** for platform-wide views where services sit below the main diagram as infrastructure concerns.

```yaml
type: it-state
services: ["Auth","Logging","Metrics"]

```

## State and Data Modeling

These two types handle entity relationships and lifecycle states.

### State

**State** draws nodes with colored states and optional connectors, perfect for service health or state machines.

Use **State** when emphasizing the current *state* of items rather than the transitions or flow between them.

```yaml
type: state
states:
  - {name: "Running", color: "green"}
  - {name: "Failed", color: "red"}

```

### ER

**ER** (Entity-Relationship) diagrams model database schemas with tables, keys, and relationships.

Use **ER** specifically for relational data modeling where entities and their cardinalities are the primary focus.

```yaml
type: er
entities:
  - {name: "User", attributes: ["id","email"]}

```

## Security and Access Control

### DP Security Matrix

**DP Security Matrix** renders a grid of roles versus components with colored cells indicating permission levels.

Pick **DP Security Matrix** when you need a **role-vs-resource** permission overview for data platforms.

```yaml
type: dp-security-matrix
roles: ["Admin","Engineer","Analyst"]
components: ["Bucket","Catalog","Notebook"]
permissions:
  - {role:"Admin", component:"Bucket", level:"Full"}

```

## Summary

- **The 27 visual types are fixed** and enforced by [`scripts/verify-semantics-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantics-motion.py); you cannot create custom types without modifying the repository source.
- **Selection follows semantic patterns first**; consult [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) before choosing a visual grammar.
- **Hierarchical data** uses Tree, Org-Chart, Nested, or Pyramid depending on whether you need reporting lines, containment, or tiered values.
- **Process data** differentiates between owner-centric (Swimlane), service-centric (Process), data-centric (Data Flow), and decision-centric (Flowchart) views.
- **Architectural views** range from high-level phases (High-Level) to specific integration patterns (DP Integration) and infrastructure layers (IT State).
- **All types accept YAML input** compatible with the Import commands defined in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) and [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md).

## Frequently Asked Questions

### Can I create a custom 28th visual type?

No. The repository enforces a strict visual-type budget of exactly 27 grammars. The CI script [`scripts/verify-semantics-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantics-motion.py) asserts this count remains stable to ensure diagram portability and tool compatibility. To add a new type, you must submit a pull request that adds a new `type-*.md` reference file and updates the verification script, effectively replacing or extending the canonical set.

### How do I import existing diagrams into these 27 visual types?

Use the **Import** commands documented in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) or [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md). These parsers map external diagram formats to the closest matching visual type from the set of 27, generating the required YAML structure. The import process respects the semantic pattern mapping defined in [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) to ensure the imported diagram uses the appropriate grammar.

### What is the difference between Swimlane and Data Flow?

**Swimlane** organizes steps horizontally by *owner* (e.g., departments or roles), making it ideal for cross-functional processes where responsibility is the primary axis. **Data Flow** also uses lanes but emphasizes how the *data payload* transforms as it moves between roles. Choose Swimlane for process ownership visualization; choose Data Flow when tracking data lineage and transformations across organizational boundaries.

### Which visual type should I use for microservice architecture?

For microservice relationships with explicit routing and hop-over lines, use **Architecture**. If showing the platform-wide infrastructure services beneath the services (like logging, auth, and metrics), use **IT State**. For a high-level view of phases (ingest, process, serve), use **High-Level**. For hub-spoke patterns like API gateways or data lakes, use **Medallion**.