Astryx Design System

Card@xds/core v0.0.14 · XDSCard

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.

ts
import {XDSCard} from '@xds/core/Card'

Best practices

Guidance	Practices
Do	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 + XDSStack or XDSSection.
Do	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.
Do	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.
Do	Keep padding consistent across sibling cards so they align visually in a grid or list.
Do	Pair a card with XDSLayout when you need a structured header, scrollable content, and footer with actions.
Don't	Default to cards for visual grouping. A heading + XDSStack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.
Don't	Wrap page sections in cards. "General Settings", "Notification Preferences", form groups: these are page regions, use XDSSection or heading + stack.
Don't	Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.
Don't	Nest cards inside other cards; flatten the hierarchy or use spacing and dividers instead.
Don't	Use color variants for status; use Banner or Badge for that. Color cards are for categorization.

Examples

Common configurations, variations, and states.

Card — Callout

Muted-variant cards for tips, notes, or supplementary information. Use when content should be visually distinct but not prominent. The muted variant uses a wash background instead of the elevated default, making it feel recessed rather than raised. Works well in sidebars, help panels, or inline callouts.

Card — Variants

Default, muted, and color variants side by side. Use color variants to categorize cards visually, like team colors, project tags, or content types. Each color uses the corresponding background token from the theme, so they adapt to light and dark mode automatically.

Card — Layout

A card with a structured header, content area, and footer with action buttons. Use for forms, dialogs, or settings panels that need clear sections. Pair XDSCard with XDSLayout to get automatic dividers between header, content, and footer. The footer aligns actions to the right by default.

Card — Simple

A card with a heading and body text. Use for summaries, descriptions, or any grouped content that needs visual separation from the page. The card handles its own border, background, and padding; just pass your content as children. Set a width to constrain it, or leave it to fill the parent.

Usage

import {XDSCard} from '@xds/core/Card'

Best practices

Guidance	Practices
Do	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 + XDSStack or XDSSection.
Do	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.
Do	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.
Do	Keep padding consistent across sibling cards so they align visually in a grid or list.
Do	Pair a card with XDSLayout when you need a structured header, scrollable content, and footer with actions.
Don't	Default to cards for visual grouping. A heading + XDSStack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.
Don't	Wrap page sections in cards. "General Settings", "Notification Preferences", form groups: these are page regions, use XDSSection or heading + stack.
Don't	Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.
Don't	Nest cards inside other cards; flatten the hierarchy or use spacing and dividers instead.
Don't	Use color variants for status; use Banner or Badge for that. Color cards are for categorization.