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

> Learn how diagram-design label geometry verification prevents rendering defects, keeping your diagrams readable, accessible, and consistent. Avoid clipped arrow labels.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-14

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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

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

```

### Verify All Shipped Assets

```bash
python3 scripts/verify-geometry.py --all

```

This command runs automatically in CI via [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml), blocking merges that introduce overlapping masks.

### Sample Output

```text
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

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) | Core verification engine; parses `<rect>` elements and reports violations |
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Defines SKILL §6 rule 6 that the verifier enforces |
| [`docs/adr/0005-label-geometry-is-verified.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0005-label-geometry-is-verified.md) | Architectural decision record explaining why verification was adopted |
| [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.