Cmpnts

Menu

Molecules

Telemetry

A labelled value, such as uptime or listeners, built on a description list.

Uptime
99.98%
Code
HTML
<dl class="telemetry">
  <dt class="small-text text-muted">Uptime</dt>
  <dd class="small-heading">99.98%</dd>
</dl>

Why it exists

A number means little without its label. HTML already has a structure for that pairing, the description list, so a screen reader keeps each value with its name. Telemetry uses it and adds a surface and a layout, and the type comes from text atoms.

These values often change while someone is looking at them, which is why Telemetry refuses to be a live region. A figure that ticks over every second would talk over everything else. The product announces only the changes that matter.

It stays small on purpose. A large stat with a description is a Card holding a Telemetry, so there’s no separate KPI component to learn.

When to use

  • For a labelled value or a row of them: a dashboard, a status strip, a player’s stats.
  • Not for a large stat with a description: that is a .card holding a Telemetry.
  • Not for a value within a known range that needs a bar: a Meter draws it.
  • Not for a Status on its own, with no label: that is a status.

Rules

  • Not a live region. Values that tick over every second would flood a screen reader. If a change matters, announce it in a separate role="status".
  • Label (dt): a text atom, with an optional leading icon.
  • Value (dd): a text atom; a unit is a smaller atom inside it. Values use tabular figures.

Label Each Value

Listeners
14,820
Latency
42ms
Bitrate
320kbps
Uptime
99.98%
Errors
3
Followers
2,310
Code
HTML
<dl class="telemetry-group" aria-label="Station">
  <div class="telemetry">
    <dt class="small-text text-muted">
      <svg class="icon" width="1em" height="1em" aria-hidden="true" focusable="false"><use href="#User"/></svg>
      Listeners
    </dt>
    <dd class="small-heading">14,820</dd>
  </div>
  <div class="telemetry">
    <dt class="small-text text-muted">Latency</dt>
    <dd class="small-heading">42<span class="small-text">ms</span></dd>
  </div>
</dl>

<!-- One metric -->
<dl class="telemetry">
  <dt class="small-text text-muted">Bitrate</dt>
  <dd class="small-heading">320<span class="small-text">kbps</span></dd>
</dl>

<!-- One bordered strip, with a divider between items -->
<dl class="telemetry-group telemetry-group--ruled" aria-label="Network">
  <div class="telemetry">
    <dt class="small-text text-muted">Uptime</dt>
    <dd class="small-heading">99.98%</dd>
  </div>
  <div class="telemetry">
    <dt class="small-text text-muted">Errors</dt>
    <dd class="small-heading">3</dd>
  </div>
</dl>

<!-- The icon in a gutter at the start of the box -->
<dl class="telemetry-group" aria-label="Audience">
  <div class="telemetry telemetry--icon-start">
    <dt class="small-text text-muted">
      <svg class="icon" width="1em" height="1em" aria-hidden="true" focusable="false"><use href="#User"/></svg>
      Followers
    </dt>
    <dd class="small-heading">2,310</dd>
  </div>
</dl>

A trend or state is a plain status in the value, with an icon and signed text, so it is never colour alone.

Listen hours
128,450 +18.2%
Code
HTML
<dl class="telemetry-group" aria-label="Listening">
  <div class="telemetry">
    <dt class="small-text text-muted">Listen hours</dt>
    <dd class="heading">
      128,450
      <span class="status status--plain status--success">
        <svg class="icon" width="1em" height="1em" aria-hidden="true" focusable="false"><use href="#ArrowUp"/></svg>
        +18.2%
      </span>
    </dd>
  </div>
</dl>

Pick the intent by meaning, not direction: a rising drop-off rate is --danger. Where the sign isn’t enough, add hidden text: <span class="sr-only">up</span> or “up 12.4% on last week”.

Do and Don’t

DoDon’t
Use a description list: dt for the label, dd for the value.Rebuild it with divs and label classes.
Pair a trend with an icon and signed text.Show a trend in colour alone.
Pick the intent by meaning: a rising drop-off rate is --danger.Pick the intent by direction.
Announce a change that matters in a separate role="status".Make a ticking value a live region.
Put a large stat with a description in a .card.Look for a KPI Card variant.

In Storybook

See also

  • Badge, Status, Chip and Kbd: Small labels chosen by their job, such as a count on something, the state of something, a value someone chose or a key to press.
  • Card: A surface with named parts, such as a header, a body and a footer, for one thing a person can read, compare or act on.
  • Lockup: A primary line of text with a secondary one under it, such as a name and an email.
  • Progress and Meter: A bar for how far a task has got, or for a measurement within a known range.

Search the docs