Mandatory Connector Rules for Diagram Boxes: 6 SVG Layout Constraints Explained

All diagram boxes in the Diagram-Design skill must obey six mandatory connector rules defined in SKILL.md §6, covering orthogonal elbows, z-order layering, crossing bridges, fanned attach points, masked labels, and visible routing.

The cathrynlavery/diagram-design repository enforces a strict visual grammar for SVG diagrams through mandatory connector rules for diagram boxes that apply universally across every diagram type. These constraints are codified in skills/diagram-design/SKILL.md section 6 and reinforced by type-specific reference files and automated validation scripts. Following them ensures connectors render cleanly without overlapping, hidden segments, or illegible labels.

The Six Connector Rules from SKILL.md §6

1. Orthogonal Rounded Elbows

All non-horizontal or non-vertical connections must use a right-angle elbow with a corner radius of 8 px. Straight diagonal lines are prohibited everywhere except the single exemption documented for fishbone diagrams in skills/diagram-design/references/type-fishbone.md.

According to skills/diagram-design/references/type-architecture.md, rounded right-angle orthogonal connectors are mandatory for all non-axis-aligned connections and must implement a two-bend elbow path with r=8.

<!-- Architecture diagram with orthogonal elbow -->
<path d="M120 80 H200 a8 8 0 0 1 8 8 V300" stroke="var(--ink)" fill="none"/>

2. Z-Order: Connectors Before Boxes

Connectors are emitted before any node <rect> in the SVG source order. This layering guarantees that node fills mask the line ends and prevents stray line tips from showing outside the box boundaries.

skills/diagram-design/references/type-dependency.md explicitly confirms that connectors are drawn before boxes as part of the full §6 rule set.

<!-- Connector rendered first -->
<path d="..." class="connector"/>
<!-- Node rectangle rendered later -->
<rect x="200" y="300" width="120" height="80" class="node"/>

3. Bridge or Hop at Crossings

When two connectors intersect, the crossing must be rendered as a small bridge (or hop) so the lines remain visually separate. This avoids the ambiguity of overlapping strokes that could be mistaken for a single continuous path.

The bridge is typically implemented by overlaying a small shape at the intersection point to simulate a gap in the underlying line.

<!-- Two crossing connectors with a bridge -->
<path d="M100 100 H180 V200 H260" class="connector"/>
<path d="M260 100 H180 V200 H100" class="connector"/>
<rect x="178" y="198" width="4" height="4" fill="var(--paper)"/>

4. Fanned Attach Points

If several edges share the same side of a box, their attachment points must be spaced ≥ 12 px apart in a fan-out pattern. This spacing prevents overlapping entry points that would clutter the diagram and obscure individual connections.

The following example shows three connectors with 20 px vertical spacing, satisfying the minimum separation requirement.

<!-- Three connectors sharing the left edge of a box -->
<line x1="80" y1="120" x2="120" y2="120" class="connector"/>
<line x1="80" y1="140" x2="120" y2="140" class="connector"/>
<line x1="80" y1="160" x2="120" y2="160" class="connector"/>
<!-- 20 px spacing ► ≥ 12 px rule satisfied -->

5. Masked Labels with Gap

Connector labels must sit on an opaque mask (a paper-fill rectangle) and maintain a 6 – 10 px clearance from the stroke. This gap ensures the text never bleeds through the underlying connector line.

The mask rectangle should use fill="var(--paper)" and stroke="none" so it blends seamlessly with the diagram background.

<g class="connector-label">
  <rect x="130" y="118" width="36" height="14"
        fill="var(--paper)" stroke="none"/>
  <text x="148" y="130" class="arrow-label">API</text>
</g>

6. No Hidden Routing

Connectors may not pass behind a non-endpoint box. Every segment must remain fully visible, which means routes must travel around nodes rather than sliding underneath them.

This rule preserves the readability of complex diagrams by ensuring that every connection path can be traced at a glance.

<!-- Connector route stays outside the box -->
<path d="M120 80 H200 V300 H280" class="connector"/>
<rect x="200" y="260" width="80" height="80" class="node"/>

Validation and CI Enforcement

Compliance with these mandatory connector rules for diagram boxes is not optional. The skills/diagram-design/scripts/verify-geometry.py script runs during continuous integration to validate that every generated diagram obeys the six rules.

Additionally, reference files such as skills/diagram-design/references/type-dependency.md, skills/diagram-design/references/type-process.md, and skills/diagram-design/references/type-org-chart.md repeatedly echo these constraints, confirming they are global requirements across all diagram types. Only skills/diagram-design/references/type-fishbone.md documents a limited exemption for diagonal bones, while all other connectors in that type still follow the full §6 set.

Summary

• Orthogonal rounded elbows with an 8 px radius are required for every non-axis-aligned connection; diagonals are prohibited.
• Z-order must place connectors before node rectangles so box fills mask line ends.
• Crossings must render a bridge or hop to keep intersecting lines visually distinct.
• Fanned attach points sharing a box side must remain spaced ≥ 12 px apart.
• Masked labels need an opaque paper-fill background and 6 – 10 px of clearance from the stroke.
• No hidden routing allows connectors to pass only through empty space, never behind unrelated boxes.
• The rules are enforced by skills/diagram-design/SKILL.md §6 and validated by verify-geometry.py.

Frequently Asked Questions

Are the mandatory connector rules for diagram boxes the same for every diagram type?

Yes. According to skills/diagram-design/references/type-dependency.md, all six §6 mandatory connector rules apply in full across every diagram type in the repository. The only documented exception appears in skills/diagram-design/references/type-fishbone.md, which permits diagonal bones, but all other connectors in fishbone diagrams must still follow the standard rules.

What happens if a connector uses a straight diagonal instead of an orthogonal elbow?

The diagram will fail validation. skills/diagram-design/references/type-architecture.md states that rounded right-angle orthogonal connectors are mandatory for all non-horizontal or non-vertical connections, and skills/diagram-design/scripts/verify-geometry.py will reject any straight diagonal routing.

How does the z-order rule prevent visual defects?

By emitting connector <path> elements before any node <rect>, the node fill paints over the line terminus. This masking eliminates stray anti-aliased line tips that would otherwise protrude slightly past the box border, producing a cleaner, pixel-precise edge.

What is the minimum spacing required for multiple connectors on the same box side?

Multiple connectors that attach to the same side of a box must use fanned attach points spaced ≥ 12 px apart. This minimum separation prevents overlapping strokes and keeps each entry point visually distinct.

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