# How Diagram Design Handles Complex Diagrams: A Layered Architecture Guide

> Learn how Diagram Design handles complex diagrams using a layered architecture. Discover strategies for complexity budget, routing, and decomposition.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: architecture
- Published: 2026-08-20

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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】.

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) | Pre-output checklist, complexity budget, fallback logic |
| [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) | Behavior-driven patterns and visual type mapping |
| [`references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-architecture.md) | Layout specs and connector rules per visual type |
| [`references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/output-spec.md) | Four-dial import configuration |
| [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) | CI validator for connector rules |
| [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) | CI validator for pattern compliance |
| [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) / [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)
- **Hard complexity budgets** in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) trigger automatic decomposition when exceeded
- **Four-dial import control** ([`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) §6-9 are validated in CI by [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md), and requires explicit user request.