Diagrams
DiagramLegend
The key: which drawn form means which kind of thing.
Usage
When to reach for it
Ships from@misoto22/design/diagrams
import { DiagramLegend } from '@misoto22/design/diagrams'Notes
The key: which drawn form means which kind of thing.
Not optional furniture in a monochrome system, and this is the one place that has to be said plainly. When the difference between a queue and a cache is a sigil rather than a colour, the key is the only place a reader is told what the sigil means — a figure whose forms are undocumented is a figure whose forms might as well not have been drawn.
A <ul> rather than a row of <span>s: it is a list of pairs, and the count is part of what a screen reader should say about it.
Anatomy
| Element | Description |
|---|---|
| Rowrequired | A wrapping, baseline-aligned row over a top rule. Inside a figure it sits between the picture and the conclusion cards, which is where a reader looks after failing to recognise a mark. |
| Kicker | The word Key before the row. title={null} drops it for a bare row, and the list keeps that word as its own accessible name either way. |
| Listrequired | A <ul> of pairs rather than a row of spans, so the count is part of what a screen reader says about it — "list, six items" is the first useful fact about a key. |
| Samplerequired | A 14 × 14 svg carrying the entry’s own markup, hidden from assistive technology. Markup rather than a name from a fixed list, because a key has to show the SAME mark the figure drew. |
| Labelrequired | The word beside the mark, in the meta voice. The standard builders take it from the same table the plate’s eyebrow prints, so a plate reading SERVICE is never explained by a key reading Datastore. |
Best practices
Do
- Build the entries with kindLegend, variantLegend or stateLegend. They are made out of the renderers’ own drawing code, so the key cannot come to show a mark the figure does not draw or a word the plate does not print.
- Leave a figure’s legend at "auto". It lists only the kinds actually drawn; "all" prints seven kinds beside a figure using three, which is four claims the picture does not support.
- Pass title={null} when the key sits under a caption that already says what it is. The list keeps Key as its accessible name, so the kicker can go without the row losing its name.
Don’t
- A key is not where a distinction is MADE. The two state tokens are the only hues these figures spend and each terminal is also its own plate shape — a difference carried by colour alone is one a reader can only look up, an entry at a time, after noticing there is a key at all.
- legend="hidden" is not free on a figure of tagged plates. A plate prints its tag OR the kind word in the same eyebrow slot and the tag wins, so on a tagged plate the kind is carried by the sigil alone — hiding the key takes the only thing that teaches that sigil off the page.
Examples
default
Two of the sets the renderers build for themselves. kindLegend draws each sigil with the same component the plates draw it with, and labels it with the same word the plate’s eyebrow prints, so a key and the figure above it cannot drift apart; stateLegend draws each state as the plate itself, colour and dash included. title defaults to Key, which is why the second one is renamed — two keys stacked in a column and both headed Key say nothing about which is which.
lines rather than plates
variantLegend keys the RELATIONSHIPS rather than the boxes, drawing each entry as the stroke itself — the heavier weight of a main path, the long dash of a line that crosses a trust boundary, the short dash of one that does not block. Leave the return variant out of a key like this: it is painted exactly as dashed is and told apart in the figure by an open arrowhead, which a 14 by 14 sample has no room to show, so listing both gives a reader two identical marks with different names. The second row overrides one label and passes title null for a bare row, since the key above it has already said Key.
a key you draw yourself
sample is markup on a 14 by 14 grid rather than a name matched against a fixed list, which is what lets a figure that draws a mark of its own document it — here, three states of ownership that no renderer knows about. Whatever goes in has to be the same mark the artwork drew: a key that invents a form sends a reader looking through the picture for something that was never there. Paint the samples with the diagram tokens rather than with fixed colours, so the key follows the figure into dark mode and onto paper.
Accessibility
- A list of pairs rather than a row of spans, so the count is part of what a screen reader says about it.
- kindLegend, variantLegend and stateLegend build the standard sets out of the renderers’ own drawing code, so the key can never drift from the figure.