Annotation Design Guidance — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · CLAUDE.md · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/annotations/design-guidance

Annotation Design Guidance

A useful annotation is not just text placed on a chart. It establishes a reading order, stays tied to its target, survives the space available, and carries enough context to remain honest when the chart travels. Semiotic's annotation APIs map directly to those design decisions.

import { LineChart } from "semiotic" const frameProps = { /* --- Data --- */ data: [ { week: 1, incidents: 12 }, { week: 2, incidents: 15 }, { week: 3, incidents: 14 }, { week: 4, incidents: 31 }, { week: 5, incidents: 22 }, { week: 6, incidents: 18 }, { week: 7, incidents: 27 }, { week: 8, incidents: 20 } ], /* --- Process --- */ xAccessor: "week", yAccessor: "incidents", /* --- Customize --- */ xLabel: "Week", yLabel: "Incidents", showPoints: true, /* --- Annotate --- */ annotations: [ { type: "callout-circle", x: 4, y: 31, label: "Primary spike to investigate", radius: 7, emphasis: "primary", color: "#d7263d" }, { type: "text", x: 7, y: 27, label: "Secondary recurrence", emphasis: "secondary", color: "#d7263d" }, { type: "y-threshold", value: 25, label: "Escalation threshold", color: "#b45309" }, { type: "callout", x: 1, y: 12, label: "Data excludes planned maintenance", defensive: true, provenance: { source: "user", confidence: 1 } } ], autoPlaceAnnotations: { density: { maxAnnotations: 3 }, progressiveDisclosure: true, redundantCues: true, cohesion: "layer" } } export default () => { return <LineChart {...frameProps} /> }

Six Design Considerations

Consideration	Question	Semiotic support
Audience	What does this reader know, and will the chart travel?	`audience`, `defensive`, visible provenance
Hierarchy	What should be read first?	`emphasis`, confidence-derived reading order
Placement	Can the note sit adjacent to its target?	`autoPlaceAnnotations`, manual offsets, curved connectors
Association	Can the reader identify the target without color?	`redundantCues`, connectors, enclosures, accessibility audit
Cohesion	Should notes blend with the chart or read as an editorial layer?	`cohesion: "blended" \| "layer"`
Amount	How many notes can the available space carry?	`density`, `responsive`, progressive disclosure

Defensive Annotations

Use defensive: true for caveats or context that must survive screenshots, exports, and redistribution. Defensive notes are never shed by density or responsive annotation passes. Add provenancewhen the note's origin or confidence matters after it leaves the original application.

Use Another Approach When...

The reader needs exact values for many points: use a table or accessible data view.
The note is application chrome or a workflow action: use a panel, tooltip, or widget annotation.
Every point needs a label: reconsider the encoding, direct-label a smaller set, or split the chart.
The annotation cannot be tied to a stable data target: keep it outside the plot and explain the limitation.

Annotations Overview - types, placement, density, and live examples.
Provenance & Lifecycle - who wrote a note, how it ages, and whether it is still believed.
Chartability Audit - checks annotation association and other receivability risks.