Diagram Approach Comparison

Reference page, not course content. Records why the three current tools were chosen, with the same diagram rendered in each so the difference is visible.

---

The split that decides everything

Mermaid and Graphviz are node-and-edge graph tools. They lay out boxes and connect them. They cannot draw a barbell, an iceberg or a set of concentric rings — there is no way to express those shapes in their language.

Tool	Schematic diagrams	Metaphor illustrations
Mermaid	yes	no
Graphviz	yes, best layout	no
Inline SVG	yes	yes

So the project runs two tools for two different jobs, plus a third held in reserve.

---

1. Inline SVG — schematic

Hand-written, no dependency, no build step. Note it follows the site theme: toggle light/dark and the arrows and text invert while the accent colours hold.

Three tiers by scope. Solid arrows down, dashed terracotta arrows up.

---

2. Inline SVG — metaphor

This is the category no graph tool can produce. Concentric rings for blast radius:

Four permission tiers by blast radius. Innermost safe, outermost forbidden.

And weight redistribution:

Same mass, redistributed. Middle-heavy becomes end-heavy.

---

3. Graphviz — rendered live

Produced by @viz-js/viz (WASM Graphviz 16.0.0), no binary installed. This is genuine Graphviz output, not a mock-up:

Genuine Graphviz output. Layout — spacing, edge routing, the curved return arrows — was computed entirely by the engine.

Note what it got right and wrong. The layout is genuinely good: it routed the two dashed return edges around the right side without being told how, and spaced the tiers evenly. But raw output hardcodes fill="#3f3f3f" on edges and labels, so it will not follow the dark theme. In the version above I hand-substituted var(--sl-color-text) afterwards — which is exactly the post-processing you would have to automate.

Source

digraph tiers {
  rankdir = TB;
  bgcolor = "transparent";
  node [shape=box, style="rounded,filled", fontname="Inter", fontcolor="white", penwidth=0];
  edge [fontname="Inter", fontsize=10];

  enterprise [label="Enterprise", fillcolor="#5B8FB9"];
  solution   [label="Solution",   fillcolor="#E8A33D", color="#C4832A", penwidth=3];
  system     [label="System",     fillcolor="#7D9A4E"];

  enterprise -> solution [label="sets constraints for"];
  solution   -> system   [label="sets constraints for"];

  system   -> solution   [style=dashed, color="#D9695B", constraint=false];
  solution -> enterprise [style=dashed, color="#D9695B", constraint=false];
}

Verdict on authorability: good, and the layout engine is the best available for dense graphs. But styling is fiddly, defaults are dated, and precise visual control means fighting it.

---

Summary

	LLM-authorable	Looks good	Theme-aware	Metaphors	Verdict
Mermaid	excellent	plain	yes, free	no	the default
Inline SVG	good	exact	yes, free	yes	for metaphors
Graphviz	good	dated	after post-processing	no	dense graphs only

Everything in the “Verdict” column was measured on this machine, not assumed.

Recommendation

Three tools, each with a clear trigger:

• Mermaid for node-and-edge diagrams — already installed, theme-aware for free, and it covers sequence and C4 diagrams that later modules will need.
• Inline SVG for the metaphor illustrations — the only option that can draw them, with exact palette control and no dependency.
• Graphviz (@viz-js/viz, already installed) held in reserve for a graph dense enough that automatic layout quality becomes the problem. Nothing in Module 1 is close to that threshold.

Two other tools were evaluated and rejected on measured evidence, then removed from the project. See CONTENT_AND_STYLE_GUIDE.md §6 and the git history before reintroducing either.