Stat card

StatCard is a compact tile for dashboard metrics: a 4px top accent in semantic colors, a muted label, and a prominent value. The top edge stays square so the accent reads as a full-width bar.

Interactive preview

Tune label, value, and accent. The preview uses the same `StatCard` import as your app.

Total staff

24

Props

PropTypeDefaultDescription
labelstring—Metric title; rendered as muted body text and exposed as the accessible name via `aria-labelledby`.
valueReactNode—Primary metric — number, string, or custom node (e.g. value + unit).
accent"primary" | "secondary" | "success" | "warning" | "destructive""primary"4px top border color; maps to design tokens.
classNamestring""Layout utilities only; avoid overriding surface or accent styles.

Installation

Install packages
pnpm add @akanaka-design/components @akanaka-design/tokens
Styles (app root)
import "@akanaka-design/tokens/css";
import "@akanaka-design/components/styles.css";

Usage

Basic usage
import { StatCard } from "@akanaka-design/components";

export function Example() {
  return <StatCard label="Total staff" value={24} />;
}

Accent variants

Use accent to reflect meaning (brand emphasis, success, attention, risk). Each maps to a token-backed top border.

Accent: primary
<StatCard label="Total staff" value={24} accent="primary" />
Accent: secondary
<StatCard label="Regions" value={3} accent="secondary" />
Accent: success
<StatCard label="Compliant" value={21} accent="success" />
Accent: warning
<StatCard label="Pending review" value={4} accent="warning" />
Accent: destructive
<StatCard label="Action required" value={3} accent="destructive" />
All accents (dashboard row)
import { StatCard } from "@akanaka-design/components";

export function MetricsRow() {
  return (
    <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-5">
      <StatCard label="Primary" value={100} accent="primary" />
      <StatCard label="Secondary" value={12} accent="secondary" />
      <StatCard label="Success" value={88} accent="success" />
      <StatCard label="Warning" value={5} accent="warning" />
      <StatCard label="Destructive" value={2} accent="destructive" />
    </div>
  );
}

Rich values

value is a ReactNode, so you can append units, trends, or short secondary text.

Rich value content
/* value accepts ReactNode — format numbers, add units, or nest content */
<StatCard
  label="Revenue"
  value={<span>£124k <span className="text-body-sm text-foreground-muted">YTD</span></span>}
  accent="success"
/>

Accessibility

  • The root is a section with aria-labelledby pointing at the label paragraph, so screen readers get a clear landmark name (e.g. “Total staff”).
  • Keep label short and unique when several stat cards sit in a row so each region is distinguishable in the rotor / landmarks list.
  • If the numeric value needs context beyond the label (e.g. currency or period), include that in value or add visible helper text next to the card; do not rely on color alone for meaning—accent reinforces status but should pair with the label/value copy.

Guidelines

When to use

  • KPI tiles on dashboards or summary strips
  • At-a-glance counts where one number is the focus

When not to use

  • Long-form content or multiple paragraphs — use Card instead
  • Interactive controls inside the metric — compose with Card or a custom layout

Content

  • Prefer short labels (“Active users”, “Open tickets”)
  • Align accent semantics with your product vocabulary (success / warning / destructive)