Diagram Types for Comparison: A Complete Guide to the Diagram-Design Repository

The Diagram-Design repository defines nine distinct diagram types optimized for comparison—including Bar/Column, Radar, Quadrant, Scatter, Line variants, Sankey, and Polar charts—each with specific visual grammars defined in skills/diagram-design/references/type-*.md files.

The Diagram-Design skill set provides a curated taxonomy of diagram types designed to amplify comparative insight across data, categories, and behaviors. When your primary storytelling goal is to compare discrete quantities, trends, or multi-criteria entities, the repository enforces strict layout conventions and visual constraints through authoritative reference files. This guide catalogs every comparison-focused diagram type available in the cathrynlavery/diagram-design repository, including their specific use cases and CLI generation methods.

Bar and Column Charts

The Bar (horizontal) and Column (vertical) diagram types serve as the foundation for direct side-by-side comparison of discrete quantities. According to skills/diagram-design/references/type-bar.md, these charts excel when each category contains a single numeric value and relative heights or lengths convey the primary message.

The repository extends basic bar charts with three specialized variants:

• Dumbbell: Emphasizes the gap between two values per row, ideal for "before vs. after" or "target vs. actual" scenarios. This variant renders the distance between paired values as the central visual element.
• Grouped: Places two series side-by-side within each category for direct visual comparison of related metrics.
• Stacked: Displays additive contributions within a single bar, enabling comparison of total magnitude while visualizing component breakdowns.

Radar Charts

Radar diagrams facilitate multi-criteria comparison of three to five entities across three to five quantitative axes on a common scale. As defined in skills/diagram-design/references/type-radar.md, this type is ideal for capability matrices, product scorecards, or framework evaluations where tabular data would prove too wide for effective scanning.

A specialized Radar variant supports comparative ranking against a common benchmark, producing a compact visual that displays strengths and weaknesses side-by-side across multiple dimensions.

Quadrant Charts

Quadrant diagrams provide 2×2 comparison frames for prioritization and positioning tasks. Defined in skills/diagram-design/references/type-quadrant.md, these charts map items across two dimensions—such as Impact × Effort or Reach × Frequency—dividing them into four logical zones. Use this type when you need to categorize items into strategic buckets based on dual-axis positioning.

Scatter Plots

Scatter diagrams compare two continuous variables to identify correlation patterns, with optional encoding of a third magnitude through point size. The reference file skills/diagram-design/references/type-scatter.md specifies this type for scenarios requiring visual analysis of relationships—or lack thereof—between two metrics, optionally weighted by a third quantitative factor.

Line Chart Variants

The Line type in skills/diagram-design/references/type-line.md supports three distinct comparison modes:

• Standard Line: Compares trends over continuous time periods, emphasizing direction and rate of change across multiple series.
• Slopegraph: Compares exact rank or value changes between two discrete snapshots, ideal for before/after metric comparison.
• Bump Chart: Tracks rank-only movement across three to six ordered snapshots, focusing exclusively on relative position changes rather than absolute values.

Sankey Diagrams

Sankey diagrams compare quantities as they flow through stages, such as budget allocations or funnel volumes. As specified in skills/diagram-design/references/type-sankey.md, this type is essential when readers must compare magnitudes as they split or merge across a controlled number of process stages. The width of flow lines encodes quantity, enabling immediate visual comparison of distribution patterns.

Polar Charts

Polar diagrams compare a single quantitative series across four to eight ordered categories where angular position carries meaning. According to skills/diagram-design/references/type-polar.md, this type suits cyclic or periodic data—such as quarterly scores or seasonal metrics—where clockwise order encodes temporal or sequential relationships.

Reference Architecture and Validation

Each diagram type resides as a self-contained Markdown file under skills/diagram-design/references/, defining layout conventions, anti-patterns, and SVG element patterns. The repository enforces these standards through validation scripts such as scripts/verify-bar.py and scripts/verify-sankey.py, which ensure that imported diagrams adhere to the prescribed visual grammar.

The rendering pipeline consumes these reference files to guarantee consistent comparative intent across all outputs. Key architectural files include:

• skills/diagram-design/references/type-*.md: Canonical definitions for each diagram type
• scripts/verify-*.py: Validation scripts enforcing visual grammar rules
• commands/export-diagram.md: CLI specification for SVG/PNG generation
• commands/import-mermaid.md and commands/import-drawio.md: Import commands mapping external sources to internal type taxonomy

Generating Comparison Diagrams via CLI

The repository provides CLI commands to generate comparison-focused diagrams from Mermaid or Draw.io source files. Each command follows a two-stage pipeline: import (parsing and validation) and export (rasterization).

# Generate a Bar chart for side-by-side quantity comparison

diagram-design import-mermaid assets/example-bar.mmd --type=bar \
  && diagram-design export-diagram assets/example-bar.html

# Create a Radar chart comparing products across multiple criteria

diagram-design import-mermaid assets/example-radar.mmd --type=radar \
  && diagram-design export-diagram assets/example-radar.html

# Build a Quadrant chart for Impact vs. Effort prioritization

diagram-design import-mermaid assets/example-quadrant.mmd --type=quadrant \
  && diagram-design export-diagram assets/example-quadrant.html

# Render a Sankey diagram comparing budget allocations across stages

diagram-design import-drawio assets/example-sankey.drawio --type=sankey \
  && diagram-design export-diagram assets/example-sankey.html

# Produce a Slopegraph for before/after metric comparison

diagram-design import-mermaid assets/example-slopegraph.mmd --type=slopegraph \
  && diagram-design export-diagram assets/example-slopegraph.html

The --type parameter maps to the corresponding type-*.md reference file, ensuring the exported diagram conforms to the established visual grammar for that comparison mode.

Summary

• The Diagram-Design repository provides nine distinct diagram types specifically architected for comparison tasks, ranging from simple bar charts to complex Sankey flows.
• Each type is governed by authoritative reference files in skills/diagram-design/references/ that define layout constraints and visual grammars.
• Validation scripts (scripts/verify-*.py) enforce type-specific rules during the import process, ensuring comparative integrity.
• CLI commands (import-mermaid, import-drawio, export-diagram) provide automated pipelines for generating standardized comparison diagrams.

Frequently Asked Questions

How do I choose between a Bar chart and a Slopegraph for comparison?

Bar charts excel when comparing multiple categories or discrete values at a single point in time, while Slopegraphs are optimized for exact before/after comparisons across exactly two time points. If your narrative focuses on rank changes rather than absolute values, use a Slopegraph; for general magnitude comparison across many categories, use Bar charts.

What is the maximum number of entities supported in a Radar chart comparison?

According to skills/diagram-design/references/type-radar.md, Radar charts optimally support three to five entities compared across three to five quantitative axes. Exceeding these limits reduces readability and violates the repository's visual grammar constraints enforced by the validation pipeline.

Can I combine multiple comparison types in a single exported diagram?

The repository's CLI processes single-type diagrams per export operation. While you cannot natively combine types (such as overlaying a Scatter plot on a Bar chart) within one command, you can generate multiple diagrams and composite them externally. Each diagram must pass its respective verify-*.py validation script independently.

What file formats does the import pipeline support for comparison diagrams?

The repository accepts Mermaid (.mmd) files via import-mermaid and Draw.io (.drawio) files via import-drawio. Both commands validate the source against the target type's reference file before exporting to HTML, SVG, or PNG formats through export-diagram.

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