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

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 script located at 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:

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

What the Self-Check Validates

The verification rules in self_check.py mirror the repository's linting pipeline enforced by 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. 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:

# 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	Headless Chromium rendering to catch overflow, clipping, and missing assets
scripts/verify-docs-sync.py	Ensures gallery, documentation, and type references stay synchronized
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:

# 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 until it reports OK.

Summary

• Primary verification: Run 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 used in pull request automation
• Extended checks: Use lint-render.py, verify-docs-sync.py, and verify-geometry.py for comprehensive pre-release validation
• Source of truth: Contract definitions reside in 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. 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. 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 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 in the repository. This file defines the exact script hash, allowed APIs, and security constraints that self_check.py enforces.

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