How to Run self_check.py on Agent-Generated Diagram Output

Run python3 skills/diagram-design/scripts/self_check.py path/to/diagram.html to validate that agent-generated HTML diagrams meet the repository's safety, accessibility, and motion-design contracts without installing any third-party dependencies.

The diagram-design skill in the cathrynlavery/diagram-design repository provides a lightweight validator located at skills/diagram-design/scripts/self_check.py. Running this script on agent-generated diagram output ensures your files comply with strict HTML, SVG, and motion standards before publication.

The Three-Stage Validation Architecture

The validator processes each diagram through a strict pipeline implemented in self_check.py. It uses only Python standard library modules, making it ideal for CI environments.

Stage 1: Parsing HTML with DiagramParser

At the core of the validator is the DiagramParser class (defined at lines 34-55 in self_check.py), a custom subclass of HTMLParser. This parser walks the entire HTML document and collects:

• Unsafe tags such as <embed> or other prohibited elements
• References to external stylesheets and remote resources
• SVG metadata including depth tracking and element hierarchy
• Script blocks for subsequent security analysis
• Motion-related data attributes like data-motion-root and data-motion-item

The parser also extracts text content from <title> and <desc> elements to verify accessibility requirements later in the pipeline.

Stage 2: Running Safety and Accessibility Checks

After parsing, the script executes three specialized validation functions that append violations to a centralized errors list.

check_svgs (lines 14-45) validates that each SVG element carries role="img", contains proper <title> and <desc> child elements, and maintains correct ARIA linking between these elements.

check_scripts (lines 47-62) enforces that at most one <script> tag exists in the document, verifies it carries only the canonical data-diagram-controls attribute, and confirms its body matches the bundled motion controller found in template-motion.html.

check_motion (starting at line 69) validates the accessible-SVG contract and motion contract. This includes verifying correct data-motion-mode values, ensuring step counts match declared items, validating playback controls exist, confirming reduced-motion and print fallbacks are present, and checking for a <noscript> explanation of the complete static frame.

Stage 3: Reporting Results

The top-level verify function (lines 53-66) orchestrates the validation by reading the file, running the parser, and executing all check functions. It returns a list of error strings describing specific violations.

The main entry point (lines 68-85) provides the command-line interface. It iterates over filenames provided as arguments, calling verify for each. When a diagram passes all checks, it prints OK <path>. When violations occur, it prints FAIL <path> followed by each specific error and exits with status code 1.

Running the Validator on Generated Diagrams

Because self_check.py has no external dependencies, you can execute it directly with any standard Python 3 interpreter.

Validate a single diagram:

python3 skills/diagram-design/scripts/self_check.py path/to/my-diagram.html

Process multiple files in a batch:

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

Integrate into a CI pipeline using the exit code:

#!/usr/bin/env bash
set -e
python3 skills/diagram-design/scripts/self_check.py generated/*.html
echo "All diagrams passed validation"

If any diagram fails validation, the script exits with status 1, automatically failing the CI job.

Interpreting Validation Output

The validator produces machine-readable output that identifies specific contract violations.

A successful validation appears as:

OK path/to/my-diagram.html

Failed validations show detailed error messages:

FAIL path/to/bad-diagram.html
  - <embed> is not allowed in a diagram file
  - svg 1 needs role=img
  - remote stylesheet is not the approved Google Fonts /css2 URL: https://evil.com/style.css
  - motion file needs a <noscript> explanation of the complete static frame

Common failures include:

• Unsafe tags: Elements like <embed> that violate the HTML sanitization policy
• Missing ARIA roles: SVG elements lacking role="img"
• Unauthorized remote resources: Stylesheets not matching the approved Google Fonts /css2 URL pattern
• Motion contract violations: Missing <noscript> blocks or incorrect data-motion-mode attributes in animated diagrams

Summary

• self_check.py lives at skills/diagram-design/scripts/self_check.py in the cathrynlavery/diagram-design repository and requires no external Python packages.
• The validator uses a custom DiagramParser to scan HTML, then runs check_svgs, check_scripts, and check_motion to enforce safety and accessibility contracts.
• Run the script with python3 skills/diagram-design/scripts/self_check.py <filename.html> to receive immediate OK/FAIL feedback.
• The script exits with status 1 when violations are found, making it suitable for continuous integration gates.
• It validates against template-motion.html for script contents and enforces strict rules on SVG accessibility attributes and motion-design fallbacks.

Frequently Asked Questions

Does self_check.py require installing any Python packages?

No. The validator uses only Python standard library modules such as html.parser and has zero third-party dependencies. You can run it immediately in any environment with Python 3 installed.

Can I validate multiple diagrams at once?

Yes. Pass multiple filenames as command-line arguments: python3 skills/diagram-design/scripts/self_check.py diagram1.html diagram2.html diagram3.html. The script validates each file sequentially and reports individual pass/fail status for each.

What should I do if the validator reports "motion file needs a explanation"?

Add a <noscript> element to your HTML that describes the complete static frame of the diagram. This ensures users with JavaScript disabled or those using assistive technologies can still understand the diagram's content, fulfilling the motion contract's accessibility requirements.

Why does the script check against template-motion.html?

The check_scripts function compares inline script content against the canonical template-motion.html file to ensure that motion controllers have not been tampered with and contain only approved interaction patterns. This prevents injection of malicious JavaScript while allowing legitimate diagram controls.

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