Design System Beacon

Card

A flexible primitive container component for displaying content. Build any card layout by composing Card with your own content structure.

Overview

Card is a primitive component designed for maximum flexibility. Instead of providing pre-built card types, Card gives you the building blocks to construct any card layout you need. Control padding, elevation, background patterns, overlays, and borders to create custom card designs.

All card styles are built using design tokens, ensuring consistency across themes and hues. Use the interactive playground below to explore all available options.

Interactive Playground

Use the controls to customize the card and see how it looks in real-time. Toggle between themes and hues to see how cards adapt to different contexts.

Color

Status

Shadow

Padding

Corner Radius

Background Pattern

Overlay

Pattern Type

Border

Height (optional)

<Card
  shadow="100"
  patternType="dot-node"
  showOverlay={false}
>
  {/* Your content here */}
</Card>

API Reference

Card component props and types.

CardProps

interface CardProps extends Omit<ComponentPropsWithRef<"div">, "slot"> {
  padding?: number;
  height?: string;
  status?: "default" | "highlighted" | "selected";
  shadow?: "0" | "50" | "100" | "200" | "300" | "400" | "500";
  showBgPattern?: boolean;
  patternType?: PatternType;
  showOverlay?: boolean;
  showBorder?: boolean;
  children?: React.ReactNode;
}

Card Props

padding

number

400

Spacing token value (100, 200, 300, 400, etc.). Maps directly to --spacing-{value}.

height

string

undefined

Fixed height as CSS value (e.g., "200px", "100%", "auto"). When set, content will scroll if it exceeds the height.

status

"default" | "highlighted" | "selected"

"default"

Background color variant. All statuses use page-primary.

shadow

"0" | "50" | "100" | "200" | "300" | "400" | "500"

undefined

Shadow/elevation level using drop-shadow tokens (--drop-shadow-0 through --drop-shadow-500).

showBgPattern

boolean

false

Whether to show background pattern overlay.

patternType

PatternType

"grid-nested"

Pattern type when showBgPattern is true. Options include CSS-based patterns organized by category: Dot (subtle, halftone, polka, stars, node, striped), Line (vertical, horizontal, stacked, hashrate, diagonal), Grid (soft, offset, graph, nested, datacenter, plus, minimal-plus), Ring (concentric, outline, quarter, orbital, radar, noise), Wave (scallop, stripe), Texture (woven, herringbone, brick, paper), and Shape (checker, triangle, zigzag, bracket). Legacy pattern names (cubes, mathematics, dots, diagonal, smudge, paper, denim, squares, mosaic, cotton) are automatically mapped to new CSS patterns.

showOverlay

boolean

false

Whether to show gradient overlay.

showBorder

boolean

true

Whether to show border. Selected status uses primary border color, others use strong-200.

Usage Examples

Card is a primitive component designed for flexibility. Here are examples of how to build common card patterns using Card with your own content structure.

Basic Card

Your content here

import { Card } from 'beacon-ui';

<Card padding={400} showBgPattern={true} patternType="dot-node">
  Your content here
</Card>

Card with Shadow

Elevated content

import { Card } from 'beacon-ui';

<Card padding={400} shadow="100" showBgPattern={true} patternType="dot-node">
  Elevated content
</Card>

Product Card Pattern

Build a product card by composing Card with images, text, chips, and buttons:

Product Title

Longer descriptive content for this product card. Visually limited to two lines within the card. Brief overview of key features designed to help users understand what the product offers at a glance.

import { Card, Button } from 'beacon-ui';
import { RightArrowIcon } from 'beacon-icons';

<Card 
  padding={500} 
  shadow="50" 
  cornerRadius={4} 
  showBgPattern={true} 
  patternType="ring-noise" 
  showOverlay={true} 
  showBorder={true}
  style={{ width: "50%" }}
