# What Is the Purpose of self_check.py in the Diagram-Design Repository?

> Discover the purpose of self_check.py in the diagram-design repository. This script validates diagram HTML for accessibility, security, and motion without dependencies.

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

---

**[`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) is a stand‑alone validation script that inspects generated diagram HTML files to enforce accessibility, security, and motion‑control contracts without requiring any third‑party dependencies.**

The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) file in the `cathrynlavery/diagram-design` repository serves as the primary quality gate for diagram generation. Located at [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py), this Python module enables installed agents and CI pipelines to run a “self‑check” on their own output, ensuring that produced HTML is safe to publish and conforms to the project's strict technical standards.

## Core Purpose and Architecture

The primary purpose of [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) is to act as a **gatekeeper** that guarantees any diagram HTML produced by the skill meets three critical requirements: accessibility for screen readers, security against code injection, and consistency with motion‑control templates. The script is referenced in the module docstring (lines 1‑13)【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L1-L13】.

Unlike external linting tools, [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) relies exclusively on the Python standard library—using `argparse`, `html.parser`, and `pathlib`—making it safe to run in any environment where the skill is installed. If validation fails, the script prints detailed error messages and exits with a non‑zero status, allowing automated systems to reject non‑conforming output immediately.

## Contract Enforcement Mechanisms

The script validates three distinct contracts through specific parser methods and check functions defined in the source file.

### Accessible SVG Contract

The `check_svgs` function (lines 14‑45)【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L14-L45】 ensures that every SVG element in the diagram is accessible to assistive technologies. It verifies that:

- Each SVG is non‑hidden and includes `role="img"`
- Proper `title` and `desc` elements are present
- Correct `aria‑labelledby` linking is established between elements

### Single‑File Safety Contract

To prevent security vulnerabilities, the script enforces a strict **single‑file safety contract** through the `handle_starttag` and `reference_error` methods (lines 57‑70)【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L57-L70】. This validation:

- Disallows unsafe tags such as `<iframe>` and `<embed>`
- Blocks executable attributes and inline event handlers
- Prohibits remote assets except for the approved Google Fonts stylesheet

### Motion Control Contract

When diagrams include animation, the `check_motion` function validates the **motion contract** (around lines 43‑69)【https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py#L69-L43】. It inspects:

- Structure of `data‑motion‑*` attributes
- Correct number of controls and required actions
- Presence of status elements
- That the embedded script matches the canonical controller defined in `skills/diagram-design/assets/template‑motion.html`

## How to Run the Self‑Check

### Command‑Line Validation

Execute the script directly against any generated HTML file:

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

```

The script prints `OK <file>` if the diagram passes all checks, or `FAIL <file>` followed by a list of specific violations.

### Programmatic Integration

Import the `verify` function to validate files within Python applications:

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

# Verify a single file and retrieve the list of errors (empty list → success)

errors = verify(Path("my-diagram.html"))
if errors:
    print("Diagram has problems:", errors)
else:
    print("Diagram is valid")

```

### CI Pipeline Integration

Add the self‑check to GitHub Actions or other CI systems to enforce contracts automatically:

```yaml
steps:
  - name: Checkout repository
    uses: actions/checkout@v3

  - name: Run self‑check on generated diagrams
    run: |
      python3 skills/diagram-design/scripts/self_check.py diagrams/*.html

```

Any non‑zero exit code will cause the workflow to fail, preventing invalid diagrams from being deployed.

## Relationship to Other Validation Tools

The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script operates as a **distilled subset** of the full repository‑wide motion verification logic found in `scripts/verify‑motion.py`. While `verify‑motion.py` performs comprehensive repository scans, [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) provides a lightweight, zero‑dependency alternative for runtime validation. Similarly, `scripts/lint‑skin.py` enforces the same SVG and safety rules for repository contributions, and `scripts/test‑self‑check.py` contains the test suite that exercises [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) against known‑good and known‑bad diagrams.

## Summary

- **[`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py)** is a stand‑alone validation script located at [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) that requires no external dependencies.
- It enforces three critical contracts: **accessible SVG markup**, **single‑file safety** (no executable code or remote assets), and **motion‑control consistency** with the canonical template.
- The script provides both **command‑line** and **programmatic** interfaces, returning non‑zero exit codes on failure for CI/CD integration.
- It enables agents to self‑validate output before publication, acting as the final quality gate in the diagram generation pipeline.

## Frequently Asked Questions

### What specific contracts does self_check.py enforce?

According to the `cathrynlavery/diagram-design` source code, the script enforces three distinct contracts: the **accessible‑SVG contract** (proper ARIA attributes and titles), the **single‑file safety contract** (blocking iframes, embeds, and executable code), and the **motion contract** (validating `data‑motion‑*` attributes against the canonical controller in `template‑motion.html`).

### Can self_check.py run without installing dependencies?

Yes. The script uses only Python standard library modules such as `argparse`, `html.parser`, and `pathlib`. This design ensures it can execute in any environment where the diagram‑design skill is installed, without requiring pip installs or virtual environments.

### How does self_check.py validate motion controls?

The `check_motion` function parses the HTML for motion markup and verifies that the embedded JavaScript controller matches the reference implementation in `skills/diagram-design/assets/template‑motion.html`. It checks the structure of `data‑motion‑*` attributes, ensures the correct number of controls exist, and validates required actions and status elements.

### What happens if a diagram fails validation?

If validation fails, the script outputs `FAIL <filename>` followed by detailed error messages describing which contract was violated (accessibility, safety, or motion). It then exits with a non‑zero status code, allowing CI pipelines, pre‑commit hooks, or runtime agents to automatically reject the non‑conforming HTML file.