# How Label Placement Geometric Verification Prevents Clipping in Diagrams > Learn how label placement geometric verification prevents clipping in diagrams by analyzing SVG paint order to ensure label masks don't overlap nodes. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-09-11 --- **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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.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:* ```bash python3 scripts/verify-geometry.py skills/diagram-design/assets/example-x.html ``` *Verify all shipped assets:* ```bash 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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/test-verify-geometry.py) validates the checker using adversarial cases: ```python def test_clipped_mask(): html = ''' ''' 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.