init: technical-visualization-haness 하네스 설계

2026-07-24 14:02:50 +09:00
parent 09d7c594da
commit f43e909162
117 changed files with 10150 additions and 1 deletions
@@ -0,0 +1,46 @@
+# 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.