# Legend item

Names one series of a chart: a swatch in its color, its name, and its value if shown. A list of them is the chart's legend.

Block: `smbk-legend-item`. Status: experimental. Figma: the Figma file, https://www.figma.com/community/file/1688324308358870630. Desktop and mobile: differ by presentation only.

## Options

| Axis | Values | Default | Meaning |
|---|---|---|---|
| `swatch` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `series`, `muted` | `1` | The series' color: 1 to 8 are the categorical colors in their fixed order, series the one color of a single series, muted the gray for everything else ("Others"). |

Parts: `smbk-legend-item__swatch`, `smbk-legend-item__label`, `smbk-legend-item__value`

## Markup

```html
<ul
  role="list"
  aria-label="Legend item"
  style="width:var(--smbk-size-width-240);max-width:100%;display:flex;flex-direction:column;gap:var(--smbk-space-stack-xs);margin:0;padding:0"
>
  <li class="smbk-legend-item smbk-legend-item--swatch-1">
    <span class="smbk-legend-item__swatch" aria-hidden="true"></span>
    <span class="smbk-legend-item__label">Design</span>
    <span class="smbk-legend-item__value">$1,357</span>
  </li>
</ul>
```

## React

```tsx
import { LegendItem } from './design-system/components/legend-item/legend-item.js';

<ul role="list" aria-label="Legend item" style={{ width: "var(--smbk-size-width-240)", maxWidth: "100%", display: "flex", flexDirection: "column", gap: "var(--smbk-space-stack-xs)", margin: 0, padding: 0 }}>
  <LegendItem swatch="1" label="Design" value="$1,357" />
</ul>
```

## Stylesheet

```css
/* smbk-legend-item — Legend item. Figma "Legend item" 7580:15.
 * One line: a small square swatch in the series' data color, the name filling the line, and the value at its
 * end in the subtle color. A chart's legend is a list of these. The swatch only repeats the color of the
 * series; the name says which series it is. */

.smbk-legend-item {
  display: flex;
  align-items: center;
  gap: var(--smbk-space-inline-sm);
  min-width: 0;
  font-family: var(--smbk-typography-body-sm-font-family);
  font-size: var(--smbk-typography-body-sm-font-size);
  font-weight: var(--smbk-typography-body-sm-font-weight);
  line-height: var(--smbk-typography-body-sm-line-height);
  letter-spacing: var(--smbk-typography-body-sm-letter-spacing);
  text-transform: var(--smbk-typography-body-sm-text-transform);
  list-style: none;
}

.smbk-legend-item__swatch {
  flex: none;
  width: var(--smbk-size-12);
  height: var(--smbk-size-12);
  border-radius: var(--smbk-radius-2);
  background: var(--smbk-color-data-categorical-1);
}

.smbk-legend-item__label {
  flex: 1 1 auto;
  min-width: 0;
  color: var(--smbk-color-text-default);
  overflow-wrap: anywhere;
}

.smbk-legend-item__value {
  flex: none;
  color: var(--smbk-color-text-subtle);
  font-variant-numeric: tabular-nums;
}

/* ---- swatch: the series' color ---- */

.smbk-legend-item--swatch-2 .smbk-legend-item__swatch { background: var(--smbk-color-data-categorical-2); }
.smbk-legend-item--swatch-3 .smbk-legend-item__swatch { background: var(--smbk-color-data-categorical-3); }
.smbk-legend-item--swatch-4 .smbk-legend-item__swatch { background: var(--smbk-color-data-categorical-4); }
.smbk-legend-item--swatch-5 .smbk-legend-item__swatch { background: var(--smbk-color-data-categorical-5); }
.smbk-legend-item--swatch-6 .smbk-legend-item__swatch { background: var(--smbk-color-data-categorical-6); }
.smbk-legend-item--swatch-7 .smbk-legend-item__swatch { background: var(--smbk-color-data-categorical-7); }
.smbk-legend-item--swatch-8 .smbk-legend-item__swatch { background: var(--smbk-color-data-categorical-8); }
.smbk-legend-item--swatch-series .smbk-legend-item__swatch { background: var(--smbk-color-data-series); }
.smbk-legend-item--swatch-muted .smbk-legend-item__swatch { background: var(--smbk-color-surface-track); }

/* ---- high contrast (forced colors) ---- */
/* The swatch keeps its series' color, so it still matches the chart's marks. */

@media (forced-colors: active) {
  .smbk-legend-item__swatch {
    forced-color-adjust: none;
  }
}
```

## Tokens it reads

