Skip to content

Annotated figure

A drawing with numbered callouts on leader lines and a key that pairs each number with its name.

<figure class="cap-annotated-figure" id="af-default" data-cap="annotated-figure">
  <svg class="cap-annotated-figure-drawing" data-layout="wide" viewBox="-240 -96 480 192" role="group" aria-labelledby="fig-wide-title fig-wide-desc">
    <title id="fig-wide-title">Figure 1. The parts of a page.</title>
    <desc id="fig-wide-desc">A page drawn as a window with four numbered parts, each on a leader to its label: 1, header; 2, sidebar; 3, content; 4, search.</desc>
    <rect class="sample-window" x="-120" y="-80" width="240" height="160" rx="6" />
    <g class="cap-annotated-figure-target" data-callout="1" role="img" aria-label="Part 1, header"><rect class="sample-part" x="-120" y="-80" width="240" height="24" /></g>
    <g class="cap-annotated-figure-target" data-callout="2" role="img" aria-label="Part 2, sidebar"><rect class="sample-part" x="-120" y="-56" width="60" height="136" /></g>
    <g class="cap-annotated-figure-target" data-callout="3" role="img" aria-label="Part 3, content"><rect class="sample-part" x="-60" y="-56" width="180" height="136" /></g>
    <g class="cap-annotated-figure-target" data-callout="4" role="img" aria-label="Part 4, search"><rect class="sample-part" x="60" y="-76" width="52" height="16" /></g>
    <g class="cap-annotated-figure-leader" data-callout="1"><line x1="-60" y1="-68" x2="-128" y2="-68" /><line x1="-128" y1="-68" x2="-146" y2="-68" /><text class="cap-annotated-figure-label" x="-151" y="-64" text-anchor="end" aria-hidden="true">1 · Header</text></g>
    <g class="cap-annotated-figure-leader" data-callout="2"><line x1="-90" y1="20" x2="-128" y2="40" /><line x1="-128" y1="40" x2="-146" y2="40" /><text class="cap-annotated-figure-label" x="-151" y="44" text-anchor="end" aria-hidden="true">2 · Sidebar</text></g>
    <g class="cap-annotated-figure-leader" data-callout="3"><line x1="40" y1="10" x2="128" y2="10" /><line x1="128" y1="10" x2="146" y2="10" /><text class="cap-annotated-figure-label" x="151" y="14" text-anchor="start" aria-hidden="true">3 · Content</text></g>
    <g class="cap-annotated-figure-leader" data-callout="4"><line x1="86" y1="-68" x2="128" y2="-68" /><line x1="128" y1="-68" x2="146" y2="-68" /><text class="cap-annotated-figure-label" x="151" y="-64" text-anchor="start" aria-hidden="true">4 · Search</text></g>
  </svg>
  <svg class="cap-annotated-figure-drawing" data-layout="narrow" viewBox="-180 -70 360 140" role="group" aria-labelledby="fig-narrow-title fig-narrow-desc">
    <title id="fig-narrow-title">Figure 1. The parts of a page.</title>
    <desc id="fig-narrow-desc">A page drawn as a window with four numbered parts, each on a leader to its label: 1, header; 2, sidebar; 3, content; 4, search.</desc>
    <rect class="sample-window" x="-80" y="-53.3" width="160" height="106.7" rx="6" />
    <g class="cap-annotated-figure-target" data-callout="1" role="img" aria-label="Part 1, header"><rect class="sample-part" x="-80" y="-53.3" width="160" height="16" /></g>
    <g class="cap-annotated-figure-target" data-callout="2" role="img" aria-label="Part 2, sidebar"><rect class="sample-part" x="-80" y="-37.3" width="40" height="90.7" /></g>
    <g class="cap-annotated-figure-target" data-callout="3" role="img" aria-label="Part 3, content"><rect class="sample-part" x="-40" y="-37.3" width="120" height="90.7" /></g>
    <g class="cap-annotated-figure-target" data-callout="4" role="img" aria-label="Part 4, search"><rect class="sample-part" x="40" y="-50.7" width="34.7" height="10.7" /></g>
    <g class="cap-annotated-figure-leader" data-callout="1"><line x1="-40" y1="-45.3" x2="-88" y2="-45" /><line x1="-88" y1="-45" x2="-106" y2="-45" /><text class="cap-annotated-figure-label" x="-111" y="-41" text-anchor="end" aria-hidden="true">1 · Header</text></g>
    <g class="cap-annotated-figure-leader" data-callout="2"><line x1="-60" y1="13.3" x2="-88" y2="27" /><line x1="-88" y1="27" x2="-106" y2="27" /><text class="cap-annotated-figure-label" x="-111" y="31" text-anchor="end" aria-hidden="true">2 · Sidebar</text></g>
    <g class="cap-annotated-figure-leader" data-callout="3"><line x1="26.7" y1="6.7" x2="88" y2="7" /><line x1="88" y1="7" x2="106" y2="7" /><text class="cap-annotated-figure-label" x="111" y="11" text-anchor="start" aria-hidden="true">3 · Content</text></g>
    <g class="cap-annotated-figure-leader" data-callout="4"><line x1="57.3" y1="-45.3" x2="88" y2="-45" /><line x1="88" y1="-45" x2="106" y2="-45" /><text class="cap-annotated-figure-label" x="111" y="-41" text-anchor="start" aria-hidden="true">4 · Search</text></g>
  </svg>
  <figcaption class="cap-annotated-figure-caption">Figure 1. The parts of a page, from the Example Co style guide.</figcaption>
