# CLI Validation Scripts That Verify Diagram Quality and Geometry in Diagram-Design

> Discover CLI validation scripts in cathrynlavery/diagram-design that automatically verify diagram quality and geometry. Ensure clipping, animation, import, and consistency.

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

---

**The diagram-design repository includes eight Python CLI utilities in `scripts/verify-*.py` that automatically validate diagram assets for geometric clipping, animation timing, import integrity, and semantic consistency.**

This article examines the validation pipeline used in `cathrynlavery/diagram-design` to enforce quality standards. Each script parses HTML or source files and reports violations against the **SKILL.md** specification, providing automated quality gates for continuous integration workflows.

## The Core Geometry Validator: [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py)

The primary script for **diagram geometry validation** is [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py). It enforces **label-mask clearance** requirements from SKILL §6, ensuring labels remain readable and are not obscured by overlapping nodes.

### What It Detects

- **Label masks clipped by later-painted nodes** (minimum 6 px clearance required)
- **Improper paint ordering** that breaks visual hierarchy

### Implementation Details

The script parses `<rect>` elements and classifies them by size:

| Classification | Dimensions | Purpose |
|----------------|-----------|---------|
| **Nodes** | ≥ 60 × 40 px | Main diagram elements (zones, containers) |
| **Masks** | 20‑120 × 8‑14 px | Label backgrounds that must stay visible |

Core functions in [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py):

- `parse_rects()` — extracts and categorizes rectangle elements
- `overlap()` — computes geometric intersection between elements
- `contained()` — checks for fully-contained cases (badge exceptions)
- `check()` — orchestrates validation and reports violations

For every mask-node pair where the node appears later in the document source, the validator computes overlap. Non-trivial intersections are flagged unless the mask is fully contained (the badge case).

### Usage Examples

```bash

# Validate all shipped HTML assets

python3 scripts/verify-geometry.py --all

# Validate a single diagram file

python3 scripts/verify-geometry.py path/to/diagram.html

```

## Animation and Motion Validation

### [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py)

Validates **motion-related elements** against SKILL §7 timing constraints. The script scans SVG/HTML for `<animate>` tags and verifies:

- `begin` and `dur` values respect minimum gap requirements
- Motion definitions exist for all arrows flagged with `data-motion`

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

```

### [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py)

Performs **higher-level semantic checks** on animated diagrams. It cross-references motion definitions with node labels to ensure consistent expression of motion semantics (e.g., "request → response") across all assets.

```bash
python3 scripts/verify-semantic-motion.py --all

```

## Import Integrity Validators

### [`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-mermaid-import.py)

Ensures **Mermaid diagram definitions** are syntactically correct and render as expected. The script:

1. Runs the Mermaid CLI to render source files
2. Diff-compares output against stored baselines
3. Reports errors with line numbers from the original `.mmd` file

```bash
python3 scripts/verify-mermaid-import.py --all

```

### [`verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-drawio-import.py)

Validates **Draw.io (`.drawio`) file transformations** into HTML assets. It parses generated HTML for unexpected `<g>` groups and verifies the paint order hierarchy:

```

background → zones → arrows → labels → nodes

```

```bash
python3 scripts/verify-drawio-import.py --all

```

## Documentation and Package Validators

### [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py)

Confirms **documentation-diagram synchronization**. The script extracts image links from Markdown files ([`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md), skill documentation), verifies referenced HTML files exist, and optionally runs geometry checks on linked diagrams.

```bash
python3 scripts/verify-docs-sync.py

```

### [`verify-plugin-package.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-plugin-package.py)

Validates **plugin package integrity** through:

- JSON schema validation for [`package.json`](https://github.com/cathrynlavery/diagram-design/blob/main/package.json) and [`plugin.json`](https://github.com/cathrynlavery/diagram-design/blob/main/plugin.json)
- Version consistency checks
- Subset verification on bundled assets

```bash
python3 scripts/verify-plugin-package.py

```

## Domain-Specific Sequence Validation

### [`verify-sequence-oauth.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-sequence-oauth.py)

Specialized validator for **OAuth sequence diagrams**. It looks for specific node IDs (`client`, `auth-server`, `resource-server`) and validates their ordering and label placement against the prescribed token-exchange flow.

```bash
python3 scripts/verify-sequence-oauth.py

```

## Common CLI Interface and CI Integration

All validation scripts share a unified interface built on Python's **`argparse`** module:

| Flag | Behavior |
|------|----------|
| `--all` | Scan every asset under `skills/diagram-design/assets/` |
| *(path)* | Validate single file |

Output format: human-readable findings followed by a summary line.

### CI Pipeline Integration

```bash

# Run all validators in sequence, failing on first error

for script in scripts/verify-*.py; do
    $script --all || exit 1
done

```

The repository's [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) integrates these checks to guarantee every committed diagram honors **SKILL.md** visual and semantic standards.

## Complete Script Reference

| File | Validation Focus | GitHub Link |
|------|---------------|-------------|
| [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) | Label-mask clipping, paint ordering | [Source](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) |
| [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) | Animation timing, motion elements | [Source](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) |
| [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) | Semantic motion consistency | [Source](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) |
| [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) | Mermaid syntax and rendering | [Source](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) |
| [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) | Draw.io transformation integrity | [Source](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) |
| [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) | Documentation-asset synchronization | [Source](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) |
| [`scripts/verify-plugin-package.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-plugin-package.py) | Package schema and bundling | [Source](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-plugin-package.py) |
| [`scripts/verify-sequence-oauth.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sequence-oauth.py) | OAuth sequence flow correctness | [Source](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-sequence-oauth.py) |

## Summary

- **[`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py)** is the primary **CLI validation script for diagram geometry**, enforcing 6 px label-mask clearance through rectangle classification and overlap detection
- **Eight specialized validators** cover geometry, motion, imports, documentation sync, packaging, and domain-specific sequences
- **Unified `argparse` interface** with `--all` flag enables both single-file and batch validation
- **CI-ready exit codes** support automated quality gates in GitHub Actions workflows
- All validators reference the **SKILL.md** specification as the authoritative source of diagram quality rules

## Frequently Asked Questions

### How do I run all diagram validation checks at once?

Use a shell loop to execute every `verify-*.py` script with the `--all` flag. The scripts exit with non-zero status on failure, making them suitable for CI pipelines that fail fast on quality violations.

### What is the minimum label-mask clearance enforced by the geometry validator?

The [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py) script enforces **≥ 6 px clearance** between label masks and any nodes painted later in the document, as specified in SKILL §6. This prevents labels from being visually clipped or obscured.

### Can I validate a single diagram file instead of all assets?

Yes. Omit the `--all` flag and provide a file path: `python3 scripts/verify-geometry.py path/to/diagram.html`. This pattern works for all validation scripts in the repository.

### How does the Mermaid import validator detect rendering regressions?

[`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-mermaid-import.py) runs the Mermaid CLI to render source `.mmd` files, then performs a diff comparison against stored baseline outputs. Errors are reported with original line numbers to simplify debugging.