`, and `<desc>` elements referenced via `aria-labelledby` - **Script integrity** – Only one `<script>` is permitted, and its body must exactly match the canonical controller from [`assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html) - **Motion markup structure** – Validates `data-motion-root`, `data-motion-mode` values, step counts, semantic item numbering, and the "two items per step" limit - **Resource safety** – Flags unsafe URLs in `<link>`, `<img>`, and `<script src="...">` references - **CSS fallbacks** – Ensures reduced-motion and print media queries are present for controlled modes The core parser class `DiagramParser` lives at [[`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L34-L45) lines 34–45, using only Python's built-in `html.parser.HTMLParser`. ## Prerequisites and Setup Install or clone the repository first: ```bash git clone https://github.com/cathrynlavery/diagram-design.git cd diagram-design ``` Generate a diagram using any skill that outputs single-file HTML (e.g., `drawio_import`, `mermaid_import`). The file must contain embedded SVG and optional motion markup—no external dependencies are loaded. ## Running the Validator ### Single file validation ```bash python3 skills/diagram-design/scripts/self_check.py path/to/my-diagram.html ``` ### Multiple files at once ```bash python3 skills/diagram-design/scripts/self_check.py diagrams/*.html ``` ### Expected output **Passing:** ```bash $ python3 skills/diagram-design/scripts/self_check.py examples/diagram.html OK examples/diagram.html ``` **Failing:** ```bash $ python3 skills/diagram-design/scripts/self_check.py bad/diagram.html FAIL bad/diagram.html - at most one script is allowed; found 2 - script 1 must exactly match the controller in template-motion.html ``` The script exits with status `0` on success and `1` on failure, making it suitable for CI integration. ## Validating Motion Markup Specifically When your diagram includes animated elements, [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) runs additional checks via the `check_motion` function at lines 69–143. These rules enforce: - Exactly one `data-motion-root` attribute in the document - `data-motion-mode` restricted to `none`, `reveal`, `step`, or `loop` - Step counts as decimal integers within documented limits - Semantic items (`data-item-*`) numbered sequentially with accessible labels - Controlled modes (`step`/`reveal`) providing playback controls, status announcements, and both reduced-motion and print CSS fallbacks The canonical motion controller reference is extracted from [[`assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html) at validator initialization (lines 64–72). ## Automating Validation in CI Add to your GitHub Actions workflow: ```yaml - name: Validate diagrams run: | python3 skills/diagram-design/scripts/self_check.py output/*.html ``` Or GitLab CI: ```yaml validate: script: - python3 skills/diagram-design/scripts/self_check.py build/**/*.html ``` The exit code mechanism guarantees pipeline failure on any validation error. ## Key Source Files | File | Purpose | |------|---------| | [[`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) | Main validator; contains `DiagramParser`, `check_svgs`, `check_motion` | | [[`skills/diagram-design/assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html) | Canonical motion controller reference | | [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) | Full repository gate that [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) mirrors in distilled form | | [`scripts/test-self-check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/test-self-check.py) | Test suite exercising validator against known-good/bad diagrams | ## Summary - **Run installed output validation** with `python3 skills/diagram-design/scripts/self_check.py <file.html>` - The tool requires **zero dependencies** beyond Python's standard library - Validates **SVG accessibility**, **script integrity**, **motion markup**, **resource safety**, and **CSS fallbacks** - Returns **exit code 0** for success, **1** for failure—CI-ready by design - Source lives in the **Diagram-Design** skill under `cathrynlavery/diagram-design` ## Frequently Asked Questions ### Does self_check.py require any pip-installed packages? No. The validator uses only Python's built-in `html.parser.HTMLParser` and standard library modules. This design ensures it runs in any environment without dependency resolution overhead. ### Can I validate diagrams that don't use motion features? Yes. The motion checks in `check_motion` are conditional—if no `data-motion-*` attributes are present, the validator skips those rules and only enforces SVG accessibility and script constraints. ### Why does my script fail the "canonical controller" check? The validator extracts the expected controller body from [`assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html) at lines 64–72. Any deviation—including whitespace changes, comments, or additional logic—triggers a failure. Copy the exact script block from the template to pass. ### How do I test the validator itself? Run `python3 scripts/test-self-check.py`, which exercises [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) against curated passing and failing diagram files. This ensures your local copy of the validator behaves correctly before you integrate it into production workflows.

# How to Run Installed Output Validation with self_check.py > Easily run installed output validation using self_check.py. This script verifies SVG accessibility, motion markup, and security with no dependencies. Get started now! - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-09-05 --- **Run installed output validation by executing `python3 skills/diagram-design/scripts/self_check.py path/to/diagram.html` from the repository root; the script checks SVG accessibility, motion markup, and security constraints without any third-party dependencies.** The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) validator is a lightweight, zero-dependency tool shipped with the **Diagram-Design** skill in the `cathrynlavery/diagram-design` repository. It ensures that generated diagram HTML files conform to strict accessibility, security, and motion contracts before they reach production or CI pipelines. ## What self_check.py Validates The validator performs five distinct inspection passes on any single-file HTML diagram: - **SVG accessibility** – Every visible SVG must carry `role="img"`, a non-empty ``, and `<desc>` elements referenced via `aria-labelledby` - **Script integrity** – Only one `<script>` is permitted, and its body must exactly match the canonical controller from [`assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html) - **Motion markup structure** – Validates `data-motion-root`, `data-motion-mode` values, step counts, semantic item numbering, and the "two items per step" limit - **Resource safety** – Flags unsafe URLs in `<link>`, `<img>`, and `<script src="...">` references - **CSS fallbacks** – Ensures reduced-motion and print media queries are present for controlled modes The core parser class `DiagramParser` lives at [[`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L34-L45) lines 34–45, using only Python's built-in `html.parser.HTMLParser`. ## Prerequisites and Setup Install or clone the repository first: ```bash git clone https://github.com/cathrynlavery/diagram-design.git cd diagram-design ``` Generate a diagram using any skill that outputs single-file HTML (e.g., `drawio_import`, `mermaid_import`). The file must contain embedded SVG and optional motion markup—no external dependencies are loaded. ## Running the Validator ### Single file validation ```bash python3 skills/diagram-design/scripts/self_check.py path/to/my-diagram.html ``` ### Multiple files at once ```bash python3 skills/diagram-design/scripts/self_check.py diagrams/*.html ``` ### Expected output **Passing:** ```bash $ python3 skills/diagram-design/scripts/self_check.py examples/diagram.html OK examples/diagram.html ``` **Failing:** ```bash $ python3 skills/diagram-design/scripts/self_check.py bad/diagram.html FAIL bad/diagram.html - at most one script is allowed; found 2 - script 1 must exactly match the controller in template-motion.html ``` The script exits with status `0` on success and `1` on failure, making it suitable for CI integration. ## Validating Motion Markup Specifically When your diagram includes animated elements, [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) runs additional checks via the `check_motion` function at lines 69–143. These rules enforce: - Exactly one `data-motion-root` attribute in the document - `data-motion-mode` restricted to `none`, `reveal`, `step`, or `loop` - Step counts as decimal integers within documented limits - Semantic items (`data-item-*`) numbered sequentially with accessible labels - Controlled modes (`step`/`reveal`) providing playback controls, status announcements, and both reduced-motion and print CSS fallbacks The canonical motion controller reference is extracted from [[`assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html) at validator initialization (lines 64–72). ## Automating Validation in CI Add to your GitHub Actions workflow: ```yaml - name: Validate diagrams run: | python3 skills/diagram-design/scripts/self_check.py output/*.html ``` Or GitLab CI: ```yaml validate: script: - python3 skills/diagram-design/scripts/self_check.py build/**/*.html ``` The exit code mechanism guarantees pipeline failure on any validation error. ## Key Source Files | File | Purpose | |------|---------| | [[`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) | Main validator; contains `DiagramParser`, `check_svgs`, `check_motion` | | [[`skills/diagram-design/assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html) | Canonical motion controller reference | | [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) | Full repository gate that [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) mirrors in distilled form | | [`scripts/test-self-check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/test-self-check.py) | Test suite exercising validator against known-good/bad diagrams | ## Summary - **Run installed output validation** with `python3 skills/diagram-design/scripts/self_check.py <file.html>` - The tool requires **zero dependencies** beyond Python's standard library - Validates **SVG accessibility**, **script integrity**, **motion markup**, **resource safety**, and **CSS fallbacks** - Returns **exit code 0** for success, **1** for failure—CI-ready by design - Source lives in the **Diagram-Design** skill under `cathrynlavery/diagram-design` ## Frequently Asked Questions ### Does self_check.py require any pip-installed packages? No. The validator uses only Python's built-in `html.parser.HTMLParser` and standard library modules. This design ensures it runs in any environment without dependency resolution overhead. ### Can I validate diagrams that don't use motion features? Yes. The motion checks in `check_motion` are conditional—if no `data-motion-*` attributes are present, the validator skips those rules and only enforces SVG accessibility and script constraints. ### Why does my script fail the "canonical controller" check? The validator extracts the expected controller body from [`assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html) at lines 64–72. Any deviation—including whitespace changes, comments, or additional logic—triggers a failure. Copy the exact script block from the template to pass. ### How do I test the validator itself? Run `python3 scripts/test-self-check.py`, which exercises [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) against curated passing and failing diagram files. This ensures your local copy of the validator behaves correctly before you integrate it into production workflows.