> ## Documentation Index
> Fetch the complete documentation index at: https://araf.badr.co.id/llms.txt
> Use this file to discover all available pages before exploring further.
# Metric Cards
> Summary metric cards for dashboards — available in 4 display types and 2 trend states.
## 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
{/* Mini sparkline SVG */}
## Installation
```bash npm theme={null}
npm install @araf-ds/core
```
```bash yarn theme={null}
yarn add @araf-ds/core
```
```bash pnpm theme={null}
pnpm add @araf-ds/core
```
## Usage
```jsx theme={null}
import { MetricCard } from "@araf-ds/core";
export default function Dashboard() {
return (
router.push("/reports/views")}
/>
);
}
```
## Type Variants
Metric Cards have **4 types** that determine how the metric is visualized.
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
```jsx theme={null}
```
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
```jsx theme={null}
}
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
```jsx theme={null}
}
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
```jsx theme={null}
```
## 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 →
```jsx theme={null}
// With action button
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)
| State | Color | Icon |
| -------- | --------------------- | ------------------ |
| Positive | `#16A34A` (Green/07) | `arrow-up-right` |
| Negative | `#B42318` (Error/700) | `arrow-down-right` |
## Breakpoints
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`
The display type of the metric card.
The metric label text, displayed above the number.
The primary metric value displayed large (e.g. `"2,000"`, `"89%"`).
The direction of the metric change — determines the color and icon of the trend indicator.
The numeric change value (e.g. `100` → displayed as `↑ 100` or `100%`).
The descriptive text for the change. Only shown on `icon-02` and `chart` types.
The icon displayed in the featured icon area. Required for `icon-01` and `icon-02` types.
Data array for the sparkline chart. Required for the `chart` type.
If `true`, displays a "View report" button at the bottom of the card (Desktop only).
Callback fired when the "View report" button is clicked. Required when `actions` is `true`.
The rendering breakpoint of the card. Mobile does not support the `actions` prop.
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
* 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 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