Metric Cards - A-raf Design System

Overview

Metric Cards are used to display key quantitative data on dashboards. Each card shows one primary metric, equipped with a trend indicator (positive/negative), and an optional action button to view a detailed report.

Views 24 hours⋮

2,000

↑ 100

↗

⋮

Views 24 hours

2,000

↑ 100

↗

Views 24 hours

⋮

2,000

↗ 100%vs last month

Views 24 hours⋮

2,000

↗ 100%vs last month

Installation

npm install @araf-ds/core

Usage

import { MetricCard } from "@araf-ds/core";

export default function Dashboard() {
  return (
    <MetricCard
      type="chart"
      label="Views 24 hours"
      value="2,000"
      trend="positive"
      change={100}
      changeLabel="vs last month"
      actions
      onViewReport={() => router.push("/reports/views")}
    />
  );
}

Type Variants

Metric Cards have 4 types that determine how the metric is visualized.

Simple
Icon 01
Icon 02
Chart

The most compact type — displays only the label, metric number, and a trend badge aligned to the bottom-right of the number. Ideal for simple metrics without additional visual context.

Views 24 hours⋮

2,000

↑ 100

Bounce Rate⋮

4,120

↓ 40

<MetricCard
  type="simple"
  label="Views 24 hours"
  value="2,000"
  trend="positive"
  change={100}
/>

Displays a large featured icon at the top of the card with a colored background and border. The icon is chosen to match the metric type. The metric number and trend badge appear below.

↗

⋮

Views 24 hours

2,000

↑ 100

↘

⋮

Bounce Rate

4,120

↓ 40

<MetricCard
  type="icon-01"
  label="Views 24 hours"
  value="2,000"
  icon={<ArrowCircleUpRightIcon />}
  trend="positive"
  change={100}
/>

Features an icon of the same size (48px), but with a different layout — the icon and label are on the same row (horizontal). The number and percentage change appear at the bottom in inline text format.

↗

Views 24 hours

⋮

2,000

↗ 100%vs last month

↘

Bounce Rate

⋮

4,120

↘ 12%vs last month

<MetricCard
  type="icon-02"
  label="Views 24 hours"
  value="2,000"
  icon={<TrendUpIcon />}
  trend="positive"
  change={100}
  changeLabel="vs last month"
/>

Displays a mini sparkline chart (128×64px) in the bottom-right corner of the card to visualize the data trend over a period. The label sits at the top, with the number and percentage change to the left of the chart.

Views 24 hours⋮

2,000

↗ 100%vs last month

Bounce Rate⋮

4,120

↘ 12%vs last month

<MetricCard
  type="chart"
  label="Views 24 hours"
  value="2,000"
  trend="positive"
  change={100}
  changeLabel="vs last month"
  chartData={[12, 18, 14, 22, 28, 35, 42, 50]}
/>

Actions

The actions prop adds a “View report” button at the bottom of the card, which can be used to navigate to a detailed report page.

actions=false (default)

Views 24 hours⋮

2,000

↑ 100

actions=true

Views 24 hours⋮

2,000

↑ 100

View report →

// With action button
<MetricCard
  type="simple"
  label="Views 24 hours"
  value="2,000"
  trend="positive"
  change={100}
  actions
  onViewReport={() => router.push("/reports/views")}
/>

Trend Indicator

Every Metric Card displays a trend indicator to show the change compared to the previous period.

Badge (Simple & Icon 01)

↑ 100 Positive↓ 40 Negative

State	Background	Text	Icon
Positive	`#ECFDF3` (Success/50)	`#027A48` (Success/700)	`arrow-up`
Negative	`#FEF3F2` (Error/50)	`#B42318` (Error/700)	`arrow-down`

Change Text (Icon 02 & Chart)

↗ 100% vs last month↘ 12% vs last month

State	Color	Icon
Positive	`#16A34A` (Green/07)	`arrow-up-right`
Negative	`#B42318` (Error/700)	`arrow-down-right`

Breakpoints

Desktop
Mobile

Card width is 388px, with 24px padding on all sides.

Property	Value
Width	388px
Padding	24px
Metric number	36px Inter SemiBold
Label	14–16px Inter Medium
Chart	128×64px
Featured icon	48×48px

