Skip to content

Diagrams

A diagram on a status page earns its place by showing a mechanism the prose cannot: who calls whom, what is temporary versus permanent, what a security predicate actually filters. A box-and-arrow decoration of the section heading does not.

Conventions

Hand-author inline SVG. No charting library, no diagramming library, no external image. A library cannot be embedded in a single self-contained file without dragging its runtime in, and an external image breaks the one-file rule.

Size with viewBox; let CSS scale it. Align to a 10-unit grid.

Colour with currentColor. Strokes and text inherit, so every diagram re-themes for free. Reserve one literal accent for the single element that actually carries meaning.

One arrowhead marker per diagram, unique id, referenced by marker-end. Ids collide across diagrams on the same page if you reuse them.

One figure, one claim. Wrap every diagram in <figure> + <figcaption>, give the <svg> role="img" and an aria-label carrying the same claim as the caption. If you cannot write the caption, the diagram is not saying anything.

Encode structure consistently across every diagram on the page. Solid border = persistent, current, live. Dashed border = temporary, shadowed, bypassing, or not yet committed. The status fills mean the same thing everywhere.

Label every arrow with what actually flows — a verb or a concrete fact ("writes", "pulls", "TTL 2–4h"). Never leave a line unlabeled.

Traps

font-size presentation attributes lose to CSS. .dia-mono { font-size: 10.5px } overrides every font-size="9" on an element carrying that class, because a presentation attribute has lower priority than any CSS rule. This is silent — the attribute sits there looking correct. On the page this skill came from, seven attributes were dead. Step a label down with a class:

.dia-xs { font-size: 9px; }
.dia-s  { font-size: 9.5px; }
.dia-m  { font-size: 11.5px; }

Labels overflow their boxes, and you cannot see it in the markup. A 23- character monospace label at 10.5px is about 145px wide; a 140px box does not hold it. The verifier measures every label against the box it sits in — run it.

Fix a row, not a label. When one sub-label overflows, step the whole row of sub-labels down together. Fixing the single offender leaves one box in a row looking different, which reads as a mistake rather than a fix.

Lines cross labels. A vertical connector will run straight through text placed near it. Give the text a theme-aware halo rather than moving it:

<text paint-order="stroke" stroke="var(--surface)" stroke-width="3.5"
      stroke-linejoin="round" fill="currentColor">writes out application data</text>

Wide diagrams must scroll inside their own container, never the page body. Wrap in a .scroller with overflow-x: auto.

Animation

Rarely worth it. If you do animate:

  • Motion is decoration, never load-bearing. The diagram must read correctly fully static — numbered steps, static arrows, a plain-language caption.
  • Default to paused, with an explicit Play / Pause control. Never autoplay.
  • Respect prefers-reduced-motion: reduce by hiding the motion control entirely, not merely skipping the animation.
  • Animate transform on a wrapper via CSS @keyframes, not raw SVG attribute animation, and toggle animation-play-state from a small inline script.