> ## 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.
# Card
> A flexible surface container for grouping related content — supports default, flat, hoverable, stat, and media variants.
## Overview
Team overview
Summary of active members.
12 members active this week.
Flat card
Subtle container without elevation.
+12.5%
Total Revenue
\$48,295
**Card** is a versatile surface container. It comes in several variants: **default** (border + shadow), **flat** (no shadow), **hoverable** (interactive), **stat** (KPI display), and **media** (image header).
***
## 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
```tsx theme={null}
import {
Card,
CardContent,
CardDescription,
CardFooter,
CardHeader,
CardStat,
CardTitle,
} from "@araf-ds/core"
export default function Example() {
return (
Team overviewSummary of your active team members.
12 members active this week.
)
}
```
***
## Variants
### Default Card
The standard card with a `1px` border, light shadow, and `12px` border radius.
Team overview
Summary of your active team members.
12 members active this week.
```tsx theme={null}
Team overviewSummary of your active team members.
12 members active this week.
```
### Flat Card
No shadow — use inside panels or sections that already have a container.
Flat card
Simple content in a flat, no-shadow container.
```tsx theme={null}
Simple content in a flat container.
```
### Hoverable (Clickable) Card
Adds a hover transition and cursor pointer — use for navigable cards.
Project Alpha
Due March 31
65% complete
```tsx theme={null}
navigate("/project/1")}>
Project AlphaDue March 31
```
### Stat Card
Optimized layout for KPI metrics with trend indicators.
+12.5%
Total Revenue
\$48,295
−3.1%
Active Users
3,842
```tsx theme={null}
}
/>
```
### With Media
Attach an image or visual header above the card content.
Project name
Description of the project goes here.
```tsx theme={null}
Project nameDescription here.
```
***
## API Reference
### Card
Visual style. Values: `default` · `flat` · `hover`
Makes the card interactive. Automatically applies hover cursor and focus ring.
Additional class names for the card container.
### CardFooter
Footer content alignment. Values: `start` · `end` · `between`
### CardStat
The metric label text (e.g. "Total Revenue").
Primary metric value displayed prominently.
Trend direction for color coding. Values: `positive` · `negative` · `neutral`
Percentage change value (e.g. `12.5` renders as `+12.5%`).
Icon displayed in the stat card header area.
***
## Accessibility
* Hoverable cards rendered with `onClick` should include a focusable element or use `role="button"` with `tabIndex={0}` and keyboard handler
* `CardTitle` renders as `
` by default — adjust heading level with the `as` prop to maintain document heading hierarchy
* Media images inside cards must have descriptive `alt` text
* Avoid putting interactive elements inside a card that is itself clickable — this creates nested interactivity issues
***
## Do's & Don'ts
* Use `CardStat` for KPI displays — it provides consistent metric layout
* Use `variant="hover"` only for cards that are genuinely navigable or clickable
* Keep card content focused on a single topic or entity
* Use `CardFooter align="between"` when you need both a label and an action button
* Don't nest a clickable card inside another clickable card
* Don't use Card as a modal replacement — use `Modal` or `Sheet` instead
* Don't use `variant="hover"` on non-interactive cards — it creates false affordance
* Don't overload a card with too many actions — limit to 1–2 per card
