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

> Discover the complexity budget and how it controls diagram density by limiting nodes and edges. Learn to maintain readability in your technical diagrams.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-12

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-uml-class.md) lines 45-52) |
| **Sequence diagram** | Lifelines, messages | Max 9 lifelines, 12 messages (as defined in [`type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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:

```python
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/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:

```python
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/type-wardley.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-wardley.md):

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```mermaid
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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-wardley.md) | Defines Wardley-specific limits (9 components, 12 links) | [View source](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-wardley.md) |
| [`type-uml-class.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-uml-class.md) | Specifies UML class diagram budgets | [View source](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-uml-class.md) |
| [`type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sequence.md) | Sets sequence diagram lifeline and message limits | [View source](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md) |
| [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) | High-level conceptual documentation of the complexity budget paradigm | [View source](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) |
| [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) | Extraction and validation engine for Mermaid diagrams (lines 1135-1178) | [View source](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) |
| [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py) | General verification script enforcing motion-item budgets (lines 303-306) | [View source](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) |

## 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/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/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/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/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/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/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/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.