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 / diagram-self-validation

Diagram self-validation

Diagram self-validation is the skill-local check that keeps generated HTML diagrams safe, accessible, and usable before delivery. It combines output checks for the generated artifact with read-only structural extraction for Mermaid and draw.io sources, plus a manual SVG export path for portable diagram artifacts; repository verification remains the stronger gate for checked-in examples. For the wider skill model, see Diagram design skill.

Validation model

The validation model separates source understanding from artifact checking. Source helpers produce a structural digest before a redraw; self_check.py checks the resulting standalone HTML after it is written; the SVG helper checks the portable form when an export is requested.

This diagram shows the main path from source or output to the next validation step.

flowchart LR
    A[Diagram source or generated HTML] --> B{Artifact role}
    B -->|Mermaid or draw.io source| C[Extraction helper]
    C --> D[Structural digest or JSON IR]
    D --> E[Redraw and apply output choices]
    B -->|Generated HTML| F[Skill-local self-check]
    E --> F
    F --> G{Pass}
    G -->|No| H[Fix the artifact]
    H --> F
    G -->|Yes| I{SVG requested}
    I -->|Yes| J[SVG export and XML gate]
    I -->|No| K[Continue review and repository checks]
    J --> K

Source and output boundaries

Mermaid and draw.io helpers read source as content. They do not render it or make design choices. The self-check reads the generated HTML and verifies contracts that must hold in a standalone deliverable. The SVG helper creates a diagram-only file when the user asks for an export. It does not change the source HTML.

The boundary matters because source structure informs the redraw, but source layout and style do not become output requirements. For the wider import workflow, see Mermaid import and draw.io import.

References: skills/…/SKILL.md• L375-388 skills/…/import-mermaid.md• L13-30 skills/…/import-drawio.md• L13-33 skills/…/export.md• L1-27

Generated artifact checks

The skill-local checker is skills/…/self_check.py. Run it against each generated HTML file with python3 <skill-dir>/scripts/self_check.py <file>. A successful result means the file has an accessible SVG and follows the single-file safety rules.

The checker covers these contracts:

  • The SVG has role="img", a first-child title, a non-empty desc, and diagram-specific IDs named by aria-labelledby.
  • Remote references are rejected except for the approved Google Fonts stylesheet.
  • Embedded executable attributes, unsafe document elements, and extra scripts are rejected.
  • Motion markup uses one valid root, bounded steps, accessible semantic items, and the expected control script.
  • Motion files include static, reduced-motion, print, and no-script fallbacks.

The checker does not replace visual review or repository gates. Connector geometry, skin rules, and the full contribution checks need the repository tools described in Diagram verification suite.

References: skills/…/self_check.py• L1-13 skills/…/self_check.py• L214-365 skills/…/SKILL.md• L446-491

Standalone SVG export

The optional helper at skills/…/export_svg.py converts a generated HTML diagram into a standalone SVG. It carries diagram styles into the SVG, keeps accessible diagram content, isolates reusable definition IDs, and refuses an export that is not valid XML or that would lose class-based diagram styles. Run it only for an explicit export request with python3 scripts/export_svg.py <html-file> [<out.svg>] from the skill directory.

The export is diagram-only. Page headers, cards, and other editorial wrappers stay in the HTML. The helper also requires a viewBox instead of guessing the diagram size, so a failed export signals that the source needs correction rather than an automatic layout change.

References: skills/…/export_svg.py• L1-20 skills/…/export_svg.py• L344-375 skills/…/export_svg.py• L379-414 skills/…/export.md• L19-37

Structural extraction

Structural extraction turns an existing source diagram into a small intermediate representation (IR). An IR is a normalized description of nodes, links, groups, and useful structural signals. It gives the redraw process enough meaning to preserve without carrying over source coordinates, styling, or executable content.

Mermaid extraction

The helper at skills/…/mermaid_extract.py accepts .mmd, .mermaid, and Markdown files with fenced Mermaid blocks. It supports flowcharts, sequence diagrams, state diagrams, ER diagrams, and quadrant charts. It reads bounded UTF-8 text and can select the first block, one block by index, or all blocks in a Markdown file. It selects blocks before parsing them, so a valid selected block remains usable when another unselected block is malformed; --diagram all still parses every block strictly. Its output is a compact Markdown digest by default; --json provides the full IR and --out writes the same UTF-8 result to a file.

