# MetricCard

> One number that matters, with its label, unit and change.

- **Level**: molecule · **Status**: stable · **Role**: content
- **Import**: `import { MetricCard } from "@rrios-forge/ui/molecules/metric-card";`
- **Source**: `packages/ui/src/molecules/metric-card`

Apple-Fitness-register dashboard tile: small caps label, tabular-nums value, optional unit + delta pill + progress + description. Always raised material (ADR-007). Three axes: `tone` (left rail + icon-pill tint), `density` (comfortable / compact), `emphasis` (default / featured — featured uses font-display).

## Use it for

- KPI / metric → `MetricCard`
- A trend in a tile or a row → `Sparkline` (in `MetricCard`'s `trend` slot)
- A chart (trend, comparison, part to whole) → `Chart` with the `form` the data's job names (`dataviz.yaml`); a single number is a `MetricCard`, many classes a `DataTable`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `tone` | — | `neutral` `info` `success` `warning` `danger` | `neutral` | Which semantic colour family the element speaks in. |
| `prominence` | — | `default` `featured` | `default` | How a surface stands among its siblings. |

## Stories

- [Playground](/?path=/story/components-molecules-metriccard--playground) · frame: `/iframe.html?id=components-molecules-metriccard--playground&viewMode=story`
- [Canonical (icon + delta + unit)](/?path=/story/components-molecules-metriccard--canonical) · frame: `/iframe.html?id=components-molecules-metriccard--canonical&viewMode=story`
- [Tones](/?path=/story/components-molecules-metriccard--tones) · frame: `/iframe.html?id=components-molecules-metriccard--tones&viewMode=story`
- [Featured (display ramp)](/?path=/story/components-molecules-metriccard--featured) · frame: `/iframe.html?id=components-molecules-metriccard--featured&viewMode=story`
- [Compact (dense panels)](/?path=/story/components-molecules-metriccard--compact) · frame: `/iframe.html?id=components-molecules-metriccard--compact&viewMode=story`
- [With progress](/?path=/story/components-molecules-metriccard--with-progress) · frame: `/iframe.html?id=components-molecules-metriccard--with-progress&viewMode=story`
- [Dashboard grid](/?path=/story/components-molecules-metriccard--dashboard-grid) · frame: `/iframe.html?id=components-molecules-metriccard--dashboard-grid&viewMode=story`
- [Minimal (no chrome)](/?path=/story/components-molecules-metriccard--minimal) · frame: `/iframe.html?id=components-molecules-metriccard--minimal&viewMode=story`

## Decisions that name it

- ADR-005 — Visual operational rules: surfaces, interaction, motion
- ADR-006 — Geometry and typography signature
- ADR-007 — Material highlight on raised surfaces
- ADR-008 — Layout layer: refined `Grid` + new `Container`
- ADR-009 — Editorial Frame: PageShell v3 + new `TopBar` molecule
- ADR-012 — Card.fill axis for symmetric growth in grids
- ADR-027 — Vibrant is the system's material, not one of its members
- ADR-029 — The page gutter belongs outside the frame
- ADR-030 — Axis vocabulary: one name, one meaning
- ADR-034 — Accessible names come from a labels provider
- ADR-036 — Data visualization: colour roles, a grammar, and three components on plain SVG
- ADR-037 — Continuity motion: a decelerating curve, a travelling indicator, view transitions and the SegmentedControl
- ADR-038 — Liquid Glass layers: glass for navigation and controls, a content material for everything read

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).