Catalog / Technique

Running diagram

Use when a case study claims something happens over time and a figure should carry it out: a state machine stepped, a request crossing an architecture, a queue hitting its bound, two parties agreeing and parting. Covers the still that makes the point with nothing pressed, the reader-started player, the seven kinds of figure, the four classes of truth and their labels, frames that name parts and never positions, and the checks.

Loads as: technique-running-diagram
Written for: An agent, to follow

Running diagram

A figure in a case study that carries out the thing the paragraph above it claims. A rules kernel steps through a game state; a request crosses an architecture and is turned back at a tenant boundary; a queue fills faster than it drains. The reader can make it go, stop it, and move through it one step at a time. It is served complete as a still, and the still is what most readers will ever see.

When to use

The claim is about behaviour over time: order, cause, agreement, divergence, a bound being hit. “The same inputs give the same sequence every time.” “The request stops here, not there.”
There is a trace to replay: the project’s own tests can emit one, or a small model can be written and labelled as a model.
The page can afford a day or two per figure and its words twice.

Do not use it for:

A claim about structure: what talks to what, who owns what. A static diagram already says it and a player adds only cost.
A number with a unit. A metric stays a static number.
A listing, a card, a hero or a page header. Those are scanning surfaces; a still may appear there, a player may not.
Anything driven by scroll. Stepping bound to scroll position is scroll takeover by another route, and the one study that compared stepping with scrolling found no benefit to buy with it.

Rules

The still makes the point. It is in the HTML, not drawn by script; it is not frame 0, which is the state before anything has happened; and it passes the screenshot test: captured with its caption and nothing else, someone who has not read the paragraph can say what it shows. Every source agrees on this, including the one defending interactivity.
Nothing moves until the reader starts it. One press to start, one to stop. No loop: a figure that loops is an ambient animation with a caption, and brings the pause criterion back.
Step is the primary act; play is a convenience. Reader control is the best-supported part of “interactive”; passive animation has the weakest support.
Under the claim it supports. Never beside the reading column while it is being read, never above its claim, never on scroll, never in a listing.
One figure runs at a time. Starting one pauses any other, by an event on document, because a copied recipe shares no module state with another copy.
Every figure says which it is. Extract, recording, model or illustration, on a line in the caption block in both languages, with what that class requires (section Decisions). Prefer a recording. An unlabelled model is the one thing here that can cost more trust than it earns.
A trace is generated by a script and committed. Never typed. A typed trace is a drawing with instruments on it.
A frame names parts and states. Never a position, never a word. That is what lets one trace drive columns on a desktop and rows on a phone with no branch in the player.
Every word is the page’s, in both languages. Control labels, the three states of the play button, the step sentences, the caption, the provenance line. No word in a canvas, none in the recipe. Frame text is data: numerals, hashes, identifiers, marked lang="en" where it is code.
Native controls, and no handler on document, on wheel or on the stage. Buttons and a range give Tab, Space, Enter, the arrows, Home and End for nothing, and the figure never competes with the page for scroll or keys. The stage is not focusable.
The figure’s box is one size in every frame. Reserve the space for the fullest frame. A value appearing mid-run pushed the paragraph below the prototype down by 33 px.
Anything placed by measurement is served hidden and carries no information: the marker, an SVG overlay. Served visible, a marker sits at the top left pointing at nothing.
Reduced motion is the still, and steps on demand. Decided through matchMedia, in one place, re-read when it changes. Play hidden, step and scrub kept, frame changes instant.
The caption states the conclusion. Not “Figure 3: prediction and reconciliation” but what the reader should leave believing. The step list, all visible with no script, is the long description.

What this skill must not do: teach an agent to animate an architecture diagram because it would look alive. Boxes lighting up in sequence, with nothing computing the sequence, dressed with a seed and a tick counter, is a fabricated exhibit. That is the failure this form exists to avoid, and an agent will reach for it first.

Decisions

Question	Choose	Because
Is the claim temporal	Only if it is about order, cause, agreement, divergence or a bound	A structural claim is a static diagram
Which kind	1 state machine stepped (medium); 2 request flow over the existing diagram (small, the cheapest that is still evidence); 3 queue and backpressure (medium; build two stills side by side first); 4 before and after of a transformation (small; build it static); 5 timeline of two parties (medium; the strongest first figure, a kernel’s tests can emit it); 6 a playable piece of game logic (large; project logic ships as script); 7 a live algorithm on a canvas (medium to large)	The kind decides the parts, the states, the controls and the still
Which class of truth	Extract: the project’s source compiled into the page, label the file and commit. Recording: a replay of output captured from the real system or its tests, label the command, the commit and the seed. Model: a reimplementation for the page, label that it is one and what it leaves out, and test it against a recording. Illustration: hand-authored frames, label it, and give it no instruments: no seed, no hash, no tick counter	A recording is the strongest class per byte and the only one a colleague with repository access can check
Which frame is the still	The frame at which the claim is visibly true in a way that would look different if it were false; prefer one with its history on it; one focal point	Frame 0 is before anything happened; the last frame is often the system back at rest
DOM or canvas	DOM for boxes, labels and anything under about a thousand parts; an SVG overlay, measured and decorative, for free-form edges; canvas 2D only for dense, textless cells, with `role="img"` and its labels in DOM; WebGL only when the subject is itself a shader	DOM reflows, prints, takes the site’s type and tokens, and gives a screen reader structure
How many frames	8 to 20; 3 to 5 is a before-and-after, build it static; past 40 nobody plays it	Whole frames cost about 130 gzipped bytes over deltas on 17 frames and save the replay logic
A sentence per frame or per event	Per event	Per frame doubled the prototype’s copy to 34 sentences across two languages, most of them repeats
How many figures on a site	One, then at most one per case study where the claim is temporal	Each is a day or two and its words twice; each model spends a little trust; nobody has measured this reader

