Make the Artifact Tell the Truth

For Diagram Design, the last mile is not a file-format afterthought. The specific question is how one semantic figure can remain coherent when it becomes HTML for a browser, SVG for vector tools, PNG for a slide, or a machine-readable registry for traceability. Following that path shows what the system can verify—accessibility, geometry, declarations, and rendering—and what still requires a person to judge whether the chosen figure tells the right story.

HTML is the source of truth

Diagram Design treats HTML as the authored artifact and the other deliverables as views derived from it. The file contains the page wrapper, CSS, and inline SVG, so a reader can open it without a build step or an application-specific project. The diagram's title and description live with the SVG, and its semantic roles, geometry, and content are present before any export begins.

That arrangement solves a familiar maintenance problem. If an author separately edits an HTML preview, an SVG handoff, and a PNG for a deck, the three files can drift. One may receive a corrected label while another keeps an obsolete connector. One may use the current brand tokens while another preserves the old palette. The repository's rule is simpler: make the HTML authoritative, then derive the requested format from that artifact.

The derivation is intentionally narrow. SVG export extracts the diagram's SVG, preserves its accessible title and description, adds the namespace needed for a standalone vector file, and injects an XML-safe font import. Browser-oriented color expressions such as rgba and transparent are normalized for consumers that do not interpret them reliably. The editorial wrapper—page heading, summary cards, and footer—is not included. An SVG export is the diagram, not a screenshot of the entire page.

PNG export renders the original HTML and captures the SVG's bounding box rather than screenshotting a guessed region. It uses a device scale factor for crisp output and a transparent background so the image can sit on a slide or document with a different paper color. The procedure waits for fonts before capture. This keeps the browser's font loading behavior in the path instead of pretending that a vector parser and a browser will always substitute the same face.

That last caveat matters. An offline vector tool may not fetch the public fonts used by the HTML, so an SVG can be structurally correct while looking typographically different in another application. PNG gives a more portable pixel result when exact appearance matters, but it gives up vector editability. The system does not hide that trade-off behind a generic “export complete” message.

Export is also manual. Generating a diagram does not silently create every possible file beside it, and the export procedure does not modify the HTML or add buttons and scripts. This preserves a clean authoring boundary: the requested output is produced deliberately, and the source remains inspectable.

Traceability adds a second view, not a second source

Some diagrams need more than a picture. A decomposition used for an audit, compliance record, or intellectual-property document may need each structural block to have a stable identifier, a parent, inputs, outputs, constraints, assumptions, and an implementation path.