Technical visualization principles

1. One dominant question

A diagram is not a decorated inventory. It is an answer to one reader question. Put that question in VizSpec and make the title state the takeaway. When two questions require different abstraction levels or reading orders, generate two diagrams.

2. Semantic correctness before aesthetics

A visually polished but undocumented relationship is misinformation. Nodes and edges therefore carry source-line evidence. The harness blocks ungrounded elements unless they are explicitly marked as assumptions.

3. Progressive disclosure

Use a small context or overview diagram first, then separate component, deployment, sequence, or data-flow views. Avoid a single “everything diagram.” Twelve nodes and eighteen edges are review thresholds, not goals.

4. Visual grammar

Nodes are noun phrases and represent things with stable identity or responsibility.
Edges are directional and labeled with verbs, protocols, events, or data.
Boundaries represent system scope, trust, network, ownership, region, or lifecycle—not arbitrary decoration.
Shape differences must correspond to meaningful categories.
Official vendor icons represent exact named services only; generic shapes represent implementation-independent concepts.
Do not encode unrelated meanings with the same visual variable.

These rules operationalize cognitive-effectiveness principles such as semiotic clarity, perceptual discriminability, semantic transparency, visual expressiveness, graphic economy, and cognitive integration.

5. Layout

Prefer left-to-right for process and data flow.
Prefer top-to-bottom for hierarchy and deployment.
Keep the main path visually straight.
Minimize crossings, bends, long return edges, and edge-node overlap.
Place labels next to the element they describe.
Align related nodes and use whitespace to expose grouping.
Use explicit arrows; avoid bidirectional arrows unless both directions truly share one semantic label.

6. Signaling and coherence

Remove decorative content that does not improve comprehension. Highlight the main path through placement, hierarchy, and concise labels rather than excessive color. Put explanatory labels adjacent to the relevant component or edge.

7. Accessibility

The SVG contains a <title> and <desc>.
Markdown includes concise alt text and a separate long description for complex structure.
Do not rely on color alone; pair category with shape, line style, labels, or grouping.
Maintain at least 3:1 contrast for meaningful non-text boundaries and indicators.
Avoid tiny labels; review at the actual documentation width.

8. Versioning and staleness

Store the canonical VizSpec, source-document hash, generated outputs, and manifest in version control. Regenerate when nearby prose changes. Review source and visualization in the same pull request.

2.8 KiB Raw Blame History