How to Resolve Connector Overlapping Issues in Complex Diagrams with diagram-design

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 ensures your diagrams remain readable and mechanically valid.

The Five Mandatory Connector Rules in SKILL.md

According to the 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.

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.

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 §1 and documented in 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.

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.

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 under Crossing arrows.

connectors:
  - from: api-gateway
    to: auth-service
    bridge: true

Step 6: Verify Again

Re-run the validator to confirm compliance before finalizing.

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.

<line x1="100" y1="200" x2="300" y2="200"
      stroke="#4f5d75" stroke-dasharray="4,3"/>

Summary

• SKILL.md defines five mandatory rules that prevent connector overlaps, including orthogonal paths and 12px minimum offsets.
• Use 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.

Frequently Asked Questions

What is the minimum spacing required between parallel connectors in diagram-design?

The 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 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. Use offsets when connectors run parallel to each other or share the same source/destination edge and need lateral separation.

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