What Is the self_check.py Validation Script in diagram-design?

self_check.py is a lightweight, pure-Python validator that an installed Diagram-Design skill can invoke to self-audit the HTML it produces, verifying safety, accessibility, and motion compliance without any third-party dependencies.

The self_check.py validation script serves as a critical quality gate in the cathrynlavery/diagram-design repository. This standalone utility enables developers to verify that generated diagram output meets strict security contracts, accessibility standards, and motion animation requirements—all using only Python's standard library.

Core Validation Responsibilities

The script performs six distinct validation passes, each targeting a specific area of diagram correctness.

Unsafe Element Detection

The validator blocks dangerous HTML patterns that could compromise security. In DiagramParser.handle_starttag at lines 61-66, the script flags:

• Prohibited tags: <base>, <embed>, <object>, <iframe>
• Event handler attributes: any attribute beginning with on (e.g., onclick, onload)

These restrictions prevent arbitrary code execution and ensure diagrams remain safely embeddable.

Remote Resource Validation

The reference_error function (lines 79-97) scrutinizes external references to prevent unauthorized assets:

• JavaScript URLs are rejected outright
• Data URLs must be image types only
• Stylesheets are limited to the approved Google Fonts /css2 endpoint

This containment strategy keeps diagram files self-contained and predictable.

SVG Accessibility Enforcement

The check_svgs function (lines 14-45) implements comprehensive accessibility requirements for vector graphics:

• At least one SVG must be visible to assistive technology (not aria-hidden)
• Every SVG requires role="img"
• First child must be a <title> element
• Title and description must contain non-empty text
• aria-labelledby attributes must reference valid IDs

These checks align with WCAG guidelines for complex image alternatives.

Controller Script Integrity

The check_scripts function (lines 47-65) validates the motion controller implementation. It:

• Permits exactly one <script> element
• Requires the canonical data-diagram-controls attribute
• Compares script body against the reference implementation loaded by canonical_controller()

This ensures consistent behavior across all generated diagrams.

Motion Contract Compliance

The check_motion function implements the full motion schema (lines 69-52, with CSS checks at lines 44-50), verifying:

Requirement	Specification
Root element	Single data-motion-root present
Mode	One of none, reveal, step, loop
Step limits	0-8 steps maximum
Item budget	≤12 animated elements
Accessibility	Proper step semantics, playback controls, status announcements
CSS fallbacks	prefers-reduced-motion and @media print rules present
No-JavaScript	<noscript> block explaining static frame

Fallback Verification

The script confirms resilient design through regex searches that validate CSS media queries for reduced motion preferences and print layouts, plus required <noscript> content for baseline accessibility.

Usage Examples

Run validation from the command line:

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

Success output:

OK path/to/generated-diagram.html

Failure output with detailed diagnostics:

FAIL path/to/generated-diagram.html
  - <iframe> is not allowed in a diagram file
  - remote stylesheet is not the approved Google Fonts /css2 URL: https://example.com/style.css
  - svg 1 needs role=img
  - data-motion-mode must be one of ['none', 'reveal', 'step', 'loop']; got 'invalid'

For programmatic integration in test suites or build pipelines:

from pathlib import Path
from skills.diagram_design.scripts.self_check import verify

errors = verify(Path("my-diagram.html"))
if errors:
    for e in errors:
        print("❌", e)
else:
    print("✅ Diagram passed all self-checks")

Relationship to Repository-Wide Tools

self_check.py functions as a focused subset of broader validation infrastructure. While lint-skin.py (root scripts/) and verify-motion.py (root scripts/) handle repository-wide standards, self_check.py packages essential checks for runtime self-validation by the skill itself.

Key dependencies:

• assets/template-motion.html — Canonical controller reference fetched by canonical_controller()
• scripts/test-self-check.py — Unit test coverage for validation logic

Why Self-Validation Matters

• Security: Prevents injection of arbitrary scripts or unauthorized remote assets
• Accessibility: Enforces proper semantic markup for assistive technologies
• Consistency: Guarantees uniform motion behavior across browser environments
• CI/CD ready: Pure standard library implementation enables frictionless automation

Summary

• self_check.py validates generated diagram HTML for security, accessibility, and motion compliance
• Uses only Python standard library (argparse, html.parser, pathlib, re, urllib)
• Six validation areas: unsafe elements, remote references, SVG accessibility, controller integrity, motion contracts, CSS fallbacks
• Command-line and programmatic APIs support both development and automated testing
• Mirrors checks from lint-skin.py and verify-motion.py for skill-level quality gates

Frequently Asked Questions

What dependencies does self_check.py require?

None. The script uses only Python's standard library including argparse for CLI parsing, html.parser for HTML traversal, and pathlib for file operations. This zero-dependency design ensures it runs in any Python environment without installation overhead.

How does self_check.py handle motion accessibility?

The check_motion function validates that diagrams respect user preferences through CSS media query detection for prefers-reduced-motion, includes @media print fallbacks, and provides <noscript> explanations. It also enforces step limits (0-8), item budgets (≤12), and proper ARIA semantics for screen reader compatibility.

Can self_check.py be used in continuous integration pipelines?

Yes. The script returns appropriate exit codes and prints machine-parseable "OK" or "FAIL" prefixes. The programmatic verify() function returns a list of error strings, making it trivial to integrate with pytest, GitHub Actions, or any CI system without additional tooling.

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