</figure>
<section class="cap-annotated-key" id="af-key" aria-label="Figure 1 key" data-for="af-default">
  <div class="cap-annotated-key-entries">
    <figure class="cap-annotated-key-entry" data-callout="1"><svg class="cap-annotated-key-art" viewBox="0 0 76 76" role="img" aria-label="Header, drawn."><rect class="sample-key-icon" x="8" y="18" width="60" height="40" rx="2" /><rect class="sample-key-icon" data-on x="8" y="18" width="60" height="6" /></svg><figcaption><span class="cap-eyebrow cap-annotated-key-num" data-variant="mono">1</span><b class="cap-annotated-key-name">Header</b><span class="cap-annotated-key-note">The site's name and its menu.</span></figcaption></figure>
    <figure class="cap-annotated-key-entry" data-callout="2"><svg class="cap-annotated-key-art" viewBox="0 0 76 76" role="img" aria-label="Sidebar, drawn."><rect class="sample-key-icon" x="8" y="18" width="60" height="40" rx="2" /><rect class="sample-key-icon" data-on x="8" y="24" width="15" height="34" /></svg><figcaption><span class="cap-eyebrow cap-annotated-key-num" data-variant="mono">2</span><b class="cap-annotated-key-name">Sidebar</b><span class="cap-annotated-key-note">Links to every section.</span></figcaption></figure>
    <figure class="cap-annotated-key-entry" data-callout="3"><svg class="cap-annotated-key-art" viewBox="0 0 76 76" role="img" aria-label="Content, drawn."><rect class="sample-key-icon" x="8" y="18" width="60" height="40" rx="2" /><rect class="sample-key-icon" data-on x="23" y="24" width="45" height="34" /></svg><figcaption><span class="cap-eyebrow cap-annotated-key-num" data-variant="mono">3</span><b class="cap-annotated-key-name">Content</b><span class="cap-annotated-key-note">The page's own words.</span></figcaption></figure>
    <figure class="cap-annotated-key-entry" data-callout="4"><svg class="cap-annotated-key-art" viewBox="0 0 76 76" role="img" aria-label="Search, drawn."><rect class="sample-key-icon" x="8" y="18" width="60" height="40" rx="2" /><rect class="sample-key-icon" data-on x="53" y="19" width="13" height="4" /></svg><figcaption><span class="cap-eyebrow cap-annotated-key-num" data-variant="mono">4</span><b class="cap-annotated-key-name">Search</b><span class="cap-annotated-key-note">Finds a post by its words.</span></figcaption></figure>
  </div>
</section>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/annotated-figure.css";
import { enhance } from "capsomer/behavior/annotated-figure";

enhance();

Usage

<figure class="cap-annotated-figure" id="parts" data-cap="annotated-figure" data-draw>
  <svg class="cap-annotated-figure-drawing" data-layout="wide" viewBox="-240 -96 480 192" role="group" aria-labelledby="parts-wide-title parts-wide-desc">
    <title id="parts-wide-title">Figure 1. The parts of a page.</title>
    <desc id="parts-wide-desc">A page with four numbered parts: 1, header; 2, sidebar; 3, content; 4, search.</desc>
    <!-- the site's art -->
    <g class="cap-annotated-figure-target" data-callout="1" role="img" aria-label="Part 1, header">…</g>
    <g class="cap-annotated-figure-leader" data-callout="1">
      <line x1="-60" y1="-68" x2="-128" y2="-68" /><line x1="-128" y1="-68" x2="-146" y2="-68" />
      <text class="cap-annotated-figure-label" x="-151" y="-64" text-anchor="end" aria-hidden="true">1 · Header</text>
    </g>
  </svg>
  <svg class="cap-annotated-figure-drawing" data-layout="narrow" …>…</svg>
  <figcaption class="cap-annotated-figure-caption">Figure 1. The parts of a page.</figcaption>
</figure>
<section class="cap-annotated-key" aria-label="Figure 1 key" data-for="parts">
  <div class="cap-annotated-key-entries">
    <figure class="cap-annotated-key-entry" data-callout="1">
      <svg class="cap-annotated-key-art" viewBox="0 0 76 76" role="img" aria-label="Header, drawn.">…</svg>
      <figcaption><span class="cap-eyebrow cap-annotated-key-num" data-variant="mono">1</span><b class="cap-annotated-key-name">Header</b><span class="cap-annotated-key-note">The site's name and its menu.</span></figcaption>
    </figure>
  </div>
