How Diagram Design Handles Complex Diagrams: A Layered Architecture Guide

Diagram Design tackles complex diagrams through a strict complexity budget, semantic-first routing, and automatic decomposition strategies that separate behavior from layout.

Complex diagrams risk becoming unreadable visual noise. The cathrynlavery/diagram-design repository implements a disciplined, code-enforced system for managing diagram-level complexity without sacrificing semantic meaning. This guide examines the six core mechanisms that keep intricate diagrams manageable and machine-verifiable.

---

Semantic-First Routing for Behavior-Driven Diagrams

When a diagram's meaning depends on dynamic behavior—queues, policy traces, security boundaries—the system prioritizes semantics over visual defaults.

The skill first loads semantic-patterns.md and selects a semantic pattern that captures the core logic. This pattern dictates:

• Required primitives
• A tighter complexity budget
• Mapping to the nearest visual type

For example, "Fan-in queue" maps to Data flow, while "Secure paved road" maps to Architecture【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/semantic-patterns.md#L9-L16】.

# Complex policy trace triggers semantic pattern selection

diagram-design \
  "Compare why these two policy requests differ for my OAuth flow."

---

Complexity Budget: Hard Limits with Automatic Enforcement

Every diagram type enforces immutable caps on visual elements. The Complexity budget table in SKILL.md defines exact limits for【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md#L62-L70】:

• Nodes
• Arrows
• Focal elements
• Other elements

Automatic split behavior: When a request exceeds these limits, Diagram Design forces an overview + detail decomposition rather than compressing elements into an illegible single view.

# Force explicit split for over-budget diagrams

diagram-design \
  "Show a detailed data-flow of my microservice mesh with 20 components." \
  --force-split

---

Four-Dial Import Control for Legacy Sources

When importing existing draw.io or Mermaid sources, Diagram Design strips source-specific geometry, colors, and fonts—retaining only semantic content. Users then configure four dials via output-spec.md【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/output-spec.md#L42-L48】:

Dial	Options	Budget Impact
format	drawio, svg, png, mermaid	Neutral
size	slide-4x3, slide-16x9, a4-portrait, social	Neutral
detail	faithful, balanced, simplified	Direct tie to budget
audience	technical, executive, mixed	Neutral

The detail dial controls budget compliance:

• faithful: May exceed budget only with zoned layouts
• balanced and simplified: Guarantee budget compliance

# Import with balanced detail enforcement (≤12 nodes)

diagram-design:import-drawio \
  large-system.drawio \
  --size=slide-16x9 \
  --detail=balanced \
  --audience=executive

---

Static Fallback and Decomposition Strategies

Each semantic pattern defines a static fallback rendering that displays essential nodes, outcomes, and labels without animation or optional layers【semantic-patterns.md §1-3】.

If density remains problematic, the system recommends view splitting as mandated by the checklist in SKILL.md【SKILL.md §9】. This ensures no single diagram carries unsustainable complexity.

---

Mandatory Connector Rules for Visual Clarity

Six non-negotiable connector rules in SKILL.md §6-9 enforce【SKILL.md §6-9】:

1. Orthogonal routing
2. Label-mask gaps
3. Non-overlapping arrows
4. Fan-out attach points
5. Proper Z-ordering

Violations trigger CI failures via scripts/verify-geometry.py, ensuring complex diagrams maintain readability under automation.

---

Optional Motion and Accessibility Guarantees

Motion is strictly a presentation layer—added only on request and never altering static meaning or relaxing the complexity budget【animation.md】.

All diagrams retain full accessibility metadata regardless of complexity【SKILL.md §10-12】:

• role="img"
• aria-labelledby
• Prefixed IDs

---

Key Implementation Files

File	Purpose
SKILL.md	Pre-output checklist, complexity budget, fallback logic
references/semantic-patterns.md	Behavior-driven patterns and visual type mapping
references/type-architecture.md	Layout specs and connector rules per visual type
references/output-spec.md	Four-dial import configuration
scripts/verify-geometry.py	CI validator for connector rules
scripts/verify-semantic-motion.py	CI validator for pattern compliance
scripts/drawio_extract.py / mermaid_extract.py	Source extraction with styling stripped

---

Summary

Diagram Design handles complexity through architectural discipline rather than manual adjustment:

• Semantic-first routing matches behavior to appropriate visual types via semantic-patterns.md
• Hard complexity budgets in SKILL.md trigger automatic decomposition when exceeded
• Four-dial import control (output-spec.md) ties detail levels to budget compliance
• Static fallbacks and recommended splits ensure readable alternatives
• Mandatory connector rules with CI enforcement prevent visual degradation
• Presentation-layer motion preserves semantic integrity and accessibility

---

Frequently Asked Questions

What happens if a diagram request exceeds the complexity budget?

Diagram Design automatically splits the output into an overview plus detail diagram. Each resulting diagram stays within its type-specific limits. Users can also force this behavior with the --force-split flag for proactive decomposition.

How does the detail dial affect complex imported diagrams?

The detail dial in output-spec.md directly governs budget adherence. Setting --detail=balanced or --detail=simplified guarantees compliance with node and arrow limits. Only faithful permits budget overruns, and solely when paired with zoned layouts.

Are connector rules enforced automatically?

Yes. Six mandatory connector rules defined in SKILL.md §6-9 are validated in CI by scripts/verify-geometry.py. Failures block diagram generation, ensuring orthogonal routing, proper Z-ordering, and non-overlapping arrows remain consistent.

Can motion be added without increasing complexity?

Motion is strictly additive and never impacts the underlying static diagram or complexity budget. It resides in the presentation layer only, as defined in animation.md, and requires explicit user request.

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