The IR keeps semantic nodes, links, groups, labels, shapes, declared direction, sequence fragments, ER fields, and quadrant titles, axes, quadrants, and points. Quadrant points retain normalized coordinates rather than invented layout positions. Its analysis adds counts, depth, hubs, entry points, terminals, unconnected nodes, cycles, collapsible groups, type candidates, and budget flags for the nine-node or twelve-edge limits and the twelve-point quadrant recommendation. It records discarded style and click directives, while Mermaid's layout-free source is reported without invented coordinates. For the import workflow that consumes this result, see Mermaid import.

References: skills/…/mermaid_extract.py• L1-18 skills/…/mermaid_extract.py• L32-55 skills/…/mermaid_extract.py• L216-264 skills/…/mermaid_extract.py• L1111-1179 skills/…/mermaid_extract.py• L1182-1347 skills/…/mermaid_extract.py• L1350-1414 skills/…/mermaid_extract.py• L1421-1579 skills/…/mermaid_extract.py• L1666-1688 skills/…/mermaid_extract.py• L1795-1810 skills/…/import-mermaid.md• L13-30

draw.io extraction

The helper at skills/…/drawio_extract.py accepts raw draw.io XML, compressed draw.io payloads, PNG files with embedded diagram data, and SVG files with embedded draw.io content. It can select one page by number or name, select all pages, emit a Markdown digest, or emit the full IR as JSON.

The digest preserves absolute node geometry as source evidence, shape families, container depth, links, waypoints, hubs, cycles, entry points, terminals, unconnected nodes, collapsible groups, and budget flags. These signals help choose a diagram type and detail level. The redraw still starts from a new layout and the current design system.

References: skills/…/drawio_extract.py• L1-19 skills/…/drawio_extract.py• L41-109 skills/…/drawio_extract.py• L162-187 skills/…/drawio_extract.py• L298-343 skills/…/drawio_extract.py• L587-676 skills/…/import-drawio.md• L13-33

Trust boundary

The extractors treat labels, links, directives, metadata, and embedded payloads as untrusted data. Their role is to report content, not to run content or obey instructions that appear inside a diagram.

Inert source content

Mermaid extraction discards source styling, front matter, directives, and click handlers while retaining safe label text. It also ignores quadrant accessibility prose and point styling while retaining point labels and coordinates. It never evaluates Mermaid, JavaScript, URLs, browser content, or directives. Draw.io extraction rejects unsafe XML declarations and bounds input and decompressed payload sizes before it builds the IR.

This protects both the engineer and the redraw process. A label can describe a command or contain hostile text, but it remains a label in the digest. A link can be reported as diagram content, but it is never opened as part of extraction.

References: skills/…/mermaid_extract.py• L1-17 skills/…/mermaid_extract.py• L267-312 skills/…/mermaid_extract.py• L732-743 skills/…/mermaid_extract.py• L1504-1547 skills/…/drawio_extract.py• L41-109 skills/…/drawio_extract.py• L62-67 skills/…/import-mermaid.md• L21-23 skills/…/import-drawio.md• L23-25

Bounded failure handling

Both helpers fail closed when the selected source is unreadable, unsupported, malformed, or above its resource limits. An exit code of 2 is an extraction error, not a partial result to redraw from.

For Mermaid, the caller reports the helper's error and stops when a selected block fails. An unselected malformed Markdown block is reported in the digest header as unparsed instead of blocking the selected result; selecting all makes that block fatal. A quadrant chart also fails when it has no points, duplicate point labels, invalid coordinates, or a malformed statement. For draw.io, the caller does the same when the file has no readable model, has invalid XML, has unsafe declarations, or has an invalid embedded payload. This keeps an incomplete digest from becoming an invented diagram.

References: skills/…/mermaid_extract.py• L32-39 skills/…/mermaid_extract.py• L216-229 skills/…/mermaid_extract.py• L332-337 skills/…/mermaid_extract.py• L412-450 skills/…/mermaid_extract.py• L1421-1579 skills/…/mermaid_extract.py• L1996-2008 skills/…/mermaid_extract.py• L2011-2016 skills/…/drawio_extract.py• L41-59 skills/…/drawio_extract.py• L162-187 skills/…/drawio_extract.py• L523-537

Validation handoff

Self-validation produces a pass or a concrete finding. A pass permits the next review stage; it does not claim that the diagram has good meaning, correct geometry, or a suitable visual type.

Local validation sequence

