What Is the Complexity Budget and Its Effect on Diagram Density?

The complexity budget is a set of quantitative limits on nodes, edges, and visual elements that prevents diagram overcrowding by capping primary components at specific thresholds—such as 9 nodes and 12 edges—ensuring consistent readability across all diagram types in the cathrynlavery/diagram-design repository.

The complexity budget is a core architectural constraint in the cathrynlavery/diagram-design repository that governs how dense or sparse a diagram can become. By enforcing strict quantitative limits on visual elements like components, dependencies, and accent items, the framework prevents the "hairball" effect that plagues complex technical illustrations. Understanding these limits is essential for contributors creating Wardley maps, UML diagrams, or sequence diagrams that must pass automated verification.

Technical Definition of the Complexity Budget

The complexity budget is not a single global value but a typed configuration where each diagram format defines its own quantitative ceilings. These limits restrict the maximum number of primary visual elements—including nodes, edges, arrows, and accent items—that can appear in a single diagram.

According to the reference specifications in the repository, typical limits include:

Diagram type	Primary elements	Budget limits
Wardley map	Components, dependency links, movement arrows, accent elements	Max 9 components, 12 links, 2 arrows, 2 accents (as defined in type-wardley.md lines 16-23)
UML class diagram	Classes, class-to-class links	Max 9 classes, 12 links (as defined in type-uml-class.md lines 45-52)
Sequence diagram	Lifelines, messages	Max 9 lifelines, 12 messages (as defined in type-sequence.md lines 89-97)

These definitions reside in the type-*.md reference files within the skills directory, where each file explicitly declares the complexity budget for its specific diagram category.

How the Complexity Budget Controls Diagram Density

The complexity budget directly constrains diagram density—the ratio of visual elements to available canvas space—through three primary mechanisms:

• Readability enforcement: By capping element counts (e.g., 9 nodes maximum), the budget prevents "hairball" drawings where excessive density obscures relationships. This ensures that dependency lines remain traceable and components remain distinguishable without zooming.

• Visual consistency: All diagrams of a given type share identical density ceilings, creating a uniform viewing experience. When comparing multiple Wardley maps, reviewers can rely on consistent component scales because no single diagram exceeds the 9-component threshold.

• Automation safety: The quantitative limits enable automated verification in CI pipelines. Scripts parse generated diagrams and validate element counts against the budget, failing builds for overly dense diagrams before they reach production.

Implementation in Verification Scripts

The enforcement mechanism relies on specialized extraction and verification scripts that parse diagram files and flag budget violations.

In [mermaid_extract.py](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py), the validation logic explicitly checks for node and edge overruns between lines 1135-1178:

if node_count > NODE_BUDGET:
    report_status = "OVER"
    violation_type = "node_budget_exceeded"
    
if edge_count > EDGE_BUDGET:
    report_status = "OVER"
    violation_type = "edge_budget_exceeded"

When the script detects more than 9 nodes or 12 edges, it outputs an OVER status and terminates with a failure code, preventing the diagram from passing validation.

Similarly, [verify-motion.py](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) enforces motion-item budgets (typically 12 items) for animated or interactive diagrams between lines 303-306:

if motion_item_count > MOTION_BUDGET:
    raise ComplexityBudgetError(
        f"Motion items {motion_item_count} exceed budget {MOTION_BUDGET}"
    )

These scripts collectively ensure that diagram density remains within human-readable limits regardless of the source format (Mermaid, Excalidraw, or Draw.io).

Practical Examples: Working Within Budget

The following examples demonstrate diagrams that respect the 9-node and 12-edge complexity budget. Both will pass automated verification.

Wardley Map Construction (Python API)

When using the diagram-design Python API to generate a Wardley map, the Diagram class internally validates against the budget defined in [type-wardley.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-wardley.md):

from diagram_design import Diagram

# Initialize Wardley map (budget: 9 components, 12 links)

d = Diagram(type="wardley")

# Add exactly 9 components (at the limit)