>
  <h5 className="text-heading-h5" style={{ margin: 0, color: "var(--fg-neutral)", textTransform: "none" }}>Product Title</h5>
  <p className="text-body3-medium" style={{ margin: 0, color: "var(--fg-neutral-tertiary)", display: "-webkit-box", WebkitLineClamp: 2, WebkitBoxOrient: "vertical", overflow: "hidden" }}>Longer descriptive content for this product card. Visually limited to two lines within the card. Brief overview of key features designed to help users understand what the product offers at a glance.</p>
  <img
    src="/images/preview/1x1_512px_preview.png"
    alt="Product"
    style={{ width: "100%", height: "auto", aspectRatio: "16/9", objectFit: "cover" }}
  />
  <Button endIcon={<RightArrowIcon size="xs" />}>
    Button
  </Button>
</Card>

Experience Card Pattern

Build an experience card with avatar, text, and metadata:

Senior Designer

Design Studio

2023-2025

import { Card, Avatar } from 'beacon-ui';

<Card padding={400}>
  <div style={{ display: "flex", gap: "var(--spacing-400)", alignItems: "flex-start" }}>
    <Avatar
      size="lg"
      type="image"
      imageUrl="/images/avatars/avatar-female.png"
    />
    <div>
      <h6 className="text-heading-h6" style={{ margin: 0, color: "var(--fg-neutral)", textTransform: "none" }}>Senior Designer</h6>
      <p className="text-body2-regular" style={{ margin: 0, color: "var(--fg-neutral-secondary)" }}>Design Studio</p>
      <p className="text-body1-regular" style={{ margin: 0, color: "var(--fg-neutral-tertiary)" }}>2023-2025</p>
    </div>
  </div>
</Card>

Info Card Pattern

Build an info card with icon and text:

Card Name

Card description text here.

import { Card } from 'beacon-ui';

<Card padding={400}>
  <div style={{ display: "flex", gap: "var(--spacing-400)", alignItems: "flex-start" }}>
    <div style={{ width: "32px", height: "32px", borderRadius: "var(--corner-radius-200)", backgroundColor: "var(--bg-primary-tonal)", flexShrink: 0 }} />
    <div>
      <p className="text-body3-medium" style={{ margin: 0, color: "var(--fg-neutral)" }}>Card Name</p>
      <p className="text-body2-regular" style={{ margin: 0, color: "var(--fg-neutral-secondary)" }}>Card description text here.</p>
    </div>
  </div>
</Card>

Card with Fixed Height

Fixed height content (200px)

import { Card } from 'beacon-ui';

<Card padding={400} height="200px">
  <div>Fixed height content</div>
</Card>

// Or use "auto" to wrap content:
<Card padding={400} height="auto">
  <div>Content that wraps</div>
</Card>

// Or use percentage:
<Card padding={400} height="100%">
  <div>Full height content</div>
</Card>

Usage Guidelines

Use Card as a flexible container for any content structure.
Compose Card with your own layout components (divs, images, buttons, etc.).
Use padding prop to control internal spacing (100, 200, 300, 400, etc.).
Use shadow prop to add elevation when needed (0, 50, 100, 200, 300, 400, 500).
Maintain consistent spacing and alignment within cards.
Ensure cards have sufficient contrast for accessibility.
Use status prop to indicate visual hierarchy (default, highlighted, selected).

Don't

Don't overload cards with too much information.
Don't use cards for navigation (use buttons or links instead).
Don't nest cards within cards unnecessarily.
Don't use cards for decorative purposes only.
Don't ignore accessibility requirements for card content.
Don't use arbitrary padding values - stick to spacing token values (100, 200, 300, etc.).
Don't mix shadow levels inconsistently in the same context.

Accessibility

Provide descriptive alt text for images in cards.
Ensure sufficient color contrast between text and background.
Use semantic HTML structure for card content.
Make interactive cards keyboard accessible.
Provide ARIA labels when cards are interactive or contain complex content.
Ensure focus states are clearly visible for interactive cards.