What Are the Six Mandatory Connector Rules in Diagram Design?

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.

Diagram Design is an open-source diagramming system governed by a strict connector grammar specified in 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 §6, these rules apply universally across all diagram types. The 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 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 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 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 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 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 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 script automates validation against these rules. It is complemented by type-specific verifiers such as verify-dumbbell.py and 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.

The 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 script aborts diagram generation immediately. The pre-output checklist defined in 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 §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 and verify-waterfall.py provide specialized validations, they all inherit and enforce the same six mandatory connector rules defined in SKILL.md §6 across every diagram type.

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