Card

Cards group related content and actions into a contained surface. Use them to present a summary, preview, or entry point to more detailed information.

Installation

Add the component and token packages to your app (workspace or registry):

pnpm add @akanaka-design/components @akanaka-design/tokens

Import design tokens and component styles once at the root of your application so utilities and CSS variables resolve:

import "@akanaka-design/tokens/css";
import "@akanaka-design/components/styles.css";

Usage

Use the named exports from @akanaka-design/components. Compose Card with header, content, and footer sections as needed.

import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
  StatCard,
  Button,
} from "@akanaka-design/components";

StatCard (recommended)

Use StatCard for dashboard metrics: a 4px top accent in semantic colors, muted label (13px), and large value (28px, medium weight). The top edge stays square so the accent is flush with the card width.

<StatCard label="Total Staff" value={24} accent="primary" />
<StatCard label="Compliant" value={21} accent="success" />
<StatCard label="Action Required" value={3} accent="destructive" />

Supported accent values: primary, secondary, success, warning, destructive (default: primary).

Basic

<Card>
  <CardHeader>
    <CardTitle>Card title</CardTitle>
    <CardDescription>A short description.</CardDescription>
  </CardHeader>
  <CardContent>
    <p>Your content here.</p>
  </CardContent>
  <CardFooter>
    <Button>Action</Button>
  </CardFooter>
</Card>

Flat variant

<Card variant="flat">
  <CardContent>
    <p>Flat card for subtle backgrounds.</p>
  </CardContent>
</Card>

Stat card (composition)

Prefer StatCard for new work so metrics stay consistent. If you must compose manually (e.g. extra rows or actions inside the tile), keep the same tokens and avoid ad hoc colors.

<Card className="border-l-4 border-l-primary-500">
  <CardContent className="space-y-2">
    <p className="text-body-sm text-foreground-muted">Total staff</p>
    <p className="text-display-sm font-semibold text-foreground">1</p>
  </CardContent>
</Card>

Safe overrides when composing: layout on Card / CardContent (w-*, space-y-*, flex). Avoid replacing surface, shadow, or base border tokens unless specified.

Props

The lists below mirror the public TypeScript API. When you add docgen later, you can generate this automatically; for now it is maintained by hand.

Card

• variant — "elevated" | "flat". Default: "elevated". Visual style variant.
• children — ReactNode. Card content.
• className — string. Default: "". Additional CSS classes.

Subcomponents

• CardHeader — Top section; typically contains title and description.
• CardTitle — Heading text inside the header.
• CardDescription — Secondary text below the title.
• CardContent — Main body content.
• CardFooter — Bottom section for actions or metadata.

StatCard

• label — string. Metric title (muted).
• value — ReactNode. Primary number or text.
• accent — "primary" | "secondary" | "success" | "warning" | "destructive". Default: "primary".
• className — string. Default: "". Layout utilities only; do not override accent or surface styles.

Guidelines

When to use

• Grouping related information (user profile, product summary)
• Dashboard widgets or data summaries
• List items that need more structure than a simple row

When not to use

• Full-page layouts
• Single pieces of content that don't need containment
• Nested cards