When an existing diagram is being redrawn, use this order:

  1. Extract the source with the matching helper.
  2. Review the digest or IR and set format, size, detail, and audience before drawing.
  3. Write the standalone HTML artifact.
  4. Run self_check.py from the installed skill directory.
  5. If the user requests an SVG, run export_svg.py and inspect the resulting diagram-only file.
  6. If the artifact is part of this repository, run the relevant repository checks as well. For import-tool changes, run the matching Mermaid, draw.io, or Excalidraw verification driver. Geometry is checked separately because the skill-local checker does not prove connector routing or label placement.
  7. Report any source content merged, collapsed, or dropped in the fidelity ledger.

This order prevents source styling or renderer layout from becoming a hidden constraint, and it keeps output problems close to the file that caused them. The export step is optional and does not replace the HTML self-check.

References: skills/…/SKILL.md• L375-388 skills/…/SKILL.md• L446-491 skills/…/SKILL.md• L531-555 skills/…/export.md• L29-37 skills/…/import-mermaid.md• L32-75 skills/…/import-drawio.md• L35-115

Import verification drivers

The import verification drivers check the extractor and the workflow around it. They run the shipped helper against normal, malformed, adversarial, and bounded inputs. They also check lossless UTF-8 output, --out parity, documentation, command wiring, and the worked example. The Mermaid driver additionally protects parser behavior for link forms, bidirectional analysis, node updates, invisible layout links, state and ER declarations, Unicode content, and nested sequence highlighting. Run python3 scripts/verify-mermaid-import.py for Mermaid changes, python3 scripts/verify-drawio-import.py for draw.io changes, or python3 scripts/verify-excalidraw-import.py for Excalidraw changes. The Excalidraw driver also checks scene structure, bound labels, groups, edge direction, dangling edges, adversarial labels, resource limits, and mobile containment. A passing driver confirms the import contract; it does not replace artifact review or visual and geometry checks.

References: scripts/verify-mermaid-import.py• L48-65 scripts/verify-mermaid-import.py• L68-126 scripts/verify-mermaid-import.py• L745-879 scripts/verify-mermaid-import.py• L882-895 scripts/verify-mermaid-import.py• L1191-1253 scripts/verify-mermaid-import.py• L1256-1465 scripts/verify-mermaid-import.py• L1467-1497 scripts/verify-drawio-import.py• L53-63 scripts/verify-drawio-import.py• L66-128 scripts/verify-drawio-import.py• L351-515 scripts/verify-drawio-import.py• L518-528 scripts/verify-excalidraw-import.py• L48-75 scripts/verify-excalidraw-import.py• L118-187 scripts/verify-excalidraw-import.py• L299-362 scripts/verify-excalidraw-import.py• L365-456 scripts/verify-excalidraw-import.py• L459-540 scripts/verify-excalidraw-import.py• L543-665

Diagnostic interpretation

Read a FAIL line as a contract violation in the artifact, not as proof that the source is wrong. Fix the generated HTML and run the same command again. Read an extractor exit-2 message as a source boundary: ask for a supported or complete source instead of guessing missing nodes or links.

The repository geometry check has a narrower role. It detects a label mask that a later-painted node can cover, while the self-check focuses on accessibility, safety, and motion structure. Together with visual review and the repository verification suite, these checks cover different failure classes rather than repeating one gate. Use Diagram diagnostics when a result needs a focused explanation.

References: skills/…/self_check.py• L353-385 scripts/verify-geometry.py• L1-30 scripts/verify-geometry.py• L111-164 skills/…/import-mermaid.md• L102-113 skills/…/import-drawio.md• L146-157 diagram-diagnostics.md

Change checklist

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

  • Changes to the accessible SVG contract in SKILL.md must stay aligned with self_check.py and every generated example's title, desc, and prefixed IDs.
  • Changes to motion metadata or the canonical controller must stay aligned with self_check.py and assets/template-motion.html, including static, print, reduced-motion, and no-script states.
  • Changes to SVG class names, page style rules, viewBox requirements, or reusable definition IDs must stay aligned with export_svg.py and references/export.md; exported fragments must keep diagram styles and isolated references.
  • Changes to supported Mermaid grammars, link semantics, node updates, invisible links, state or ER declarations, quadrant titles, axes, labels, point coordinates, fenced-block selection, front matter or directive handling, semantic node and edge fields, discarded source fields, digest fields, output encoding, or selection flags must stay aligned with references/import-mermaid.md and the Mermaid verification driver.
  • Changes to draw.io container formats, page selection, digest escaping, output encoding, or embedded payload limits must stay aligned with references/import-drawio.md and the draw.io verification driver.
  • Changes to Excalidraw scene parsing, edge binding semantics, discarded-content counts, resource limits, UTF-8 output, or example containment must stay aligned with scripts/verify-excalidraw-import.py and the Excalidraw import surfaces.
  • Changes to connector or label-mask rules need the repository geometry checks; a passing skill-local self-check does not cover them.

