Positioning Diagram Types in Diagram-Design: The Complete Taxonomy of 27 Layouts

The diagram-design repository defines 27 distinct positioning diagram types—from Bar Charts to Venn diagrams—each codified in dedicated reference files under skills/diagram-design/references/ to enforce consistent layout rules across Mermaid and DrawIO imports.

The cathrynlavery/diagram-design project provides a comprehensive positioning-diagram taxonomy that standardizes how visual layouts map to semantic purposes. This system ensures that diagrams converted from external sources adhere to a unified editorial style guide through machine-readable positioning rules stored in markdown reference files.

Understanding Positioning Diagram Types

A positioning diagram type is a canonical layout specification that dictates how diagram elements should be arranged regardless of their source format. In diagram-design, each type encodes specific geometric constraints—such as root placement, orthogonal connectors, lane ordering, or circle radii—that rendering scripts apply to rebuild diagrams with consistent editorial styling.

The taxonomy serves as the foundation for the project's import tooling. When you invoke import-mermaid or import-drawio, the extractor scripts—scripts/mermaid_extract.py and scripts/drawio_extract.py—parse the source file and apply the positioning rules defined in the corresponding type-*.md reference file.

The 27 Positioning Diagram Types

The complete taxonomy contains 27 positioning diagram types, organized by functional category below. Each entry links to its canonical specification in the skills/diagram-design/references/ directory.

Data Visualization and Analytics

These types handle quantitative and relational data representations:

• Bar / Column Chart (type-bar.md): Compares discrete categories or time-based values. Ideal for categorical comparisons and trend analysis.

• Line Chart (type-line.md): Displays continuous quantitative trends over an axis. Best suited for time-series data.

• Scatter Plot (type-scatter.md): Correlates two continuous variables to identify relationships or distributions.

• Radar / Spider (type-radar.md): Provides multi-axis performance or attribute comparison in a radial layout.

• ER / Data Model (type-er.md): Renders entity-relationship diagrams for relational database schemas.

• DP integration (type-dp-integration.md): Visualizes data-platform integration flows with explicit source and consumer zones.

• DP security matrix (type-dp-security-matrix.md): Maps security controls against data-processing activities in a matrix format.

System Architecture and Infrastructure

These types document technical systems and their relationships:

• Architecture (type-architecture.md): High-level system component boxes and connectors for broad technical overviews.

• Data Flow (type-data-flow.md): Illustrates the flow of data between logical zones, often utilizing swimlane-style arrangements.

• High-Level (type-high-level.md): Broad-stroke system overviews designed for minimal detail and maximum conceptual clarity.

• IT current-state (type-it-state.md): Captures operational state diagrams for IT components and network zones.

• Layer Stack (type-layers.md): Represents stacked architectural tiers such as OSI models or application layers.

• Medallion (type-medallion.md): Depicts multi-tiered medallion architectures (Bronze-Silver-Gold) common in data lakehouse designs.

Process Modeling and Workflow

These types capture procedural logic and temporal sequences:

• Flowchart (type-flowchart.md): Documents decision logic, algorithms, and user-facing branching flows.

• Process (type-process.md): Linear or multi-lane processes with explicit steps and lane demarcations.

• Swimlane (type-swimlane.md): Parallel process lanes for RACI matrices or cross-functional flow analysis.

• Sequence (type-sequence.md): Ordered interactions such as message flows or timeline steps between actors.

• State Machine (type-state.md): Finite-state transitions and lifecycle diagrams for system behavior modeling.

• Loop (type-loop.md): Cyclical processes that repeat indefinitely, emphasizing iterative workflows.

• Gantt Chart (type-gantt.md): Project timelines with tasks, dependencies, and milestone markers.

• Timeline (type-timeline.md): Chronological events, milestones, and historical progressions.

Organizational and Hierarchical Structures

These types represent containment and reporting relationships:

• Tree / Hierarchy (type-tree.md): Classic top-down or left-to-right tree structures for taxonomies and org charts.

• Org Chart / Responsibility Map (type-org-chart.md): Organizational hierarchies or responsibility allocation matrices.

• Nested Containment (type-nested.md): Hierarchical containment where children are visually embedded within parent containers.

