# DiagramLegend

The key: which drawn form means which kind of thing.

- Group: Diagrams
- Import: `import { DiagramLegend } from '@misoto22/folio/diagrams'`
- Page: https://ui.misoto22.com/components/diagram-legend/
- Related: architecture-figure, lifecycle-figure

## When to reach for it

Not optional furniture in a monochrome system. When a queue and a cache differ by a sigil rather than a colour, this is the only place a reader is told what the sigil means.

## Anatomy

- **Row** (required) — 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.
- **List** (required) — 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.
- **Sample** (required) — 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.
- **Label** (required) — 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.

## 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.

## DiagramLegend

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.

### Props

- `entries` (required) — `DiagramLegendEntry[]`.
- `title` — `string | null` default `'Key'`. The kicker before the row. Pass null for a bare row.
- `className` — `string`.

## Example — default

```tsx
import { DiagramLegend, kindLegend, stateLegend } from '@misoto22/folio/diagrams'

<div className="flex flex-col gap-6">
  <DiagramLegend entries={kindLegend(['frontend', 'backend', 'database', 'messagebus', 'security'])} />
  <DiagramLegend title="States" entries={stateLegend(['start', 'active', 'decision', 'success', 'failure'])} />
</div>
```

## Example — lines rather than plates

```tsx
import { DiagramLegend, variantLegend } from '@misoto22/folio/diagrams'

<div className="flex flex-col gap-6">
  <DiagramLegend title="Lines" entries={variantLegend(['default', 'emphasis', 'security', 'dashed'])} />
  <DiagramLegend
    title={null}
    entries={variantLegend(['emphasis', 'dashed'], {
      dashed: { label: 'Published to a topic' },
    })}
  />
</div>
```

## Example — a key you draw yourself

```tsx
import { DiagramLegend } from '@misoto22/folio/diagrams'

<DiagramLegend title="Ownership" entries={OWNERSHIP} />
```