# Flux 2.0 — Metric

Headline figures with a label and a change, aligned on one surface. The top of a dashboard.

Reference: https://flux.kaptio.com/components/metric/
Requires: https://flux.kaptio.com/tokens/v2/flux.css and flux-components.css

## Use it when
Shows the few numbers that say how something is going — berths sold, revenue booked, bookings waiting on a supplier — with how each has moved. Related metrics share one surface and one grid, so their labels, values and changes line up and read as a set rather than as separate cards competing for attention.

## Do not use it when
Not for the attributes of one record; that is a Description list. Not for comparing many rows; that is a Table. If a figure has no comparison and nobody acts on it, it probably does not belong at the top of the page.

## Markup

### Metric row

<dl class="flux-metrics">
  <div class="flux-metric">
    <dt class="flux-metric__label">Berths sold</dt>
    <dd class="flux-metric__value">79.7%</dd>
    <dd class="flux-metric__change" data-tone="positive"><svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M8 12.5V3.5M4.5 7L8 3.5L11.5 7" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" /></svg><span>+3.2 pts</span> <span class="flux-metric__context">vs last week</span></dd>
  </div>
  <div class="flux-metric">
    <dt class="flux-metric__label">Revenue booked</dt>
    <dd class="flux-metric__value"><span class="flux-metric__unit">ISK</span>48.2m</dd>
    <dd class="flux-metric__change" data-tone="positive"><svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M8 12.5V3.5M4.5 7L8 3.5L11.5 7" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" /></svg><span>+6.1%</span> <span class="flux-metric__context">vs last week</span></dd>
  </div>
  <div class="flux-metric">
    <dt class="flux-metric__label">Bookings on request</dt>
    <dd class="flux-metric__value">14</dd>
    <dd class="flux-metric__change" data-tone="negative"><svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M8 12.5V3.5M4.5 7L8 3.5L11.5 7" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" /></svg><span>+5</span> <span class="flux-metric__context">since Monday</span></dd>
  </div>
  <div class="flux-metric">
    <dt class="flux-metric__label">Cancellations</dt>
    <dd class="flux-metric__value">3</dd>
    <dd class="flux-metric__change"><svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M8 3.5V12.5M4.5 9L8 12.5L11.5 9" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" /></svg><span>−1</span> <span class="flux-metric__context">vs last week</span></dd>
  </div>
</dl>

### Without changes

<dl class="flux-metrics">
  <div class="flux-metric">
    <dt class="flux-metric__label">Departures this week</dt>
    <dd class="flux-metric__value">23</dd>
  </div>
  <div class="flux-metric">
    <dt class="flux-metric__label">Travellers</dt>
    <dd class="flux-metric__value">412</dd>
  </div>
  <div class="flux-metric">
    <dt class="flux-metric__label">Guides assigned</dt>
    <dd class="flux-metric__value">19 of 23</dd>
  </div>
</dl>

## API
- flux-metrics (class): The dl and its surface. Lays out metrics in columns of at least --flux-metric-min-width that wrap. Inside a flux-card it drops its border, fill and padding, because the card is already the surface.
- flux-metric (class): One metric: a div holding one dt and one or two dd. Spans three subgrid rows so parts align across the row.
- flux-metric__label (class): The dt naming the figure.
- flux-metric__value (class): The dd holding the figure, on one line. Include the unit: a symbol such as % inline, a currency code or unit word in flux-metric__unit before the figure.
- flux-metric__unit (class): A span inside the value for a currency code or unit word, set at label size so the figure keeps the weight.
- flux-metric__change (class): Optional dd: an aria-hidden arrow svg, the signed change in a span, then flux-metric__context.
- data-tone (attribute): On the change: positive or negative, by meaning. Leave it off for a neutral change.
- flux-metric__context (class): The comparison period, such as "vs last week". Required whenever there is a change.

## Accessibility
- Use dl, dt and dd so each figure is announced with its label.
- Colour is never the only signal: the arrow shows direction and the signed text states it, so a change reads correctly without the tint.
- Write the sign and unit into the text, as "+3.2 pts" or "−1". A bare number gives no direction to a screen reader.
- Name the row with a heading above it when the page has more than one set of metrics.

## Keyboard
- —: Not interactive. If a metric opens a report, put a link in the label rather than making the whole tile a button.

## Tokens
- --flux-metric-min-width
- --flux-metric-padding
- --flux-metric-gap-x | -gap-y | -part-gap
- --flux-metric-bg | -border | -radius
- --flux-metric-label-color | -label-size
- --flux-metric-value-color | -value-size | -value-tracking
- --flux-metric-change-size | -neutral | -positive | -negative
- --flux-metric-icon-size

## Do
- Show three to five metrics. More than that and none of them is headline.
- Use one comparison period across the row, so the changes can be compared.
- Decide the tone from the consequence: rising cancellations are negative even though the arrow points up.
- Keep related metrics on one surface, and put the work they point to — the exceptions table — directly below.

## Do not
- Do not give every metric its own card. One surface groups them; the important change carries the emphasis.
- Do not wrap the row in a second bordered box. Inside a card it drops its own surface and uses the card’s; do not add vertical dividers between metrics either.
- Do not colour a change just because it moved. Neutral is the default.
- Do not add a coloured bar, icon tile or sparkline to each metric as decoration.
- Do not shrink the value to fit more metrics in a row. Let the row wrap.