Tuning

Dial	Start	Range	At the low end	At the high end
`interval`	700 ms	350 to 1500	Steps blur; large changes near three a second approach the flash threshold	The run feels stalled; a 17-step trace takes 25 s
`travel`	220 ms	0 to 400, under half the interval	The marker jumps	The marker is still moving when the next step lands
`playFrom`	start	start, current	A press replays the whole run	A press skips the run-up the still summarises
`reduced`	step	step, cuts	No play; step and scrub only	Play remains, with no tweening
`steps`	current	current, all	One sentence under the figure	The whole list, always
`rest` (content)	the claim’s frame	never 0
Frames (content)	8 to 20	3 to about 40	A before-and-after	Scrub-only
Parts (content)	10 to 30	up to about 40 on a phone		The figure stops fitting a screen
States (content)	3 or 4	up to 5		The reader needs a legend

The duration ranges are estimates anchored on the guidance that 100 to 500 ms suits a state change and longer reads as delay. None was tuned on a person. The rest frame is found with the screenshot test; the interval by reading the longest step sentence aloud.

Rest state

The still, as served: every sentence visible, the controls and the marker hidden, the rest frame’s states on the parts. That is the figure before the player mounts, with no script, after destroy(), in print, in a link preview, and under reduced motion. The player is an enhancement in the plain sense: taking it away removes convenience and no information.

Cost

Bytes (measured on the research’s prototype): the player 1.7 kB gzipped before the hook and the toggles, under 2.8 kB with them; a trace of 17 frames over 72 keys 540 B; the figure’s CSS 1.5 kB; a whole page with one figure 6.3 kB. A page could afford nine figures and should not have them.
To run: at rest nothing. Per step, attribute and text writes and one layout read for the marker, 2.4 ms on a desktop with 24 parts (measured). One composited transform for the marker.
To build (estimates; no first-hand account of authoring time was found for any reference): the player with tests and checks, 2 to 3 days; a still from a trace with no player, half a day to a day; a trace figure with the player, 1 to 2 days each, about half of it choosing the still and writing the sentences twice; a browser-side model with its verification against a recording, 3 to 6 days.
To read: nothing, if the still makes the point.

Checklist

npm test: the model’s step is pure, the trace is the same every run, the committed fixtures match the generator, and the player’s unit tests pass on the served markup.
check/browser/figure.mjs: with script disabled the controls and marker are hidden and every sentence visible; mounted, next and back move one frame, the scrubber’s arrows and Home work and keep focus, Space on play starts the run; the stage is one height across every frame; the run ends on the last frame; a second figure pauses the first; at rest nothing is scheduled; reduced motion hides play and the marker never animates; the Turkish page at 360 px has no horizontal scroll and the marker on its cell; thirty mounts and destroys leave the served markup.
Looked at in the stills: the served still and the mounted rest frame are the same picture plus controls; the first frame is one agreeing pair; the last is twelve; the Turkish page is rows.
The screenshot test, by eye: the still with its caption alone says what it shows.
Tab through the page once: nothing focused is covered, and four Tabs leave the figure.
Every figure carries its class of truth, in both languages.
Run once with a screen reader, once in Safari and once in Firefox before it is marked passed.

Recipes

stepped-figure: the player. The figure, its words and its trace are the page’s.

Sources

hohman-interactive-articles: the survey of interactive articles, their costs, and “closer to building a website than writing a blog post”
tse-fewer-interactives: a news graphics desk found most readers scroll and do not click
ons-less-interactivity: chart controls went unused; a message-first title did more than controls, and small multiples replaced them
aisch-in-defense-of-interactive-graphics: the reply: 15 percent is not nobody, and only what is crucial must not sit behind a click
tversky-animation-can-it-facilitate: animation showed no reliable advantage over static graphics carrying the same information; reader control is the better-supported benefit
mckenna-visual-narrative-flow: stepping against scrolling made no measurable difference for 240 readers; the visuals and the transitions did
red-blob-games-a-star: a figure that rests mid-run beside one that rests empty, on one page
red-blob-making-of-circle-drawing: the author’s own statement that diagram code is not the original algorithm
ciechanowski-mechanical-watch: figures that run on load and keep running under reduced motion, legible as stills because the subject is a physical object
site-samwho: simulations that run on load, whose meaning is entirely in their motion
marlow-dabbish-github-hiring: employers trusted what was hard to fake and quick to verify
wcag-pause-stop-hide: the pause criterion, which a reader-started figure meets by construction
wcag-three-flashes: the flash threshold the interval’s low end approaches
wcag-no-keyboard-trap: focus that enters a figure must leave it with the keyboard alone
wcag-dragging-movements: a scrubber needs a single-pointer alternative, which the step buttons are
wcag-target-size-minimum: the 24 by 24 CSS pixel floor for a control
apg-slider-pattern: the keys a scrubber answers to, and aria-valuetext for a value that is not usefully a number
mdn-input-range: the native scrubber, and that its tick marks vary by browser
mdn-prefers-reduced-motion: reduced motion through matchMedia
mdn-intersection-observer: pausing a figure that has left the screen
mdn-element-animate: the marker’s one animation
bcd-resizeobserver: re-placing a measured marker when the figure reflows
bcd-subgrid: the grid that turns from columns to rows
nng-scrolljacking-101: why stepping is never bound to scroll
nng-animation-duration: the duration anchors behind the interval and travel ranges
w3c-i18n-text-size: short strings grow most in translation, and control labels are all short strings
mdn-text-transform: the dotted capital I under lang="tr"