Card width is 328px (inside a 360px container with 16px left/right padding). The layout does not change significantly — only the width adapts. The actions prop is not available on the mobile variant.

Property	Value
Width	328px
Padding	24px
Metric number	36px Inter SemiBold
Actions	Not available

Views 24 hours⋮

2,000

↑ 100

Design Tokens

Card

Token	Value
Background	`#FFFFFF`
Border radius	`8px`
Padding	`24px`
Shadow	`0px 1px 3px rgba(16,24,40,0.1)` + `0px 1px 2px rgba(16,24,40,0.06)`

Typography

Element	Font	Size	Weight	Color
Label (Simple/Icon 01)	Inter	14px	500	`#71717A`
Label (Icon 02/Chart)	Inter	16px	500	`#011829`
Metric number	Inter	36px	600	`#011829`
Change text	Inter	14px	500	`#16A34A` / `#B42318`
Context label	Inter	14px	500	`#71717A`

Featured Icon (Icon 01)

Trend	Background	Border
Positive	`#22C55E`	`8px solid #16A34A`
Negative	Color matching the metric type	8px solid border (darker shade)

Featured Icon (Icon 02)

Trend	Background	Border	Icon color
Positive	`#DBEAFE`	`8px solid #EFF6FF`	`#1D4ED8`
Negative	`#FEE2E2`	`8px solid #FFF1F2`	`#DC2626`

API Reference

`MetricCard`

type

"simple" | "icon-01" | "icon-02" | "chart"

required

The display type of the metric card.

label

string

required

The metric label text, displayed above the number.

value

string | number

required

The primary metric value displayed large (e.g. "2,000", "89%").

trend

"positive" | "negative"

required

The direction of the metric change — determines the color and icon of the trend indicator.

change

number

required

The numeric change value (e.g. 100 → displayed as ↑ 100 or 100%).

changeLabel

string

default:"\"vs last month\""

The descriptive text for the change. Only shown on icon-02 and chart types.

icon

ReactNode

The icon displayed in the featured icon area. Required for icon-01 and icon-02 types.

chartData

number[]

Data array for the sparkline chart. Required for the chart type.

actions

boolean

default:"false"

If true, displays a “View report” button at the bottom of the card (Desktop only).

onViewReport

() => void

Callback fired when the “View report” button is clicked. Required when actions is true.

breakpoint

"desktop" | "mobile"

default:"\"desktop\""

The rendering breakpoint of the card. Mobile does not support the actions prop.

className

string

Additional class name for custom styling.

Accessibility

Use a descriptive aria-label on the card for screen readers, e.g. aria-label="Views 24 hours: 2,000, up 100 from the previous period"
Trend icons should include aria-hidden="true" since they are already represented by the change text
The “View report” button must have clear text or an aria-label if it only shows an icon
Ensure the trend badge color contrast meets WCAG AA (green #027A48 on #ECFDF3 ✓)
The sparkline chart should include role="img" and an aria-label describing the trend

Do’s & Don’ts

Do

Use one metric per card
Ensure changeLabel provides clear context (e.g. “vs last week”)
Choose the chart type for metrics with significant fluctuations that need to be visualized
Arrange cards in a 3–4 column grid on desktop
Use the icon-01 type for metrics with a clear visual category (sales, traffic, etc.)

Don't

Don’t display more than one large number per card
Don’t use the chart type for static data (with no change over time)
Don’t let value get too long — truncate if needed (e.g. 2.3M not 2,312,400)
Don’t hide the trend indicator — always provide change context
Don’t use actions=true without a working onViewReport handler

Documentation Index

​Overview

​Installation

​Usage

​Type Variants

​Actions

​Trend Indicator

​Badge (Simple & Icon 01)

​Change Text (Icon 02 & Chart)

​Breakpoints

​Design Tokens

​Card

​Typography

​Featured Icon (Icon 01)

​Featured Icon (Icon 02)

​API Reference

​MetricCard

​Accessibility

​Do’s & Don’ts

Do

Don't

Overview

Installation

Usage

Type Variants

Actions

Trend Indicator

Badge (Simple & Icon 01)

Change Text (Icon 02 & Chart)

Breakpoints

Design Tokens

Card

Typography

Featured Icon (Icon 01)

Featured Icon (Icon 02)

API Reference

`MetricCard`

Accessibility

Do’s & Don’ts