69 lines
6.8 KiB
Markdown
69 lines
6.8 KiB
Markdown
# 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](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/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](https://aws.amazon.com/architecture/icons/) | Architecture diagrams communicate design, deployment, and topology; use current official product icons and keep iconography simple. |
|
|
| [AWS Reference Architecture Diagrams](https://aws.amazon.com/architecture/reference-architecture-diagrams/) | Reference diagrams pair the visual with numbered explanatory flow and, in many cases, an editable source package. |
|
|
| [Google Cloud icon library](https://cloud.google.com/icons) | Official product and category icons are distributed as SVG and PNG assets. |
|
|
| [IBM Cloud — Documenting your environment architecture](https://cloud.ibm.com/docs/openshift?topic=openshift-document-environment) | 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](https://docs.oracle.com/en-us/iaas/Content/General/Reference/graphicsfordiagrams.htm) | OCI distributes toolkits in PowerPoint, draw.io, and Visio, with service icons, templates, examples, and guidance. |
|
|
| [GitHub Docs — Creating diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) | Mermaid can live directly in Markdown and is suitable for repository-adjacent, text-reviewed diagrams. |
|
|
| [GitLab Flavored Markdown — Diagrams and flowcharts](https://docs.gitlab.com/user/markdown/#diagrams-and-flowcharts) | GitLab supports Mermaid, PlantUML, Kroki, and diagrams.net editing in wiki workflows, demonstrating a heterogeneous diagram toolchain. |
|
|
| [Structurizr features](https://docs.structurizr.com/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](https://www.w3.org/TR/SVG2/) | Vector publication format with text, structure, and accessibility hooks. |
|
|
| [Mermaid documentation](https://mermaid.ai/open-source/intro/) | Text-based flow, sequence, state, ERD, and other diagram families. |
|
|
| [D2 documentation](https://d2lang.com/) | Text-to-diagram workflow with automatic layout and SVG/PNG/PDF export. |
|
|
| [Graphviz documentation](https://graphviz.org/documentation/) | Mature graph layout for dependency and dense relationship graphs. |
|
|
| [diagrams.net documentation](https://www.drawio.com/doc/) | Broad stencil ecosystem and manual enterprise diagram editing. |
|
|
| [Excalidraw developer documentation](https://docs.excalidraw.com/) | Editable JSON scene model and informal whiteboard-style visual language. |
|
|
| [Structurizr — Why “as code”?](https://docs.structurizr.com/as-code) | Version-controlled C4 models, multiple abstraction levels, and renderer-independent architecture semantics. |
|
|
|
|
## Agent-host packaging
|
|
|
|
| Source | Harness implication |
|
|
|---|---|
|
|
| [OpenAI Codex — Build skills](https://developers.openai.com/codex/build-skills) | Repository skills live under `.agents/skills`; package the repeatable workflow as a focused `SKILL.md` bundle and keep deterministic implementation in scripts/CLI. |
|
|
| [Claude Code — Extend Claude with skills](https://code.claude.com/docs/en/skills) | Claude Code follows the open Agent Skills standard and loads task-specific `SKILL.md` instructions. |
|
|
| [Claude Code — Project memory](https://code.claude.com/docs/en/memory) | Keep durable repository rules in `CLAUDE.md`; keep procedural detail in a skill. |
|
|
| [Google Antigravity — Agent Skills](https://antigravity.google/docs/skills) | Workspace skills live at `.agents/skills/<skill>/SKILL.md` and can bundle instructions, scripts, and references. |
|
|
| [Google Antigravity CLI best practices](https://antigravity.google/docs/cli/best-practices) | Use `AGENTS.md` or `GEMINI.md` for repository-wide rules. |
|
|
| [AGENTS.md](https://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](https://www.w3.org/WAI/WCAG22/quickref/#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](https://www.w3.org/WAI/tips/designing/) | 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](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) | 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”](https://doi.org/10.1109/TSE.2009.67), 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.](https://www.cambridge.org/core/books/multimedia-learning/), Cambridge University Press, 2021 | Coherence, signaling, spatial contiguity, and segmenting/progressive disclosure. |
|
|
| Helen C. Purchase, [“Which aesthetic has the greatest effect on human understanding?”](https://doi.org/10.1007/3-540-63938-1_67), 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:
|
|
|
|
1. choose a visual abstraction for a specific reader question;
|
|
2. use a consistent notation and current official icons where exact vendor products matter;
|
|
3. preserve an editable source;
|
|
4. publish a stable, accessible artifact;
|
|
5. 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.
|