How to Contribute Diagram Examples Using lint-skin.py and CI Validation Gates

To contribute a diagram example to the Diagram Design repository, you must validate your HTML file locally with scripts/lint-skin.py before submitting a pull request that passes the automated CI gate matrix.

The Diagram Design repository by cathrynlavery enforces strict quality controls on every contribution, ensuring each diagram meets color, font, accessibility, and asset safety standards defined in the canonical style guide. Contributing requires running local linting checks followed by automated validation via GitHub Actions gates that block merging until all findings are resolved.

Understanding the Contribution Pipeline

Contributing a new diagram follows a three-stage validation pipeline. First, you run local checks using the skin linter. Second, you push your changes and trigger the CI workflow. Third, you address any failures until the gate matrix shows zero findings.

The pipeline treats every diagram as a checked-in artifact that must satisfy visual design, accessibility, and security policies. The lint-skin.py script serves as the primary validator, parsing HTML and extracting SVG metadata to verify compliance against skills/diagram-design/references/style-guide.md (lines 21-23).

Local Linting with lint-skin.py

Before committing, run scripts/lint-skin.py to validate your example against the allowed color palette and typography families.

Validating Single Files

To check a specific diagram file, execute the linter with the target path:

python3 scripts/lint-skin.py skills/diagram-design/assets/example-my-type.html

The script checks for color compliance, font-family restrictions, a11y (accessibility) contracts, and external-asset violations. It verifies that only the canonical motion controller is present and rejects any remote resources or disallowed CSS.

Running the Baseline Check

To verify your changes do not break existing examples while skipping legacy files exempted in scripts/lint-skin-baseline.txt, use:

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

This validates all example-*.html files and the three template-*.html files against the current skin definitions, ensuring repository-wide consistency.

CI Gate Validation

When you open a pull request, the GitHub Actions workflow defined in .github/workflows/ci.yml automatically executes the full gate matrix.

The Gate Matrix

According to CONTRIBUTING.md (lines 26-33), the CI pipeline runs python scripts/lint-skin.py --all --baseline alongside domain-specific validators including scripts/verify-geometry.py for label-mask collision detection and scripts/verify-semantic-motion.py for animation compliance. Every gate must return green status before merging is permitted.

If any gate fails, the CI logs print the exact file path, line number, and violation category:

skills/diagram-design/assets/example-my-type.html:12: a11y: duplicate accessible-name id="my-type-title" is not allowed

Resolving CI Failures

Fix the reported issue—such as changing the ID to my-type-title-alt—then re-run the local linter to confirm resolution before pushing your amendment. The PR status will update automatically once the CI re-runs the full suite.

Step-by-Step Contribution Workflow

Follow this complete workflow to contribute a new diagram example:

# 1. Create a feature branch

git checkout -b add-my-example

# 2. Copy the appropriate template

cp skills/diagram-design/assets/template.html \
   skills/diagram-design/assets/example-my-type.html

# 3. Edit the file (update title, description, and SVG content)

# 4. Validate locally

python3 scripts/lint-skin.py skills/diagram-design/assets/example-my-type.html

# 5. Check against the full baseline

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

# 6. Commit and push

git add skills/diagram-design/assets/example-my-type.html
git commit -m "feat: add example-my-type"
git push origin add-my-example

Open a pull request on GitHub. The CI pipeline will automatically re-run lint-skin.py alongside scripts/lint-render.py and geometry verifiers. Address any reported failures by amending your commit and pushing updates until the PR summary shows 0 finding(s).

Summary

• Local validation: Run scripts/lint-skin.py against new examples to check colors, fonts, accessibility, and asset safety before committing.
• Baseline testing: Use --all --baseline to verify your changes do not regress existing examples while respecting legacy exemptions listed in scripts/lint-skin-baseline.txt.
• CI enforcement: The GitHub Actions workflow in .github/workflows/ci.yml executes the full gate matrix including verify-geometry.py and verify-semantic-motion.py checks that must all pass.
• Failure resolution: CI logs provide exact file paths and line numbers (e.g., example-my-type.html:12: a11y) for rapid debugging.
• Template usage: Start from template.html, template-dark.html, or template-full.html to ensure the embedded motion controller matches the canonical digest expected by the linter.

Frequently Asked Questions

What does lint-skin.py check in diagram examples?

The script validates HTML examples against the style guide defined in skills/diagram-design/references/style-guide.md. It verifies color palette compliance, font-family restrictions, SVG accessibility name contracts, canonical motion controller presence, and rejects external assets or unauthorized CSS.

How do I handle CI failures for accessibility violations?

When the CI reports an error like a11y: duplicate accessible-name, locate the specified line in your HTML file and ensure every ID is unique and matches the file slug. For example, change id="my-type-title" to id="my-type-title-alt", then re-run python3 scripts/lint-skin.py locally to confirm the fix before pushing.

Can I submit examples that use legacy styling?

Legacy examples listed in scripts/lint-skin-baseline.txt are exempt from full skin checks but still undergo accessibility validation. New contributions must pass the complete lint suite; you cannot add new files to the baseline exemption list.

Where does the CI workflow run the validation scripts?

The GitHub Actions configuration in .github/workflows/ci.yml executes scripts/lint-skin.py --all --baseline together with scripts/lint-render.py, scripts/verify-geometry.py, and other domain-specific checkers. This gate matrix runs automatically on every pull request to ensure all shipped diagrams conform to the current design system.

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