# The Six Mandatory SVG Connector Rules in the diagram-design System

> Master the six mandatory SVG connector rules for diagrams. Learn to use rounded orthogonal connectors, fanned attach points, and proper layering for compliant SVG diagrams.

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

---

**Use rounded orthogonal connectors with proper label margins, no overlaps, fanned attach points, correct layering, and non-overlapping masks to create compliant SVG diagrams.**

The **diagram-design** system by Cathryn Lavery enforces a strict visual grammar for all diagrams. These six **SVG connector rules** ensure every illustration remains traceable, accessible, and visually clean. They are documented in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) and automatically validated by [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) as part of the pre-output checklist.

## Rule 1: Rounded Right-Angle (Orthogonal) Connectors

All connectors must use **quarter-arc elbows** with a radius of **8 px** (minimum 6 px). Diagonal `<line>` elements are prohibited unless the source and target nodes share identical x or y coordinates.

The elbow-path formula is defined in [`skills/diagram-design/references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-architecture.md). This rule eliminates jagged corners and maintains a consistent architectural aesthetic across all diagrams.

## Rule 2: Label-to-Connector Margin

Every arrow label must maintain a **6–10 px gap** from the connector stroke. The label placement follows axis alignment:

- **Horizontal connectors**: label sits above
- **Vertical connectors**: label sits beside

An **opaque mask rect** behind each label prevents text from clashing with the stroke path. This mask must never touch the connector path itself.

## Rule 3: No Overlapping Connectors

Connectors may not share stroke paths or run directly atop each other. Two mechanisms enforce this:

- **Crossing arrows**: use a *bridge/hop* primitive (defined in [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md))
- **Parallel arrows**: offset by **≥12 px**

This rule preserves visual clarity in dense diagrams where multiple relationships traverse similar regions.

## Rule 4: Fan Attach Points for Shared Edges

When multiple connectors enter or exit the **same edge of a box**, each receives a distinct attach point. Spacing requirements:

- Standard: **≥12 px** apart
- Absolute minimum: **8 px**

The attach-point formula from [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) calculates position as `L × k / (N + 1)` measured from the leading corner, where `L` is edge length, `k` is the connector index, and `N` is the total connector count.

## Rule 5: Connector Behind Non-Endpoint Boxes

A connector must **not pass behind any box except its source or target**. The single exception: geometrically unavoidable transits. In these cases:

- Stroke must be **dashed**
- Label must be placed at the **visible end** of the connector

This prevents the visual ambiguity of "mystery arrows" emerging from unexpected locations.

## Rule 6: Label Mask Must Not Overlap Later Nodes

The **opaque mask rect** behind each label must never overlap a node rendered after the label. Z-order violations cause node fills to clip the text.

**Placement strategy**: position labels on empty canvas segments **before** any node is painted. This ensures correct layering without complex SVG grouping.

## Complete Compliant Example

The fragment below demonstrates all six rules in a single valid SVG:

```svg
<svg role="img" aria-labelledby="diag-title diag-desc" width="300" height="200">
  <title id="diag-title">Sample diagram – all connector rules applied</title>
  <desc id="diag-desc">Illustrates the six mandatory connector rules.</desc>

  <!-- 1️⃣ Rounded orthogonal connector (source → target) -->
  <path d="M40,60 h40 a8,8 0 0 1 8,8 v40 a8,8 0 0 1 -8,8 h-40"
        fill="none" stroke="#4f5d75" marker-end="url(#arrow)" />

  <!-- 2️⃣ Label with 8 px gap and opaque mask -->
  <rect x="80" y="50" width="36" height="12" rx="2" fill="#f5f5f5"/>
  <text x="98" y="60" fill="#7a8399" font-size="8"
        font-family="'Geist Mono', monospace" text-anchor="middle">READ</text>

  <!-- 4️⃣ Fan attach points (two connectors from same right edge) -->
  <path d="M120,68 h40 a8,8 0 0 1 8,8 v20 a8,8 0 0 1 -8,8 h-40"
        fill="none" stroke="#4f5d75" marker-end="url(#arrow)"/>
  <path d="M120,112 h40 a8,8 0 0 1 8,8 v20 a8,8 0 0 1 -8,8 h-40"
        fill="none" stroke="#4f5d75" marker-end="url(#arrow)"/>

  <!-- 5️⃣ Transit connector behind an intervening box (dashed) -->
  <rect x="170" y="80" width="80" height="40" fill="#fff" stroke="#ccc"/>
  <path d="M150,100 h20 a8,8 0 0 1 8,8 v0"
        fill="none" stroke="#4f5d75" stroke-dasharray="4,3"
        marker-end="url(#arrow)"/>

  <!-- Arrow markers -->
  <defs>
    <marker id="arrow" markerWidth="8" markerHeight="6" refX="7"
            refY="3" orient="auto">
      <polygon points="0 0, 8 3, 0 6" fill="#4f5d75"/>
    </marker>
  </defs>
</svg>

```

### How This Satisfies All Six Rules

- **Rule 1**: Both `<path>` elements use `a8,8` rounded elbows
- **Rule 2**: The `<rect>`+`<text>` pair creates a masked label with 8 px spacing
- **Rule 3**: No paths overlap; parallel connectors are distinct
- **Rule 4**: Right-edge connectors at `y=68` and `y=112` are fanned 44 px apart
- **Rule 5**: The dashed path demonstrates the transit-behind-box exception
- **Rule 6**: All masks appear before the gray box node

## Automated Enforcement

The **diagram-design** system validates these rules automatically:

| File | Purpose |
|------|---------|
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Authoritative rule documentation (section **Mandatory connector rules**) |
| [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) | Automated validator run during pre-output checklist |
| [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) | Full skill validation including accessibility contracts |

Run `python scripts/verify-geometry.py` before committing any diagram to ensure compliance.

## Summary

- **Rounded elbows** (`r=8px`) replace all diagonal lines
- **6–10 px margins** separate labels from connector strokes
- **No overlaps** — use bridges for crosses, 12 px offsets for parallels
- **Fan attach points** (`≥12 px`) for shared edges
- **Dashed strokes** only for unavoidable transit-behind-box situations
- **Mask placement** must precede any overlapping node in paint order

## Frequently Asked Questions

### What happens if a connector violates the rounded elbow rule?

The pre-output checklist will reject the diagram. [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) detects `<line>` elements and acute angles, flagging them as rule violations. Only `path` elements with proper arc commands (`A` or `a`) satisfy the checker.

### Can I use different corner radii for larger diagrams?

The minimum radius is **6 px**, but **8 px** is the standard. Larger radii are permitted if they maintain visual consistency. The verification script checks `rx` and `ry` values against these thresholds, not the absolute radius.

### How does the system handle complex node layouts where Rule 5 seems impossible?

When a connector must transit behind an intervening box due to topological constraints, apply the **dashed stroke exception**. Document this in the diagram description for accessibility. The validator accepts dashed `stroke-dasharray` values as intentional, verified exceptions.