What Is the Purpose of Label Geometry Verification in Diagram-Design?

Diagram-Design verifies label geometry to prevent rendering defects where node fills clip arrow labels, ensuring all diagrams remain readable, accessible, and visually consistent.

The cathrynlavery/diagram-design repository enforces strict visual rules for its SVG-like diagram assets. One critical rule—defined in SKILL §6, rule 6—prohibits label masks from overlapping nodes drawn after them. The label geometry verification system automates this enforcement, catching layout errors before they reach production.

Why Label Geometry Verification Exists

Generated diagrams in this repository use layered rendering: connectors and labels draw first, then nodes fill on top. When a label's opaque mask rectangle (the small background behind text) intersects a later-drawn node, the node's fill obscures part of the label. This produces clipped, unreadable text—a rendering defect, not a stylistic choice.

The verification system prevents this by:

• Parsing HTML assets to extract all <rect> elements
• Classifying rectangles as nodes (≥ 60 × 40 px) or label masks (20–120 × 8–14 px)
• Checking paint order to detect illegal overlaps

How the Verification Logic Works

The scripts/verify-geometry.py script implements the core check. For each label mask, it validates that any later-drawn node either:

• Does not overlap the mask at all, or
• Fully contains the mask (the legal "badge chip" case)

When neither condition holds, the script reports a finding with precise coordinates and remediation guidance:

example.html:27: label mask (145,80 30x10) is clipped by node (120,70 80x40) declared later at line 35 (overlap 5x3px) - move the label onto a free segment of its connector

This output identifies the exact file, line numbers, rectangle dimensions, and overlap size—enabling rapid fixes.

Running the Label Geometry Verification

Verify a Single Diagram

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

Verify All Shipped Assets

python3 scripts/verify-geometry.py --all

This command runs automatically in CI via .github/workflows/ci.yml, blocking merges that introduce overlapping masks.

Sample Output

example-x.html:42: label mask (88,120 24x10) is clipped by node (80,115 80x40) declared later at line 58 (overlap 4x5px) - move the label onto a free segment of its connector
Summary: 1 file(s) checked, 1 finding(s).

Programmatic Use

from pathlib import Path
from scripts.verify_geometry import check

findings = check(Path("skills/diagram-design/assets/example-x.html"))
if findings:
    for f in findings:
        print(f)
else:
    print("No geometry issues found.")

Guarantees Provided by Verification

According to the cathrynlavery/diagram-design source code, label geometry verification ensures three outcomes:

• All arrow labels remain legible — The 6–10 px gap between mask and connector stays intact
• No node fill obscures label text — Upholding the accessible-SVG contract
• Diagram aesthetics stay consistent — Preventing hidden defects that only surface after rendering

Key Implementation Files

File	Purpose
scripts/verify-geometry.py	Core verification engine; parses <rect> elements and reports violations
skills/diagram-design/SKILL.md	Defines SKILL §6 rule 6 that the verifier enforces
docs/adr/0005-label-geometry-is-verified.md	Architectural decision record explaining why verification was adopted
.github/workflows/ci.yml	CI pipeline executing verify-geometry.py --all on every push

Summary

• Label geometry verification prevents a specific rendering defect: node fills clipping arrow label text
• The scripts/verify-geometry.py script parses SVG-like HTML, classifies rectangles, and checks paint order
• Violations trigger precise, actionable findings with file paths, line numbers, and remediation steps
• CI automation via .github/workflows/ci.yml enforces the rule on every contribution
• The system upholds readability, accessibility, and visual consistency across all diagram variants

Frequently Asked Questions

What happens if a label mask overlaps a node in diagram-design?

The verify-geometry.py script flags the conflict as a finding, halting CI until fixed. The label text would render as partially covered by the node's fill, making it unreadable.

How does the verifier distinguish nodes from label masks?

It uses size thresholds defined in the source: nodes measure at least 60 × 40 pixels, while label masks fall within 20–120 × 8–14 pixels. These dimensions reflect the repository's standardized visual system.

Can I run the geometry check without using CI?

Yes. Run python3 scripts/verify-geometry.py --all locally, or check individual files by passing their path. You can also import check() from scripts.verify_geometry for programmatic validation.

Why does the "badge chip" case allow full containment?

When a node fully contains a label mask, the label renders as an intentional overlay—readable and stylistically controlled. Partial overlaps create unpredictable clipping, which the verifier rejects.

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