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

> Learn to contribute diagram examples to cathrynlavery/diagram-design. Validate HTML locally with lint-skin.py and pass CI gates for successful pull requests.

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

---

**To contribute a diagram example to the Diagram Design repository, you must validate your HTML file locally with [`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) (lines 21-23).

## Local Linting with lint-skin.py

Before committing, run [`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-skin-baseline.txt), use:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) automatically executes the full gate matrix.

### The Gate Matrix

According to [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) for label-mask collision detection and [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-skin.py) alongside [`scripts/lint-render.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-skin-baseline.txt).
- **CI enforcement**: The GitHub Actions workflow in [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) executes the full gate matrix including [`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py) and [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html), [`template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-dark.html), or [`template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) executes `scripts/lint-skin.py --all --baseline` together with [`scripts/lint-render.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-render.py), [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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.