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

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, these types are not user-extensible; the CI script 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 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. 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.

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

Reference: 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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; you cannot create custom types without modifying the repository source.
• Selection follows semantic patterns first; consult 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 and 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 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 or 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 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.

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