```json
{
  "space": {
    "inline": {
      "sm": {
        "$type": "dimension",
        "$value": "{{space.6}}",
        "$description": "Gap between things side by side, small."
      }
    }
  },
  "typography": {
    "body-sm": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Geist, Geist Fallback, system-ui, sans-serif",
        "fontSize": "14px",
        "fontWeight": 400,
        "lineHeight": 1.5,
        "letterSpacing": "0px"
      }
    }
  },
  "size": {
    "12": {
      "$type": "dimension",
      "$value": "12px",
      "$description": "Raw size step, 12 px. Only for fixed sizes inside a component; semantic sizes (size/control, icon, mark) point here."
    }
  },
  "radius": {
    "2": {
      "$type": "dimension",
      "$value": "2px",
      "$description": "Raw corner step, 2 px. Semantic corners (radius/control, container) point here."
    }
  },
  "color": {
    "data": {
      "categorical": {
        "1": {
          "$type": "color",
          "$value": "{{palette.light.categorical.1}}",
          "$description": "Categorical position 1 (blue). Fixed order, never cycled. Light blue/600, dark blue/400. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
        },
        "2": {
          "$type": "color",
          "$value": "{{palette.light.categorical.2}}",
          "$description": "Categorical position 2 (orange). Light orange/500, dark orange/400. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
        },
        "3": {
          "$type": "color",
          "$value": "{{palette.light.categorical.3}}",
          "$description": "Categorical position 3 (neutral). Light grey/700, dark grey/300. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
        },
        "4": {
          "$type": "color",
          "$value": "{{palette.light.categorical.4}}",
          "$description": "Categorical position 4 (green). Light green/500, dark green/400. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
        },
        "5": {
          "$type": "color",
          "$value": "{{palette.light.categorical.5}}",
          "$description": "Categorical position 5 (purple). Light purple/500, dark purple/300. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
        },
        "6": {
          "$type": "color",
          "$value": "{{palette.light.categorical.6}}",
          "$description": "Categorical position 6 (teal). Light teal/600, dark teal/500. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
        },
        "7": {
          "$type": "color",
          "$value": "{{palette.light.categorical.7}}",
          "$description": "Categorical position 7 (yellow). Light yellow/500, dark yellow/500. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
        },
        "8": {
          "$type": "color",
          "$value": "{{palette.light.categorical.8}}",
          "$description": "Categorical position 8 (pink). Light pink/600, dark pink/300. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
        }
      },
      "series": {
        "$type": "color",
        "$value": "{{palette.light.series}}",
        "$description": "The single series colour; the same as categorical 1, so one series and the first of many agree. Light blue/600, dark blue/400. Marks reach 3:1 on the plot background; never colour alone: direct labels, markers or patterns too."
      }
    },
    "text": {
      "default": {
        "$type": "color",
        "$value": "{{color.grey.900}}",
        "$description": "Main text."
      },
      "subtle": {
        "$type": "color",
        "$value": "{{color.grey.700}}",
        "$description": "Secondary text: descriptions, metadata."
      }
    },
    "surface": {
      "track": {
        "$type": "color",
        "$value": "{{color.grey.500}}",
        "$description": "The filled track of a switch that is off: 3:1 against the page so the switch shows where it is (decision C)."
      }
    }
  }
}
```

## Purpose

Names one series of a chart: a small swatch in the series' color, its name, and its value if the chart shows one. A chart's legend is a list of legend items, one per series, in the chart's order. The name, not the swatch, says which series is which.

## Anatomy

- The block, a list item as wide as its list.
- The swatch part, a small square in the series' color. Its swatch is one of the eight categorical colors, the series color of a chart with one series, or muted, the gray for everything else.
- The label part, the series' name, filling the line.
- The value part, the series' value, at the end of the line in the subtle color.

## When to use

- Beside or under a chart with two or more series, to name each one.
- With values, as a small table of the chart's parts: a donut's shares, a bar's totals.

## When not to use

- A chart with one series. Its title names it.
- As a control that hides or shows a series. A legend item takes no action.
- Without the series also labelled on the chart where eight or fewer are shown, or a table of the values.

## Behavior

The name wraps when the line is too narrow; the value keeps its place at the end. Nothing moves and nothing takes focus.

## Accessibility

### What it does for you

- The swatch is decoration and hidden from screen readers; they hear the name, then the value.
- Legend items are list items. Nothing takes focus.
- In high contrast mode the swatch keeps its series' color, so it still matches the chart.

### What you must do

- Put legend items in a list, `ul` with `role="list"` where the page removes its bullets, so a screen reader says how many series there are.
- Never tell series apart by color alone. Label the series on the chart too, or give the chart a table of its values.

### How to test

- With a screen reader, the list is announced with its number of items, and each item is read as its name, then its value, with no mention of the swatch.
- With text at 200% and the page 320 pixels wide, a long name wraps and the value keeps its place at the end.
- In a forced-color mode, each swatch still shows its series' color, matching the chart's marks.

## Usage rules

### Do

- Give the series in the chart's order, with the colors in their fixed order: 1 to 8.
- Gather everything past the eighth series into one muted item, such as "Others".
- Use the same name in the legend as on the chart and in its table.

### Don't

- Repeat a color for a ninth series.
- Use the feedback colors for series; they mean success, warning and danger.