# How to Resolve Connector Overlapping Issues in Complex Diagrams with diagram-design > Resolve connector overlapping in complex diagrams with diagram-design by enforcing five SKILL rules and validating with verify-geometry.py. Achieve cleaner, more readable designs. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-08-18 --- **To resolve connector overlapping issues in complex diagrams with diagram-design, enforce the five mandatory connector rules defined in SKILL.md—rounded orthogonal paths, proper label margins, distinct attach points with fanning, 12px offsets for parallel routes, and bridge primitives for crossings—then validate with verify-geometry.py.** The `cathrynlavery/diagram-design` repository provides a strict visual grammar for creating clear technical diagrams. When multiple connectors intersect or share paths in complex layouts, the rendering violates the design system's mandatory geometric constraints. Understanding and applying the connector rules defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) ensures your diagrams remain readable and mechanically valid. ## The Five Mandatory Connector Rules in SKILL.md According to the [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) specification, all diagram types inherit these strict geometric constraints that directly prevent overlapping: - **Rounded right-angle (orthogonal) connectors**: Diagonal or straight-line paths are forbidden because they inevitably cross other arrows or run on top of each other. - **Label-to-connector margin (6–10px)**: Labels must maintain a gap from the stroke to prevent hiding the underlying line, which creates the visual illusion of overlapping connectors. - **No overlapping connectors**: Two arrows must never occupy the same geometric segment. When paths converge, you must offset them by at least 12px or insert a bridge/hop primitive. - **Fan attach points**: When multiple connectors share the same edge of a box, each must use a distinct attach point spaced at least 12px apart. - **Avoid routing behind unrelated boxes**: Connectors passing behind boxes that are neither source nor destination must be rerouted or rendered as dashed transit lines. ## Step-by-Step Resolution Workflow ### Step 1: Run the Geometry Validator Detect violations automatically using the built-in validator located in the scripts directory. ```bash python3 scripts/verify-geometry.py path/to/diagram.html ``` This script reports overlapping paths, missing margins, and illegal attach points defined in the specification. ### Step 2: Convert All Connectors to Orthogonal Elbows Imported diagrams from tools like Draw.io retain original waypoints that likely violate the orthogonal rule. Reroute every connector to comply with the mandatory elbow geometry. ```bash diagram-design import-drawio path/to/raw.drawio.svg \ --reroute-connectors \ --output examples/fixed.html ``` The `--reroute-connectors` flag enforces the rounded right-angle paths required by [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) §1 and documented in [`references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/import-drawio.md). ### Step 3: Fan Attach Points For edges receiving multiple arrows, calculate distinct attach offsets using the formula `L * k/(N+1)` and assign them in your YAML configuration. ```yaml connectors: - from: ui to: api from_side: right to_side: left offset: 0 # first attach point - from: ui to: db from_side: right to_side: left offset: 12 # 12px below first (fan spacing) ``` ### Step 4: Offset Parallel Arrows When connectors travel in the same direction, add a visual offset expressed as a `dx`/`dy` delta to prevent geometric overlap. ```yaml connectors: - from: db-primary to: cache offset: 12 # pushes path 12px down - from: db-replica to: cache offset: -12 # pushes path 12px up ``` ### Step 5: Add Bridge/Hop Primitives for Crossing Arrows For orthogonal intersections, insert a bridge segment that lifts one arrow over the other. Set the `bridge: true` flag as defined in [`references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-architecture.md) under *Crossing arrows*. ```yaml connectors: - from: api-gateway to: auth-service bridge: true ``` ### Step 6: Verify Again Re-run the validator to confirm compliance before finalizing. ```bash python3 scripts/verify-geometry.py examples/complex.html ``` Expect output confirming no overlapping connectors, proper 6–10px margins, and correct fanning. ### Step 7: Optional Visual Tweaks for Transit Lines For connectors that must pass behind unrelated boxes (violating rule 5), adjust the `stroke-dasharray` to indicate non-direct interaction. ```svg ``` ## Summary - **SKILL.md** defines five mandatory rules that prevent connector overlaps, including orthogonal paths and 12px minimum offsets. - Use [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) to automatically detect geometric violations before and after applying fixes. - Apply **fanning** to distribute attach points when multiple connectors share an edge, using the `L * k/(N+1)` calculation. - Implement **offset** values (≥12px) for parallel connectors traveling the same direction. - Insert **bridge** primitives for unavoidable orthogonal crossings, enabled via the `bridge: true` YAML flag. - Convert imported diagrams using `--reroute-connectors` to ensure compliance with the orthogonal connector rule specified in [`references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/import-drawio.md). ## Frequently Asked Questions ### What is the minimum spacing required between parallel connectors in diagram-design? The [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) specification mandates a minimum offset of **12 pixels** between parallel connector segments to prevent geometric overlap. This applies both to fanned attach points on shared edges and to offset directives for connectors traveling in the same direction. ### How do I detect overlapping connectors automatically? Run `python3 scripts/verify-geometry.py` against your diagram HTML file. This validator checks for path intersections, missing label margins (6–10px requirement), and incorrect attach point distributions, reporting specific violations that break the no-overlapping-connectors rule. ### Can I import existing Draw.io diagrams without manual rerouting? No. The [`references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/import-drawio.md) guide explicitly requires rerouting every connector upon import. Use the CLI command with `--reroute-connectors` to automatically convert diagonal paths into the mandatory rounded right-angle orthogonal format and apply fanning algorithms. ### When should I use bridge primitives instead of offsets? Use **bridge** (hop) primitives when two orthogonal connectors must geometrically intersect at a crossing point, as documented in [`references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-architecture.md). Use **offsets** when connectors run parallel to each other or share the same source/destination edge and need lateral separation.