Prepared Docs

Overview

MetricCard is a closed preset on CardHeader and CardContent, not a Card variant. It accepts no children. The value stays base-colored. Tone, when present, colors only the delta label and arrow fill.

When to use

Compact KPI tiles where label and value are the equivalent of the visual.
Optional odometer animation on the numeric value and, separately, a visual-only delta roll.
Header range controls that are not combined with a clickable tile.
A decorative sparkline or compact chart in trailing when there is no delta.

When not to use

Full charts, semantic tables, or nested body controls: use ordinary Card.
Selectable plan or feature cards: use radio or checkbox card groups.
Navigation: MetricCard has an action target only. There is no href branch.
A clickable tile that also needs header controls: put the action in CardFooter on ordinary Card.

Composition

Interior layout is locked: Card Surface padding, a header label, then a flush-left non-heading value.

The value is always TextType.NumericDisplay at 2.4rem. Tabular figures keep percentages, counts, durations, and animated values visually consistent.
delta is a discriminated model. Direction picks the arrow; tone picks the color. They stay orthogonal so a decrease can be success.
Tone is an invariant, not a default to override: it colors the delta label text and the arrow fill only. The large value stays TextColor.Base under every tone, selected, and loading state.
introduced and unavailable render a localized label with no arrow, tone, or magnitude.
delta and trailing are mutually exclusive. Trailing stays decorative and aria-hidden. The 2.8rem trailing box mounts only when trailing is a renderable node, not false from condition && visual.
controls forwards to CardHeader.controls. It is unrepresentable on a clickable MetricCard.
Loading shows one visible status, hides skeleton geometry, and suppresses value, subtitle, trailing, and delta.

Best practices

Localize label, subtitle, loadingLabel, delta status labels, and action aria-label with useTranslation().
Keep trailing decorative. Named charts belong in ordinary Card with a visible summary.
Supply from only when loading-to-ready should roll; omission snaps.
Put any spoken delta wording in the value announcement. The delta odometer is visual-only.

Don't

Pass children or Card appearance props.
Color the large value with tone.
Combine delta with trailing, or controls with onClick.
Announce every odometer tick. Live mode defaults off.

Card
Text for NumericDisplay, NumericCompact, and the CoreText odometer contract
Visualization charts
Skeleton for the single-status loading cluster

Message / Accessibility

Metric Card / API and Development

Overview

When to use

Compact KPI tiles where label and value are the equivalent of the visual.
Optional odometer animation on the numeric value and, separately, a visual-only delta roll.
Header range controls that are not combined with a clickable tile.
A decorative sparkline or compact chart in trailing when there is no delta.

When not to use

Full charts, semantic tables, or nested body controls: use ordinary Card.
Selectable plan or feature cards: use radio or checkbox card groups.
Navigation: MetricCard has an action target only. There is no href branch.
A clickable tile that also needs header controls: put the action in CardFooter on ordinary Card.

Composition

Interior layout is locked: Card Surface padding, a header label, then a flush-left non-heading value.

The value is always TextType.NumericDisplay at 2.4rem. Tabular figures keep percentages, counts, durations, and animated values visually consistent.
delta is a discriminated model. Direction picks the arrow; tone picks the color. They stay orthogonal so a decrease can be success.
Tone is an invariant, not a default to override: it colors the delta label text and the arrow fill only. The large value stays TextColor.Base under every tone, selected, and loading state.
introduced and unavailable render a localized label with no arrow, tone, or magnitude.
delta and trailing are mutually exclusive. Trailing stays decorative and aria-hidden. The 2.8rem trailing box mounts only when trailing is a renderable node, not false from condition && visual.
controls forwards to CardHeader.controls. It is unrepresentable on a clickable MetricCard.
Loading shows one visible status, hides skeleton geometry, and suppresses value, subtitle, trailing, and delta.

Best practices

Localize label, subtitle, loadingLabel, delta status labels, and action aria-label with useTranslation().
Keep trailing decorative. Named charts belong in ordinary Card with a visible summary.
Supply from only when loading-to-ready should roll; omission snaps.
Put any spoken delta wording in the value announcement. The delta odometer is visual-only.

Don't

Pass children or Card appearance props.
Color the large value with tone.
Combine delta with trailing, or controls with onClick.
Announce every odometer tick. Live mode defaults off.

Card
Text for NumericDisplay, NumericCompact, and the CoreText odometer contract
Visualization charts
Skeleton for the single-status loading cluster

Message / Accessibility

Metric Card / API and Development