Conceptual and Matrix Layouts

These types support classification and set theory visualization:

• Quadrant (type-quadrant.md): Two-dimensional classification systems such as 2×2 matrices for prioritization or risk assessment.

• Pyramid / Funnel (type-pyramid.md): Funnel-style conversion flows or hierarchical reduction diagrams.

• Venn / Set Overlap (type-venn.md): Intersection of sets, shared attributes, and Ikigai-style conceptual frames.

Using Positioning Types in the CLI

The import-mermaid and import-drawio commands accept a --type parameter that accepts any of the 27 identifiers (the slug following type- in the reference filename). The tool ignores the original source layout and rebuilds the diagram according to the selected positioning rules.

# Force a Venn diagram layout during Mermaid import

instagit import-mermaid my-diagram.mmd --type=venn --format=svg --size=doc-wide

# Generate a Tree diagram with dark theme

instagit import-mermaid taxonomy.mmd --type=tree --variant=dark --detail=balanced

# Render a Gantt chart from DrawIO source

instagit import-drawio project-plan.drawio --type=gantt --format=html+png --audience=engineer

The --type flag references the positioning rules defined in files like skills/diagram-design/references/type-venn.md, while --detail, --size, and --variant control fidelity, canvas dimensions, and visual themes respectively.

Technical Implementation

The positioning system relies on specific files within the repository structure:

• skills/diagram-design/references/*.md: Contains the 27 canonical layout specifications (e.g., type-venn.md, type-tree.md) that define geometric constraints and styling rules.

• commands/import-mermaid.md: CLI wrapper documentation that invokes scripts/mermaid_extract.py to parse Mermaid source and apply positioning types.

• commands/import-drawio.md: CLI wrapper for DrawIO XML sources, utilizing the same taxonomy through scripts/drawio_extract.py.

• skills/diagram-design/SKILL.md and skills/diagram-design/references/output-spec.md: Define the available output formats, size presets, and visual variants referenced by the CLI flags.

The extractor scripts—scripts/mermaid_extract.py and scripts/drawio_extract.py—determine the source grammar and hand off the selected positioning type to the renderer, ensuring the output conforms to the editorial standards defined in the reference files.

Summary

• The cathrynlavery/diagram-design repository defines 27 positioning diagram types stored in skills/diagram-design/references/.

• Each type codifies specific geometric and layout rules that override source formatting to ensure editorial consistency.

• The system supports Mermaid and DrawIO inputs through import-mermaid and import-drawio commands with the --type parameter.

• Rendering scripts (mermaid_extract.py, drawio_extract.py) parse input files and apply positioning rules from the corresponding type-*.md reference files.

• Types range from data visualizations (Bar, Line, Scatter) to architectural diagrams (Layer Stack, Medallion) and conceptual layouts (Venn, Quadrant).

Frequently Asked Questions

What is the difference between a positioning diagram type and a diagram format?

A diagram format (e.g., SVG, PNG, HTML) specifies the output file type, while a positioning diagram type defines how elements are arranged geometrically within that file. According to the source code, the positioning type dictates root placement, connector styles, and lane ordering, whereas the format determines the rendering engine and file extension.

How do I add a custom positioning diagram type to the taxonomy?

You would create a new markdown file in skills/diagram-design/references/ following the type-[identifier].md naming convention. This file must define the positioning rules, layout constraints, and purpose statement. The CLI tools automatically detect new type files when they follow the established schema documented in skills/diagram-design/SKILL.md.

Can I use positioning diagram types with tools other than Mermaid and DrawIO?

Currently, the positioning system is implemented specifically for Mermaid and DrawIO sources through scripts/mermaid_extract.py and scripts/drawio_extract.py. However, the underlying positioning rules in skills/diagram-design/references/ are format-agnostic markdown specifications. Extending support to other formats would require creating new extractor scripts that map foreign syntax to the 27-type taxonomy.

Where are the visual style variants defined for each positioning type?

Visual variants (e.g., dark mode, high-contrast) are defined in skills/diagram-design/references/output-spec.md, while the base geometric positioning rules live in individual type-*.md files. The --variant CLI flag references the output specification, and --detail controls the fidelity level, but both operate within the geometric constraints established by the positioning type file.

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