Connector Overlay (HTML/CSS)
Best for: showing how components actually reach each other — sync calls, async events, and the one
dependency that is only allowed to go one way
Avoid when: containment is the point and nothing calls anything → nested-zones.md already encodes
reachability by nesting, and arrows on top of it would be a second, contradicting diagram
Answers: which component talks to which, in which direction, and where the fan-in is
Data Shape
Components are absolutely positioned at known coordinates inside a position: relative canvas, and one
absolutely positioned <svg> sits over them with pointer-events: none. Each component gets an id, and
each connector is a <path> whose d is a chain of M and L between those components' edges.
The one rule that matters: connectors are orthogonal — strictly horizontal and vertical segments, no
diagonals and no curves. <line>, Bézier C/S/Q commands and diagonal paths all look hand-drawn next
to right angles, and a diagram of right angles reads as a system rather than a sketch.
Key Options
| Option | Effect |
|---|---|
viewBox="0 0 w h" matching the canvas |
The SVG scales with the figure instead of drifting out of alignment |
pointer-events: none on the overlay |
Links never intercept a selection or a link inside a box |
| Two markers, open and filled | Open reads as "eventually"; filled reads as "and it must succeed" |
stroke-dasharray for async links |
Line style is a second channel, so the diagram still reads in greyscale |
| Labels on the horizontal run of a path | Vertical runs are too narrow to hold text without colliding with the line |
| A legend strip under the canvas | Two line styles do not need to be decoded from context |
Pitfalls
- ❌ Diagonal or curved connectors → ✅ right angles only; this is the single most recognisable tell of a hand-made HTML architecture diagram
- ❌ Omitting the canvas height → ✅ absolute children collapse the parent, the SVG ends up zero-height, and every connector disappears while the boxes still look fine
- ❌ Forgetting
pointer-events: none→ ✅ the overlay silently swallows clicks over the whole figure - ❌ Connector labels placed on a vertical run → ✅ put them on the horizontal run, and offset the path's mid-segment so two links do not share it
- ❌ Drawing both containment bands and a full set of arrows → ✅ pick one; nesting already means reachability
- ❌ More than about eight connectors → ✅ at that density the crossings carry more information than the links do; split the figure
Alternatives
| Variant | Use instead |
|---|---|
| Containment rather than calls | nested-zones.md |
| Stage order rather than pairwise calls | pipeline-stages.md |
| Dependencies a diagram engine can lay out for you | PlantUML examples in dependencies-and-relations |