# How to Verify the Output of an Installed Diagram-Design Agent

> Verify your diagram-design agent output using self_check.py. Ensure HTML diagrams meet accessibility, structural, and motion-safety standards. Run the script now for validation.

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

---

**Run `python3 skills/diagram-design/scripts/self_check.py <path-to-diagram.html>` to validate that any generated HTML diagram meets accessibility, structural, and motion-safety requirements.**

The **diagram-design** skill from the `cathrynlavery/diagram-design` repository generates self-contained HTML files embedding SVG diagrams with optional motion controllers. After installation, you need reliable ways to confirm that an agent's output complies with the project's strict design system contracts. This guide shows you the exact verification workflow used in production CI.

## Run the Built-In Self-Check Script

The fastest way to verify diagram-design agent output is the [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script located at [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py). This tool performs the same validations that run on every pull request.

Execute it against any generated diagram:

```bash
python3 skills/diagram-design/scripts/self_check.py diagram.html

```

The script returns `OK` on success or a detailed error message on failure. It parses the HTML, extracts the primary `<svg>` element, and validates:

- **Accessibility attributes**: `role="img"`, resolvable `aria-labelledby` references, presence of `<title>` and `<desc>` elements with valid IDs
- **ID uniqueness**: No duplicate identifiers across the document
- **Motion controller compliance**: Any animation script must match the approved contract from [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md)

## What the Self-Check Validates

The verification rules in [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) mirror the repository's linting pipeline enforced by [`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-skin.py). Understanding these checks helps you interpret failures and fix source documents.

### Accessibility Requirements

Every diagram-design output must include:

- A `<title>` element with a unique ID referenced by `aria-labelledby`
- A `<desc>` element providing extended description
- Proper `role="img"` declaration on the SVG container
- Zero duplicate ID attributes anywhere in the document

These requirements ensure screen readers and assistive technologies can navigate generated diagrams correctly.

### Motion Safety Guarantees

If motion is enabled, the controller must be the **exact, reviewed script** specified in [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md). The self-check rejects:

- Remote asset references
- Inline event handlers
- Arbitrary CSS imports

This security model prevents arbitrary code execution from untrusted diagram sources.

### Structural Integrity Checks

The validator confirms:

- Well-formed SVG markup
- Existence of all referenced icon assets
- Presence of three variant tabs in the HTML wrapper: **light**, **dark**, and **full-editorial**

## Optional Extended Validation Scripts

For CI debugging or pre-release verification, run the broader linting suite that ships with `cathrynlavery/diagram-design`:

```bash

# Render all examples and detect visual regressions

python3 scripts/lint-render.py --all

# Confirm documentation consistency with generated assets

python3 scripts/verify-docs-sync.py

# Validate geometric constraints for label placement

python3 scripts/verify-geometry.py --all

```

| Script | Purpose |
|--------|---------|
| [`scripts/lint-render.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-render.py) | Headless Chromium rendering to catch overflow, clipping, and missing assets |
| [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) | Ensures gallery, documentation, and type references stay synchronized |
| [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) | Validates label positioning and area-encoding diagram constraints |

## Complete Verification Workflow

Follow this three-step process after any agent-generated diagram:

```bash

# 1. Generate a diagram through your agent host

/diagram-design:make-architecture diagram.html

# 2. Verify the output locally

python3 skills/diagram-design/scripts/self_check.py diagram.html

# → "OK" indicates full compliance

# 3. Optional: run full lint suite for production releases

python3 scripts/lint-render.py --all
python3 scripts/verify-docs-sync.py
python3 scripts/verify-geometry.py --all

```

Fix any reported errors—such as `duplicate ID "title-1"`, `missing <desc>`, or `unauthorized motion script`—then re-run [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) until it reports `OK`.

## Summary

- **Primary verification**: Run [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) against any generated HTML file
- **Validation coverage**: Accessibility attributes, ID uniqueness, motion-safety contracts, and structural integrity
- **CI parity**: The self-check enforces identical rules to [`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-skin.py) used in pull request automation
- **Extended checks**: Use [`lint-render.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-render.py), [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py), and [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py) for comprehensive pre-release validation
- **Source of truth**: Contract definitions reside in [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md)

## Frequently Asked Questions

### What should I do if the self-check reports a duplicate ID error?

Locate the conflicting identifier in your source HTML, rename one instance to ensure uniqueness, and re-run [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py). Duplicate IDs break accessibility references and must be resolved before the diagram passes validation.

### Does the verification work for diagrams with motion enabled?

Yes. The self-check actively validates motion-enabled diagrams against the approved controller specification in [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md). Any deviation—including remote scripts or inline handlers—triggers a clear failure message.

### Can I integrate these checks into my own CI pipeline?

Absolutely. The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script returns exit code 0 on success and non-zero on failure, making it compatible with GitHub Actions, GitLab CI, or any automated testing framework. The broader linting suite in `scripts/` provides additional coverage for release gates.

### Where are the motion controller specifications documented?

The complete motion contract lives at [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) in the repository. This file defines the exact script hash, allowed APIs, and security constraints that [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) enforces.