# Type-Specific Complexity Budgets for Sequence and Flowchart Diagrams

> Discover type-specific complexity budgets for sequence and flowchart diagrams. Learn how strict caps on lifelines, messages, and nodes ensure clarity and maintainability in your designs.

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

---

**Sequence diagrams enforce strict caps on lifelines (5), messages (12), and combined fragments (1–2), while flowchart diagrams limit visual density to 9 nodes and 12 edges regardless of the authoring tool.**

The `cathrynlavery/diagram-design` repository maintains editorial quality through hard **complexity budgets** that vary by diagram type. These thresholds prevent visual overload by restricting element counts during the extraction and validation process.

## Sequence Diagram Complexity Limits

Sequence diagrams follow granular constraints documented in [`skills/diagram-design/references/type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md). These rules govern actor density, interaction volume, and fragment nesting to ensure readability in technical documentation.

### Lifeline and Message Caps

The primary interaction surface is strictly bounded:

- **Maximum lifelines (actors):** 5 (lines 89–91)
- **Maximum messages (arrows):** 12 (lines 91–92)

Exceeding either threshold requires refactoring the diagram into multiple views, such as separating overview and detail concerns.

### Combined Fragment Restrictions

Fragment usage prevents excessive nesting and alternate-path sprawl:

- **Combined fragments (alt/opt/loop):** 1 by default; a second fragment is permitted only if each is a single-region `opt` or `loop` construct (lines 92–94).
- **Maximum `alt` regions:** 2 (lines 93–94).
- **Fragment nesting depth:** 1 (lines 94–95).

### Coral Highlight Budget

Visual emphasis is rationed to maintain focus on critical paths:

- **Coral (highlight) elements:** Maximum 2, ideally limited to 1 (lines 95–96).

## Flowchart Diagram Complexity Limits

Flowcharts utilize a unified node-and-edge counting system enforced consistently across all supported drawing tools.

### Node and Edge Thresholds

The verification logic in [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) defines absolute caps at lines 1135–1136:

- **Maximum drawable nodes:** 9
- **Maximum drawable edges (arrows):** 12

These limits apply universally to **all flowchart-type sources**, including Mermaid, Excalidraw, and Draw.io diagrams. The extraction logic in [`excalidraw_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/excalidraw_extract.py) and [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) implements identical thresholds to ensure cross-tool consistency.

### Budget Violation Detection

When extraction scripts process flowchart sources, they calculate boolean flags to identify violations:

```python
over_node_budget = node_count > 9
over_edge_budget = edge_count > 12

```

If either flag evaluates to true, the tooling recommends splitting the diagram into an "overview" (happy-path) view and a "detail" view rather than rendering an overly dense single diagram.

## Comparative Analysis of Budget Constraints

| Aspect | Sequence Diagram | Flowchart Diagram |
|--------|------------------|-------------------|
| **Primary element limit** | 5 lifelines | 9 nodes |
| **Arrow/message limit** | 12 messages | 12 edges |
| **Fragment/region control** | 1–2 combined fragments, max 2 `alt` regions, nesting depth 1 | No fragment concept; budget managed by node/edge count |
| **Highlight (coral) budget** | Up to 2 coral messages | No dedicated coral budget (highlights are part of node/edge styling) |
| **Enforcement mechanism** | Documented in [`type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sequence.md) (lines 89–96) | Programmatic in [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), [`excalidraw_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/excalidraw_extract.py), [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) (lines 1135–1136) |

## Managing Budget Exceedances

When either diagram type approaches its complexity ceiling, the prescribed remediation strategy involves editorial decomposition. For sequence diagrams exceeding the 5-actor or 12-message threshold, authors should split the workflow into an overview diagram showing primary interactions and a secondary detail diagram examining alternate flows or error conditions.

Flowcharts that trigger `over_node_budget` or `over_edge_budget` flags require similar abstraction—either consolidating sequential steps into higher-level process nodes or distributing logic across multiple linked diagrams to respect the 9-node and 12-edge limits.

## Summary

- **Sequence diagrams** enforce limits of 5 lifelines, 12 messages, 1–2 combined fragments, and 2 coral highlights as specified in [`skills/diagram-design/references/type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md) (lines 89–96).
- **Flowchart diagrams** apply a universal limit of 9 nodes and 12 edges across Mermaid, Excalidraw, and Draw.io sources, enforced by extraction scripts such as [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) (lines 1135–1136).
- Both diagram types recommend splitting into overview and detail views when budgets are exceeded.
- The repository uses explicit line-level documentation for sequences and programmatic validation for flowcharts to maintain consistent editorial standards.

## Frequently Asked Questions

### What happens when a sequence diagram exceeds the 5-lifeline limit?

The diagram violates the complexity budget defined in [`type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sequence.md) (lines 89–91). Authors must refactor the diagram into multiple views—typically an overview showing primary actors and a detail view examining specific interactions—to comply with the 5-actor maximum.

### Can flowcharts use coral highlights like sequence diagrams?

No. Flowcharts do not implement a dedicated coral highlight budget. While sequence diagrams restrict coral elements to 2 instances (lines 95–96), flowchart highlighting is handled through general node and edge styling without specific quantitative limits separate from the 9-node and 12-edge budgets.

### How does the tooling programmatically detect flowchart budget violations?

The extraction scripts—including [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), [`excalidraw_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/excalidraw_extract.py), and [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py)—calculate `over_node_budget` and `over_edge_budget` booleans by comparing counts against the 9-node and 12-edge thresholds (lines 1135–1136). Sequence diagrams currently rely on manual adherence to the documented limits in [`type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sequence.md).

### Are the complexity budgets configurable per project?

According to the source analysis, the budgets are hardcoded constants. Sequence limits are static values in [`type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sequence.md), while flowchart limits are defined in Python verification scripts, ensuring consistent editorial standards across all diagrams in the repository.