# What Are the Six Mandatory Connector Rules in Diagram Design?

> Learn the six mandatory connector rules in diagram design for clear, professional visuals. Discover how to implement orthogonal elbows, label margins, non-overlapping routes, and more.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-10

---

**The six mandatory connector rules in Diagram Design require rounded orthogonal elbows, strict label margins, non-overlapping routing, fanned attachment points, dashed strokes for behind-box passes, and mask ordering that prevents node clipping, all enforced by [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py).**

Diagram Design is an open-source diagramming system governed by a strict connector grammar specified in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md). The **six mandatory connector rules in Diagram Design** define non-negotiable geometric constraints that ensure every diagram remains readable, traceable, and visually unambiguous, regardless of diagram type.

## The Connector Grammar Specification

According to [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) §6, these rules apply universally across all diagram types. The [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) automation aborts generation if any violation is detected during the pre-output checklist (§9).

### 1. Rounded Right-Angle (Orthogonal) Connectors

All off-axis connections must use **quarter-arc elbows** with a default radius of `8 px` (minimum `6 px`). Straight diagonal `<line>` elements constitute a hard fail.

This rule guarantees clean, readable layouts and makes edge direction obvious without relying on slopes.

```svg
<svg viewBox="0 0 120 80" role="img">
  <!-- orthogonal elbow (r=8) -->
  <path d="M20,30 H70 a8,8 0 0 1 8,8 V60" stroke="#2d3142" fill="none"
        marker-end="url(#arrow)"/>
</svg>

```

### 2. Label-to-Connector Margin (6–10 px)

Every arrow label must sit on an **opaque mask rect** positioned `6 px` to `10 px` away from the connector stroke. This prevents the label from obscuring the arrow, preserving the ability to trace the connection path.

```svg
<svg viewBox="0 0 120 40">
  <path d="M10,20 H100" stroke="#2d3142" marker-end="url(#arrow)"/>
  <!-- mask rect 6 px above the line -->
  <rect x="44" y="10" width="32" height="12" fill="#f5f5f5"/>
  <text x="60" y="20" text-anchor="middle" font-family="Geist Mono"
        font-size="8">READ</text>
</svg>

```

### 3. No Overlapping Connectors

Connectors may not share the same stroke path or run on top of each other. When two arrows must cross, use the **bridge/hop** primitive. If connectors would otherwise overlap, fan them apart by at least `12 px` to ensure each relationship is individually traceable.

```svg
<svg viewBox="0 0 140 80">
  <!-- first arrow -->
  <path d="M20,30 H70 V50" stroke="#2d3142" marker-end="url(#arrow)"/>
  <!-- second arrow crossing, lifted by a bridge -->
  <path d="M20,50 H50 a8,8 0 0 0 8,-8 V30 H120"
        stroke="#2d3142" marker-end="url(#arrow)"/>
</svg>

```

### 4. Fan Attach Points on Shared Edges

When multiple connectors exit or enter the **same edge** of a box, each must have its own attach point. Spacing must be `≥12 px` apart, or `≥8 px` for very small boxes. This avoids "pin-point" congestion that makes it impossible to follow a particular edge.

```svg
<svg viewBox="0 0 140 80">
  <rect x="80" y="20" width="40" height="40" fill="#fff" stroke="#2d3142"/>
  <!-- three arrows fan out from the left edge -->
  <path d="M20,30 H80" stroke="#2d3142" marker-end="url(#arrow)"/>
  <path d="M20,40 H80" stroke="#2d3142" marker-end="url(#arrow)"/>
  <path d="M20,50 H80" stroke="#2d3142" marker-end="url(#arrow)"/>
</svg>

```

### 5. Connectors Must Not Pass Behind Non-Endpoint Boxes

Unless the box is unavoidable on the orthogonal path, the connector must be routed around it. If passing behind is unavoidable, the stroke must be **dashed** and the label placed at the visible end. This signals that the intervening box is not an endpoint and prevents accidental visual occlusion.

```svg
<svg viewBox="0 0 140 80">
  <rect x="60" y="30" width="40" height="20" fill="#fff" stroke="#2d3142"/>
  <!-- dashed line passing behind the rectangle -->
  <path d="M20,40 H60 a0,0 0 0 0 0,0 V40 H120"
        stroke="#2d3142" stroke-dasharray="4,3"
        marker-end="url(#arrow)"/>
</svg>

```

### 6. Label Masks Must Not Overlap Nodes Drawn Later

Because nodes are painted after labels, a mask landing inside a node would be clipped. The label must be placed on a segment that runs through empty canvas, or the node’s `x+width` must be cleared before the mask starts. This guarantees label legibility by ensuring the node fill does not hide part of the text.

```svg
<svg viewBox="0 0 140 80">
  <!-- label and mask drawn first -->
  <rect x="44" y="10" width="32" height="12" fill="#f5f5f5"/>
  <text x="60" y="20" font-family="Geist Mono" font-size="8">WRITE</text>
  <!-- node drawn afterwards (will not clip the mask) -->
  <rect x="80" y="20" width="40" height="40" fill="#fff" stroke="#2d3142"/>
  <path d="M20,30 H100" stroke="#2d3142" marker-end="url(#arrow)"/>
</svg>

```

## Verification and Enforcement

The [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) script automates validation against these rules. It is complemented by type-specific verifiers such as [`verify-dumbbell.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-dumbbell.py) and [`verify-waterfall.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-waterfall.py) in the same directory. Color tokens referenced in the examples (e.g., `paper` `#f5f5f5`, `ink` `#2d3142`, `accent` `#eb6c36`) are defined in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md).

The [`assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template.html) file demonstrates the correct rendering order: connectors and labels are drawn before nodes to satisfy Rule 6 and prevent clipping artifacts.

## Summary

- **Rounded orthogonal elbows** are mandatory; diagonal lines trigger a validation failure.
- **Label masks** require `6–10 px` clearance from connector strokes to prevent obscuring arrows.
- **Overlapping connectors** are prohibited; use bridge primitives or fanning instead.
- **Shared edges** must use fanned attach points spaced at least `12 px` apart.
- **Connectors passing behind** non-endpoint boxes must use dashed strokes and visible-end labels.
- **Draw order** must place labels before nodes to prevent mask clipping.

## Frequently Asked Questions

### What happens if a connector violates one of the six rules?

The [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py) script aborts diagram generation immediately. The pre-output checklist defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) §9 treats any violation as a hard error that must be resolved before output.

### Can I use straight diagonal lines instead of rounded elbows?

No. [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) §6 Rule 1 explicitly prohibits straight diagonal `<line>` elements. All off-axis connections must use quarter-arc elbows with a radius of at least `6 px` to maintain visual clarity.

### How does the system prevent label text from being hidden by diagram nodes?

Rule 6 enforces draw order: labels and their opaque masks are rendered before node fills. The label must sit on a canvas segment that clears the node's `x+width` boundary before the mask starts, ensuring the node fill cannot clip the text.

### Are the connector rules the same for all diagram types in the repository?

Yes. While type-specific scripts like [`verify-dumbbell.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-dumbbell.py) and [`verify-waterfall.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-waterfall.py) provide specialized validations, they all inherit and enforce the same **six mandatory connector rules** defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) §6 across every diagram type.