` 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) has **no external dependencies**, you can execute it directly with any standard Python 3 interpreter. Validate a single diagram: ```bash python3 skills/diagram-design/scripts/self_check.py path/to/my-diagram.html ``` Process multiple files in a batch: ```bash python3 skills/diagram-design/scripts/self_check.py diagrams/*.html ``` Integrate into a CI pipeline using the exit code: ```bash #!/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`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py)** lives at [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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 <noscript> 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

# How to Run self_check.py on Agent-Generated Diagram Output > Easily run self_check.py on agent-generated diagram output to ensure safety and accessibility without extra installs. Validate HTML diagrams quickly with our guide. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-09-09 --- **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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py)), a custom subclass of `HTMLParser`. This parser walks the entire HTML document and collects: - **Unsafe tags** such as `

` 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 `` 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) has **no external dependencies**, you can execute it directly with any standard Python 3 interpreter. Validate a single diagram: ```bash python3 skills/diagram-design/scripts/self_check.py path/to/my-diagram.html ``` Process multiple files in a batch: ```bash python3 skills/diagram-design/scripts/self_check.py diagrams/*.html ``` Integrate into a CI pipeline using the exit code: ```bash #!/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`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py)** lives at [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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 <noscript> 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.