Card / Surface

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

• Group related information and actions on one surface. The default 24px padding balances all four sides, and spacing sets the hierarchy of title, description, body, and actions. To align card grid text with the surrounding body text, set Grid.bleed and Card.Root.padding to the same token step. Do this only when the outer container has room for the extended surface and the focus indicator.
• Stretched to a taller neighbor in a row, a card keeps its parts at the top and its Footer at the bottom, so the footers of a row line up. A bar, such as a Meter, takes a line of its own in the Footer.
• For a card that opens something, such as an item's details, put Card.Action in the Title: its button, or its link with href, stretches over the card, and hover, press and focus show on the whole card. Other controls on the card stay on top and keep their own actions.
• In a collection of like items, leave the padding to the card and its density: SizeProvider density='compact' around the grid tightens every card at once. See Collections in the Layout foundation for where each part goes.

• Don't wrap every page section in a card or stack cards inside cards. Separate sections with headings and spacing instead. A dashboard is the exception, where each data panel is a plane: use Dashboard.Panel.
• Don't make the card itself a button or wrap it in a link. Card.Action keeps one named target in the title, and the other controls on the card still work.
• Don't color a card's band, border or plane to show its state. Say the state with a StatusBadge.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Root(Surface) → Header(Title(optional Action) + Description) + Body + Footer

Keyboard and accessibility

Only the actions enter the Tab order. Root is a plain div with no focus or click behavior; with Card.Action, the action is the one stop for the card, and the focus ring draws around the whole card. Set Title.level to match the surrounding heading hierarchy. When the card needs a group name, connect it with aria-labelledby.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { Card, Button } from '@surflane/ui'

<Card.Root aria-labelledby='environment-title'>
  <Card.Header>
    <Card.Title id='environment-title' level={3}>
      DEMO main
    </Card.Title>
    <Card.Description>Platform API environment</Card.Description>
  </Card.Header>
  <Card.Body>Three services are ready to deploy.</Card.Body>
  <Card.Footer>
    <Button onClick={inspect}>Inspect environment</Button>
  </Card.Footer>
</Card.Root>

// The whole card opens the item: the title's action stretches over it.
<Card.Root>
  <Card.Header>
    <Card.Title>
      <Card.Action onClick={() => open(service)}>{service.name}</Card.Action>
    </Card.Title>
  </Card.Header>
  <Card.Body>{service.summary}</Card.Body>
</Card.Root>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens