6.7 KiB
6.7 KiB
Source catalog
Reviewed on 2026-07-23. This catalog favors first-party vendor documentation, official project documentation, standards, and primary research.
Enterprise documentation and architecture-diagram practice
| Source | What was extracted for the harness |
|---|---|
| Microsoft Azure Well-Architected Framework — Create architecture design diagrams | Choose a diagram type for the message and audience; use progressive disclosure, explicit directional arrows, clear labels, consistent notation, accessibility, and version-controlled source. |
| AWS Architecture Icons | Architecture diagrams communicate design, deployment, and topology; use current official product icons and keep iconography simple. |
| AWS Reference Architecture Diagrams | Reference diagrams pair the visual with numbered explanatory flow and, in many cases, an editable source package. |
| Google Cloud icon library | Official product and category icons are distributed as SVG and PNG assets. |
| IBM Cloud — Documenting your environment architecture | IBM explicitly lists multiple valid authoring tools, including IBM design tools, draw.io, Mural, Mermaid, presentation tools, and vector editors. |
| Oracle Cloud Infrastructure Architecture Diagram Toolkits | OCI distributes toolkits in PowerPoint, draw.io, and Visio, with service icons, templates, examples, and guidance. |
| GitHub Docs — Creating diagrams | Mermaid can live directly in Markdown and is suitable for repository-adjacent, text-reviewed diagrams. |
| GitLab Flavored Markdown — Diagrams and flowcharts | GitLab supports Mermaid, PlantUML, Kroki, and diagrams.net editing in wiki workflows, demonstrating a heterogeneous diagram toolchain. |
| Structurizr features | A single architecture model can generate multiple consistent views; static SVG/PNG and code-oriented exports can coexist. |
Diagram formats and rendering ecosystems
| Source | Relevant capability |
|---|---|
| SVG 2 specification | Vector publication format with text, structure, and accessibility hooks. |
| Mermaid documentation | Text-based flow, sequence, state, ERD, and other diagram families. |
| D2 documentation | Text-to-diagram workflow with automatic layout and SVG/PNG/PDF export. |
| Graphviz documentation | Mature graph layout for dependency and dense relationship graphs. |
| diagrams.net documentation | Broad stencil ecosystem and manual enterprise diagram editing. |
| Excalidraw developer documentation | Editable JSON scene model and informal whiteboard-style visual language. |
| Structurizr — Why “as code”? | Version-controlled C4 models, multiple abstraction levels, and renderer-independent architecture semantics. |
Agent-host packaging
| Source | Harness implication |
|---|---|
| OpenAI Codex — Skills and plugins | Package the repeatable workflow as a reusable skill and keep deterministic implementation in scripts/CLI. |
| Claude Code — Extend Claude with skills | Claude Code follows the open Agent Skills standard and loads task-specific SKILL.md instructions. |
| Claude Code — Project memory | Keep durable repository rules in CLAUDE.md; keep procedural detail in a skill. |
| Google Antigravity — Agent Skills | Workspace skills live at .agents/skills/<skill>/SKILL.md and can bundle instructions, scripts, and references. |
| Google Antigravity CLI best practices | Use AGENTS.md or GEMINI.md for repository-wide rules. |
| AGENTS.md | A model-neutral repository instruction file reduces host-specific duplication. |
Accessibility standards
| Source | Harness requirement |
|---|---|
| WCAG 2.2 Quick Reference — 1.1.1 Non-text Content | Every diagram needs an equivalent text alternative; complex diagrams need both a short description and a longer equivalent description. |
| W3C WAI — Designing for Web Accessibility | Do not use color as the only information channel; provide sufficient contrast, grouping, and media alternatives. |
| WCAG 2.2 — 1.4.11 Non-text Contrast | Meaningful graphical objects and states require adequate contrast against adjacent colors. |
Cognitive and graph-readability foundations
| Source | Principle applied |
|---|---|
| Daniel L. Moody, “The Physics of Notations”, IEEE Transactions on Software Engineering, 2009 | Semantic clarity, perceptual discriminability, semantic transparency, complexity management, graphic economy, dual coding, and cognitive integration. |
| Richard E. Mayer, Multimedia Learning, 3rd ed., Cambridge University Press, 2021 | Coherence, signaling, spatial contiguity, and segmenting/progressive disclosure. |
| Helen C. Purchase, “Which aesthetic has the greatest effect on human understanding?”, Graph Drawing, 1997 | Edge crossings, bends, and related graph aesthetics materially affect comprehension. |
Synthesis used by this repository
The reviewed organizations do not converge on one authoring extension. They converge on a workflow pattern:
- choose a visual abstraction for a specific reader question;
- use a consistent notation and current official icons where exact vendor products matter;
- preserve an editable source;
- publish a stable, accessible artifact;
- keep the diagram synchronized with the text and architecture lifecycle.
TechViz adds a stricter semantic layer before those formats: grounded VizSpec JSON with line-level evidence, deterministic compilation, and automated quality gates.