Prepared Docs

Overview

Card is the painted surface for grouped content. It owns interior spacing, radius, elevation, and slot layout. The parent owns width, height, margin, and placement. ClickableCard adds one native action control, stretched to fill the card, for an atomic action or same-context link.

Ordinary layout, spacing, background, border, radius, overflow, and elevation are expressed through semantic Box and FlexBox props. Card SCSS is reserved for nested-surface behavior, content bleed, interaction pseudo-states, and the stretched action overlay.

When to use

Group a heading, body, and optional footer that belong together.
Present short, atomic, non-interactive content that the whole card should activate.
Nest a scrollable region inside CardContent when the parent sets a block size.
Host range controls, a named chart, or a table on an ordinary Card.

When not to use

KPI tiles with a locked label/value layout: use MetricCard.
Multi-select or mutually exclusive choices: use Checkbox cards or Radio cards.
Full charts, tables, forms, or nested controls inside a clickable surface: use ordinary Card and keep the action outside the content.

Composition

Card is a column. Slots are CardHeader, CardContent, and CardFooter. MetricCard is a closed preset over CardHeader and CardContent.

Surface paints the nearest Alt or Alt2 background and a border.
Ghost keeps interior spacing without paint.
Radius is fixed to BorderRadius.Medium (8px).
Elevation is None or Low; Low is legal only on Surface.
CardHeader is a column. Its top row wraps the BodyLarge strong title with accessory and controls at the end; the optional description sits below.
Card titles always use sentence-case TextType.BodyLarge strong typography. Overline text is not a card-title treatment.
CardControls is a SegmentedControl with an optional sibling kebab Menu. It is not a new card type.

ClickableCard uses the same slots except controls. The action target is a sibling of those slots, absolutely positioned over the card padding box. It is the only tab stop. Do not put buttons, links, tables, named charts, or Scrollable inside it.

Controls versus clickable

ClickableCard does not accept a controls prop. Because React children are opaque to TypeScript, composition can still place a CardHeader with controls inside it; the development guard warns when it detects those interactive descendants. Treat that warning as invalid card composition.

A card that needs both navigation and header controls should put navigation in an explicit CardFooter action. Do not wrap the card in an ancestor link and stop-propagate from the controls.

accessory stays non-interactive. Interactive chrome belongs in controls.

Chart card

A chart card is ordinary Card: CardHeader with CardControls, CardContent with bleed to the inline edges around the chart, and an optional footer. Use a named chart from Visualization charts plus a visible summary. Do not introduce a ChartCard component.

Table card

A table card is ordinary Card: header controls, a Table in CardContent, and a centered CardFooter action such as "View all". Do not introduce a TableCard component.

Content guidelines

Localize header title and description with useTranslation().
Keep ClickableCard copy short. Long-form text belongs in ordinary Card.
Footer actions sit in CardFooter, not in the header accessory, when the card is not clickable.
CardControls labels, menu trigger name, and overflow radios are LocalizedMessage.

Best practices

Let the parent size the card; Card fills that block size so CardContent can shrink with min-block-size: 0.
Use Scrollable inside ordinary CardContent for overflow.
Use external on navigation cards that must open a new context.
Put range segments in CardControls and extra ranges in the kebab as radios.

Don't

Nest Card inside Card. Nested Surface paint is only for a Card sitting on another painted surface.
Put interactive descendants inside ClickableCard.
Combine controls with ClickableCard or a clickable MetricCard.
Cast string literals to LocalizedMessage. Call formatMessage.

Metric card for closed KPI tiles.
Visualization charts for named and decorative charts.
Table for table compositions inside Card.
Checkbox cards for selectable card groups.

Callout / Accessibility

Card / API and Development

Controls versus clickable

Overview

When to use

Group a heading, body, and optional footer that belong together.
Present short, atomic, non-interactive content that the whole card should activate.
Nest a scrollable region inside CardContent when the parent sets a block size.
Host range controls, a named chart, or a table on an ordinary Card.

When not to use

KPI tiles with a locked label/value layout: use MetricCard.
Multi-select or mutually exclusive choices: use Checkbox cards or Radio cards.
Full charts, tables, forms, or nested controls inside a clickable surface: use ordinary Card and keep the action outside the content.

Composition

Card is a column. Slots are CardHeader, CardContent, and CardFooter. MetricCard is a closed preset over CardHeader and CardContent.

Surface paints the nearest Alt or Alt2 background and a border.
Ghost keeps interior spacing without paint.
Radius is fixed to BorderRadius.Medium (8px).
Elevation is None or Low; Low is legal only on Surface.
CardHeader is a column. Its top row wraps the BodyLarge strong title with accessory and controls at the end; the optional description sits below.
Card titles always use sentence-case TextType.BodyLarge strong typography. Overline text is not a card-title treatment.
CardControls is a SegmentedControl with an optional sibling kebab Menu. It is not a new card type.

Controls versus clickable

A card that needs both navigation and header controls should put navigation in an explicit CardFooter action. Do not wrap the card in an ancestor link and stop-propagate from the controls.

accessory stays non-interactive. Interactive chrome belongs in controls.

Chart card

Table card

A table card is ordinary Card: header controls, a Table in CardContent, and a centered CardFooter action such as "View all". Do not introduce a TableCard component.

Content guidelines

Localize header title and description with useTranslation().
Keep ClickableCard copy short. Long-form text belongs in ordinary Card.
Footer actions sit in CardFooter, not in the header accessory, when the card is not clickable.
CardControls labels, menu trigger name, and overflow radios are LocalizedMessage.

Best practices

Let the parent size the card; Card fills that block size so CardContent can shrink with min-block-size: 0.
Use Scrollable inside ordinary CardContent for overflow.
Use external on navigation cards that must open a new context.
Put range segments in CardControls and extra ranges in the kebab as radios.

Don't

Nest Card inside Card. Nested Surface paint is only for a Card sitting on another painted surface.
Put interactive descendants inside ClickableCard.
Combine controls with ClickableCard or a clickable MetricCard.
Cast string literals to LocalizedMessage. Call formatMessage.

Metric card for closed KPI tiles.
Visualization charts for named and decorative charts.
Table for table compositions inside Card.
Checkbox cards for selectable card groups.

Callout / Accessibility

Card / API and Development

Controls versus clickable