Diagram quality assurance
Diagram quality assurance keeps generated examples truthful in source, in browser paint, and in the documentation that exposes them. It combines policy, geometry, motion, theme, import, render, and synchronization gates so a change remains valid from authored data to the reader-facing artifact.
Quality gate model
The quality system checks each kind of truth where it can be observed. Source gates inspect declared structure and policy. Geometry gates compare data with the marks that represent it. Browser gates inspect rendered paint. Synchronization gates compare examples with the pages, packages, gallery, and screenshot records that expose them.
This diagram shows how an example moves through the gates before publication.
flowchart LR
A[Generated diagram example] --> B[Source and policy checks]
A --> C[Geometry and meaning checks]
A --> D[Browser paint checks]
B --> E[CI verification matrix]
C --> E
D --> E
E --> F[Documentation and screenshot sync]
F --> G[Merge and Pages publication]
The Diagram verification suite describes checker coverage and visual regression. CI and Pages automation describes workflow execution and publication.
Source and policy checks
Source checks enforce contracts that do not need a browser. They cover accessible SVG content, skin and font policy, local assets, motion structure, import safety, and data bindings. Chart-specific gates fail closed when a claimed mark or value cannot be read, because an unchecked mark can make a figure look valid while changing its meaning. A shared CSS scan also rejects escaped declaration names that could hide a geometry-changing rule from a verifier.
scripts/lint-skin.py applies shared visual and accessibility rules. scripts/verify-contrast.py checks token use and contrast. scripts/verify-semantic-motion.py checks semantic-pattern guidance and the policy-trace example. The chart gates compare declared data with the geometry that represents it. They protect shared scales, area and volume, rank rows, bins, running totals, complete categorical grids, and monotone ramps.
The source layer now includes dedicated contracts for event modeling, requirement traceability, SBGN, Steps, and Unit Grid. These checks bind printed labels and IDs to their rows or stages, require valid relationship direction, keep static SVG content visible, and reject movement or paint rules that could separate declarations from what a reader sees.
Mermaid imports have a dedicated safety and fidelity gate. It checks flowchart, sequence, state, ER, and quadrant-chart forms; Markdown block selection; invisible links; sequence fragments and numbering; Unicode; bounded source and statement sizes; malformed input; UTF-8 output; and command and documentation wiring. Imported content remains inert text, and unsafe or oversized input fails instead of passing with lost meaning. Quadrant charts preserve their axes, quadrants, points, and discarded styling notes without allowing source text to become executable content.
References: scripts/verify-mermaid-import.py• L163-180 scripts/verify-mermaid-import.py• L1440-1597 scripts/verify-mermaid-import.py• L1699-1800 scripts/verify-event-modeling.py• L157-246 scripts/verify-requirement-traceability.py• L48-156 scripts/verify-sbgn.py• L943-1223 scripts/verify-steps.py• L423-571 scripts/verify-unit-grid.py• L565-664 scripts/css_property_scan.py• L92-120
Draw.io, Excalidraw, and PlantUML imports have matching gates. Each gate runs the shipped extractor against representative and hostile inputs. It checks scene or graph meaning, malformed input, resource limits, safe text output, Unicode output, command wiring, documentation routes, and the worked example. This keeps an import change from passing while its extractor, instructions, or example has drifted.
These import gates treat imported content as untrusted diagram data. They preserve visible meaning as inert text, record content that cannot be imported, reject unsafe or oversized input, and keep the command, prompt, reference, skill route, fixture, and worked example in sync.
The architecture containment gate checks one declared diagram root, stable identities, scope budgets, parent selection, geometric containment, allowed scope shapes, node placement, endpoint targets, peerings, sibling axes, and the shared 4px grid. It also rejects style or animation changes that can move checked geometry away from the authored bounds.
References: scripts/verify-drawio-import.py• L857-960 scripts/verify-excalidraw-import.py• L651-734 scripts/verify-plantuml-import.py• L1031-1210 scripts/verify-architecture-containment.py• L623-742
Geometry and visual encoding
Geometry checks protect meaning that a generic render check cannot judge. They compare declared values, shared scales, positions, areas, widths, heights, paths, labels, and focal marks. They also reject transforms, hidden marks, or CSS overrides when raw coordinates no longer prove what the browser draws.
The chart contracts cover the main ways a figure can state a false relationship while still rendering:
| Diagram family | Protected meaning |
|---|---|
| Arc diagram | Nodes share one baseline and pitch. Arc spans, endpoints, radii, labels, and the focal accent agree. |
| Beeswarm and bubble | Declared values map to positions or area. Marks remain readable and labels stay with their marks. |
| Box plot | Five-number summaries, whiskers, outliers, ticks, labels, and one shared value scale agree. |
| Bump and slopegraph | Rank or value positions use one shared grid or scale. Rows, endpoints, and labels preserve order. |
| Marimekko and streamgraph | Widths, heights, layers, periods, totals, and shared scales conserve the declared data. |
| Polar and ridgeline | Rings, spokes, baselines, bins, amplitudes, labels, and category values use the declared layout. |
| Waterfall | Signed deltas conserve the running total. Bars, carries, labels, and polarity treatments show that total. |
| Schedule network | Task durations and precedence links recompute one project finish. Ranks, critical status, ports, routes, and printed fields agree with that model. |
| Architecture delta, service blueprint, and SBGN | Objects stay within their grids or bounds. Relationships, layers, compartments, and endpoints remain valid. |
| Event modeling and requirement traceability | Rows or stages keep their IDs, visible labels, relationship direction, and column or lane meaning. |
| Steps and Unit Grid | Equal segments or cells keep their count, order, size, spacing, state, and printed totals. |
These checks make data relations survive edits to coordinates and paint order. They use type budgets and fail closed when too little structure remains to verify the claim.
References: scripts/verify-arc-diagram.py• L854-995 scripts/verify-beeswarm.py• L572-826 scripts/verify-box-plot.py• L1447-1806 scripts/verify-bubble.py• L677-931 scripts/verify-bump.py• L461-774 scripts/verify-marimekko.py• L749-1050 scripts/verify-polar.py• L508-832 scripts/verify-ridgeline.py• L714-1072 scripts/verify-slopegraph.py• L657-918 scripts/verify-streamgraph.py• L703-1012 scripts/verify-waterfall.py• L337-581 scripts/verify-schedule-network.py• L73-129 scripts/verify-schedule-network.py• L264-361 scripts/verify-schedule-network.py• L368-613 scripts/verify-architecture-delta.py• L330-496 scripts/verify-service-blueprint.py• L692-968 scripts/verify-sbgn.py• L1188-1257 scripts/verify-event-modeling.py• L171-241 scripts/verify-requirement-traceability.py• L62-150 scripts/verify-steps.py• L468-570 scripts/verify-unit-grid.py• L575-663 scripts/css_property_scan.py• L92-120
Arc diagram geometry
The arc diagram gate protects a seat-rail model in which node order gives meaning to arc height. It requires enough nodes and arcs to show the shared pitch, then compares each named span with its endpoints, baseline, radius, direction, and focal accent. It also requires one visible label for each node and rejects transforms or hiding rules that can move or remove counted marks.
References: scripts/verify-arc-diagram.py• L792-932 scripts/verify-arc-diagram.py• L945-995
Service blueprint geometry
Service blueprint checks keep customer, frontstage, backstage, and support work on one shared stage grid. The line of visibility keeps visible work above the boundary and hidden work below it. Each stage still needs a customer, frontstage, and backstage cell with an explicit empty name when a cell does not apply.
References: scripts/verify-service-blueprint.py• L692-778 scripts/verify-service-blueprint.py• L814-968
Box plot geometry
Box plot checks keep a statistical summary honest in both axes. Each series declares five ordered values on one shared linear value axis. The gate aligns the box, median, whiskers, fences, outliers, value ticks, and category label with those declarations.
References: scripts/verify-box-plot.py• L1447-1482 scripts/verify-box-plot.py• L1495-1806
Schedule network geometry
The schedule network gate checks a bounded precedence model and the visible SVG that presents it. It recomputes earliest and latest times, total float, ranks, project finish, and critical links from task durations and finish-to-start links. The drawn task grids, arrow ports, routes, critical styling, summaries, and printed fields must then agree with that result.
The contract keeps the schedule readable as a network rather than a time-scaled bar chart. Tasks use fixed grid dimensions, ranks advance from left to right, routes avoid task boxes and one another, and every task field remains bound to its task.
References: scripts/verify-schedule-network.py• L73-129 scripts/verify-schedule-network.py• L264-361 scripts/verify-schedule-network.py• L368-613
Render and visual checks
The render gate opens each example in pinned headless Chromium and checks what the browser paints. It detects collapsed SVGs, page overflow, runtime errors, missing local assets, and ink cut off by the SVG or a containing element. It compares an authored render with staged overflow releases, so it tests visible spill rather than relying only on source bounds.
The browser is part of this contract because font metrics, strokes, markers, filters, and clipping can change pixels without changing source structure. The browser check runs on one pinned Linux environment so its paint result is a stable rendering oracle.
References: scripts/lint-render.py• L1-19 scripts/lint-render.py• L22-65 scripts/lint-render.py• L413-488 .github/…/ci.yml• L323-351
Motion behavior
Motion checks preserve a useful static artifact when animation is optional. The semantic motion gate requires step-mode controls, a complete static frame, deterministic test frames, accessible live status, keyboard paths, reduced-motion and print fallbacks, and a no-JavaScript path. It also blocks remote scripts, interval timing, and randomness so the same state can be checked each time.
The gate treats the policy-trace example as a reviewed contract. Its five ordered steps and visible PASS, FAIL, SKIPPED, NOT REACHED, and FIRST DIVERGENCE states must remain tied to the geometry and the accessible description.
References: scripts/verify-semantic-motion.py• L392-551 scripts/verify-motion.py• L13-19 scripts/verify-motion.py• L261-494
Theme polarity
Theme polarity checks protect words that describe a color ramp. A directional tone claim is measured against the file's own paper and ink, while contrast against the paper remains readable in both light and dark skins.
The contrast and polarity gates fail closed when a ramp, paper, token, or supported wording is missing. Type-specific checks also preserve polarity for data such as waterfall increases and decreases, and for the shared fills used by Unit Grid cells.
References: scripts/verify-skin-polarity.py• L1-19 scripts/verify-skin-polarity.py• L48-63 scripts/verify-contrast.py• L101-207 scripts/verify-waterfall.py• L520-559 scripts/verify-unit-grid.py• L514-562
Documentation and artifact synchronization
Synchronization checks keep the example set reachable, installable, and described by one source of truth. They compare the visual-type guide with the skill description, plugin manifests, gallery tabs, command and prompt routes, package metadata, and every support path that a strict skill bundler can extract. They also keep type counts, size presets, split reference routes, font links and fallback order, export defaults, type ramps, registered legacy sizes, Loop guidance, and Factory install commands aligned.
Canonical screenshots form a second synchronization boundary. Each of the 51 canonical types needs a source, a committed PNG, and a manifest entry with matching order, renderer settings, digests, and dimensions. The record uses Playwright Chromium at a 1440 by 1000 viewport with 2x scale and waits for document fonts before capture.
References: scripts/verify-docs-sync.py• L60-145 scripts/verify-docs-sync.py• L577-665 scripts/verify-docs-sync.py• L1302-1365 scripts/verify-docs-sync.py• L1636-1760 scripts/verify-docs-sync.py• L1819-1879 scripts/verify-screenshot-freshness.py• L21-100
Environment diagnostics
Environment diagnostics provide a read-only readiness check before the full suite runs. scripts/verify-doctor.py confirms that a usable Python runtime exists, probes Playwright and Chromium for PNG export, checks maintainer-only scripts and command routes in a source checkout, and reports common path issues.
The doctor separates hard failures from warnings. A missing runtime or required maintainer file fails. A missing Playwright package, unavailable browser, or common path issue warns unless --strict is used. The optional JSON report gives automation a stable summary without changing the checks.
References: scripts/verify-doctor.py• L26-56 scripts/verify-doctor.py• L145-235 scripts/verify-doctor.py• L238-285 scripts/verify-doctor.py• L307-367 scripts/verify-doctor.py• L401-469
CI execution
Pull requests and pushes to main run the CI workflow. Source-level gates run across Linux, Windows, and macOS on Python 3.11 and 3.12. The browser paint comparison stays on one pinned Linux environment so pixel results use one rendering oracle.
Most verification steps use if: always() so the job summary reports the complete set of gate results even when an earlier check fails. A non-zero result still blocks a clean validation outcome. Pages publication runs from main after the repository reaches its publication boundary.
References: .github/…/ci.yml• L3-16 .github/…/ci.yml• L86-114 .github/…/ci.yml• L331-351 .github/…/ci.yml• L363-413 .github/…/pages.yml• L1-40 .maintainer-policy.json• L34-109
Change checklist
When these files or sections are changed, remember to consider these:
- Add a diagram type only when its verifier, example route, type reference, gallery tab, selection description, and canonical screenshot record can move together.
- Add or change a Schedule network example only when its task model, precedence links, CPM fields, fixed task grid, critical styling, and three theme variants remain synchronized.
- Change a quantitative chart only when declared values, shared scales, marks, labels, and type-specific conservation or ordering rules remain aligned.
- Add an event modeling or requirement traceability example only when IDs, visible headings, row or stage order, relationship endpoints, and gap labels remain consistent.
- Change SBGN, architecture delta, or service blueprint geometry only when bounds, grids, compartments, layers, visibility boundaries, and relationship endpoints still describe the drawn marks.
- Change Steps or Unit Grid layout only when the printed counts, reading order, equal dimensions, spacing, state fills, and focal treatment still agree.
- Change motion policy or its example only when the static frame, reduced-motion path, keyboard controls, accessible status, deterministic test path, and five policy steps remain present.
- Change a theme ramp, token, legend wording, or export font link only when both skins preserve contrast, polarity, family parity, and fallback order.
- Change a canonical example, screenshot renderer, or capture setting only when the PNG and manifest digests and dimensions are regenerated under the same renderer contract.
- Change a command, prompt, reference, package path, preset, split SKILL.md section, or import route only when docs sync can still resolve every route and packaged support file.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A declared value, ID, endpoint, or label does not match its drawn mark | The diagram renders but states a false relationship or loses trace meaning | Type-specific geometry and semantic verifiers fail closed |
| A schedule duration, precedence link, rank, or critical flag disagrees with the recomputed network | The project finish or critical path tells a different story from the visible task graph | verify-schedule-network.py recomputes the bounded model and checks task fields, ports, routes, and summaries |
| A transform, CSS geometry rule, hidden ancestor, or unsupported SVG feature moves or hides checked geometry | Source coordinates no longer describe what the reader sees | Diagram verifiers reject movement, hiding, and unbounded marks |
| An event or trace row has a missing relationship or a link that targets the wrong cell | The process or evidence chain appears complete when it is not | verify-event-modeling.py and verify-requirement-traceability.py check IDs, links, direction, and visible gap labels |
| SBGN arcs cross, touch, or connect the wrong glyph kinds | A process map can imply a false reaction or relation | verify-sbgn.py checks arc kinds, endpoints, route contact, containment, and visibility |
| Motion lacks a complete static or reduced-motion path | Some readers lose the diagram or its state meaning | verify-semantic-motion.py checks fallbacks, controls, status, and deterministic states |
| A theme ramp or state fill loses contrast or reverses its stated polarity | Marks or labels become unreadable or change meaning across skins | Contrast, polarity, waterfall, and Unit Grid gates measure the declared theme contract |
| A canonical source changes without a screenshot and manifest refresh | The committed visual record describes an old example | verify-screenshot-freshness.py compares source and PNG digests, order, renderer, and dimensions |
| A gallery tab, reference route, packaged path, preset, or export surface drifts | Users see an unreachable example or an incorrect install or export contract | verify-docs-sync.py checks routes, support files, counts, presets, fonts, and surface parity |
Key files
| File | Why to read it |
|---|---|
| .github/…/ci.yml | Defines the source gates and pinned browser gate. |
| scripts/lint-render.py | Shows how browser paint, overflow, clipping, runtime errors, and isolation are checked. |
| scripts/verify-geometry.py | Provides the repository entry point for the packaged geometry checker. |
| scripts/verify-event-modeling.py | Defines ordered command, event, read-model stages and their arrows. |
| scripts/verify-requirement-traceability.py | Defines source, requirement, design, and test links. |
| scripts/verify-sbgn.py | Defines SBGN glyph bounds, compartments, arc direction, and route checks. |
| scripts/verify-architecture-delta.py | Defines before-and-after grids, identities, containment, and relationship coverage. |
| scripts/verify-service-blueprint.py | Defines visibility-line, stage-grid, layer, census, and printed-label checks. |
| scripts/verify-steps.py | Defines equal rail segments, stage numbers, medallions, and focal treatment. |
| scripts/verify-unit-grid.py | Defines equal cells, counts, reading order, spacing, and state fills. |
| scripts/verify-semantic-motion.py | Defines semantic-pattern, controller, static fallback, and accessibility checks. |
| scripts/verify-mermaid-import.py | Defines Mermaid import meaning, safety, limits, encoding behavior, and documentation wiring. |
| scripts/verify-schedule-network.py | Defines the bounded CPM model and the visible task, link, route, and summary contract. |
| scripts/css_property_scan.py | Defines the shared check that prevents escaped CSS property names from hiding geometry rules. |
| scripts/verify-docs-sync.py | Defines the contract between examples, skill text, manifests, gallery, package surfaces, routes, fonts, sizes, and references. |
| scripts/verify-screenshot-freshness.py | Defines canonical source, screenshot, renderer, and manifest consistency. |
| docs/diagram-verification-suite.md | Describes checker coverage and visual regression behavior. |
| docs/ci-and-pages-automation.md | Describes workflow execution and publication. |
| .github/…/pages.yml | Shows the publication boundary for gallery assets. |
| .maintainer-policy.json | Declares the local quality suite and merge gates. |