Understanding Complexity Budgets for Diagram Types: When and How to Split Diagrams

Complexity budgets enforce hard limits on visual primitives per diagram type, triggering mandatory splits into logical sub-diagrams when exceeded to maintain readability and CI compliance.

The diagram-design repository by cathrynlavery defines strict complexity budgets for every visual type—from UML class diagrams to Sankey charts—that cap nodes, edges, and accent elements to prevent visual clutter. These budgets are enforced by verification scripts and extraction logic, ensuring diagrams remain readable, printable, and valid within the SKILL guidelines established in SKILL.md.

What Are Complexity Budgets?

A complexity budget is a predefined limit on the number of visual primitives—such as nodes, edges, members, and accent elements—that a single diagram may contain while remaining legible and printable. According to SKILL.md § 7, every diagram type in the repository carries specific quantitative constraints that prevent cognitive overload.

Enforcement Through Verification Scripts

The repository automates budget compliance through Python verification scripts located in the scripts/ directory. Files such as verify-uml-class.py, verify-sankey.py, and verify-dependency.py parse diagrams using extractors like mermaid_extract.py and drawio_extract.py. These extractors set boolean flags—"over_node_budget" and "over_edge_budget"—when limits are exceeded. If a diagram violates its budget, the extractor outputs a diagnostic line:

- budget: nodes OVER (max 9), edges OK (max 12)

The CI pipeline rejects diagrams with these flags unless they are split into compliant sub-diagrams.

Complexity Budgets by Diagram Type

Each diagram type defined in the references/ directory specifies unique constraints tailored to its visual grammar.

UML Class Diagrams

According to references/type-uml-class.md, class diagrams must respect the following caps:

• Maximum 7 classes
• Maximum 8 relationships
• Maximum 5 members per compartment
• Maximum 2 accent elements

When these limits are exceeded, the guidelines instruct you to split by package, rendering separate diagrams per module to isolate cohesive groups of classes.

Database Schemas and Dependencies

The references/type-db-schema.md file enforces a tight schema budget:

• Maximum 5 tables
• Maximum 8 columns shown per table
• Maximum 6 foreign-key edges
• Maximum 2 accent elements

For dependency diagrams, references/type-dependency.md adds a constraint of maximum 1 back-edge (cycle) and limits tables to 5 with 8 column rows each. When over budget, you should collapse leaf clusters into aggregated nodes (e.g., “+6 leaves”) and distribute remaining elements across separate diagrams.

Flow and Process Diagrams

Process diagrams governed by references/type-process.md (§ 10) limit the total count of steps, decision points, and connective arrows to preserve flow readability. Sankey diagrams, documented in references/type-sankey.md, use a qualitative budget: a column is over budget when its label-gutter cannot accommodate a centred label, typically triggering a split into an overview plus detail pair rather than adding a fourth column or ninth node.

Strategic and Journey Maps

Wardley maps per references/type-wardley.md cap the number of nodes and edges to preserve narrative clarity. Journey maps in references/type-journey.md lack hard numeric caps but enforce that no single activity or slice may exceed its visual capacity. When limits are reached, split into separate maps per activity or collapse slices into count cards.

Operational Visualizations

Kanban boards follow WIP limits defined in references/type-kanban.md, where exceeding a column’s card count triggers the accent budget limit of 2 elements total. Deployment diagrams in references/type-deployment.md treat any environment forcing a column beyond its label-gutter capacity as over budget. Polar charts from references/type-polar.md similarly fail when label-gutter width is insufficient. In all three cases, the remedy is to split into multiple diagrams—per environment, activity, or data subset—or to aggregate overflow into count cards (e.g., “+14 more”).

When to Split Diagrams According to SKILL Guidelines

Section 7 of SKILL.md mandates that any diagram exceeding its type-specific budget must be split. The splitting strategy depends on the diagram’s semantic orientation.

Package-Oriented Splits

