Card is a bordered, elevated container for discrete, self-contained items: things you could reorder, remove, or interact with independently. Cards are NOT the default layout tool. Most content groups don't need a container at all; spacing and alignment create visual grouping naturally. Only reach for a Card when items need clear interaction boundaries or visual comparison in a grid.
Preview loads on approachPreview loads on approach
Exact source · card-showcase
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
import {Card} from '@astryxdesign/core/Card';
import {Stack} from '@astryxdesign/core/Layout';
import {Text, Heading} from '@astryxdesign/core/Text';
export default function CardShowcase() {
return (
<Card width={320}>
<Stack direction="vertical" gap={2}>
<Heading level={4}>Card title</Heading>
<Text type="body" color="secondary">
Cards group related content with a border and background. Use them for
profiles, settings panels, or data summaries.
</Text>
</Stack>
</Card>
);
}
Usage
Card is a bordered, elevated container for discrete, self-contained items: things you could reorder, remove, or interact with independently. Cards are NOT the default layout tool. Most content groups don't need a container at all; spacing and alignment create visual grouping naturally. Only reach for a Card when items need clear interaction boundaries or visual comparison in a grid.
Ask "could I reorder or remove this independently?" If yes, it's a card. If no, it's just a section of the page: use a heading + Stack or Section.
Use cards for discrete items: a single user profile, a single notification, a single metric, a product in a grid. Each card represents one "thing" with clear interaction boundaries.
Spacing and alignment alone create visual grouping. Not everything needs a container; try removing the card and see if the grouping is still clear from whitespace and typography.
Keep padding consistent across sibling cards so they align visually in a grid or list.
Pair a card with Layout when you need a structured header, scrollable content, and footer with actions.
Default to cards for visual grouping. A heading + Stack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.
Wrap page sections in cards. "General Settings", "Notification Preferences", form groups: these are page regions, use Section or heading + stack.
Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.
Nest cards inside other cards; flatten the hierarchy or use spacing and dividers instead.
Use color variants for status; use Banner or Badge for that. Color cards are for categorization.
Typed props
Prop
Type and behavior
width
SizeValue
Width of the card (number = pixels, string = used as-is).
height
SizeValue
Height of the card (number = pixels, string = used as-is).
Internal padding using the spacing scale. Omit it and the card takes the theme's card padding rather than a step, so passing a step is a decision to override the theme, not a way to restate the default.
Background color variant. default uses the standard card background. transparent drops the background entirely. muted uses the muted background for de-emphasised cards. The non-semantic variants use the corresponding --color-background-<name> token.
elevation
'none' | 'low' | 'med' | 'high' · default 'none'
Resting shadow depth. none is flat; low/med/high map to the shadow token scale. Raise a card only when it needs to float above surrounding content.
Anatomy
Container · required
The outer box with border, background, border-radius, and padding.
Content · required
Any children rendered inside the card. Often a stack of heading, text, and actions.
Theming
Container theming is enabled.
Targets
astryx-card
Visual props: variant, elevation
Variables
--_card-radius · private
Border radius of the card
Default: var(--radius-container)
--_card-elevation · private
Resting shadow of the card, set from the elevation prop. Composed into the card box-shadow list alongside --_card-ring rather than written as boxShadow directly, so a ring and an elevation can coexist.
Default: 0 0 transparent
--_card-ring · private
Inset ring drawn in the card box-shadow list. SelectableCard sets it to show selection without taking over the shadow.