Important failure modes

TriggerConsequenceGuard
Generated SVG lacks a usable title/desc relationshipAssistive technology cannot identify the diagram reliablyself_check.py checks the first-child title, non-empty text, prefixed IDs, and aria-labelledby order
Generated HTML includes an unapproved remote asset or executable attributeA standalone artifact can fetch unexpected content or run unsafe behaviorself_check.py rejects remote references, unsafe elements, and on* attributes
Motion markup has missing steps, hidden fallback items, or the wrong controllerPlayback and the complete static frame can disagreeself_check.py checks step continuity, accessible labels, fallback visibility, and the canonical controller
SVG export has no viewBoxThe helper cannot preserve a known drawing size and refuses to guessexport_svg.py stops before writing the export
SVG export keeps classes but loses diagram CSSClass-styled shapes can render as black or lose their intended typeexport_svg.py carries scoped diagram rules and rejects a class-based fragment without them
Several exported SVGs reuse definition IDsMarkers, filters, or other shared resources can resolve to the wrong figureexport_svg.py prefixes definition IDs and rewrites matching references
Selected Mermaid source uses an unsupported grammar, malformed edge or quadrant statement, invalid UTF-8 input, invalid point data, or exceeds a source, statement, node, edge, or point limitThe redraw would start from incomplete or guessed structuremermaid_extract.py exits 2; report the message and stop; use --diagram all when every Markdown block must pass
Mermaid link, node, state, ER, quadrant, or Unicode parsing changes without matching driver coverageThe structural digest can silently lose meaning before redrawverify-mermaid-import.py exercises the supported grammar and regression cases, then fails the driver
Draw.io input has unsafe XML, bad embedded data, or an oversized decoded payloadParsing can be unsafe or resource-heavydraw.io_extract.py rejects DTD/entity declarations and applies input and decoded-size limits
Excalidraw input has malformed scene data, unsupported export form, invalid geometry, or too many elementsThe import cannot produce a trustworthy scene modelverify-excalidraw-import.py requires specific exit-2 errors and checks the documented resource caps
Excalidraw labels contain prompt-like text or external payloadsUntrusted source content could be mistaken for instructions or leak through the digestverify-excalidraw-import.py checks that labels stay escaped and inert while links and payloads stay out
Extractor output is sent through a legacy encoding or differs between stdout and --outNon-ASCII labels can be lost or saved output can differ from the reviewed digestThe import verification drivers compare UTF-8 stdout with --out and check caller-owned stdout
A label mask overlaps a later-painted nodeThe node fill clips the label into an unreadable fragmentRun scripts/verify-geometry.py for repository artifacts

Key files

FileWhy to read it
skills/…/SKILL.mdDefines the self-validation checklist, import boundary, export rule, connector rules, and the split between skill-local and repository checks
skills/…/self_check.pyDefines the installed-skill output gate for accessible SVG, safe single-file HTML, and motion structure
skills/…/export_svg.pyDefines the manual HTML-to-SVG export gate, style carry-over, XML normalization, and reference isolation
skills/…/mermaid_extract.pyDefines the normalized Mermaid source model, selected-block parsing, quadrant handling, and digest or JSON output
skills/…/drawio_extract.pyDefines draw.io payload decoding, page selection, normalized structure, and structural signals
skills/…/export.mdExplains the portable SVG and PNG export contract and its diagram-only scope
skills/…/import-mermaid.mdExplains how Mermaid extraction feeds type choice, redraw, and delivery
skills/…/import-drawio.mdExplains how draw.io extraction feeds type choice, redraw, and delivery
skills/…/template-motion.htmlProvides the canonical motion controller and the complete static and accessible motion states
scripts/verify-geometry.pyChecks a geometry defect that the skill-local self-check does not cover
scripts/verify-mermaid-import.pyVerifies Mermaid parsing, safety and limit cases, UTF-8 output, documentation, command wiring, regression behavior, and the worked example
scripts/verify-drawio-import.pyVerifies draw.io parsing, payload and digest safety, UTF-8 output, documentation, command wiring, and the worked example
scripts/verify-excalidraw-import.pyVerifies Excalidraw scene parsing, safety and limit cases, UTF-8 output, documentation, command wiring, and the worked example