Validation Scripts for Linting Diagram Output in the Diagram-Design Repository

The diagram-design repository provides a three-tier validation system consisting of a core linter (lint-skin.py), specialized verification wrappers (verify-*.py), and automated test suites (test-*.py) that enforce accessibility standards and visual consistency across all diagram outputs.

The cathrynlavery/diagram-design project maintains strict quality standards for generated diagrams through a comprehensive suite of validation scripts for linting diagram output. These tools ensure that all HTML-based diagrams meet accessibility requirements, use correct font references, and exclude prohibited markup. This article examines the complete validation architecture, from the core SVG inspector to CI-ready verification pipelines.

Core Linter: scripts/lint-skin.py

The foundation of the validation ecosystem is scripts/lint-skin.py, a Python-based linter that parses HTML example files and template files to enforce visual and structural policies. This script acts as the primary gatekeeper for diagram quality, checking both concrete examples and generation templates.

What It Validates

According to the source code in scripts/lint-skin.py, the linter performs the following inspections:

• Accessibility attributes: Verifies that SVG elements contain required accessibility markup, including role="img" and aria-label attributes, ensuring diagrams are screen-reader compatible.
• Font validation: Confirms that any referenced font files exist on disk and are correctly referenced within the markup.
• Security restrictions: Flags disallowed HTML constructs such as inline scripts (<script> tags) and external resource references that could compromise security or rendering consistency.
• Baseline exclusions: Supports a baseline file at scripts/lint-skin-baseline.txt that lists known-good exceptions to skip when running --all.

Command-Line Usage

The linter supports flexible invocation patterns suitable for both local development and continuous integration environments.

# Lint a single example file

python scripts/lint-skin.py path/to/example.html

# Lint all examples, excluding baseline entries

python scripts/lint-skin.py --all

# Lint all examples and treat any finding as a hard failure (CI mode)

python scripts/lint-skin.py --all --fail-on-finding

Verification Scripts

Built atop the core linter, the repository includes specialized verification scripts that wrap lint-skin.py to validate curated diagram collections. These verify-*.py scripts define ROOT paths pointing to the repository root, select specific example files (.html, .drawio, .mmd), and execute the core linter via subprocess.run([sys.executable, ROOT / "scripts/lint-skin.py", …]).

Individual Verification Wrappers

Each verification script targets a specific diagram category or import pipeline:

• verify-sequence-oauth.py: Validates sequence diagrams and OAuth-specific examples using python scripts/lint-skin.py --all --baseline.
• verify-mermaid-import.py: Checks diagrams imported from Mermaid syntax against accessibility standards.
• verify-drawio-import.py: Lints Draw.io (diagrams.net) import examples for structural compliance.
• verify-geometry.py: Enforces standards on geometry-related diagram outputs.
• verify-motion.py and verify-semantic-motion.py: Handle general and semantic motion diagram validation, respectively.
• verify-plugin-package.py: Validates that plugin packages include properly linted diagram assets.
• verify-docs-sync.py: Ensures documentation examples reflect the current codebase and pass all linting checks.

Each script inspects the return code from the core linter and prints a concise pass/fail message suitable for CI log aggregation.

Automated Test Suites

To prevent regressions in the validation scripts themselves, the repository maintains a comprehensive test suite in scripts/test-*.py files. These tests create temporary directories, copy the linter into test sandboxes, and assert expected exit codes and output strings.

Key test files include:

• test-lint-a11y.py: Validates that the linter correctly identifies missing aria-label or role attributes, validates font paths, and respects the baseline file entries.
• test-self-check.py: Runs a high-level self-check that includes the linter and other verification steps.
• test-verify-motion.py and test-verify-geometry.py: Execute their respective verification scripts in isolated temporary project copies to ensure wrapper logic remains functional.
• test-verify-docs-sync.py: Confirms that documentation synchronization checks continue to catch drift between code and docs.
• test-plugin-package.py: Verifies that the plugin packaging process includes mandatory linting steps.
• test-fix-mojibake.py: Ensures proper handling of character-encoding edge cases that could affect SVG output rendering.
• test-build-icons-devicon.py and test-build-icons-quoted-attributes.py: Validate that autogenerated icon assets meet the same style and attribute requirements as standard diagram output.

These tests are typically executed with pytest scripts/ or by invoking individual scripts directly.

CI/CD Integration Workflow

When building or modifying diagram-generation pipelines, the recommended workflow leverages all three validation layers:

1. Local development: Run python scripts/lint-skin.py against new or modified example files to catch accessibility violations immediately.
2. Pre-integration: Execute the relevant verification script (e.g., python scripts/verify-mermaid-import.py) to ensure the full example set passes.
3. Continuous integration: Run pytest scripts/ to detect regressions in the linter logic itself, followed by python scripts/lint-skin.py --all --fail-on-finding to enforce zero-tolerance policies.

Additionally, skills/diagram-design/scripts/self_check.py provides a high-level orchestration script that runs a curated subset of the above checks for rapid validation during skill development.

Summary

• The core linter (scripts/lint-skin.py) enforces accessibility, font, and security policies on HTML-based diagram output.
• Verification scripts (verify-*.py) provide CI-ready wrappers that lint specific diagram categories including Mermaid, Draw.io, OAuth, and geometry examples.
• Test suites (test-*.py) guarantee that the linter correctly identifies violations and respects baseline exclusions.
• The system uses a baseline file (scripts/lint-skin-baseline.txt) to manage known-good exceptions when running global checks.
• All scripts support --fail-on-finding for strict CI pipelines where any lint finding constitutes a build failure.

Frequently Asked Questions

How do I run the linter on all diagram examples at once?

Use the --all flag with the core linter script. Execute python scripts/lint-skin.py --all from the repository root to validate every HTML example while automatically skipping entries listed in scripts/lint-skin-baseline.txt. For continuous integration environments where any finding should break the build, add the --fail-on-finding flag.

What accessibility standards does the diagram linter enforce?

The linter validates that all SVG elements include accessibility attributes such as role="img" and aria-label to support screen readers. It also verifies that font references resolve to actual files and flags prohibited markup like inline scripts or external resources that could impact accessibility or security.

Which verification script should I use for Mermaid diagrams?

Use scripts/verify-mermaid-import.py specifically for validating diagrams imported from Mermaid syntax. This wrapper invokes the core linter with appropriate paths and arguments for the Mermaid example set, ensuring they meet the repository's visual and structural standards before integration.

How do I add an exception for a known-good diagram that fails linting?

Add the file path to scripts/lint-skin-baseline.txt. The core linter reads this baseline file when invoked with --all or --baseline, allowing specified files to skip validation. This is useful for legacy diagrams or third-party imports that cannot be modified but are approved for use.

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