import {
  Meta,
  Title,
  Subtitle,
  Description,
  Primary,
  Controls,
  Stories,
} from '@storybook/addon-docs/blocks';
import * as MapLegendStories from './map-legend.stories';

<Meta of={MapLegendStories} />

<Title />
<Subtitle>Reads the color and size encodings of a map.</Subtitle>

<Description />

<Primary />

<Controls />

---

## Variations

<Stories />

---

## AI Best Practices

> [!IMPORTANT]
>
> - **Pair the size key with the marker scale** — pass the same `MapScale` object to `markers[].scale` and to `sizeKey.scale`. A legend built from a different scale silently misreports every symbol on the map.
> - **Tokens, never literals** — `colorToken` accepts a CSS custom property name (`'--chart-1'`). A hex value will not follow a light/dark switch, and the legend will drift away from the map it describes.
> - **Overlay needs a positioned ancestor** — `variant="overlay"` positions itself absolutely. Wrap the map and the legend together in a `relative` container.
> - **A proportional-symbol map without a size key is unreadable** — a disc twice as wide means nothing until the scale is stated.