How Geometry Verification Prevents Overlapping Labels and Nodes in SVG Diagrams

Geometry verification prevents overlapping labels and nodes by parsing SVG rectangles, classifying them by size thresholds, respecting SVG paint order, and flagging any non-contained intersections where later-painted nodes would obscure label masks.

The cathrynlavery/diagram-design repository renders complex diagrams as static HTML files with embedded SVG. To ensure geometry verification catches visual defects before shipping, the repository includes scripts/verify-geometry.py, a dedicated auditor that scans every generated diagram for spatial contradictions between label masks and node elements.

Parsing SVG Rectangles from Generated Diagrams

The verification script begins by extracting every <rect> element from the diagram HTML. Using the regular expression RECT_RE defined at lines 42‑49, the parser scans the raw markup and instantiates lightweight Rect objects for each match.

Each Rect stores:

• Coordinates (x, y)
• Dimensions (width, height)
• Line number and file offset (to track declaration order)

This extraction phase creates a complete spatial index of every rectangular boundary in the diagram, enabling downstream collision detection.

Classifying Nodes and Label Masks by Geometry

Once extracted, rectangles are categorized based on dimensional heuristics that distinguish interactive nodes from text label masks.

Identifying Node Boundaries

Nodes are defined as substantial UI elements. The script classifies any rectangle measuring at least 60 × 40 pixels as a node, using the constants NODE_MIN_W and NODE_MIN_H defined at lines 51‑53. These thresholds filter out minor decorative elements while capturing the primary diagram blocks.

Detecting Label Masks

Label masks represent the semi-transparent backgrounds behind text labels. The script identifies these as rectangles with:

• Width between 20‑200 px (MASK_MIN_W to MASK_MAX_W)
• Height between 8‑14 px (MASK_MIN_H to MASK_MAX_H)

These specific ranges, implemented at lines 54‑56, distinguish text backgrounds from larger node containers.

Respecting SVG Paint Order Constraints

SVG renders elements in document order, meaning later declarations paint on top of earlier ones. The verification script respects this stacking context by comparing file offsets.

At lines 24‑25, the logic checks whether a node's offset is greater than a mask's offset. When true, the node is considered painted after (and therefore visually above) the label mask. This paint-order awareness prevents false positives where a label intentionally overlays a node.

Detecting and Reporting Spatial Conflicts

The core verification logic computes geometric relationships between every mask-node pair where the node renders later.

Calculating Overlap Dimensions

The overlap helper function (lines 95‑99) computes the horizontal (dx) and vertical (dy) intersection dimensions between a mask and a node. If both values are positive, the rectangles collide in 2D space.

Handling Permitted Containment

The contained helper (lines 102‑108) checks whether a mask lies completely inside a node boundary. This condition is explicitly allowed for badge-like chips that intentionally sit within nodes, filtering out valid design patterns before flagging errors.

Flagging Violations

For every mask-node collision where the node paints later, the script applies two exclusion filters at lines 27‑34:

1. Trivial overlaps (dx ≤ 1 px or dy ≤ 1 px) are ignored as sub-pixel artifacts
2. Fully-contained masks are skipped (handled by the containment check)

Remaining violations generate findings specifying the exact overlap size and a remediation suggestion: "move the label onto a free segment of its connector".

Running Geometry Verification

Users execute the verifier against specific diagrams or the entire asset library.

Check a single diagram:

python3 scripts/verify-geometry.py skills/diagram-design/assets/example-wardley.html

Validate all shipped assets:

python3 scripts/verify-geometry.py --all

At lines 61‑64, the script prints each violation and a summary count of files inspected:

$ python3 scripts/verify-geometry.py --all
example-wardley.html:12: label mask (120,30 30x10) is clipped by node (90,20 80x50) declared later at line 35 (overlap 30x20px) - move the label onto a free segment of its connector
Summary: 20 file(s) checked, 1 finding(s).

For CI integration, import the verification logic programmatically:

from pathlib import Path
from scripts.verify_geometry import check

failures = check(Path("skills/diagram-design/assets/example-wardley.html"))
assert not failures, f"Geometry errors: {failures}"

Summary

• The verification script parses all <rect> elements in generated HTML diagrams using the regex pattern RECT_RE to build a spatial index of every rectangle.
• Rectangles are classified as nodes (≥60×40px) or label masks (20‑200px wide, 8‑14px tall) using dimensional thresholds defined in scripts/verify-geometry.py.
• The script respects SVG paint order by comparing element offsets to determine which rectangles render visually on top of others.
• The overlap helper calculates intersection dimensions while the contained helper permits badge-like masks to reside fully inside nodes without triggering violations.
• Trivial overlaps (≤1px) and fully-contained masks are filtered out; remaining collisions generate explicit error messages suggesting repositioning labels onto free connector segments.

Frequently Asked Questions

What file contains the geometry verification implementation?

The core logic resides in scripts/verify-geometry.py. This script defines the RECT_RE regex, Rect class, dimensional thresholds (NODE_MIN_W, MASK_MAX_H, etc.), and the overlap/contained helper functions that perform spatial analysis.

How does the script distinguish between a node and a label mask?

The script applies strict dimensional heuristics. Any rectangle at least 60 × 40 pixels is classified as a node (lines 51‑53), while rectangles between 20‑200 px wide and 8‑14 px tall are classified as label masks (lines 54‑56). These size ranges separate large interactive blocks from text backgrounds.

Why does the verification logic check SVG paint order?

Because SVG renders elements sequentially, a node declared later in the file will visually obscure earlier elements. The script compares file offsets at lines 24‑25 to determine which element paints on top. Only collisions where the node paints after the label mask are flagged as errors, since these represent cases where text would be clipped by overlapping nodes.

Can geometry verification be automated in CI pipelines?

Yes. The script exposes a check() function that accepts a pathlib.Path object and returns a list of failures. You can import from scripts.verify_geometry import check in Python test suites or CI steps to assert that no geometry errors exist before deployment, as shown in the programmatic usage example above.

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