2.6 KiB
2.6 KiB
Format and tool selection
The harness separates semantic source, editable source, and publication artifact.
| Format | Best use | Strengths | Failure mode / constraint |
|---|---|---|---|
| VizSpec JSON | Canonical meaning and evidence | Tool-neutral, lintable, traceable, deterministic | Not intended for manual presentation |
| SVG | Default publication in web/Markdown/docs | Scalable, searchable, accessible metadata, text diff | Keep scripts, external references, and foreignObject out |
| draw.io / diagrams.net | Enterprise architecture and official cloud stencils | Familiar manual editing, strong connector semantics, broad vendor libraries | Plain exported SVG loses editing semantics unless diagram data/source is preserved |
| Mermaid | Sequence, state, ERD, compact flow near Markdown | Small textual source, GitHub/GitLab rendering, easy review | Layout control and accessibility vary by renderer/version |
| D2 | Auto-laid-out architecture and data flow | Concise source, SVG-first output, good layout defaults | Requires D2 for native rendering beyond generated source |
| Graphviz DOT | Dense dependency and relationship graphs | Mature graph layout and crossing reduction | Less suitable for manual architecture storytelling |
| Excalidraw | Concept sketch, workshop, informal explanation | Fast visual ideation and approachable editing | Hand-drawn semantics can imply lower precision; JSON diffs are noisy |
| Structurizr DSL / C4 | Multiple architecture views from one model | One model can generate context/container/component/deployment views | Introduce when the repository needs a durable multi-view architecture model |
| PlantUML/Kroki | Broad diagrams-as-code ecosystems | Many diagram families and server rendering | Server/runtime dependency and syntax-specific portability |
| PNG | Compatibility fallback | Universal display | Raster, weak accessibility, poor scaling; never the only source |
| Print and controlled distribution | Stable pagination and vector output | Weak as an editable or repository-native source |
Default policy
- Always preserve VizSpec JSON.
- Always publish SVG unless the target platform forbids it.
- Preserve one editable source selected by intent:
- architecture/deployment/network → draw.io;
- sequence/state/ERD/compact flow → Mermaid;
- data-flow/auto-layout architecture → D2;
- dense dependency → DOT;
- conceptual workshop visual → Excalidraw.
- Generate PNG or PDF only as downstream delivery formats.
- Use official provider icon packs only for explicitly named services; keep the provider's product label visible.