28 Visual Diagram Types in diagram-design: Complete Guide with Use Cases

Diagram-design ships a fixed taxonomy of 28 visual diagram types, each with dedicated reference documentation under skills/diagram-design/references/ and unified rendering through a single core engine.

The diagram-design repository by Cathryn Lavery organizes visual communication into a strict, extensible system. Whether you're importing Mermaid files, converting Draw.io diagrams, or exporting to HTML, understanding these 28 diagram types ensures you select the right layout for your data. This guide covers every type, its intended use case, and how to invoke it via the CLI.

---

Complete List of 28 Diagram Types in diagram-design

The source code defines 28 distinct diagram types across six functional categories. Each type lives in its own markdown specification file.

Classic Charting Types

These handle quantitative data visualization:

• Bar (type-bar.md): Categorical comparisons, distributions, and rankings
• Line (type-line.md): Trends over time, continuous data progression
• Scatter (type-scatter.md): Correlation analysis, outlier detection
• Radar (type-radar.md): Multi-variable performance profiles, skill assessments

Hierarchical Structure Types

For parent-child relationships and nested information:

• Tree (type-tree.md): File systems, decision trees, taxonomies
• Org-Chart (type-org-chart.md): Company hierarchies, reporting structures
• Architecture (type-architecture.md): System components, deployment topologies
• Nested (type-nested.md): Containers-within-containers, Russian doll layouts

Process and Flow Types

For temporal sequences and operational flows:

• Flowchart (type-flowchart.md): Algorithm logic, business processes, decision paths
• Process (type-process.md): Step-by-step workflows with clear start/end points
• High-Level (type-high-level.md): Executive summaries, simplified system overviews
• Sequence (type-sequence.md): Object interactions, API call flows, system dynamics
• Timeline (type-timeline.md): Historical events, project milestones, roadmaps
• Swimlane (type-swimlane.md): Cross-functional processes, role-based activities
• Gantt (type-gantt.md): Project scheduling, dependency tracking, resource allocation

State-Based Visualization Types

For condition transitions and security modeling:

• State (type-state.md): Finite state machines, UI component lifecycles
• IT State (type-it-state.md): Infrastructure states, service health transitions
• Data Flow (type-data-flow.md): Information movement through systems, GDPR/privacy mapping
• DP Security Matrix (type-dp-security-matrix.md): Data protection risk assessment, compliance grids
• DP Integration (type-dp-integration.md): Data protection system interoperability

Specialized Layout Types

For conceptual and strategic frameworks:

• Venn (type-venn.md): Set relationships, overlapping audience segments
• Quadrant (type-quadrant.md): 2x2 matrices, competitive positioning, prioritization grids
• Pyramid (type-pyramid.md): Hierarchical value, Maslow-style needs, food chains
• Medallion (type-medallion.md): Centralized hub-and-spoke, core-periphery relationships
• Loop (type-loop.md): Cyclical processes, feedback loops, continuous improvement
• Layers (type-layers.md): OSI stack-style abstractions, cake-layer architectures
• ER (type-er.md): Entity-relationship modeling, database schema design

---

How to Specify Diagram Types in diagram-design

The CLI exposes diagram type selection through the --type flag. Override automatic detection when your source format is ambiguous.

Import with Explicit Type

diagram-design import-mermaid my-diagram.mmd --type gantt

diagram-design import-drawio my-diagram.drawio --type architecture

Export with Default Type Detection

diagram-design export-diagram --output diagram.html

When omitted, the engine infers type from source content structure. The reference files in skills/diagram-design/references/*.md define the inference rules.

---

Key Implementation Files

File Path	Purpose
skills/diagram-design/references/type-*.md	Authoritative specifications for all 28 diagram types
commands/import-mermaid.md	Mermaid import CLI with --type option
commands/import-drawio.md	Draw.io import CLI with --type option
commands/export-diagram.md	Export to HTML/PNG documentation
assets/template-*.html	Rendering templates (light, dark, full variants)
scripts/*.py	Validation scripts enforcing type-specific constraints

The Python validation scripts apply specialized rules: for example, DP Security Matrix has strict edge constraints checked at build time.

---

When to Use Each Diagram Type Category

Choose based on your communication goal:

• Quantitative comparison → Bar, Line, Scatter, Radar
• Organizational clarity → Tree, Org-Chart, Nested
• Process documentation → Flowchart, Sequence, Swimlane, Gantt
• System modeling → Architecture, Layers, Data Flow, ER
• Compliance and security → DP Security Matrix, DP Integration, IT State
• Strategic frameworks → Quadrant, Pyramid, Venn, Medallion

The diagram-design engine normalizes all inputs to these 28 canonical types, ensuring consistent output regardless of source format.

---

Summary

• Diagram-design defines 28 fixed diagram types in skills/diagram-design/references/
• Types span charting, hierarchy, process, state, security, and specialized layouts
• Use --type flag to override automatic detection: import-mermaid, import-drawio
• Each type has dedicated validation rules enforced by Python scripts
• HTML templates in assets/ render final output in multiple themes

---

Frequently Asked Questions

How does diagram-design handle automatic type detection?

The engine analyzes source structure—Mermaid grammar tokens, Draw.io XML shapes, or JSON schema—to infer type. When ambiguous, it defaults to generic Flowchart or requires explicit --type specification per commands/import-mermaid.md.

Can I create custom diagram types beyond the 28?

No. The taxonomy is fixed. The repository enforces this through validation scripts that reject unknown types. Extending requires modifying scripts/*.py and adding a new type-*.md reference file.

What's the difference between State and IT State diagram types?

State (type-state.md) models general finite state machines for software components. IT State (type-it-state.md) specializes in infrastructure monitoring, capturing service health transitions (up, degraded, down) with operational metadata.

Which diagram type should I use for GDPR compliance documentation?

Use DP Security Matrix for risk assessment grids and DP Integration for mapping how data protection systems connect. Both enforce data-flow-specific validation rules absent in generic diagram types.

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