Universal Complexity Budgets for Nodes, Arrows, and Accent Elements in Diagram Design

Diagram Design enforces hard limits of 9 nodes, 12 arrows, and 2 accent elements per diagram to maintain a target visual density of 4/10, ensuring every diagram remains readable and editorially disciplined.

The cathrynlavery/diagram-design repository implements these universal complexity budgets as immutable constraints across all 40 supported visual types. Unlike type-specific limits (such as maximum polar categories or tree depth), these three caps apply universally to flowcharts, radar charts, timelines, and every other diagram variant, preserving consistent information density regardless of visual form.

The Three Universal Limits

The complexity budget is defined in skills/diagram-design/SKILL.md (lines 71-73) and enforced by the pre-output Taste Gate (section 9). Exceeding any limit triggers a requirement to split the diagram into separate overview and detail views.

Nodes (Maximum 9)

Every diagram may contain no more than 9 distinct nodes. In the source code geometry validator, nodes are identified as <rect> or <g> elements carrying a data-node attribute. This cap prevents node overcrowding and ensures each entity receives sufficient visual attention on a single-page layout.

Arrows and Transitions (Maximum 12)

The budget allows up to 12 arrows or transitions connecting nodes. The validation script detects these as <line> or <path> elements with a marker-end attribute. This limit maintains traceability for the reader's eye, preventing the "spaghetti code" effect common in dense flowcharts.

Accent Elements (Maximum 2)

Only 2 accent-styled elements (designated by the coral color/class) are permitted per diagram. The validator identifies these via the .accent CSS class. Restricting high-contrast accents ensures they retain emergency or highlight value rather than becoming background noise.

Where the Budget Is Defined

The canonical specification resides in skills/diagram-design/SKILL.md within the Complexity Budget table. The relevant lines establish:

• Line 71: Max nodes = 9
• Line 72: Max arrows / transitions = 12
• Line 73: Max coral elements = 2

These values are hard constraints rather than recommendations. The Taste Gate checklist (section 9) explicitly references "Within the type’s complexity budget (§7)?" as a mandatory pass/fail criterion before any diagram reaches final output.

Validation and Enforcement

The repository provides automated and manual mechanisms to verify compliance before submission.

Automated CI Checks

The .github/workflows/ci.yml pipeline automatically runs the geometry validator on every pull request. The workflow executes scripts/verify-geometry.py against generated diagram files:

# Run the geometry/complexity validator on a generated diagram file

python3 scripts/verify-geometry.py path/to/diagram.html

This script parses the SVG structure, counts nodes, arrows, and accent elements, and fails the build if any count exceeds the universal caps. This ensures no code merge can introduce diagrams that violate the editorial density standards.

Manual Verification Script

For local development or pre-commit validation, invoke the same Python script used in CI:

# .github/workflows/ci.yml

- name: Verify diagram complexity
  run: |
    python3 scripts/verify-geometry.py generated/diagram.html

The script exits with a non-zero status and prints specific overflow errors if it detects:

• More than 9 elements with [data-node] attributes
• More than 12 path or line elements with arrow markers
• More than 2 elements using the .accent class

Handling Budget Overruns

If content requires more than 9 nodes, 12 arrows, or 2 accents, the specification mandates architectural decomposition rather than constraint relaxation. Create an overview diagram showing high-level relationships, followed by detail diagrams that drill into specific subsystems. This approach preserves the 4/10 target density while accommodating complex information architectures.

Programmatic Implementation

Developers building live editors or custom diagram generators can implement runtime guards using the same selection logic as the official validator.

Python Validator (CI Integration)

Integrate the validator into build scripts to block invalid diagrams at generation time:

# Example usage within a build pipeline

import subprocess
result = subprocess.run(
    ['python3', 'scripts/verify-geometry.py', 'output/diagram.html'],
    capture_output=True
)
if result.returncode != 0:
    raise ValueError(f"Complexity budget exceeded: {result.stdout.decode()}")

JavaScript Guard (Live Editors)

For browser-based editing environments, implement client-side validation using DOM queries that mirror the Python validator's logic:

<script>
function checkComplexity(svg) {
  const nodes   = svg.querySelectorAll('[data-node]').length;
  const arrows  = svg.querySelectorAll('path[marker-end], line[marker-end]').length;
  const accents = svg.querySelectorAll('.accent').length;

  if (nodes > 9)   alert('Too many nodes (max 9).');
  if (arrows > 12) alert('Too many arrows (max 12).');
  if (accents > 2) alert('Too many accent elements (max 2).');
}
document.addEventListener('DOMContentLoaded', () => {
  const svg = document.querySelector('svg');
  checkComplexity(svg);
});
</script>

This runtime check prevents authors from exceeding the universal complexity budgets for nodes, arrows, and accent elements before the diagram reaches the CI pipeline.

Summary

• 9 nodes maximum: Counted via [data-node] attributes in the SVG output, defined in SKILL.md line 71.
• 12 arrows/transitions maximum: Counted via [marker-end] attributes, defined in SKILL.md line 72.
• 2 accent elements maximum: Counted via .accent CSS class, defined in SKILL.md line 73.
• Universal application: These limits apply across all 40 visual types in the repository, independent of type-specific constraints.
• Automated enforcement: scripts/verify-geometry.py and .github/workflows/ci.yml block violations before merge.
• Resolution pattern: Exceeding any limit requires splitting the diagram into overview and detail views rather than increasing caps.

Frequently Asked Questions

Why are the universal complexity budgets set at 9, 12, and 2?

These values target a visual density of 4/10, ensuring diagrams fit comfortably on a single page without overwhelming the reader. The 9-node limit prevents entity overcrowding, the 12-arrow limit maintains traceable connection paths, and the 2-accent limit preserves the semantic weight of highlight elements. These specific integers emerged from editorial testing to optimize cognitive load across the 40 supported diagram types.

What happens if a diagram exceeds the complexity budget?

The Taste Gate (section 9 of SKILL.md) rejects any diagram exceeding these limits. The recommended architectural response is decomposition: split the content into an overview diagram showing high-level structure and separate detail diagrams for granular information. This preserves readability while accommodating complex subject matter.

Do these limits apply to all diagram types in the repository?

Yes. The universal complexity budgets apply identically across all 40 visual types, from flowcharts to radar charts. While individual diagram types may impose additional constraints (such as maximum polar categories or tree depth), the 9-node, 12-arrow, and 2-accent limits remain constant regardless of visual representation.

How can I verify my diagram respects the budget before submitting?

Run the scripts/verify-geometry.py validator locally against your generated HTML/SVG file. For automated safety, the CI pipeline defined in .github/workflows/ci.yml performs this check on every pull request. For live development, implement the JavaScript guard function shown in the Programmatic Implementation section to receive immediate browser alerts when approaching limits.

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