</section>
import { AnnotatedDrawing, AnnotatedFigure, AnnotatedKey } from "capsomer/react/annotated-figure";

<AnnotatedFigure id="parts" draw caption="Figure 1. The parts of a page.">
  <AnnotatedDrawing id="parts-wide" layout="wide" view={WIDE_VIEW} title="…" description="…" callouts={WIDE} art={<Window />} />
  <AnnotatedDrawing id="parts-narrow" layout="narrow" view={NARROW_VIEW} title="…" description="…" callouts={NARROW} />
</AnnotatedFigure>
<AnnotatedKey for="parts" label="Figure 1 key" entries={KEY} />

Examples

A narrow container shows the narrow drawing, whose leaders draw in

<!-- The same figure as the default, copied in by the script below with its ids renamed. -->
<div class="sample-narrow" id="af-narrow-host"></div>

API reference

AnnotatedDrawing

PropTypeRequiredDoes
idstringYesKeys the title and description ids; unique on the page.
layout"wide" | "narrow""wide" or "narrow" when the figure has one drawing for each; the container's width picks one.
view{ x: number; y: number; w: number; h: number }Yes
titlestringYes
descriptionstringYesThe whole drawing in words, with every callout: what a reader who cannot see it is told.
artReactNodeDrawn first, under every callout.
calloutsCallout[]Yes
afterReactNodeDrawn last: a scale bar, a north arrow.

AnnotatedFigure

PropTypeRequiredDoes
idstringYesThe figure's id, which a key outside it names in for.
drawbooleanDraw each leader in once the figure is in view (not under reduced motion).
captionReactNode
childrenReactNodeYesOne AnnotatedDrawing, or a "wide" and a "narrow" one; an AnnotatedKey inside it, if it belongs there.

AnnotatedKey

PropTypeRequiredDoes
forstringThe figure it belongs to, when it sits outside it.
labelstringYes
entriesKeyEntry[]Yes

Functions

FunctionSignatureDoes
scalePoint(p: Point, k: number, from?: Point, to?: Point): Pointp moved so that from lands on to, scaled by k about it.
scalePathData(d: string, map: (p: Point) => Point): stringEvery "x y" (or "x,y") pair in an absolute path's data passed through map: a path drawn on one canvas, placed on another. Commands with one number (H, V) and relative commands are not pairs and are left as they are, so draw the path in absolute M, L, C and Q.
sideCallout(opts: { from: Point; side: 1 | -1; y: number; edge: number; cx?: number | undefined; elbow?: number | undefined; tail?: number | undefined; gap?: number | undefined; baseline?: number | undefined; }): CalloutPlaceA callout whose label sits beside the drawing: a leader from from out to an elbow just past edge (the drawing's half width from cx), then level to its tail, and the label after the tail, on the right (side 1) or the left (-1), at height y.
viewBox(v: { x: number; y: number; w: number; h: number; }): stringA view box as the attribute wants it.
nextPin(pinned: string | null, id: string): string | nullThe pin after a tap on id: the same callout again unpins it.
drawLeaders(svg: Element): voidEach leader grows from its start with transform: scale(), which looks like the line being drawn and, unlike a stroke-dashoffset draw, runs on the compositor. The plain transform property: Chrome does not composite the individual transform properties on SVG. Values go through the CSSOM. The timing is the motion tokens: each leader's long leg draws in --dur-slow, its short leg in --dur-base once the long one is drawn, the leaders --dur-base apart, on the arriving --ease-out.
attach(figure: HTMLElement): () => voidWires one figure: its callouts and the entries of every key that names it (data-for its id) light together. With data-draw on the figure, the drawing on show draws its leaders in once it is in view, except under reduced motion. Returns a function that detaches.
enhance(root?: Element | Document | DocumentFragment): () => voidAttaches to every [data-cap="annotated-figure"] under root not yet attached. Returns a function that detaches. The root is Element | Document | DocumentFragment, not ParentNode: under @cloudflare/workers-types an HTMLFormElement does not type as a ParentNode, so a site could not pass its form.
round1(n: number): numberA number at one decimal: coordinates in the markup stay short and stable.

CSS variables

VariableDefault
--cap-figure-inkvar(--text)

Parts and data attributes

ClassIs
.cap-annotated-figurethe root
.cap-annotated-figure-captiona part
.cap-annotated-figure-drawinga part
.cap-annotated-figure-labela part
.cap-annotated-figure-leadera part
.cap-annotated-figure-targeta part
AttributeValues
data-layoutnarrow wide
data-litpresent or absent
data-livepresent or absent

Accessibility

KeyDoes
TabPasses the figure: nothing in it is a control
  • The drawing is role="group" named by its title and described by its description; each target is role="img" named by its number and name; each key drawing is role="img" too, and the key is a named region.
  • The lit state is a pointer's aid; everything it shows is in the key's text.
  • Screen readers: no manual NVDA or VoiceOver run, by decision (2026-11-07); the automated browser checks and a front-end review stand in. Automated: see the site's Tests page.