The 27 Visual Types Supported by diagram-design: A Complete Catalog

The diagram-design skill maintains a fixed taxonomy of exactly 27 visual types—ranging from architecture diagrams and flowcharts to domain-specific data-platform layouts like medallion and DP security matrices—each defined in dedicated reference files under skills/diagram-design/references/.

The cathrynlavery/diagram-design repository provides a structured approach to generating editorial diagrams through a constrained set of layout grammars. Understanding these diagram-design visual types is essential for effectively invoking the skill and selecting the appropriate representation for your data. The canonical list is documented in the "Visual-type guide (27)" section of skills/diagram-design/SKILL.md.

Complete Catalog of the 27 diagram-design Visual Types

Each visual type corresponds to a specific layout grammar stored as a markdown reference file. When you request a diagram, the skill loads the matching file from skills/diagram-design/references/ to determine node placement, edge routing, and stylistic constraints.

Visual Type	Purpose	Reference File
Architecture	Components and connections in a system	type-architecture.md
IT current-state	Legacy landscape grouped by phase or department	type-it-state.md
Flowchart	Decision logic with branches	type-flowchart.md
Sequence	Time-ordered messages between actors	type-sequence.md
State machine	States, transitions, and guards	type-state.md
ER / data model	Entities, fields, and relationships	type-er.md
Timeline	Events positioned on a time axis	type-timeline.md
Swimlane	Cross-functional process with hand-offs	type-swimlane.md
Quadrant	Two-axis positioning and prioritization	type-quadrant.md
Radar / Spider	Multi-axis comparison of quantitative criteria	type-radar.md
Loop	Reinforcing cycle or flywheel (last step feeds first)	type-loop.md
Nested	Hierarchy expressed by containment	type-nested.md
Tree	Parent-to-children relationships	type-tree.md
Org chart	Human, agent, or team ownership and reporting	type-org-chart.md
Layer stack	Stacked abstraction levels	type-layers.md
Venn	Overlap between sets	type-venn.md
Pyramid / Funnel	Ranked hierarchy or conversion drop-off	type-pyramid.md
Bar chart	Categorical quantitative comparison	type-bar.md
Line chart	Continuous trends over time	type-line.md
Gantt	Tasks and phases on a timeline	type-gantt.md
Scatter plot	Distribution and correlation between two variables	type-scatter.md
High-Level	End-to-end data stack on a container cluster	type-high-level.md
Process	Multi-actor sequential workflow with data hand-offs	type-process.md
Medallion	Multi-tier data storage with quality levels and access policies	type-medallion.md
Data flow	Role-scoped pipeline steps (who does what)	type-data-flow.md
DP integration	Sources-to-core-to-consumers topology	type-dp-integration.md
DP security matrix	Per-role and per-component access-permission matrix	type-dp-security-matrix.md

How to Invoke diagram-design Visual Types

You trigger a specific layout by naming the visual type in your prompt. The skill extracts the type and loads the corresponding reference file before rendering.

Request an architecture diagram:

/skill:diagram-design
Make me an architecture diagram of my app: frontend, backend, database, Redis cache.

Generate a quadrant analysis:

/skill:diagram-design
I need a quadrant showing Q2 projects by impact vs effort.

Create a sequence diagram:

/skill:diagram-design
Give me a sequence of a bearer token refresh flow (401 → refresh → retry).

To start from a scaffold instead of a prompt, copy the HTML template and edit the JSON-like input block:

cp skills/diagram-design/assets/template.html my-diagram.html

# Edit my-diagram.html: set <title>, <desc>, and the input block describing nodes/edges

Key Files and Repository Architecture

The stability of the 27-type invariant is enforced by the repository structure and CI checks. The following files define the diagram-design system:

• skills/diagram-design/SKILL.md — Central skill description containing the visual-type guide and checklist
• skills/diagram-design/references/*.md — One file per visual type (the 27 types listed above)
• skills/diagram-design/references/semantic-patterns.md — Behavioral patterns evaluated before visual type selection
• skills/diagram-design/references/style-guide.md — Single source of truth for colors, typography, and tokens
• skills/diagram-design/assets/template*.html — Scaffolds for new diagrams (light, dark, full-editorial, motion)
• skills/diagram-design/assets/example-<type>.html — Rendered examples of every visual type (three variants each)
• skills/diagram-design/scripts/drawio_extract.py — Draw.io to structured IR converter
• skills/diagram-design/scripts/mermaid_extract.py — Mermaid to structured IR converter
• scripts/verify-docs-sync.py and scripts/verify-semantic-motion.py — CI checks that enforce the 27-type invariant

Summary

• diagram-design supports exactly 27 visual types covering architecture, process modeling, data analytics, and platform-specific diagrams.
• Each type is defined in a dedicated reference file located in skills/diagram-design/references/ (e.g., type-architecture.md).
• The canonical list is documented in SKILL.md under the "Visual-type guide (27)" section.
• You invoke types by name in prompts (e.g., "Create a medallion diagram"), or by copying scaffolds from assets/template*.html.
• The repository uses CI scripts (verify-docs-sync.py) to enforce the fixed taxonomy and prevent unregistered visual types.

Frequently Asked Questions

What are the 27 visual types in diagram-design?

The 27 types include traditional diagrams (flowchart, sequence, state machine, ER model, org chart), analytical charts (bar, line, scatter, radar, quadrant), structural layouts (architecture, nested, tree, layers), and data-platform specific visualizations (medallion, DP integration, DP security matrix, high-level). Each is optimized for a specific communicative purpose, from showing component connections to mapping access permissions.

How do I choose the right visual type for my data?

Select based on the relationship you need to emphasize. Use architecture or layer stack for system structure, sequence or swimlane for process flow, quadrant or radar for comparative analysis, and medallion or data flow for data platform concepts. The skill automatically matches your description to the reference file if you mention the type name explicitly.

What is the difference between visual types and semantic patterns?

Visual types are the 27 layout grammars that determine spatial arrangement. Semantic patterns (defined in references/semantic-patterns.md) describe behavioral structures like fan-in queues or circuit breakers. When you request a diagram with a semantic pattern, the skill loads the pattern file first, then selects the nearest compatible visual type from the 27-catalog to render it.

Can I create custom visual types beyond the 27?

No, the taxonomy is fixed. The repository includes CI checks (verify-docs-sync.py) that enforce the 27-type invariant to maintain consistency across renders. If you need a new layout grammar, you must propose it as a new reference file in skills/diagram-design/references/ and update the invariant checks, effectively adding a 28th type to the catalog.

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