How Label Placement Geometric Verification Prevents Clipping in Diagrams

Label placement geometric verification prevents visual clipping by analyzing SVG paint order to guarantee that label masks never overlap nodes rendered later in the document.

Diagram readability depends on text remaining unobscured by overlapping node fills. In the cathrynlavery/diagram-design repository, label placement geometric verification automatically enforces design rules that ensure every label mask remains fully visible by detecting spatial conflicts where later-drawn nodes would clip earlier labels.

Parsing and Classifying SVG Geometry

The verification pipeline begins in scripts/verify-geometry.py by extracting geometric primitives from SVG source files and categorizing them by function.

Extracting Rectangle Data

The script scans raw SVG markup using the RECT_RE regular expression defined on lines 42-48. Each match is processed by the parse_rects function (lines 79-92), which instantiates lightweight Rect objects recording the rectangle’s x-coordinate, y-coordinate, width, height, and source line offset. This offset value is critical because it represents the SVG paint order—elements appearing later in the file render on top of earlier elements.

Distinguishing Nodes from Label Masks

After extraction, the classifier applies dimensional heuristics to separate structural elements from label backgrounds:

• Nodes are identified as rectangles meeting minimum thresholds of 60×40 pixels, enforced by the constants NODE_MIN_W and NODE_MIN_H on lines 51-52.
• Label masks are rectangles falling within protective ranges: 20-200 pixels wide and 8-14 pixels high, bounded by MASK_MIN_W, MASK_MAX_W, MASK_MIN_H, and MASK_MAX_H on lines 53-56.

This classification allows the verifier to apply different geometric rules to drawing primitives versus text-protection zones.

Detecting Paint-Order Violations

The check function (lines 22-34) implements the core clipping prevention logic. For each label mask, the algorithm iterates through all nodes appearing later in the source file (node.offset > mask.offset), because these nodes render on top and could visually obscure the label.

The geometric test uses two helper functions:

• overlap (lines 95-99): Calculates the intersecting width and height between the mask and node bounding boxes.
• contained (lines 102-108): Determines whether the mask rectangle sits entirely within the node boundaries.

A violation is emitted when the overlap in both dimensions exceeds 1 pixel and the mask is not fully contained within the node. This captures the exact scenario prohibited by SKILL.md rule 6:

"A label mask must not overlap a node drawn after it… because the node fill would clip the label at render time."

When detected, the script outputs a specific diagnostic including line numbers and overlap dimensions, forcing contributors to relocate the label onto a free connector segment with the required 6-10 pixel margin from node edges.

Continuous Integration Enforcement

The geometric verification runs automatically via .github/workflows/ci.yml, which executes python scripts/verify-geometry.py --all on every push and pull request. By failing the build immediately upon detecting clipping violations, the CI pipeline guarantees that no diagram assets with overlapping label masks can merge into the main branch.

This automated enforcement maintains the invariant that no label mask is ever partially covered by a node fill, eliminating visual clipping at render time across all generated diagrams.

Running the Verification Locally

Developers can run the verifier against single files or the entire asset library:

Verify a specific diagram:

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

Verify all shipped assets:

python3 scripts/verify-geometry.py --all

Typical failure output:

example-x.html:73: label mask (150,30 40x12) is clipped by node (120,20 80x40) declared later at line 78 (overlap 30x12px) - move the label onto a free segment of its connector

Fixing violations requires positioning the mask so its x coordinate starts after the node’s right edge plus margin. If a node ends at 200 px, place the mask at ≥ 206 px to maintain the required gap.

The test suite in scripts/test-verify-geometry.py validates the checker using adversarial cases:

def test_clipped_mask():
    html = '''
    <svg>
      <rect x="10" y="10" width="80" height="40"/>          <!-- node -->
      <rect x="50" y="20" width="40" height="12"/>          <!-- label mask (overlaps node) -->
    </svg>'''
    path = ROOT / "tmp.html"
    path.write_text(html)
    assert verify_geometry.check(path)  # non-empty findings → failure

Summary

• Label placement geometric verification parses SVG rectangles using RECT_RE and classifies them as nodes or masks based on dimensional constants in scripts/verify-geometry.py.
• The check function respects paint order by comparing each mask only against nodes with higher line offsets, identifying overlaps that would cause visual clipping.
• Violations trigger CI failures via .github/workflows/ci.yml, preventing merges that would result in obscured labels.
• The system enforces SKILL.md rule 6, requiring label masks to avoid overlapping later-drawn nodes and maintain 6-10 pixel margins.

Frequently Asked Questions

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

The script applies strict dimensional thresholds defined at the top of verify-geometry.py. Rectangles measuring at least 60×40 pixels are classified as nodes, while rectangles between 20-200 pixels wide and 8-14 pixels high are classified as label masks. This size-based heuristic allows the algorithm to apply clipping logic only to text protection zones rather than structural diagram elements.

What specific geometric condition triggers a clipping violation?

The verifier flags a violation when three conditions are met: the mask and node overlap by more than 1 pixel in both dimensions, the node appears later in the SVG source (indicating it renders on top), and the mask is not fully contained within the node's boundaries. The overlap helper calculates intersection dimensions while contained checks for total enclosure, ensuring only problematic partial overlaps fail the check.

Why does the verification rely on source file line order rather than z-index attributes?

According to the SVG specification and the implementation in parse_rects, elements are rendered in document order unless explicit z-index values are present. The diagram-design repository relies on this default paint order, using the offset attribute captured during parsing to determine stacking context. This approach matches the rendering engine's behavior without requiring complex CSS parsing, ensuring that any node declared after a label mask in the source will indeed paint over it.

Can the verification script fix clipping errors automatically?

No, the script operates as a diagnostic tool only. When verify-geometry.py detects a violation, it outputs the specific file, line numbers, and overlap dimensions, then exits with a failure code. Contributors must manually adjust the mask coordinates—typically by moving the label to a clear segment of its connector with the required 6-10 pixel buffer from node edges—to resolve the error and pass CI validation.

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