Visual explainer

Visual explainer

Read first

Topic.md for the question, who it's for, what they should understand, the parts, the steps, the comparison and the numbers; the cover picture and anything else wired in.

The page, in order

1. The answer first: the question as the title, the answer in one or two plain sentences, and the wired cover picture.
2. The big picture: one diagram of the whole system in inline SVG, the parts as labelled boxes, arrows for what flows between them, each arrow labelled with what moves (money, data, a request). Nine boxes at most.
3. Step by step: the steps from Topic.md as a numbered flow (a vertical timeline, or cards joined by arrows), each with a short title, one or two sentences and the part it happens in, in that part's colour from the diagram.
4. Compared: a table or side-by-side cards for the comparison in Topic.md.
5. The numbers: three or four key figures from Topic.md as large stats with one line each.
6. Words to know: each term the page uses, in one line.
7. A recap in one short paragraph, and where to read more if Topic.md has sources.

Diagrams

• Built by hand in inline SVG, never pictures of text or external libraries: rounded boxes sized to their labels (no label runs past its box), clear arrowheads, labels in the page's font at a readable size, one colour per kind of part, used the same way in every diagram and step.
• One idea per diagram, read left to right on wide screens and top to bottom under 700 px (the same boxes, stacked), with no crossing arrows and nothing cut off.
• Hovering or tapping a part highlights it and its steps, with a small script; everything reads without it.

Look

• Calm and editorial: one typeface family, a clear scale (44 / 26 / 17), lines under 70 characters, generous space, a light background with Topic.md's accent colour (or dark if it asks), and parts told apart by tints of that one colour and by their labels, not by new colours.
• Responsive from 360 px wide: a diagram scales down or scrolls sideways inside its own box, never shrinking its labels below 12 px.
• Real headings, a title and description in each SVG, and colour never the only way two things are told apart.

Words

Short, plain sentences for the reader in Topic.md, an analogy where it helps, and every fact from Topic.md: nothing made up.

Avoid

Walls of text, diagrams that decorate instead of explain, more than nine boxes in one diagram, invented numbers, unexplained jargon, and stock imagery.