What Are the 6 Mandatory Connector Routing Rules?

Diagram Design enforces six strict, non-negotiable connector routing rules—rounded orthogonal elbows with 8 px radius, label-to-connector margins of 6–10 px, no overlapping connectors with bridge primitives, shared-edge fan-out with ≥12 px spacing, dashed strokes when passing behind unrelated nodes, and label masks that avoid node overlap—all defined in skills/diagram-design/SKILL.md and validated by scripts/verify-geometry.py.

These mandatory connector routing rules form the visual grammar of the diagram-design repository by cathrynlavery. They ensure every diagram remains readable, traceable, and semantically unambiguous across all outputs. The rules are codified in the project's SKILL.md specification and automatically enforced through a dedicated geometry verification script.

---

Rule 1: Rounded Right-Angle (Orthogonal) Connectors

All connectors must use orthogonal elbows with quarter-arc corners. The standard radius is 8 px, with a minimum of 6 px permitted only for tight layouts.

Diagonal <line> elements are restricted to cases where both endpoints share identical x or y coordinates—effectively horizontal or vertical segments only.

<path d="M100 40 h40 a8 8 0 0 1 8 8 v40" 
      stroke="#4f5d75" stroke-width="1" fill="none"
      marker-end="url(#arrow-default)"/>

The a8 8 0 0 1 8 8 command creates the mandatory quarter-arc. This convention is specified in [SKILL.md § Mandatory connector rules – rule 1](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L71) and detailed further in [references/type-architecture.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-architecture.md).

---

Rule 2: Label-to-Connector Margin

Every arrow label must maintain a 6–10 px gap from the stroke. This is achieved through a mask rectangle that guarantees visual separation and prevents the label from obscuring the line.

<rect x="130" y="68" width="36" height="12" rx="2" fill="#f5f5f5"/>
<text x="148" y="77" fill="#7a8399" font-size="8"
      font-family="'Geist Mono', monospace" text-anchor="middle">
  WRITE
</text>

The mask sits 14 px above the arrow (8 px text height + 6 px minimum gap). Source: [SKILL.md § Mandatory connector rules – rule 2](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L73).

---

Rule 3: No Overlapping Connectors

Connectors may never share identical stroke paths or render atop one another. When orthogonal arrows must cross, a bridge / hop primitive is required. Parallel connectors must be offset by ≥ 12 px.

<path d="M120 80 h40 a8 8 0 0 1 8 8 v40"
      stroke="#4f5d75" stroke-width="1" fill="none"
      marker-end="url(#arrow-default)"/>
<path d="M160 120 a4 4 0 0 0 8 0" 
      stroke="#fff" stroke-width="4" fill="none"/>

The white semicircle "bridges" the crossing point, preserving traceability for both arrows. Source: [SKILL.md § Mandatory connector rules – rule 3](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L75).

---

Rule 4: Shared-Edge Fan-Out

When multiple connectors attach to the same edge of a node, each requires a distinct attach point. Spacing follows:

• ≥ 12 px standard minimum
• 8 px minimum for very small boxes
• Formula: offset = L · k / (N + 1)

<path d="M180 40 h40 a8 8 0 0 1 8 8 v20" .../>
<path d="M180 80 h40 a8 8 0 0 1 8 8 v20" .../>
<path d="M180 120 h40 a8 8 0 0 1 8 8 v20" .../>

Attach points here are spaced 40 px apart, well above the 12 px threshold. Source: [SKILL.md § Mandatory connector rules – rule 4](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L77).

---

Rule 5: Avoid Passing Behind Unrelated Boxes

A connector cannot run behind any node that is not its source or destination, except when geometrically unavoidable. In unavoidable cases, three conditions apply:

• Stroke must be dashed (stroke-dasharray="4,3")
• Label placed at the visible end
• No arrowhead may land on the intervening box

<path d="M100 200 h80 a8 8 0 0 1 8 8 v40"
      stroke="#4f5d75" stroke-dasharray="4,3"
      stroke-width="1" fill="none"
      marker-end="url(#arrow-default)"/>

The dashed style visually signals the connector's non-direct path. Source: [SKILL.md § Mandatory connector rules – rule 5](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L84).

---

Rule 6: Label Mask Must Not Overlap Nodes

The opaque mask rectangle for any label must not intersect nodes rendered after the label. Labels should occupy connector segments in open canvas space—typically beyond a node's edge.

<path d="M200 300 h60 a8 8 0 0 1 8 8 v30"
      stroke="#4f5f5f75" stroke-width="1" fill="none"
      marker-end="url(# arrow-default)"/>

<rect x="260" y="318" width="40" height="12" rx="2" fill="#f5f5f5"/>
<text x="280" y="327" fill="#7a8399" font-size="8"
      font-family="'Geist Mono', monospace" text-anchor="middle">
  SAVE
</text>

The mask at x=260 clears the node's right edge at x=200 by 60 px. Source: [SKILL.md § Mandatory connector rules – rule 6](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L90).

---

Automated Validation

All six mandatory connector routing rules are enforced by scripts/verify-geometry.py:

python3 scripts/verify-geometry.py <diagram.svg>

This script runs as part of the repository's CI pipeline, rejecting any SVG that violates the routing grammar. The validator checks:

• Elbow radii and orthogonal compliance
• Label margin distances
• Overlap detection and bridge presence
• Fan-out spacing calculations
• Dashed stroke application for behind-box segments
• Mask-to-node intersection tests

---

Summary

• Rounded orthogonal elbows (8 px radius, 6 px minimum) replace diagonal lines
• 6–10 px margins separate labels from connector strokes via mask rectangles
• Zero tolerance for overlaps—bridges for crossings, ≥12 px offsets for parallels
• Distributed attach points for shared-edge fan-out using offset = L · k / (N + 1)
• Dashed strokes with visible-end labels when passing behind unavoidable boxes
• Mask placement in open canvas to prevent node intersection

These rules, defined in skills/diagram-design/SKILL.md and enforced by scripts/verify-geometry.py, guarantee consistent, professional diagram output across all diagram-design implementations.

---

Frequently Asked Questions

What happens if a diagram violates one of the mandatory connector routing rules?

The CI pipeline rejects the build. Running python3 scripts/verify-geometry.py locally reports specific violations with line numbers and required corrections before submission.

Can I use diagonal connectors instead of orthogonal elbows?

Only when both endpoints share identical x or y coordinates—effectively horizontal or vertical. True diagonal <line> elements are prohibited by rule 1 of the mandatory connector routing rules.

Why 8 px specifically for the elbow radius?

The 8 px standard balances visual clarity with space efficiency. The 6 px minimum accommodates tight layouts while maintaining the quarter-arc recognizability that distinguishes diagram-design output.

Where can I see a fully compliant example diagram?

The repository includes [assets/example-data-flow.html](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-data-flow-full.html)—a rendered SVG demonstrating all six rules in a production data flow diagram.

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