Card

Card

A surface that groups related content. Reach for it when a section needs a visible boundary; otherwise use Stack or Box.

Variants

<Card>Default outlined</Card>
<Card variant="elevated">Floating</Card>
<Card variant="flat">Recessed</Card>

Interactive

<Card interactive asChild>
  <a href="/profile">Open profile</a>
</Card>

Do / Don’t

• Do put one primary heading per card.
• Don’t nest cards more than one level deep — collapse to flat sections instead.
• Don’t put onClick on the card itself — wrap or render an <a> / <button> child.

Install: @helixui/core

import { Card } from '@helixui/core'

status: stable · since: 0.1.0

Tags: container, surface, elevation, group, panel

Live playground

Open the full editor or source on GitHub.

Anatomy

┌──────────────────────────────────┐
│                                  │
│   <children>                     │   ← arbitrary content; helixui recommends Stack inside
│                                  │
└──────────────────────────────────┘
 ↑ surface bg + border (outlined) | shadow.md (elevated) | flat (no border, subtle bg)
 ↑ rounded by radius.lg, padded by space.5

Layout

• display — block
• width — fill
• height — content
• intrinsicSize — fills available width, hugs content height, ~20px internal padding
• stackable — true
• fullBleed — false

Visual

A rounded rectangle with generous internal padding (space.5) and large radius (radius.lg). outlined shows a 1px subtle border on the default surface, elevated removes the border and uses a soft shadow (shadow.md), flat is borderless with a slightly recessed background tint. With interactive, hover lifts the shadow half a step and focus shows a 2px focus-ring border.

Props

Name	Type	Default	Description
variant	'flat' | 'outlined' | 'elevated'	outlined	Visual treatment.
interactive	boolean	false	Adds hover/focus affordance — set on cards that act as links or buttons.

Tokens used

color.bg.surface.default, color.bg.surface.subtle, color.border.default, color.border.strong, color.border.focus, radius.lg, space.5, shadow.md

Accessibility

Notes

• When interactive, also render an interactive element (<a> or <button>) inside or on top, with appropriate role.
• The card itself is presentational — do not put onClick on it without a role.

Composes with

Component	Relation	Note
Stack	child	Use Stack inside Card to control vertical rhythm of contents.
Heading	child	Common first child as a card title.
Text	child	Body content of a card.
Button	child	Action(s) at the bottom of the card.
Sheet	alternative	Use Sheet for content that should overlay the page.

Prompt examples

These are the AI prompt → JSX mappings used by the helixui prompt DSL and integrations like Cursor / Claude Code.

group related content into a panel

“wrap this in a card”

<Card>
  <Stack gap={3}>
    <Heading size="md">Title</Heading>
    <Text>Description goes here.</Text>
  </Stack>
</Card>

make a clickable card linking elsewhere

“card that links to /settings”

<Card interactive asChild>
  <a href="/settings">
    <Stack gap={2}>
      <Heading size="sm">Settings</Heading>
      <Text size="sm" tone="muted">Manage your account.</Text>
    </Stack>
  </a>
</Card>

raised hero card on a list page

“elevated card with a CTA”

<Card variant="elevated">
  <Stack gap={4}>
    <Heading size="lg">Upgrade to Pro</Heading>
    <Text>Unlock advanced analytics.</Text>
    <Button>Upgrade</Button>
  </Stack>
</Card>