Data viz
KPI cluster
The row of stat tiles that crowns a dashboard. Each tile pairs a headline number and a tone-aware delta with an embedded micro-viz — a sparkline for a trend, a gauge for a rate against a ceiling.
npx shadcn@latest add @orbit/kpi-clusterOverview
Sprint 24 at a glance — four tiles, four micro-viz shapes.
Micro-viz types
Set viz on each tile. Area and line trace a series over time, bars suit discrete periods, and a gauge frames a value against its 0–100 ceiling. A lone tile is just a KPITile.
Tone-aware delta
Direction and meaning are separate. The arrow follows the number's movement; the color follows whether that movement is good. A falling cycle-time is green and points down — so set tone by impact, not by sign.
Layout
One columns prop drives an equal-width grid. Tiles never shrink their numbers — give six tiles room, or stack to two on a narrow panel.
Props
KPICluster lays out the grid; each entry in data (or a standalone KPITile) takes the tile fields.
| Prop | Type | Default | Description |
|---|---|---|---|
| data | KPITileData[] | — | The tiles, most important metric first. KPICluster only. |
| columns | number | data.length | Equal-width grid columns (1–6). KPICluster only. |
| label | string | — | Metric name shown above the value. |
| value | string | — | Headline value, preformatted — it is never scaled down. |
| unit | string | — | Unit rendered after the value (“pts”, “%”, “d”). |
| delta | string | — | Delta text (“+18%”, “−11%”) — a leading minus draws a down arrow. |
| tone | "pos" | "neg" | "warn" | "neutral" | "neutral" | Impact of the change — colors the pill with success / danger / warning / neutral tokens. |
| dir | "up" | "down" | — | Arrow direction override, when sign and direction disagree. |
| viz | "area" | "line" | "bar" | "gauge" | "area" | Micro-viz shape for the tile. |
| accent | string | "var(--pri)" | Viz color (any token or color-mix). |
| series | number[] | — | Series for area | line | bar. |
| gauge | number | — | 0–100 value for the gauge arc. Falls back to parsing value. |
| …rest | HTMLAttributes | — | Forwarded to the root (div for KPICluster, figure for KPITile), including ref and className. |
Usage
A KPI cluster is a glance, not a report — three to six tiles of the metrics that decide the day, nothing more.
Limit to the vital few
Three to six tiles. Past that the row stops being a glance and becomes a table.
Mix unrelated time frames
If one tile is “this sprint” and another is “all-time”, the row reads as inconsistent. Align the window.
Set tone by impact
Fewer bugs is good even though the arrow may point either way — color by what it means, not its sign.
Use a gauge for an open metric
Gauges imply a 0–100 ceiling. For an unbounded count like velocity, use a sparkline instead.
Keyboard & accessibility
The cluster is a group of labelled figures; every delta is spelled out as arrow plus text.