For UML class diagrams and architectural diagrams, partition by package or module. This aligns with the natural software boundaries and keeps related classes visually cohesive while respecting the 7-class limit.

Environment-Oriented Splits

Deployment diagrams should generate one diagram per environment. This prevents a single diagram from attempting to render development, staging, and production topologies simultaneously, which would violate label-gutter constraints.

Activity-Oriented Splits

Journey maps and Kanban boards split by activity or workflow phase. When a Kanban column exceeds its WIP limit, aggregate the backlog into a single count card rather than listing every item, preserving the accent budget for critical highlights.

Data-Oriented Splits

Sankey, DB schema, and Polar diagrams split into overview plus detail views. Alternatively, collapse dense leaf clusters into single aggregated nodes to reduce edge and node counts while maintaining visual reference to the underlying data volume.

Detecting Budget Violations in Code

You can programmatically detect budget violations using the repository’s extraction utilities. Below is an example of splitting a UML class diagram when the class count exceeds the budget:

from collections import defaultdict

# Assume `parser` is an instance of the UML class extractor

if len(parser.classes) > 7:
    # Group classes by their Python package name

    packages = defaultdict(list)
    for cls in parser.classes:
        packages[cls.package].append(cls)

    for pkg, classes in packages.items():
        # Render a separate diagram per package

        draw_uml_class_diagram(classes, outfile=f"{pkg}.svg")

For Sankey diagrams, detect the budget flags and execute a split:

info = extract_sankey(diagram_source)
if info["over_node_budget"] or info["over_edge_budget"]:
    print("⚠️ Sankey is over budget – split into overview + detail")
    # Example split: first-stage nodes → overview.svg, remaining → detail.svg

    split_sankey(info, ["stage-1"], "overview.svg")
    split_sankey(info, ["stage-2", "stage-3"], "detail.svg")

Summary

• Complexity budgets are hard limits defined in SKILL.md and references/type-*.md files that restrict nodes, edges, and accent elements per diagram type.
• Verification scripts (verify-*.py) and extractors (mermaid_extract.py, drawio_extract.py) automate budget checking via over_node_budget and over_edge_budget flags.
• UML class diagrams max out at 7 classes and 8 relationships; exceeding this requires splitting by package.
• Database schemas are limited to 5 tables and 8 columns per table; overflow necessitates showing sub-systems or aggregating leaves.
• Splitting strategies vary by diagram semantics: package-oriented for architecture, environment-oriented for deployment, activity-oriented for workflows, and data-oriented for schemas and flows.
• CI compliance depends on resolving budget violations before diagrams are merged.

Frequently Asked Questions

What happens when a UML class diagram exceeds its complexity budget?

When a UML class diagram contains more than 7 classes or 8 relationships, the extractor sets over_node_budget or over_edge_budget to true. You must refactor the diagram into multiple package-specific sub-diagrams, each containing logically related classes that fit within the limits defined in references/type-uml-class.md.

How do I split a Sankey diagram that has too many columns?

If a Sankey diagram’s label-gutter cannot accommodate centered labels—typically indicating a fourth column or ninth node—you should split it into two linked diagrams: an overview showing high-level flows and a detail diagram expanding specific stages. This approach preserves readability without violating the visual constraints in references/type-sankey.md.

Are there automated tools to check complexity budgets before committing diagrams?

Yes. The repository provides verify-*.py scripts for each diagram type. These scripts parse source files using mermaid_extract.py or drawio_extract.py and validate against budgets defined in the reference files. Integration into CI pipelines ensures that over-budget diagrams are flagged before deployment.

What is the complexity budget for database schema diagrams?

According to references/type-db-schema.md, database schema diagrams are capped at 5 tables, 8 columns per table, 6 foreign-key edges, and 2 accent elements. If your schema exceeds these limits, display a sub-system view or aggregate peripheral tables into leaf clusters to maintain compliance.

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