Annotations That Adapt and Travel
Make the annotation layer responsive to its container and its reader, and let a note defend itself once the chart leaves the page: responsive shedding, cohesion modes, audience-scaled amount, and defensive traveling notes that carry their provenance visibly.
Elijah Meeks·
Semiotic already had an annotation layer that is data-bound, hierarchically ordered, well-placed, un-crowded (density-aware), and legibly associated to its target. But modern annotation research asks two more questions a production chart can't avoid: does the layer adapt to the space and the reader it lands in, and what happens to a note once the chart leaves the page it was made on?
Responsive shedding
Density sheds by count against the plot area, and because placement already runs with the chart's live dimensions, that budget already tightens as a responsive chart shrinks. Semiotic annotations have an importance axis:{ responsive: true } (or { minWidth }, default 480px) sheds secondary-emphasis notes once the plot narrows past the breakpoint, whileprimary and unmarked notes stay. It pools its verdict with the density pass, and under progressiveDisclosure the shed notes are deferred rather than dropped.
Same annotations, two widths. Below the breakpoint (left) the two secondary notes are shed; primary and unmarked notes stay.
Cohesion modes
Should a note blend into the chart or stand apart from it? That used to be implicit but it should be a choice. cohesion: "blended" (the default look) lets notes adopt the chart's mark colors and typography. cohesion: "layer" presents them as a distinct editorial layer. The theme's annotation color and an italic editorial face presents commentary reads as commentary. Set it per annotation, or chart-wide; a per-annotation value wins.
cohesion: "layer" presents notes as a distinct editorial layer and styles them with the annotation color and an italic editorial face.
Amount adapts to the reader
The same AudienceProfile that biases chart suggestion can bias annotation amount. Pass it through the density pass and the budget scales by the audience's aggregate familiarity: a low-familiarity audience keeps more orienting notes, an expert audience fewer. It is the annotation analogue of the orienting nudgedescribeChart already adds to its L4 sentence for low-familiarity readers.
autoPlaceAnnotations={{ density: true, audience: { familiarity: { Scatterplot: 5 } }, // experts → fewer notes }}Defensive, traveling annotations
The paper's sharpest practitioner insight is that charts circulate as screenshots, stripped of provenance, and good authors anticipate that reuse by embedding caveats directly on the chart. A defensive note operationalizes this: it is never shed by the density budget or responsive shedding so it survives into every export path. And when it carries provenance, the layout pass bakes the source and confidence visibly into its label, so a stray screenshot still says who made the note and how sure they were.
The tight budget sheds the ordinary notes, but the defensive AI caveat stays and renders its source and confidence inline.
{ type: "callout", pointId: "F", label: "Spike may be a sensor glitch", defensive: true, // never shed; always exported provenance: { source: "ai", confidence: 0.62 } // rendered as "(AI · 62%)" }Adapt, then defend
It's not enough that the annotation layer behaves well in the container it's given and the house style it's asked to match. Individual notes also need to behave well for the reader in front of them but also for the reader who will see this chart months later, out of context, in someone else's deck. Together they push the communicative layer past "renders correctly" toward "survives contact with the real world."