3.6 KiB
3.6 KiB
Research synthesis: enterprise technical-document diagrams
Observed enterprise practice
- AWS publishes official architecture icons and explicitly supports common drawing tools including diagrams.net/draw.io and Figma. Its guidance frames diagrams as communication of design, deployment, and topology.
- Microsoft Azure's Well-Architected guidance emphasizes selecting and layering diagram types by message, audience, and lifecycle; directional arrows; clear labels; consistency; legends; accessibility; progressive disclosure; and version-controlled source files. Azure also distributes official SVG architecture icons and asks authors to keep product names with icons and avoid distortion.
- Google Cloud distributes official product icons in SVG and PNG for architecture diagrams and documentation.
- IBM Cloud identifies draw.io as an approved design tool and also publishes SVG and presentation assets.
- Oracle Cloud publishes architecture toolkits for draw.io, Visio, and PowerPoint and exposes editable DRAWIO plus SVG versions for reference architectures.
- GitHub renders Mermaid in Markdown and supports additional structured visual formats. GitLab supports Mermaid, PlantUML, Kroki, and diagrams.net content in documentation/wiki workflows.
The shared pattern is not a single winning authoring format. It is a source-preserving pipeline: official semantics/iconography, editable source, and a stable publication artifact.
Why the harness uses an intermediate representation
Direct generation into draw.io XML, Mermaid, or SVG couples semantic reasoning to tool syntax and makes factual review difficult. VizSpec creates a review boundary:
- document context and evidence;
- semantic intent and relationships;
- deterministic layout/rendering;
- visual and accessibility quality gates.
This supports multiple agent hosts and multiple output ecosystems without allowing format-specific details to become undocumented facts.
Relevant research principles
- The “Physics of Notations” framework argues that cognitively effective visual notations require semantic clarity, perceptual discriminability, semantic transparency, manageable visual complexity, cognitive integration, and related principles.
- Multimedia-learning research supports coherence (remove irrelevant material), signaling (make organization and essentials visible), and spatial contiguity (place words near the graphics they explain).
- Graph-drawing research repeatedly treats crossings, bends, edge length, and layout regularity as major readability variables.
- W3C accessibility guidance requires text alternatives for non-text content and sufficient contrast for meaningful non-text visual information. Complex diagrams need structured descriptions beyond a short alt phrase.
Source set used for the design
Primary vendor/documentation sources reviewed:
- AWS Architecture Icons and Architecture Center
- Microsoft Azure Well-Architected Framework: Architecture design diagrams; Azure Architecture Icons
- Google Cloud Architecture Center and Cloud icon library
- IBM Cloud design resources
- Oracle Cloud Infrastructure architecture diagram toolkits and reference architectures
- GitHub Docs: Creating diagrams in Markdown
- GitLab Docs: Mermaid, PlantUML, Kroki, and diagrams.net integrations
- Mermaid, D2, Graphviz, Structurizr/C4, diagrams.net, and Excalidraw official documentation
- W3C Web Content Accessibility Guidelines and WAI complex-images guidance
The executable policy in this repository is intentionally stricter than any single source: it combines evidence grounding, accessible output, source preservation, and agent-host portability.