# 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:

1. document context and evidence;
2. semantic intent and relationships;
3. deterministic layout/rendering;
4. 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.