<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
Prop
Type
Required
Does
id
string
Yes
Keys 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
title
string
Yes
description
string
Yes
The whole drawing in words, with every callout: what a reader who cannot see it is told.
art
ReactNode
Drawn first, under every callout.
callouts
Callout[]
Yes
after
ReactNode
Drawn last: a scale bar, a north arrow.
AnnotatedFigure
Prop
Type
Required
Does
id
string
Yes
The figure's id, which a key outside it names in for.
draw
boolean
Draw each leader in once the figure is in view (not under reduced motion).
caption
ReactNode
children
ReactNode
Yes
One AnnotatedDrawing, or a "wide" and a "narrow" one; an AnnotatedKey inside it, if it belongs there.
AnnotatedKey
Prop
Type
Required
Does
for
string
The figure it belongs to, when it sits outside it.
label
string
Yes
entries
KeyEntry[]
Yes
Functions
Function
Signature
Does
scalePoint
(p: Point, k: number, from?: Point, to?: Point): Point
p moved so that from lands on to, scaled by k about it.
scalePathData
(d: string, map: (p: Point) => Point): string
Every "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; }): CalloutPlace
A 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.
The pin after a tap on id: the same callout again unpins it.
drawLeaders
(svg: Element): void
Each 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): () => void
Wires 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): () => void
Attaches 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): number
A number at one decimal: coordinates in the markup stay short and stable.
CSS variables
Variable
Default
--cap-figure-ink
var(--text)
Parts and data attributes
Class
Is
.cap-annotated-figure
the root
.cap-annotated-figure-caption
a part
.cap-annotated-figure-drawing
a part
.cap-annotated-figure-label
a part
.cap-annotated-figure-leader
a part
.cap-annotated-figure-target
a part
Attribute
Values
data-layout
narrowwide
data-lit
present or absent
data-live
present or absent
Accessibility
Key
Does
Tab
Passes 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.