Introducing a new way to review your PRs.

Read the announcement

cathrynlavery / diagram-design

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

View on GitHub

23 documents · Updated Nov 20, 2026

docs / ci-and-pages-automation

CI and Pages automation

GitHub Actions provides the repository's automated quality and publishing loop. Pull requests and pushes to main run the check suite, while pushes to main can also publish the static diagram gallery and update plugin version metadata. This page complements Diagram quality assurance and Diagram verification suite.

Workflow map

The workflows separate review checks from main-branch publishing and post-merge maintenance. A pull request enters CI only; a push to main can enter all three paths.

flowchart LR
    PR[Pull request to main] --> CI[CI checks]
    Push[Push to main] --> CI
    Push --> Pages[Build gallery artifact]
    Pages --> Deploy[Deploy GitHub Pages]
    Push --> Bump[Prepare and publish version update]
    Bump --> Main[Updated main]
    Main --> CI
    Main --> Pages

Repository validation

The CI workflow is the repository's review gate. It checks package metadata and maintainer policy, validates package rules, verifies Python compatibility, and runs source, rendered-output, documentation, accessibility, geometry, import, motion, and chart-data checks. It also checks generated assets, screenshots, thumbnails, standalone SVG exports, packaged self-checks, architecture-delta records, axonometric plan examples, and visual tone claims. The package gate also validates the Claude marketplace package and protects the rule that pull requests do not change manifest versions. The checks run on pull requests and on pushes to main, so the branch remains checked after automation creates a new commit.

CI uses separate package and compatibility checks plus a platform and Python-version matrix for the broad validation job. The matrix covers Linux, Windows, and macOS with Python 3.11 and 3.12, while the compatibility check covers Python 3.9. The rendered-layout check runs on one Linux Python 3.12 leg because its headless Chromium pixel result is the single calibrated visual reference; the other matrix legs still run the source checks. Validation steps report their outcomes even when an earlier check fails, which gives maintainers one summary of the run instead of stopping at the first error. The workflow also compares generated icon assets with their checked-in form and records each verification gate in the run summary. The standalone SVG export check protects the contract that exported files retain their needed styles and do not collide in their definition IDs. Arc diagrams also have dedicated span-geometry and checker gates. See the diagram verification suite for the checks themselves.

References: .github/…/ci.yml• L3-14 .github/…/ci.yml• L16-78 .github/…/ci.yml• L79-102 .github/…/ci.yml• L103-570 .github/…/ci.yml• L572-625 .github/…/ci.yml• L626-738

The Pages workflow publishes the gallery as a static artifact. On a push to main, or after a manual dispatch, it packages skills/diagram-design/assets and sends that artifact to the GitHub Pages deployment environment. There is no separate site build in this workflow; the gallery's HTML assets are the hosted output.

Only one Pages deployment runs at a time. A new run waits for an active deployment instead of cancelling it, which avoids replacing a deployment while it is in progress. Pull requests do not publish the hosted gallery because this workflow has no pull-request trigger.

References: .github/…/pages.yml• L1-16 .github/…/pages.yml• L17-46 README.md• L105-107

Post-merge version maintenance

The Auto Version Bump workflow keeps the four plugin manifests and the shared skill metadata aligned after changes reach main. It examines the merged commits since the last manifest bump, uses release labels to choose the strongest required bump, and prepares a tightly limited update. A second job rechecks the branch before it publishes the change, so a newer push does not receive a stale version update.

The preparation job runs with read-only access and passes a short-lived patch artifact to the publishing job. The publishing job checks the artifact's paths and exact version changes again before it commits. The protected token is introduced only for the final push. Concurrent main-branch updates are serialized; if main advances during preparation or publication, the current run does not push and a newer queued run recomputes the update. Pull requests must not change plugin versions because the CI package gate enforces this boundary. Details belong in Plugin release automation.

References: .github/…/auto-bump.yml• L1-21 .github/…/auto-bump.yml• L23-35 .github/…/auto-bump.yml• L50-145 .github/…/auto-bump.yml• L147-219 .github/…/auto-bump.yml• L220-321 .github/…/auto-bump.yml• L323-368 .github/…/ci.yml• L43-78

Review previews

