Metric card
<forma-metric-card>
A compact labeled value with context and optional action, without inventing metric meaning.
- Authoring tag
<forma-metric-card>- Category
- Data display
- Behavior owner
- Application content
- Canonical source
patterns/metric-card.html
Purpose
A metric card shows one application-supplied number or short value with its label, optional context and an optional link to the underlying records. Forma gives the card a border, a secondary-colored label and a large display-type value that scales with the viewport. It never computes, compares, colors by trend or interprets the value: whether a number is good, bad, stale or unknown is text the application writes.
Use when
- A dashboard or overview needs a few headline values users check at a glance, such as open work or outstanding receivables.
- Each value has a clear label and, where needed, context such as the period, freshness or a status in words.
- A value leads to a list or report the user can open for detail.
Avoid when
- The value updates live and the update should be marked: use Metric value change, which adds the neutral update tint and live announcement.
- Several related values about one record are shown: use Key-value list.
- The number is a proportion of a known range users need to judge: show it with a native
meteror a Progress bar. - The value needs its derivation explained: pair the card with a Provenance trail rather than packing it into the card.
Behavior to know
- The value uses the display font at
clamp(2rem, 8vw, 3.5rem)with a line-height of 1, so it scales down on phones. - Label, value and any following content stack in a single grid column with 0.5rem gaps.
- The card is
min-inline-size: 0, so it can shrink inside Dashboard grid or Responsive grid columns. - No color is applied to the value; direction and state must be written as text.
Basic example
The smallest correct markup: the canonical pattern from patterns/metric-card.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal metric card
Rendered from the canonical pattern file.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-metric-card class="forma-component-tag">
<article class="forma-metric-card">
<div class="forma-metric-card__label">Outstanding AR</div>
<div class="forma-metric-card__value">$42,500</div>
<div class="forma-metric-card__context"><span class="forma-status-lozenge" data-state="attention">$12,500 overdue</span></div>
<a href="#details">View receivables</a>
</article>
</forma-metric-card>
Click or tap the code once to select all of it, then copy.
Examples
Value not available
The metric source is unavailable. The card shows the word Unknown instead of zero or a dash, and a sentence says why, so a missing number is never read as a real one.
Source unavailable
The payment processor feed has not reported since 06:00 UTC.
<forma-metric-card class="forma-component-tag">
<article class="forma-metric-card" aria-labelledby="metric-card-unknown-value-label">
<div class="forma-metric-card__label" id="metric-card-unknown-value-label">Failed payments today</div>
<div class="forma-metric-card__value">Unknown</div>
<p><span class="forma-status-lozenge" data-state="unknown">Source unavailable</span></p>
<p>The payment processor feed has not reported since 06:00 UTC.</p>
</article>
</forma-metric-card>
Click or tap the code once to select all of it, then copy.
Value with freshness and period
The value is stated with its period and a Freshness line, so users can tell how current it is. A trend is written as words ("down 4 from last week"), not as a green or red arrow.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
Down 4 from the previous 7 days.
Last updated Stale: refresh overdue by 2 hours
View incidents<forma-metric-card class="forma-component-tag">
<article class="forma-metric-card" aria-labelledby="metric-card-stale-with-freshness-label">
<div class="forma-metric-card__label" id="metric-card-stale-with-freshness-label">Open incidents, last 7 days</div>
<div class="forma-metric-card__value">12</div>
<p>Down 4 from the previous 7 days.</p>
<p class="forma-freshness"><span class="forma-freshness__label">Last updated</span> <time datetime="2026-09-29T05:00:00Z">05:00 UTC</time> <span>Stale: refresh overdue by 2 hours</span></p>
<a href="#metric-card-stale-with-freshness-incidents">View incidents</a>
</article>
</forma-metric-card>
Click or tap the code once to select all of it, then copy.
Dashboard row with long labels
Three cards in a Dashboard grid. Labels of different lengths wrap inside their cards; the value scale stays the same across cards, so no value looks more important than another.
As of 29 Sep 2026.
31 invoices past due.
No open disputes.
<forma-metric-card class="forma-component-tag">
<section class="forma-dashboard-grid" aria-label="Receivables overview">
<article class="forma-metric-card"><div class="forma-metric-card__label">Outstanding receivables across all subsidiaries</div><div class="forma-metric-card__value">$1,204,500</div><p>As of 29 Sep 2026.</p></article>
<article class="forma-metric-card"><div class="forma-metric-card__label">Overdue</div><div class="forma-metric-card__value">$212,040</div><p>31 invoices past due.</p></article>
<article class="forma-metric-card"><div class="forma-metric-card__label">Disputed</div><div class="forma-metric-card__value">0</div><p>No open disputes.</p></article>
</section>
</forma-metric-card>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile metric stack
Two cards at phone width. The value shrinks toward its 2rem minimum and each card keeps its label, context and link in reading order.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
What changes at narrow widths
- The value size follows
clamp(2rem, 8vw, 3.5rem): about 2rem at 320px and 390px, reaching 3.5rem only at wide viewports. - Inside Dashboard grid the cards collapse to one column at 40rem and below, keeping the application's order.
- Long labels and context text wrap; the card has
min-inline-size: 0so it never forces horizontal scrolling. - The trailing link is an ordinary inline link; keep its text descriptive so it is a usable tap target on its own line.
- Rotation only changes the value's viewport-relative size between the clamp bounds.
<forma-metric-card class="forma-component-tag">
<div class="forma-stack" data-density="compact">
<article class="forma-metric-card">
<div class="forma-metric-card__label">Needs attention</div>
<div class="forma-metric-card__value">7</div>
<p><span class="forma-status-lozenge" data-state="attention">3 overdue</span></p>
<a href="#metric-card-mobile-metric-stack-attention">Open attention queue</a>
</article>
<article class="forma-metric-card">
<div class="forma-metric-card__label">Completed this month</div>
<div class="forma-metric-card__value">42</div>
<p>Through 29 September.</p>
</article>
</div>
</forma-metric-card>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
aria-labelledby | article.forma-metric-card | id of .forma-metric-card__label | — | Names the card by its label when several cards appear together. |
datetime | time | ISO date-time | — | Machine-readable update time in freshness context. |
href | a | URL | — | Optional link to the records behind the value. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-metric-card | Block class | — | The card root, usually an article. Bordered grid with 1.25rem padding and 0.5rem gaps; shrinkable to zero width. |
.forma-metric-card__label | Element class | — | The metric's label in secondary text color, 0.8125rem, semibold. |
.forma-metric-card__value | Element class | — | The value in the display font at clamp(2rem, 8vw, 3.5rem), line-height 1. |
| Keys | Result |
|---|---|
| Tab | Reaches the optional link or button in the card. The card itself is not focusable. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Known value | application text in .forma-metric-card__value | The number or short value in display type. |
| Unknown or unavailable | application text such as Unknown plus context | Forma has no special styling; the words carry the state. |
| Stale | context text, for example a Freshness line | The age of the value is stated next to it. |
| Updated | data-forma-value-change on the value (see Metric value change) | A neutral tint briefly marks an application-published update. |
Accessibility
Forma provides
- Label and value are real text in reading order, so screen readers read the label before the value.
- The value has no color coding, so meaning never depends on hue.
- Text uses semantic color tokens that map to system colors in forced-colors mode.
Your application supplies
- Name the card with
aria-labelledbyon the label when cards are presented as a group. - Write units, period and direction as text ("Down 4 from last week").
- Show Unknown, Unavailable or Stale explicitly; never substitute zero.
- Give links descriptive text rather than "More".
Responsive behavior
- Intrinsic width: the card shrinks to its container (
min-inline-size: 0). - The value scales with the viewport between 2rem and 3.5rem.
- Arrange several cards with Dashboard grid (three columns, one at 40rem and below) or Responsive grid.
- Very long unbroken values can still exceed a narrow card; keep values short or format them with separators.
Motion
- No animation on the card itself. Marking a live update is the separate Metric value change contract, which tints the value with a neutral perceptual fade and never counts through numbers.
Usage guidance
Do
- Pair each value with its period and, for live data, its freshness.
- Link to the records behind the number when users will want to act on it.
Avoid
- Coloring the value green or red to imply good or bad.
- Animating numbers counting up; show the authoritative value immediately.
- Showing zero or a dash when the value is unknown.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.