Source-Level Style Checking for Diagram Design Anti-Patterns: Complete Guide

The scripts/lint-skin.py script in the cathrynlavery/diagram-design repository performs comprehensive source-level style checking to detect and prevent anti-patterns in Diagram Design HTML files.

The cathrynlavery/diagram-design project enforces strict visual and security standards across its diagram examples through automated linting. Source-level style checking for Diagram Design anti-patterns ensures that every HTML diagram adheres to approved colour palettes, accessibility requirements, and security constraints before merging into the main branch.

The lint-skin.py Enforcement Script

The scripts/lint-skin.py file serves as the primary validation engine for the Diagram Design style guide. It parses HTML diagram source files and validates them against comprehensive rules defined in skills/diagram-design/references/style-guide.md, catching anti-pattern violations at the exact line numbers where they occur.

Visual Consistency Validation

The linter enforces strict adherence to the project's visual identity by checking:

• Approved colour palettes: Only colours defined in the style guide are permitted; custom hex codes like "#ff0000" trigger violations
• Font family restrictions: Only authorized typography from the design system may be used
• CSS hygiene: Prohibits constructs such as @import statements and remote url() references that could introduce external dependencies

Security and Accessibility Checks

Beyond aesthetics, the script validates critical safety and accessibility standards:

• External asset blocking: Prevents src attributes pointing to external HTTP(S) resources
• Executable attribute detection: Blocks potentially dangerous executable properties in markup
• SVG accessibility mandate: Requires proper <title>, <desc>, and role="img" attributes on all SVG elements for screen reader compatibility

Motion Controller Verification

The linter compares embedded JavaScript motion controllers against the canonical template in skills/diagram-design/assets/template-motion.html. Any deviation from the shipped template triggers an anti-pattern warning, ensuring consistent animation behaviour across all examples.

Running the Source-Level Style Checker

Single File Analysis

Validate an individual diagram during development:

python3 scripts/lint-skin.py path/to/example-foo.html

Batch Processing with Baselines

Run comprehensive checks across the entire repository while exempting legacy files:

python3 scripts/lint-skin.py --all --baseline

The --baseline flag references scripts/lint-skin-baseline.txt, which lists historical examples exempt from current style-guide enforcement. This allows teams to grandfather existing assets while ensuring all new contributions meet modern standards.

Understanding Lint Output

The script outputs machine-readable violation reports that include file paths, exact line numbers, and descriptive error messages:

skills/diagram-design/assets/example-bubble.html:12: color: "#ff0000 is not in the style-guide palette"
skills/diagram-design/assets/example-bubble.html:45: external-asset: external HTTP(S) src is not allowed

Each line follows the format filepath:line: description, enabling direct navigation to anti-pattern locations in your editor or IDE.

Configuration and Rule Definitions

Style Guide Authority

The skills/diagram-design/references/style-guide.md file serves as the single source of truth for all visual standards. It defines the approved colour palette, font stack, spacing units, and layout grids that lint-skin.py enforces programmatically at the source level.

Template Baseline

The skills/diagram-design/assets/template-motion.html file contains the canonical motion-controller script. The linter performs string or structural comparisons against this template to detect unauthorized modifications to animation logic or timing functions.

Summary

• Primary enforcement: scripts/lint-skin.py performs all source-level style checking for Diagram Design anti-patterns
• Visual standards: Validates against skills/diagram-design/references/style-guide.md for colours, fonts, and CSS constraints
• Security focus: Blocks external assets, executable attributes, and prohibited CSS imports such as @import
• Accessibility mandate: Requires SVG <title>, <desc>, and role="img" attributes on all diagram images
• Template integrity: Ensures motion controllers match the canonical template in skills/diagram-design/assets/template-motion.html
• Legacy support: Uses scripts/lint-skin-baseline.txt with the --baseline flag to exempt historical files

Frequently Asked Questions

What specific anti-patterns does the Diagram Design linter detect?

The script detects colour palette violations, unauthorized font families, external HTTP(S) assets in src attributes, missing SVG accessibility markup, prohibited CSS constructs including @import and remote url() functions, and deviations from the canonical motion controller template defined in the repository.

How do I exclude legacy files from style checking?

Add relative file paths to scripts/lint-skin-baseline.txt. When invoking the linter with the --baseline flag, the script automatically skips these entries while validating all other HTML files against current style-guide requirements.

Can the linter check multiple files simultaneously?

Yes. Use python3 scripts/lint-skin.py --all to scan the entire repository, or pass multiple file paths as arguments to check specific diagrams during local development before committing changes.

Where are the style rules and colour palettes defined?

The authoritative specifications live in skills/diagram-design/references/style-guide.md, which documents approved hex colours, typography stacks, spacing units, and structural requirements that the lint-skin.py script enforces against all new diagram contributions.

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