Type-Specific Complexity Budgets for Sequence and Flowchart Diagrams

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. 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 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 and 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:

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 (lines 89–96)	Programmatic in mermaid_extract.py, excalidraw_extract.py, 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 (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 (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 (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, excalidraw_extract.py, and 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.

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, while flowchart limits are defined in Python verification scripts, ensuring consistent editorial standards across all diagrams in the repository.

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