KPI Card

Sizes — mini · sm · md · lg

Four sizes scale the value, suffix, trend, icon, and card padding together. Use mini for the densest layouts — a smaller value sitting tight to its label (half the gap), sm for dense dashboards with many metrics on screen, md as the default, and lg when the KPI row is the page's hero. Note: the trend value uses raw text-* font-bold rather than a t-h* token so the semantic text-success / text-destructive color isn't overridden by the token's text-foreground-strong.

Compact group — merged-border block

Wrap KpiCards in <KpiCardGroup compact> to merge them into a single visual block — children drop their individual rounding and shadow and their borders overlap by 1px so the seam reads as one line. Horizontal on desktop, stacks vertically on mobile. Pairs with any size, shown below at all three.

Compact table — two rows (4 + 2)

<KpiCardGroup compact columns={4}> renders one seamless bordered table with 1px hairline dividers. The first row is four cells; the second row's two cards use className="sm:col-span-2" to each span two columns, so it reads as two wider cells — all attached as a single block.

States — positive · negative · small · empty

Pass change as a signed percentage: positive renders a success pill with an up-arrow, negative renders destructive with a down-arrow, and 0 or undefined renders no delta at all (zero isn't a trend). When the numeric value resolves to 0 and no change is provided, the card shows a quiet "No data yet" empty state instead.

Icon · description · loading

Pass an icon to add a muted topic glyph in the top-end corner (useful when several KPIs share a row and the eye needs an extra cue). description renders a small context line under the value — most often the comparison window the change refers to. While loading is true the card swaps to skeleton placeholders without changing its height, so the dashboard layout doesn't jump on fetch.

Clickable

Pass an onClick handler and the card automatically becomes interactive — resting at shadow-xs and lifting to shadow-md on hover, with a pointer cursor. No extra prop required.