Diagram Design Complexity Budget Limits for All 27 Diagram Types

The Diagram-Design repository enforces complexity budget limits that range from the global default of approximately 15 nodes to specific bounds like 14–20 nodes for DP integration diagrams, with Sequence diagrams limited to one fragment and Faithful mode allowing up to 24 nodes before mandatory splitting.

Understanding complexity budget limits is essential for producing readable, professional diagrams in the cathrynlavery/diagram-design open-source system. Each of the 27 supported diagram types inherits a baseline constraint, though four categories carry specialized rules that override the global default. This guide breaks down every limit, cites the source files where they are defined, and shows how the engine enforces them automatically.

---

How the Complexity Budget System Works

The Diagram-Design engine calculates complexity based on node count, fragment count, and visual density rather than raw pixel dimensions. The system references type-specific markdown files to determine thresholds before rendering output.

According to SKILL.md § 7, the universal rule states: when a diagram exceeds its complexity budget, it must be split into an overview plus detail view【/skills/diagram-design/SKILL.md†L117】. The engine loads the matching type-*.md file first, checks the declared budget, and applies automatic splitting or prompts for simplification【/skills/diagram-design/SKILL.md†L119】.

---

Complete Complexity Budget Limits by Diagram Type

Global Default Budget (22 Diagram Types)

The majority of diagram types inherit the global default budget of approximately 15 nodes. This applies to:

• Architecture
• IT current-state
• Flowchart
• Tree
• Class
• Component
• Deployment
• Entity-relationship
• State machine
• Activity
• Use case
• Gantt
• Pie chart
• Bar chart
• Line chart
• Area chart
• Scatter plot
• High-Level
• Process
• Medallion
• Data flow
• DP security matrix

These types contain no explicit override in their reference files, so the engine falls back to the § 7 rule【/skills/diagram-design/SKILL.md†L117】.

Sequence Diagram: Strict Fragment Limit

Sequence diagrams operate under the most restrictive rule: one fragment per diagram by default. A second fragment is permitted only if both fragments stay under the budget【/skills/diagram-design/references/type-sequence.md†L82】. This design prevents the "staircase" effect that plagues verbose sequence diagrams.

Quadrant Diagram: House Defaults Applied

Quadrant diagrams incorporate specific visual constraints—paper texture, dot pattern, typography, legend strip, and 4 px grid—that constitute "house defaults." The complexity budget matches the global default but is explicitly acknowledged as applying within this visual framework【/skills/diagram-design/references/type-quadrant.md†L46】.

DP Integration: Explicit Node Range

DP integration diagrams carry the only hard numerical range in the type system: 14–20 nodes serves as the practical upper bound for a single diagram【/skills/diagram-design/references/type-dp-integration.md†L381】. Beyond this threshold, the engine enforces mandatory splitting regardless of visual density.

The source file at type-dp-integration.md line 381 documents this as a practical ceiling derived from integration mapping patterns, not an arbitrary limit.

---

Faithful Mode: The Documented Exemption

Faithful mode provides the sole authorized pathway to exceed standard complexity budgets, but with escalating structural requirements:

Node Threshold	Required Action
1–9 nodes	Standard layout permitted
10–24 nodes	Layout must be zoned
25+ nodes	Mandatory split into overview + detail

These rules appear in SKILL.md with the explicit statement: "faithful is the one documented exemption"【/skills/diagram-design/SKILL.md†L535】. Importantly, Faithful mode never relaxes connector rules from § 6—the budget exemption applies only to node density, not to line routing constraints.

---

Code Example: Querying Budget Programmatically

The Diagram-Design engine exposes budget data through its reference file loader. Below is Node.js-style pseudo-code demonstrating how a plugin or external tool can retrieve limits for any diagram type:

import { loadReference } from '@diagram-design/loader';

async function getComplexityBudget(diagramType) {
  const ref = await loadReference(`type-${diagramType}.md`);
  
  // Extract explicit numeric ranges or fallback to default
  const budgetLine = ref.match(/budget.*?(\d+–\d+|\d+)/i);
  return budgetLine ? budgetLine[1] : 'default (≈15 nodes)';
}

(async () => {
  console.log(await getComplexityBudget('sequence'));        // "default"
  console.log(await getComplexityBudget('dp-integration'));  // "14–20"
  console.log(await getComplexityBudget('nonexistent'));     // "default (≈15 nodes)"
})();

This pattern mirrors how the engine itself resolves budget constraints during the render pipeline.

---

Key Source Files Reference

File Path	Purpose
SKILL.md § 7	Global complexity budget rule and splitting requirement【/skills/diagram-design/SKILL.md†L117】
SKILL.md "faithful" section	Exemption rules for Faithful mode【/skills/diagram-design/SKILL.md†L535】
references/type-sequence.md	Fragment limit for Sequence diagrams【/skills/diagram-design/references/type-sequence.md†L82】
references/type-quadrant.md	House defaults budget acknowledgment【/skills/diagram-design/references/type-quadrant.md†L46】
references/type-dp-integration.md	14–20 node concrete limit【/skills/diagram-design/references/type-dp-integration.md†L381】
references/type-*.md (22 files)	Inherited global default for all other diagram types

All files reside in the cathrynlavery/diagram-design repository under the /skills/diagram-design/ path.

---

Summary

• 22 diagram types use the global default of ~15 nodes with automatic overview+detail splitting on exceedance.
• Sequence diagrams are limited to one fragment, with conditional allowance for a second.
• Quadrant diagrams apply the default within a specific house visual style (paper, dot pattern, 4 px grid).
• DP integration has the only explicit numeric range: 14–20 nodes.
• Faithful mode permits temporary budget exceedance with zoning required above 9 nodes and mandatory splitting above 24 nodes.
• The engine enforces all limits by loading type-*.md reference files before rendering, as specified in SKILL.md § 119.

---

Frequently Asked Questions

What happens when a diagram exceeds its complexity budget?

The Diagram-Design engine automatically splits the output into an overview plus detail view or prompts the user to reduce visual elements. This behavior is hard-coded in SKILL.md § 7 and applies unless Faithful mode is explicitly activated【/skills/diagram-design/SKILL.md†L117】.

Can I override the complexity budget for any diagram type?

Only through Faithful mode, which is the sole documented exemption. Even then, you must apply zoned layout above 9 nodes and cannot exceed 24 nodes without splitting. Standard diagram types have no configuration flag to disable budget enforcement.

Why does DP integration have a specific 14–20 node range while other types use a vague "approximately 15"?

The DP integration type addresses data platform architecture patterns where integration point density follows predictable scaling curves. The 14–20 range reflects empirical testing for readable Azure Data Factory and similar integration maps, documented at line 381 of type-dp-integration.md. Other diagram types vary too widely in visual density to justify fixed numbers.

Do connector rules ever relax when using Faithful mode?

No. According to SKILL.md, connector rules in § 6 never relax the budget—Faithful mode affects only node density and layout zoning, not line routing constraints【/skills/diagram-design/SKILL.md†L535】.

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