Visual changes use rendered evidence as part of review. The pull request template asks contributors to attach a preview for each changed diagram variant, and it requires light, dark, and full-editorial previews when a new diagram type is added. The assigned workflows publish the main gallery but do not generate pull-request screenshot attachments.

The committed preview collection now includes light, dark, and full-editorial arc-diagram images for reviewers. These files support side-by-side review before the live Pages gallery provides the browsable artifact after a main-branch push. The example collection and its variant rules are described in Diagram example gallery.

References: .github/PULL_REQUEST_TEMPLATE.md• L5-19 .github/PULL_REQUEST_TEMPLATE.md• L33-39 docs/…/arc-diagram-light.png docs/…/arc-diagram-dark.png docs/…/arc-diagram-full.png README.md• L105-107

Change checklist

When these files or sections are changed, remember to consider these:

  • When a CI gate is added, removed, or renamed, update the CI summary and the contributor-facing validation list so the reported result still maps to a real check.
  • When a new diagram verifier or contract gate is added, keep its source check and its CI summary row aligned so failures remain visible in the run summary.
  • When the standalone SVG export contract changes, keep its export validation and the matching CI summary gate aligned.
  • When the gallery entry point or asset directory changes, update the Pages artifact path and the links that users use to open the hosted or local gallery.
  • When a visual example or canonical screenshot changes, keep the gallery registration, screenshot digest data, and freshness gate aligned.
  • When version ownership changes, keep the PR no-bump rule, release-label policy, manifest allowlist, and post-merge publish path consistent.
  • When Pages permissions, its environment, or its concurrency policy changes, recheck who can publish and whether deployments can overlap.

Important failure modes

TriggerConsequenceGuard
A pull request edits one of the plugin manifest versionsThe package gate rejects the pull request before mergeLeave version changes to Auto Version Bump on main and use release labels for a larger bump
A visual change makes the rendered result spill, collapse, or overflowThe Linux Chromium render gate fails even when source checks passKeep the pinned Playwright and Chromium pair and inspect the rendered output rather than relying on source geometry
A standalone SVG export loses its styles or conflicts in its definition IDsThe standalone export gate fails even when the source diagram checks passKeep the export contract and its dedicated validation aligned with the SVG output
Architecture-delta snapshots or ledger data fall out of syncThe architecture-delta gate rejects the change even when other diagram checks passUpdate the checked snapshot and ledger inputs with the related architecture change
A tone claim no longer matches the polarity of its rampThe skin-polarity gate rejects the affected diagram setKeep the claim text and the referenced ramp semantics aligned
A shipped example is not reachable from the gallery or a support link points to a missing fileThe documentation and routing gate failsRegister the example and update its routing and reference links in the same change
The Pages artifact path no longer contains the gallery entry pointThe deployment has no valid hosted gallery outputTreat skills/diagram-design/assets and its entry point as the Pages publish contract
main advances between version preparation and the final pushThe current bump is skipped, leaving the newer queued run to recalculate itDo not bypass the source and freshness checks or push the prepared patch manually
The prepared version artifact contains an unexpected path or a broader file changeThe publishing job refuses to commit the bumpKeep the release allowlist and exact semantic validation aligned with the files that own the version
AUTO_BUMP_TOKEN is missing or cannot update protected mainThe validated version update is not publishedKeep the secret configured and limit its use to the final publish step

Key files

FileWhy to read it
.github/…/ci.ymlDefines the pull-request and main-branch quality gate, its package and compatibility checks, its platform matrix, its rendered-output oracle, its diagram contract gates, and its run summary.
.github/…/pages.ymlDefines how the static gallery becomes a GitHub Pages artifact and how deployments are serialized.
.github/…/auto-bump.ymlDefines the protected post-merge version-maintenance path, its restricted patch artifact, and its stale-branch protections.
.github/PULL_REQUEST_TEMPLATE.mdDefines the visual preview evidence expected from diagram changes.
docs/…/arc-diagram-light.png, docs/…/arc-diagram-dark.png, docs/…/arc-diagram-full.pngProvide the committed light, dark, and full-editorial arc-diagram review evidence.
CONTRIBUTING.mdMaps the workflow gates to contributor actions and explains the no-version-bump rule.
README.mdShows the public gallery link and the local gallery entry point that Pages publishes.