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

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 and automatically validated by 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. 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)
• 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 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 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	Authoritative rule documentation (section Mandatory connector rules)
scripts/verify-geometry.py	Automated validator run during pre-output checklist
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 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.

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