for i in range(9):
    d.add_component(f"Component-{i}", y=i*0.1)

# Add exactly 12 dependency links (at the limit)

edges = [
    (0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6),
    (6, 7), (7, 8), (0, 2), (1, 3), (2, 4), (3, 5)
]
for src, dst in edges:
    d.add_dependency(src, dst)

d.render("compliant-wardley.html")

Running verify-wardley.py or the generic validation suite against this output reports ok because the diagram respects the 9-node and 12-link thresholds.

Mermaid Flowchart Verification

For Mermaid diagrams, the budget applies to the rendered graph elements. A compliant flowchart stays under the 9-node limit:

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Task 1]
    B -->|No| D[Task 2]
    C --> E[End]
    D --> E
    F[Optional] --> G[Cleanup]
    G --> E
    %% 7 nodes, 6 edges: well within budget

Verify the budget compliance using the extraction script:

python -m skills.diagram_design.scripts.mermaid_extract example.mmd

Expected output confirms density compliance:

[VALID] Node count: 7 (budget: 9)
[VALID] Edge count: 6 (budget: 12)
Status: OK

If you add a tenth node or a thirteenth edge, the script flags the diagram as OVER and exits with error code 1, causing CI pipelines to reject the file.

Key Files in the Complexity Budget Architecture

The following source files define, implement, and enforce the complexity budget constraints:

File	Purpose	GitHub Link
type-wardley.md	Defines Wardley-specific limits (9 components, 12 links)	View source
type-uml-class.md	Specifies UML class diagram budgets	View source
type-sequence.md	Sets sequence diagram lifeline and message limits	View source
SKILL.md	High-level conceptual documentation of the complexity budget paradigm	View source
mermaid_extract.py	Extraction and validation engine for Mermaid diagrams (lines 1135-1178)	View source
verify-motion.py	General verification script enforcing motion-item budgets (lines 303-306)	View source

Summary

• The complexity budget is a typed configuration limiting diagram elements (typically 9 nodes and 12 edges) to prevent visual overcrowding.
• It enforces diagram density constraints through automated verification scripts that reject diagrams exceeding quantitative thresholds.
• Each diagram type defines specific limits in type-*.md reference files, ensuring format-appropriate constraints for Wardley maps, UML diagrams, and sequence charts.
• Verification occurs in CI pipelines via [mermaid_extract.py](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) and [verify-motion.py](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py), which report OVER status for budget violations.
• Contributors must split complex diagrams or remove non-essential elements when approaching budget limits to maintain readability and pass automated checks.

Frequently Asked Questions

What happens when a diagram exceeds its complexity budget?

When element counts surpass the defined thresholds—such as exceeding 9 nodes in a Wardley map—the verification scripts immediately flag the diagram with an OVER status. In [mermaid_extract.py](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py), this triggers a non-zero exit code that fails CI pipelines, preventing the dense diagram from merging into the main branch.

Are complexity budget limits configurable per diagram type?

Yes, each diagram type maintains its own budget specification in dedicated reference files. For example, [type-sequence.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md) defines 9 lifelines and 12 messages, while [type-wardley.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-wardley.md) permits 2 movement arrows and 2 accent elements. These type-specific configurations allow appropriate density limits for each visual paradigm.

How does the complexity budget differ between Mermaid and Excalidraw formats?

The budget applies conceptually to both formats—capping the logical elements (nodes, edges) regardless of rendering engine. However, [mermaid_extract.py](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) parses text-based Mermaid syntax to count elements, while Excalidraw verification likely processes JSON scene data. Both implementations enforce the same numerical thresholds to ensure consistent diagram density across export formats.

Why is diagram density specifically limited to 9 nodes and 12 edges?

These values derive from cognitive load research cited in the framework's [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), indicating that human working memory typically handles 7±2 discrete items effectively. The limit of 9 primary nodes with 12 connecting edges represents the maximum density where relationship lines remain traceable without interactive zooming, ensuring diagrams function as standalone communication artifacts rather than requiring exploration tools.

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