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

> Discover the self_check.py validation script in diagram-design. This pure-Python tool audits HTML output for safety, accessibility, and motion compliance without dependencies.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-14

---

**[`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash
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:

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) functions as a **focused subset** of broader validation infrastructure. While [`lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-skin.py) (root `scripts/`) and [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py) (root `scripts/`) handle repository-wide standards, [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) packages essential checks for runtime self-validation by the skill itself.

Key dependencies:

- **[`assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html)** — Canonical controller reference fetched by `canonical_controller()`
- **[`scripts/test-self-check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-skin.py) and [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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.