How to Run Installed Output Validation with self_check.py

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 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 <title>, 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
• 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/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:

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

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

Multiple files at once

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

Expected output

Passing:

$ python3 skills/diagram-design/scripts/self_check.py examples/diagram.html
OK examples/diagram.html

Failing:

$ 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 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/skills/diagram-design/assets/template-motion.html) at validator initialization (lines 64–72).

Automating Validation in CI

Add to your GitHub Actions workflow:

- name: Validate diagrams
  run: |
    python3 skills/diagram-design/scripts/self_check.py output/*.html

Or GitLab CI:

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)	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)	Canonical motion controller reference
scripts/verify-motion.py	Full repository gate that self_check.py mirrors in distilled form
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 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 against curated passing and failing diagram files. This ensures your local copy of the validator behaves correctly before you integrate it into production workflows.

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