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.
Contributing to Diagram Design
Thanks for wanting to contribute — this project only gets better with more eyes on it.
Please read CODE_OF_CONDUCT.md first. All contributions are expected to keep the community welcoming.
What this project is
Diagram Design is an agent skill (Claude Code, Codex, Factory Droid, Pi) that produces editorial-quality diagrams as self-contained HTML files. The repo is documentation-first: skills/diagram-design/SKILL.md is the index, each of the 45 visual types has its own reference file, and the extractor scripts in skills/diagram-design/scripts/ turn draw.io, Mermaid, and Excalidraw sources into a structured IR.
See README.md for the full picture, including the design system and the import/export flows.
Before you start
- Create an issue first for anything non-trivial (new type, behavior change, import grammar work). Small fixes and docs can go straight to a PR.
- Work on a branch — never commit directly to
main. - Keep the scope tight. One PR = one concern. Mixing a new diagram type with a docs rewrite makes review slow.
- Keep at most five PRs open at a time. GitHub enforces this limit for contributors without write access, including draft PRs. Finish review feedback and close or merge an existing PR before opening another. If you have more ideas, open an issue first so we can agree on priority. Maintainers may ask you to close duplicate or superseded PRs.
- Python 3.10+ is required for the development scripts (CI runs 3.11 and 3.12 across Linux, Windows, and macOS).
Validation gates
Every validation gate below must pass before a PR is ready. They also run automatically as GitHub Actions CI (.github/workflows/ci.yml).
Do not bump the plugin version in your PR. The Claude, Codex, Factory, and Qoder manifest versions are bumped automatically on main after each merge by the Auto Version Bump workflow (.github/workflows/auto-bump.yml, ADR 0009), so pull requests must leave all four plugin.json versions untouched — CI rejects any change to them. This keeps open PRs from conflicting with each other on every merge. If your change warrants more than a patch release, say so in the PR description and the maintainer will apply the release:minor or release:major label before merging; the label selects the bump size. (scripts/bump-plugin-version.py still exists for the workflow and the maintainer — contributors never need to run it.)
| What it checks | Command |
|---|---|
| Plugin bump helper and adversarial package cases | python3 scripts/test-plugin-package.py |
| Maintainer policy matches native manifests and current CI gates | python3 scripts/test-maintainer-policy.py |
| OpenAI plugin directory listing limits and upload ZIP contents | python3 scripts/test-build-openai-plugin-zip.py |
| Manifest versions untouched and synchronized; valid marketplace paths; packaged skill | python3 scripts/verify-plugin-package.py --require-no-bump origin/main |
| Claude marketplace and plugin schema, with warnings treated as errors | claude plugin validate . --strict |
| Accessible SVG contract (unit tests for the a11y linter) | python3 scripts/test-lint-a11y.py |
No HTML comment in the skill trips the Hermes Agent install scanner's html_comment_injection rule (#482) |
python3 scripts/test-install-scan.py |
| Semantic-pattern routing | python3 scripts/verify-semantic-motion.py --markdown-only |
| Animated-example structure and accessibility | python3 scripts/verify-semantic-motion.py --example-only |
| Skin conformance of every example and template (colors, fonts, a11y, assets, scripts) | python3 scripts/lint-skin.py --all --baseline |
| Skin token contrast: every text token clears 4.5:1 and every essential mark 3:1 on paper, light and dark, with translucent tokens composited first | python3 scripts/test-verify-contrast.py && python3 scripts/verify-contrast.py |
| Rendered-layout checker and shipped examples/templates | python3 scripts/lint-render.py --self-test && python3 scripts/lint-render.py --all |
| Quantitative polar encoding and variant parity | python3 scripts/test-verify-polar.py && python3 scripts/verify-polar.py |
| Heatmap monotone opacity ramp, complete N×M grid, ≤1 focal cell | python3 scripts/test-verify-heatmap.py && python3 scripts/verify-heatmap.py --all |
| A single file, e.g. a new example | python3 scripts/lint-skin.py skills/diagram-design/assets/example-my-type.html |
| Sequence-doc consistency (ATL fragments, budgets) | python3 scripts/verify-sequence-oauth.py |
| Semantic-motion verifier behaves (pass + adversarial cases) | python3 scripts/test-verify-semantic-motion.py |
| Sequence-oauth verifier behaves (pass + adversarial cases) | python3 scripts/test-verify-sequence-oauth.py |
| draw.io import path (real extractor vs fixtures + docs sync) | python3 scripts/verify-drawio-import.py && python3 scripts/test-verify-drawio-import.py |
| Mermaid import path (grammars, adversarial input, caps, docs sync) | python3 scripts/verify-mermaid-import.py |
| Excalidraw import path (scenes, adversarial input, caps, docs sync) | python3 scripts/verify-excalidraw-import.py && python3 scripts/test-verify-excalidraw-import.py |
| Optional motion contract (fallbacks, controls, budgets, determinism) | python3 scripts/test-verify-motion.py |
| Doctor diagnostics contract (env checks, script presence, routing wiring) | python3 scripts/verify-doctor.py |
| Doctor diagnostics adversarial tests | python3 scripts/test-verify-doctor.py |
| Every shipped motion template/example | python3 scripts/verify-motion.py --shipped |
| Docs/routing sync (description hooks, gallery, README tree, reference links and style-guide anchors, strict-bundler support paths, command/prompt surfaces, font-link parity, template title fallback order, SKILL.md split routing) | python3 scripts/verify-docs-sync.py && python3 scripts/test-verify-docs-sync.py |
| Canonical README screenshots match their example HTML sources and recorded PNG digests | python3 scripts/verify-screenshot-freshness.py |
| Packaged PNG exporter's stalled-webfont fallback (window.stop on timeout, warning, normal load) | python3 scripts/test-export-wait.py (requires Playwright; skips without it) |
| Screenshot freshness checker behaves (CRLF checkout, real source drift, raw PNG digests) | python3 scripts/test-verify-screenshot-freshness.py |
| README WebP previews match their PNGs, manifest, dimensions, and full-size links | python3 scripts/test-build-readme-thumbs.py && python3 scripts/build-readme-thumbs.py --check (requires Pillow==12.1.1) |
Packaged output self-check behaves (pass + adversarial cases, including --offline) |
python3 scripts/test-self-check.py |
Standalone SVG export carries CSS, namespaces defs IDs, and honors --system-fonts |
python3 scripts/test-export-svg-standalone.py |
| Label masks are never clipped by a node painted after them; connectors stay orthogonal, off node borders, corners, and each other, and on their own ports | python3 scripts/verify-geometry.py --all |
| Label geometry checker behaves (pass + adversarial cases) | python3 scripts/test-verify-geometry.py |
| Architecture delta snapshots preserve identity, ledger coverage, signatures, positions, and relationship endpoints | python3 scripts/verify-architecture-delta.py --all |
| Architecture delta checker behaves (pass + adversarial cases) | python3 scripts/test-verify-architecture-delta.py |
| Architecture containment IDs, parents, geometry, PaaS placement, and peerings | python3 scripts/verify-architecture-containment.py --all |
| Architecture containment checker behaves (pass + adversarial cases) | python3 scripts/test-verify-architecture-containment.py |
| Exploded examples are what the builder produces | python3 scripts/build-exploded-examples.py --check |
| Exploded axonometric silhouettes match their declared boxes, gaps are equal, and labels sit in one clear column | python3 scripts/verify-exploded.py --all |
| Exploded axonometric checker behaves (pass + adversarial cases) | python3 scripts/test-verify-exploded.py |
| Axonometric plan examples are what the builder produces | python3 scripts/build-axonometric-plan-examples.py --check |
| Axonometric plan boxes match their declared footprints, paint back to front, never overlap, and carry one clear tag each | python3 scripts/verify-axonometric-plan.py --all |
| Axonometric plan checker behaves (pass + adversarial cases) | python3 scripts/test-verify-axonometric-plan.py |
| Traceable block decomposition registries have unique IDs, resolving parents, names, and no cycles | python3 scripts/verify-block-registry.py --all |
| Block registry checker behaves (pass + adversarial cases) | python3 scripts/test-verify-block-registry.py |
| Treemap cells match the values they are labelled with, and labels fit | python3 scripts/verify-treemap.py --all |
| Treemap checker behaves (pass + adversarial cases) | python3 scripts/test-verify-treemap.py |
| Marimekko columns, segments and areas match the amounts they declare, in one series order | python3 scripts/verify-marimekko.py --all |
| Marimekko checker behaves (pass + adversarial cases) | python3 scripts/test-verify-marimekko.py |
| Dumbbell domain resolves finitely and its marks clear 3:1 | python3 scripts/verify-dumbbell.py |
| Dumbbell checker behaves (pass + adversarial cases) | python3 scripts/test-verify-dumbbell.py |
| Slopegraph axes share one scale and every endpoint matches its printed value | python3 scripts/verify-slopegraph.py --all |
| Slopegraph checker behaves (pass + adversarial cases) | python3 scripts/test-verify-slopegraph.py |
| Streamgraph layers tile one shared scale on a symmetric baseline and every total is a sum | python3 scripts/verify-streamgraph.py --all |
| Streamgraph checker behaves (pass + adversarial cases) | python3 scripts/test-verify-streamgraph.py |
| Ridgeline ridges share one amplitude and every printed range matches its bins | python3 scripts/verify-ridgeline.py --all |
| Ridgeline checker behaves (pass + adversarial cases) | python3 scripts/test-verify-ridgeline.py |
| Sankey flow conservation and ribbon geometry | python3 scripts/verify-sankey.py --all |
| Sankey checker behaves (pass + adversarial cases) | python3 scripts/test-verify-sankey.py |
| Waterfall running-total conservation and signed-bridge geometry | python3 scripts/verify-waterfall.py --all |
| Waterfall checker behaves (pass + adversarial cases) | python3 scripts/test-verify-waterfall.py |
| Service-blueprint visibility line, stage grid, and census | python3 scripts/verify-service-blueprint.py --all |
| Service-blueprint checker behaves (pass + adversarial cases) | python3 scripts/test-verify-service-blueprint.py |
| Bubble positions sit on shared axis scales and area encodes every declared size | python3 scripts/verify-bubble.py --all |
| Bubble checker behaves (pass + adversarial cases) | python3 scripts/test-verify-bubble.py |
| Bump vertices sit exactly on one rank grid and every endpoint label is placed on both axes | python3 scripts/verify-bump.py --all |
| Bump checker behaves (pass + adversarial cases) | python3 scripts/test-verify-bump.py |
| Beeswarm dots sit exactly at their values on one shared scale with no overprint | python3 scripts/verify-beeswarm.py --all |
| Beeswarm checker behaves (pass + adversarial cases) | python3 scripts/test-verify-beeswarm.py |
| Box-plot five-number summaries sit on one shared scale, ordered, with outliers outside the whiskers | python3 scripts/verify-box-plot.py --all |
| Box-plot checker behaves (pass + adversarial cases) | python3 scripts/test-verify-box-plot.py |
| Every directional tone claim matches the ramp it describes, on every skin | python3 scripts/verify-skin-polarity.py --all |
| Skin-polarity checker behaves (pass + adversarial cases) | python3 scripts/test-verify-skin-polarity.py |
Generated icon assets are up to date (icons.html, primitive-icons.md) |
python3 scripts/build-icons.py then git diff --exit-code on the two generated files |
The semantic-pattern gate also caps skills/diagram-design/SKILL.md at 40,000 bytes so the installed skill remains practical to load. If that gate fails, reduce duplication or move detail into a routed reference; do not remove routing vocabulary from frontmatter. SKILL.md is a router: SVG markup and the long form of the connector rules live in references/primitives-core.md, and the 4px grid table, per-type complexity budget rows, page layout, and summary cards live in references/layout-budget.md (ADR 0004, 2026-09-27 amendment). A new type's budget row goes in layout-budget.md, not SKILL.md.
Keep diagram claims checked
Every diagram gets the common skin, accessibility, render, and geometry gates above. A chart with a numerical or structural claim also needs a type-specific verifier: identify the claim (for example, waterfall running totals, Sankey flow conservation, or treemap area shares), bind each displayed value to machine-readable data, and compare the rendered marks and labels with recomputed values. Add a complete valid example and at least one plausible rendered error as an adversarial fixture. The waterfall case shows a chart whose end label says 236 when its signed contributions sum to 238.
Name the pair scripts/verify-<type>.py and scripts/test-verify-<type>.py, then run both on the shipped variants in CI. scripts/test-maintainer-policy.py now fails if any verifier or its adversarial test is missing from the CI-backed local gate list. This guards the wiring as new checkers arrive.
The current type checkers verify internal consistency of the chart and its declarations. They cannot prove that a correctly drawn number matches an external budget, spreadsheet, or API. To cover that boundary for generated diagrams, keep an independent source-data file, make the type verifier compare it with the chart's declarations, package the verifier with the installed skill, and call it from the generated-output self-check. Until a type has that path, run its repository verifier explicitly and do not describe the source data as verified.
Keep native plugin and marketplace description fields within 500 characters
for Cowork installation compatibility (#208).
They must still name every visual type; keep fuller feature details in the skill
frontmatter and Codex longDescription. The docs-sync gate checks both length
and routing vocabulary, and the package gate keeps native descriptions aligned.
The Codex interface block doubles as the OpenAI plugin directory listing, so
displayName and shortDescription stay within 30 characters and
longDescription within 4,000. scripts/build-openai-plugin-zip.py --check
enforces those limits. The maintainer publishes the directory listing; please
don't submit this plugin to OpenAI or any other plugin directory yourself.
Run them all at once before pushing:
python3 scripts/test-plugin-package.py \
&& python3 scripts/test-maintainer-policy.py \
&& python3 scripts/test-build-openai-plugin-zip.py \
&& python3 scripts/verify-plugin-package.py --require-no-bump origin/main \
&& claude plugin validate . --strict \
&& python3 scripts/test-lint-a11y.py \
&& python3 scripts/test-install-scan.py \
&& python3 scripts/verify-semantic-motion.py --markdown-only \
&& python3 scripts/verify-semantic-motion.py --example-only \
&& python3 scripts/verify-motion.py --shipped \
&& python3 scripts/lint-skin.py --all --baseline \
&& python3 scripts/lint-render.py --self-test \
&& python3 scripts/lint-render.py --all \
&& python3 scripts/test-verify-polar.py \
&& python3 scripts/verify-polar.py \
&& python3 scripts/test-verify-heatmap.py \
&& python3 scripts/verify-heatmap.py --all \
&& python3 scripts/verify-sequence-oauth.py \
&& python3 scripts/test-verify-semantic-motion.py \
&& python3 scripts/test-verify-sequence-oauth.py \
&& python3 scripts/verify-drawio-import.py \
&& python3 scripts/test-verify-drawio-import.py \
&& python3 scripts/verify-mermaid-import.py \
&& python3 scripts/verify-excalidraw-import.py \
&& python3 scripts/test-verify-excalidraw-import.py \
&& python3 scripts/test-verify-motion.py \
&& python3 scripts/verify-doctor.py \
&& python3 scripts/test-verify-doctor.py \
&& python3 scripts/verify-docs-sync.py \
&& python3 scripts/test-verify-docs-sync.py \
&& python3 scripts/verify-screenshot-freshness.py \
&& python3 scripts/test-verify-screenshot-freshness.py \
&& python3 scripts/test-build-readme-thumbs.py \
&& python3 scripts/build-readme-thumbs.py --check \
&& python3 scripts/test-verify-contrast.py \
&& python3 scripts/verify-contrast.py \
&& python3 scripts/test-self-check.py \
&& python3 scripts/test-export-svg-standalone.py \
&& python3 scripts/verify-geometry.py --all \
&& python3 scripts/test-verify-geometry.py \
&& python3 scripts/verify-architecture-delta.py --all \
&& python3 scripts/test-verify-architecture-delta.py \
&& python3 scripts/verify-architecture-containment.py --all \
&& python3 scripts/test-verify-architecture-containment.py \
&& python3 scripts/build-exploded-examples.py --check \
&& python3 scripts/verify-exploded.py --all \
&& python3 scripts/test-verify-exploded.py \
&& python3 scripts/build-axonometric-plan-examples.py --check \
&& python3 scripts/verify-axonometric-plan.py --all \
&& python3 scripts/test-verify-axonometric-plan.py \
&& python3 scripts/verify-block-registry.py --all \
&& python3 scripts/test-verify-block-registry.py \
&& python3 scripts/verify-treemap.py --all \
&& python3 scripts/test-verify-treemap.py \
&& python3 scripts/verify-marimekko.py --all \
&& python3 scripts/test-verify-marimekko.py \
&& python3 scripts/verify-dumbbell.py \
&& python3 scripts/test-verify-dumbbell.py \
&& python3 scripts/verify-slopegraph.py --all \
&& python3 scripts/test-verify-slopegraph.py \
&& python3 scripts/verify-streamgraph.py --all \
&& python3 scripts/test-verify-streamgraph.py \
&& python3 scripts/verify-ridgeline.py --all \
&& python3 scripts/test-verify-ridgeline.py \
&& python3 scripts/verify-sankey.py --all \
&& python3 scripts/test-verify-sankey.py \
&& python3 scripts/verify-waterfall.py --all \
&& python3 scripts/test-verify-waterfall.py \
&& python3 scripts/verify-service-blueprint.py --all \
&& python3 scripts/test-verify-service-blueprint.py \
&& python3 scripts/verify-bubble.py --all \
&& python3 scripts/test-verify-bubble.py \
&& python3 scripts/verify-bump.py --all \
&& python3 scripts/test-verify-bump.py \
&& python3 scripts/verify-beeswarm.py --all \
&& python3 scripts/test-verify-beeswarm.py \
&& python3 scripts/verify-box-plot.py --all \
&& python3 scripts/test-verify-box-plot.py \
&& python3 scripts/verify-skin-polarity.py --all \
&& python3 scripts/test-verify-skin-polarity.py \
&& python3 scripts/test-export-wait.py
If a gate fails
verify-plugin-package.py: if it reports a version change, drop the manifest edits from your branch — versions are bumped onmainafter merge, never in a PR. If packaging validation fails, keep all native marketplaces pointed at the repository root and keep the shared skill atskills/diagram-design/SKILL.md.lint-skin.py: the failure message names the file, line, and category (color,font-family,a11y,external-asset,pure-black,script). Colors must come from the palette inskills/diagram-design/references/style-guide.md; fonts from the allowed list; diagrams must satisfy the accessible SVG contract (see below). The linter also requires the SHA-pinned controller fromtemplate-motion.htmlverbatim and rejects remote resources, CSS@import, non-fragment CSSurl(), event handlers,srcdoc, executable URLs, and extra scripts.verify-*.py: the extractor's real behavior no longer matches its fixture or the documentation, or the reference/command/prompt wiring drifted. Fix the source of truth — do not widen a test to avoid a failure.verify-screenshot-freshness.py: a canonical minimal-light example or its committed PNG changed without a synchronized catalog refresh. Before the first regeneration, install the renderer withpython3 -m pip install playwright && python3 -m playwright install chromium. Then runpython3 scripts/render-canonical-screenshots.py, inspect all 45 renders, and commit the updated PNGs plusdocs/screenshots/manifest.json. The gate hashes example sources in their canonical LF form, so a checkout that converts LF to CRLF still passes;scripts/test-verify-screenshot-freshness.pycovers that case, real source drift, and raw PNG digests.build-readme-thumbs.py --check: a README preview is missing, stale, corrupt, the wrong size, orphaned, or no longer links to its full PNG. Install the pinned renderer withpython3 -m pip install Pillow==12.1.1, runpython3 scripts/build-readme-thumbs.py, inspect the preview changes, and commit the WebPs plusdocs/screenshots/thumbs/manifest.json.verify-marimekko.py: a column is drawn off its category's share of the width, a segment off its series' share of the column, the columns do not share one plot height or one gutter, segments leave a gap or overlap, a series changes order between columns, a second segment wears the accent, anything positions a segment or a bound label from atransformattribute, an inlinestyle, or a<style>rule, or a label, caption or key disagrees with the rect it binds. Fix the geometry or the declaration so they state one thing — never widen a column or pad a segment to fit a label, and never drop a category or a series to tidy the grid.verify-slopegraph.py: the two axes disagree about scale or origin, or an endpoint is drawn somewhere other than where its own declared value belongs. Fix the coordinate, never the label — and never move a point to stop two endpoint labels colliding, because crowded labels mean the values really are close.verify-streamgraph.py: a layer's drawn thickness disagrees with its declared values, the stack has a gap or overlap, the envelope drifts off its midline, a boundary curve bends away from where its vertices put it, or a legend entry prints a name other than the layer it binds. Fix the geometry or the declaration so they state one thing — never bridge a zero period, float a band to open room, or reshape a curve between vertices to smooth the story.verify-ridgeline.py: a ridge is drawn on its own amplitude, a baseline sits off the stack's pitch or away from its drawn rule, a ridge is sampled on its own x positions, or a printed range is wider than the bins it claims. Fix the geometry or the declaration so they state one thing — never renormalise a single ridge to make it readable, and never move a baseline to buy one ridge headroom.verify-bubble.py: a bubble is drawn off the shared axis scale its peers describe, its radius disagrees with the one area constant (r = K·√size), a second bubble wears the accent, an overlapping smaller bubble is painted under a larger one, or a bound label/tick disagrees with the mark it names. Fix the geometry, never the binding — and never nudge a bubble to open up space, because crowded bubbles mean the values really are close.verify-bump.py: a vertex sits off the rank grid the figure itself declares, a snapshot's ranks are not a permutation of 1..N, a segment curves or arrives by a relative command, or an endpoint label is missing a coordinate, drawn inboard of the end it names, or off the gutter its peers share. Fix the geometry or the declaration, never the label — and never nudge a vertex off its row to dodge a label collision, because a rank between two ranks is not a rank.verify-beeswarm.py: a dot is drawn off the shared value scale its peers describe, two dots declaring one value sit at two positions, a pair overprints instead of dodging, a second radius or a second non-focal fill appears, a second dot wears the accent, two dots share adata-name(or one is empty), anything positions a mark from CSS (transform,translate/rotate/scale, a geometry property, a motion path) by any carrier — attribute, inlinestyle, or<style>rule, or a bound label/tick disagrees with the mark it names. Fix the geometry, never the binding — and never move a dot along the value axis to open up space, because crowding is data and the dodge is the only honest resolution.verify-box-plot.py: a box, median, whisker or outlier is drawn off the shared value scale its peers describe, the five-number order is broken, an outlier sits inside the whiskers or the Tukey fences, a category label names the wrong series, a second series wears the accent, two series share adata-name, anything positions a mark from CSS, or a bound tick disagrees with the mark it names. Fix the geometry, never the binding — and never move a box along the value axis to open up space, because crowded boxes mean the summaries really are close.verify-skin-polarity.py: a legend key or caption names the ramp's direction by lightness (darker is larger) in a file whose ramp composites the other way.inkis a role, not a colour — it resolves near-black on light paper and near-white on dark — so one set of opacities runs darker as it strengthens in the light skin and lighter in the dark one. Name the direction by contrast against the paper (stronger contrast is larger), which survives the skin swap, and ship the same sentence in every variant; never invert the word for one file. The gate also fails closed on a claim it cannot substantiate — no resolvable paper colour, fewer than three rank-bearing ramp members, or a ramp that is not strictly ordered — and on wording it cannot parse: a tone word within six words of a magnitude word that no supported sentence form binds. Rephrase that as<tone> <is|means|represents> <magnitude>(stronger contrast is larger), because a claim the gate cannot read is a claim nothing checks.verify-geometry.py: a label mask overlaps a node declared later in the document, so the node fill clips the label at render time. Move the label to a free segment of its connector — keep the 6–10px gap from the stroke required by SKILL.md §6, and do not shrink the mask to sneak under the check. It also fails an arrowed connector with a diagonal straight segment, a segment lying on a node's border, an endpoint within 8px of a node corner, a port closer to another on the same edge than rule 4 allows (12px, or 8px on an edge under 48px), a straight run stacked on another connector, or path data it cannot parse. Reroute the connector so it leaves each box perpendicular to the edge it starts on, from its own port; do not drop the marker or the node stroke to get past the check.verify-architecture-delta.py: a stable ID, snapshot membership, status, signature, position, endpoint, or ledger target disagrees with the declared migration. Followtype-architecture-delta.md: record every changed object in the center ledger, retain unchanged positions on matching grids, and distinguish CHANGED, MOVED, and REWIRED by what actually differs. Fix the diagram and metadata together; never suppress the ledger entry to hide an unaccounted change.verify-architecture-containment.py: a nested Architecture figure withdata-grammar="architecture-containment"has a duplicate ID, an unresolved or cyclic parent, a child drawn outside its declared parent, an admin band that is not a dashed rx=4 rectangle, a traffic box that is not a solid rx=8 rectangle, a managed PaaS box sitting inside a traffic scope, an endpoint that is not inside one, a peering that does not join two traffic scopes, mixed sibling axes, or off-grid bounds. Followtype-architecture.mdContainment: keep administrative and traffic shapes distinct, put managed services in the admin band that owns them, and put only the private endpoint in the subnet.verify-exploded.py: a part's silhouette is off the projection of the box it declares, a level sits at two heights, the gaps differ or fall under max(0.5 x top-face height, 3 x part thickness), a leader bends, starts off its part, or crosses another part, labels crowd or leave the column, or an animated lift disagrees with the geometry. Change the model inscripts/build-exploded-examples.pyand rebuild; never nudge a drawn coordinate, and never shrink a gap to fit the canvas.verify-axonometric-plan.py: a box's silhouette is off the projection of its declared footprint, a box stands outside the plate, floats above it, or shares floor with another, a box is painted after one in front of it, or a tag is off its plan point, stands on a room or roof it does not name, overlaps another tag, runs past two words, or is missing or doubled for a room or building. Change the plan inscripts/build-axonometric-plan-examples.pyand rebuild; move a tag to open floor rather than shrinking it.verify-block-registry.py: a Traceable block decomposition diagram (semantic-patterns.md§ 8) has a duplicatedata-block-id, adata-block-parentthat doesn't resolve to another block's id in the same file, a blankdata-block-id, a missing or blankdata-block-name, or a cycle in the parent chain. Fix the diagram's attributes — the checker mirrors the source rather than validating semantics, so a passing file is only as correct as the IDs and parents actually authored on it.- Icon assets: you changed
scripts/vendor/icons/orscripts/build-icons.pyand the generated files went stale. Rerunpython3 scripts/build-icons.pyand commit the regenerated files.
Do not add a file to scripts/lint-skin-baseline.txt to get your example through. The baseline exists only for legacy pre-2.0 examples that legitimately predate the current skin, and it still receives a11y checks.
How the gates work
This section used to live in the README. It explains what the main gates measure and why, so a failure makes sense before you try to fix it.
Skin lint and the accessible SVG contract
Before submitting a new example, run python3 scripts/lint-skin.py <your-new-example.html>. The repository-wide check python3 scripts/lint-skin.py --all --baseline covers examples and templates and must stay green. The linter's a11y category rejects diagram SVGs without a resolving accessible name, an empty or misplaced title/description, or unsafe bare title / desc IDs. It also pins the exact reviewed motion controller and rejects remote assets, CSS @import, non-fragment CSS url(), and executable attributes such as onclick or srcdoc.
CI separately verifies semantic routing, animated-example structure, animated skin, every shipped motion asset, and adversarial mutations of the controller contract, and it reports later gate outcomes even when an earlier gate fails. Both motion verifiers exempt root SVGs marked aria-hidden="true" from diagram naming checks; decorative icons never replace the required accessible diagram.
Geometry and data-encoding gates
Label placement is gated geometrically: python3 scripts/verify-geometry.py --all fails CI when a label mask overlaps a node declared later in the document, because the node fill would clip the text at render time. The same script fails diagonal connectors, connectors that run along a node's border or attach at its corner, ports crowded closer than 12px, and arrows stacked on one trunk. Label masks and nodes are compared in canvas coordinates after supported enclosing or element translate() transforms, so separate snapshot panels do not overlap merely because they reuse local coordinates.
Treemaps get a second geometric gate, because their whole claim is that area is the encoding. verify-treemap.py measures area error as a relative figure, since an absolute one passes exactly the small cells most likely to be wrong. Waterfalls get the same treatment for the running total, and Sankey, polar, heatmap, marimekko and the Line and Scatter variants each have their own encoding verifier. Diagrams using the traceable block decomposition pattern get a structural gate (verify-block-registry.py) so the --registry JSON export cannot misrepresent the tree it describes. Every verifier has a test-verify-*.py partner that keeps it honest in both directions.
Docs sync
python3 scripts/verify-docs-sync.py fails CI if the SKILL.md description loses a type's lexical hook, the gallery can't reach a shipped example, the README tree names a file that doesn't exist, a relative reference link is broken, a support path is not shipped inside the skill package, or a command/prompt surface drifts from its routed reference. It also holds the type count in one place: commands may not state a count at all, and counts in reader-facing docs must equal the number of references/type-*.md files. The gallery gives each type one number, 01 to N in document order, and every other example is a lettered variant (04a, 04b) placed directly after its type. python3 scripts/test-verify-docs-sync.py exercises these checks adversarially.
The same count check covers this guide, SKILL.md, and the current onboarding and semantic-pattern references. Historical changelog entries and ADRs keep the count that was accurate when they were written. After a new type merges, a maintainer must also update the repository's GitHub About description, Cathryn's profile README, and diagramdesign.dev; those live outside this CI check.
The skill also ships skills/diagram-design/scripts/self_check.py, a distilled output checker installed agents can run on their own generated diagrams; python3 scripts/test-self-check.py keeps it honest.
Render lint
lint-skin.py reads the source. lint-render.py renders it: headless Chromium reports what actually got painted, which catches content cut off by the SVG viewport, collapsed SVGs, horizontal page overflow, missing local assets and JS errors. Both run in CI on every pull request.
pip install playwright && playwright install chromium # same dep as PNG export
python3 scripts/lint-render.py --self-test # checks the checks
python3 scripts/lint-render.py --all # examples and templates
python3 scripts/lint-render.py <your-new-example.html>
python3 scripts/lint-render.py --fonts --all # measure with the real webfonts
Clipping is measured by paint, not geometry. getBoundingClientRect() on an SVG child ignores stroke width, markers and filter bleed, and knows nothing about clip-path or overflow: visible, so it both misses real clipping and invents clipping that isn't there. Instead each SVG is screenshot as authored and again with its overflow released, and the two are diffed: ink that appears outside was being cut off. Releases are staged (the SVG alone, then each clipping ancestor) so a wrapper release can't mask spill at the SVG's own edge, and an SVG authored overflow: visible inside a clipping wrapper is still checked. --self-test asserts all of that on 23 cases, over half of them cases that must not be flagged, and it also asserts the DOM is byte-identical after measuring.
There are no golden images, so there is nothing to re-record and no PNGs in the repo for this gate. Network is cut at the browser's resolver, which covers WebSockets and anything else that bypasses request routing, with request routing as a second layer; --fonts excludes exactly the two Google Fonts hostnames and allows them only over HTTPS. Since the oracle is pixels, CI pins Playwright and its Chromium build rather than installing whatever is newest.
Font metrics differ between the default run and --fonts. With network blocked (the default, and what CI runs), text is laid out in the fallback faces, not Instrument Serif and Geist. That is deterministic and machine-independent, which is what a linter needs, and it is also exactly what a diagram looks like in system-font mode. Run --fonts --all locally when you care whether real webfont text fits its box.
CI
All pull requests and pushes run these gates on Linux, Windows, and macOS through GitHub Actions (.github/workflows/ci.yml). Pixel-based gates run on one Linux leg only, because antialiasing and font fallback differ per OS.
The accessible SVG contract (a11y)
Every diagram <svg> must satisfy the contract enforced by the linter:
role="img"andaria-labelledbynaming the<title>and<desc>.<title>is the first child of<svg>(before<defs>).- IDs are prefixed per diagram and variant:
<slug>-title/<slug>-desc— forexample-loop-dark.htmlthe slug isloop-dark, so the IDs areloop-dark-title/loop-dark-desc. Baretitle/descIDs and duplicate IDs are rejected. <title>is the short subject name (≈ the<h1>, ≤ 60 chars);<desc>is one sentence describing the content, not the geometry.- Purely decorative SVGs (
aria-hidden="true") are exempt.
The contract lives in scripts/lint-skin.py (lint_accessible_svgs) and is unit-tested by scripts/test-lint-a11y.py. When in doubt, pattern-match an existing example.
Working on examples (diagrams)
Every diagram type ships three variants: minimal light (example-<type>.html), minimal dark (example-<type>-dark.html), and full editorial (example-<type>-full.html).
- Copy the closest template (
skills/diagram-design/assets/template.html,template-dark.html, ortemplate-full.html). - Load the matching
references/type-<name>.mdand follow its layout conventions. - Replace the eyebrow, h1, and SVG body; replace the
[diagram-slug]placeholders with your file's slug and keep the<title>/<desc>slots filled. - Run the taste gate in
SKILL.md§9, then the linter:
python3 scripts/lint-skin.py skills/diagram-design/assets/example-my-type.html
New examples should be added to the gallery (assets/index.html) so they stay browsable.
Motion is opt-in. Start from skills/diagram-design/assets/template-motion.html, follow references/animation.md, and run python3 scripts/verify-motion.py <file> plus python3 scripts/test-verify-motion.py. A motion file must preserve complete no-JavaScript, reduced-motion, print, screenshot, and export states. Keep the controller byte-for-byte identical to the template; changes require updating the canonical template, example, documentation, and adversarial tests together.
Design decisions (ADRs)
Settled policies live as short records in docs/adr/ — one pinned motion controller, semantic patterns never expanding the visual-type taxonomy, the reveal-only autoplay rule, the SKILL.md byte cap with its trigger-rich description requirement, geometric label placement being verified rather than reviewed, and plugin versions being bumped on main after merge rather than in PRs. Read the relevant ADR before proposing a change that touches one; when a PR settles a new policy, add an ADR in the same PR.
Adding a new diagram type
- Write
skills/diagram-design/references/type-<name>.md— layout conventions, anti-patterns, and a worked pattern for that type. Mirror an existing reference's structure. - Add the row to the selection table in
skills/diagram-design/SKILL.md§3 and the type's name to the frontmatterdescription—verify-docs-sync.pyfails if the description loses or lacks a type's lexical hook. - Add the three example variants (see above) and register them in the gallery (
assets/index.html) with the next type number; extra examples of an existing type go directly after it as lettered variants (data-parent-type, eyebrow04a).verify-docs-sync.pyfails on any shipped example the gallery can't reach and on any numbered tab without a matchingtype-*.md. - Run the full gate suite — new examples are linted automatically by
--all. - After merge, the maintainer updates the GitHub About description, Cathryn's profile README, and diagramdesign.dev to the new count, then checks the live pages. Contributors do not need write access to those surfaces.
Changing the icon set
Icons are generated, never hand-edited:
- Add or replace the source SVG in
scripts/vendor/icons/<source>/(tabler/,simple/, …). Keep license provenance inTHIRD_PARTY_LICENSES.mdaccurate. - Regenerate and verify:
python3 scripts/build-icons.py
git diff --exit-code -- skills/diagram-design/assets/icons.html skills/diagram-design/references/primitive-icons.md
Touching the import paths
- draw.io:
skills/diagram-design/scripts/drawio_extract.py— must passscripts/verify-drawio-import.py, which drives the extractor againstscripts/fixtures/sample-architecture.drawioin all four container formats (raw XML, deflate+base64, PNG-embedded, SVG-embedded). - Mermaid:
skills/diagram-design/scripts/mermaid_extract.py— must passscripts/verify-mermaid-import.py, which covers every supported grammar, multi-block Markdown, adversarial labels, trust-boundary behavior, resource caps, and named failures. - Excalidraw:
skills/diagram-design/scripts/excalidraw_extract.py— must passscripts/verify-excalidraw-import.py, which covers scene parsing, bound labels, groups and frames, adversarial labels, trust-boundary behavior, resource caps, and named failures.
All three scripts treat their input as untrusted data — they never render, fetch, or execute source content. Keep it that way. If you add a grammar or a new security boundary, extend the corresponding verifier with a fixture before merging.
Documentation and wiring must stay in sync: the import references, SKILL.md §11, the slash commands in commands/, and the Pi prompt templates in prompts/ each describe the same flows. The verifiers check this — keep both sides updated in one PR.
Documentation
Most of this repo is documentation. When behavior changes, update the affected reference files and the README in the same PR. Loose ends here are what the verifiers and reviewers will catch.
Commit and PR conventions
Commit messages follow Conventional Commits: type(scope): summary, e.g. fix(import): support current Mermaid syntax, ci: verify Mermaid imports, docs(onboarding): clarify the URL flow. Keep summaries short and imperative.
A good PR:
- has a clear title and a description that says what changed and why;
- mentions how you tested it (which gates you ran);
- keeps generated and source files consistent (extractor + verifier + reference + command in one change);
- is rebased on
mainand green on CI.
Questions?
Open a discussion or comment on the relevant issue. If it's about security, use the private reporting path in SECURITY.md.