# What Are the 6 Mandatory Connector Routing Rules?

> Master the 6 mandatory connector routing rules for clear diagrams. Learn about rounded elbows, spacing, and label masks to improve your visual communication.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) and validated by [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

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

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

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

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

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

```svg
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py):

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) and enforced by [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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.