How to Debug Label Placement Issues Using the Geometry Verification Tool in diagram-design

The geometry verification tool (verify-geometry.py) detects when label masks overlap with nodes that appear later in the SVG paint order, causing labels to be visually clipped by node fills.

The cathrynlavery/diagram-design repository includes a dedicated geometry checker that analyzes SVG output to prevent labels from being obscured by overlapping nodes. By parsing rectangle elements and comparing their paint order, the tool identifies exactly which label placements will render incorrectly before they reach production.

How the Geometry Verification Tool Detects Clipping

The verification script located at scripts/verify-geometry.py implements a multi-stage analysis pipeline to identify geometric conflicts between labels and nodes.

Rectangle Classification Logic

The tool first extracts all <rect> elements from diagram HTML files using the RECT_RE regular expression defined at lines 42–49. It then categorizes each rectangle based on dimensional heuristics:

• Nodes: Rectangles with width ≥ 60px and height ≥ 40px (NODE_MIN_W, NODE_MIN_H at lines 51–53)
• Label masks: Rectangles with width between 20–200px and height between 8–14px (MASK_MIN_W, MASK_MAX_W, MASK_MIN_H, MASK_MAX_H at lines 53–56)

Paint Order Analysis

Each Rect object stores the file offset of its opening tag in the offset attribute (lines 24–26). The tool uses this to determine paint order: if a node appears later in the file (node.offset > mask.offset), it will be painted on top of the label mask, potentially clipping it. This temporal sequencing check is critical because SVG renders elements in document order.

Overlap and Containment Filtering

Before reporting an error, the tool performs two geometric checks at lines 95–108:

1. Overlap calculation: Computes the intersecting area between mask and node rectangles
2. Containment check: Uses the contained() function to determine if the mask lies entirely within the node (indicating a badge like EXT, EDGE, or ORIG)

Masks that are fully contained are considered intentional badges and are excluded from error reports. Additionally, tiny overlaps where dx <= 1.0 or dy <= 1.0 are ignored as visually negligible (lines 26–28).

Step-by-Step Debugging Workflow

Follow this systematic approach to identify and resolve label clipping issues:

1. Run the checker Execute python3 scripts/verify-geometry.py --all to scan every asset, or target a specific file to isolate problems.

2. Parse the output Locate lines matching the pattern:

filename.html:42: label mask (120,30 30x10) is clipped by node (120,20 80x50) declared later at line 55 (overlap 6x12px)

This reveals the exact coordinates, dimensions, and paint order conflict.

3. Inspect the source HTML Open the indicated file and navigate to the reported line numbers to examine the actual <rect> elements.

4. Verify the conflict Confirm that the label mask rectangle overlaps spatially with the node rectangle that appears later in the document.

5. Apply the fix Choose one of three resolution strategies:

• Reorder elements: Move the node definition before the label mask in the HTML so the label paints on top
• Relocate the label: Shift the mask coordinates to a free segment of the connector
• Resize the mask: Adjust dimensions within the 20–200px width and 8–14px height constraints

6. Validate the fix Re-run the verification tool to ensure zero findings before committing.

Running the Verification Tool

Command Line Usage

Check all diagrams in the repository:

python3 scripts/verify-geometry.py --all

Check a single diagram file:

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

Interpreting Output

Typical error output looks like this:

example-x.html:42: label mask (124,28 30x10) is clipped by node (120,20 80x50) declared later at line 55 (overlap 6x12px) - move the label onto a free segment of its connector
Summary: 1 file(s) checked, 1 finding(s).

The line number points to the <rect> tag position, while the coordinates indicate the exact pixel overlap causing the visual glitch.

Resolving Clipping Errors

Reordering SVG Elements

The most reliable fix involves ensuring the node appears before the label in document order:

<!-- Fixed paint order: node first, then label -->
<rect x="120" y="20" width="80" height="50" class="node"/>
<rect x="124" y="28" width="30" height="10" class="label-mask"/>

Relocating Label Masks

Move the mask to a coordinate space free from node overlap:

<rect x="200" y="80" width="30" height="10" class="label-mask"/>

Adjusting Mask Dimensions

Ensure mask dimensions remain within the valid ranges detected by the tool:

• Width: 20px to 200px
• Height: 8px to 14px

Programmatic API Access

Integrate the checker into custom workflows by importing the check function:

from pathlib import Path
from scripts.verify_geometry import check

findings = check(Path("skills/diagram-design/assets/example-x.html"))
for finding in findings:
    print(finding)  # prints each clipping warning with line numbers

Summary

• Geometry verification happens in scripts/verify-geometry.py using dimensional heuristics (NODE_MIN_W, MASK_MAX_H) to distinguish nodes from labels
• Paint order matters: The tool compares Rect.offset values to detect when a node declared later in the file will clip an earlier label mask
• Overlap thresholds: Tiny overlaps under 1.0px are ignored, and fully contained masks are treated as intentional badges
• Fixing issues: Reorder SVG elements so labels paint after nodes, relocate masks to free coordinates, or adjust mask dimensions within the 20–200px × 8–14px constraints

Frequently Asked Questions

What causes label masks to be clipped by nodes?

Label masks get clipped when they spatially overlap with a node that appears later in the SVG document order. Since SVG renders elements sequentially, later nodes paint on top of earlier labels. The verify-geometry.py script detects this by comparing the offset attribute of each Rect object to determine paint sequence.

Why are some overlapping rectangles not reported as errors?

The tool filters out fully contained masks (treating them as badges like EXT, EDGE, or ORIG) using the contained() function at lines 102–108. It also ignores microscopic overlaps where dx <= 1.0 or dy <= 1.0 pixels because these are visually imperceptible in the final render.

How does paint order affect label visibility?

SVG uses document order as the default paint order. Elements defined later appear visually "on top" of earlier elements. The tool specifically checks node.offset > mask.offset to identify cases where a node will obscure a label, regardless of z-index or CSS stacking contexts.

Can I use the geometry verification tool in CI/CD pipelines?

Yes. The script returns a non-zero exit code when findings are detected, making it suitable for pre-commit hooks or continuous integration. Run python3 scripts/verify-geometry.py --all as a build step to ensure all diagram assets pass geometry validation before deployment.

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