Skip to content
skrewww

Content & Data

Chart Metric

Chart Metric is a labeled value with an optional directional delta, for use above a chart or standalone — the delta's direction drives only its icon, never a color.

Single component — no variants

betaReact AvailableFigma UnavailableDocs Partial
React last updated
2026-09-22
Documentation last updated
2026-09-22
Accessibility target
WCAG 2.2 AA (target)
Version
0.1.0-beta

Known open questions

  • No Figma reference exists for Chart Metric — its typography was extracted from three independent, ad hoc implementations that already existed: Banking Account Card's `.balance`, Banking Balance Summary's `.totalValue` (byte-identical CSS to `.balance`), and the Reference App overview page's raw Tailwind `text-3xl font-semibold tabular-nums`. No Figma parity is claimed.
  • Positive/negative semantic coloring (e.g. tying `direction` to a feedback/status color) is an explicit non-goal for v1: an increase is not always a good outcome (spend, churn, error rate), so no green-is-good/red-is-bad rule exists. If a future, evidence-based semantic model is designed, it is a deliberate addition, not a bug fix.
  • Chart Metric was not retrofitted onto Banking Account Card, Banking Balance Summary, or the Reference App overview page — all three predate it and remain unchanged; the duplication is recorded as evidence, not migrated.

Purpose

A labeled value with an optional directional delta, for use above a chart (typically inside Chart Card) or standalone.

Anatomy

A label (`p`, semantic/text/secondary) above a value (`p`, semantic/text/primary, tabular-nums), with an optional delta rendered inline after the value: a directional icon (ArrowUp, ArrowDown, or Minus from Phosphor, aria-hidden), a visually-hidden word ("Increased"/"Decreased"/"Unchanged") naming the direction for assistive tech, the pre-formatted delta value, and an optional comparison label. The delta's color is the same semantic/text/secondary as the label — never a feedback/status token — regardless of direction.

Variants and states

default

When to use

Summarizing a chart with a headline number — a total, a count, a current value — optionally with how it changed versus a comparison period.

When not to use

Business-specific metrics with their own semantics (revenue, occupancy, patient counts) — those are an industry composition's naming decision, not Chart Metric's; it only displays a pre-formatted label/value/delta you supply.

Accessibility

The delta's direction is announced in words ("Increased"/"Decreased"/"Unchanged") via visually-hidden text before the value, so it is never conveyed by the icon or color alone. The delta icon is aria-hidden.

Common mistakes

Assuming an "increase" is colored green (or a "decrease" red) — it never is; `direction` selects only the icon. Passing an unformatted number — value/delta are pre-formatted strings, matching Bar/Line/Area Chart's own established convention.

Properties

label (string). value (pre-formatted string, e.g. "$4,231.09"). delta ({ direction: "up" | "down" | "flat"; value: string; label?: string } — direction drives only the icon; value is pre-formatted, e.g. "+4.2%"; label is optional comparison context, e.g. "vs last 30 days").

Why doesn't an upward delta render green (or a downward delta red)?

Direction is not sentiment. An increase can be a bad outcome (costs, churn, error rate) as easily as a good one, so Chart Metric makes no claim either way — it shows an arrow and lets the label/context ("Revenue" vs. "Errors") carry the meaning.

Why isn't this a `size` variant?

All three real implementations Chart Metric replaces used the same 1.5rem/700-weight value styling — there was no evidence for a second size, so v1 ships exactly one.

Tokens used

semantic/text/primarysemantic/text/secondary

Component API

PropTypeDefaultDescription
labelstring—The metric's label.
valuestring—Pre-formatted value (e.g. "$4,231.09") — formatting is the consumer's responsibility.
delta{ direction: "up" | "down" | "flat"; value: string; label?: string }—Optional directional delta. `direction` selects only the icon; `value` is pre-formatted (e.g. "+4.2%"); `label` is optional comparison context (e.g. "vs last 30 days").

React example

Copy React example
import { ChartMetric } from "@/components/ui";

export function Example() {
  return <ChartMetric label="Total balance" value="$4,231.09" />;
}

export function WithDeltaExample() {
  return (
    <ChartMetric
      label="Revenue"
      value="$12,000"
      delta={{ direction: "up", value: "+4.2%", label: "vs last 30 days" }}
    />
  );
}

Related components

Related tokens