Skip to content

Card

C-18 · Components · Content

All elements · Card on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Card.

Card

C-18WCAG 2.2 AA · Passed #411
Axis Values
data-orientation · data-density · data-elevation vertical · horizontal / compact / none · md
data-clickable · data-state=selected interaction
__media · __header · __heading · __title · __subtitle · __content · __actions · __footer slots
Rest · hover · selected · horizontal · compact
jd
Water damage claim
CS-2041 · opened 14 Aug
Kitchen ceiling leak reported by tenant; assessor visit scheduled.
In reviewHigh
ak
Selected card
data-state="selected"
Primary-50 surface, primary-300 border, small shadow.
Updated 2h ago
jdak
With media
16:9 slot
Media slot above the header for thumbnails and previews.
Horizontal
Media on the left, 120px
Compact (kanban card)
12px padding all round.
Backlogjd

Guidance

When to use

  • Show one record as a self-contained summary: title, subtitle, a short body, status and people.
  • Show items on a Kanban board with data-density="compact".
  • Show documents or media with a thumbnail in __media, above the header or beside it with data-orientation="horizontal".
  • Group a block of related settings or a specimen on a page with data-elevation="none".
  • Let users open or pick an item by clicking the whole card with data-clickable, showing the chosen one with data-state="selected".

When to consider something else

  • When users scan many items and compare a few fields, use List or Table; cards take more space per item. See List.
  • When the data is columns of values, use Table. See Table.
  • When the message is a status or alert, use Banner. See Banner.
  • When the content is a full record with tabs and history, use the Object page. See ObjectDisplay.

Usability

Do
  • Keep the title to one line and put the identifier and date in __subtitle.
  • Put at most two actions in __actions; move the rest to a More Menu in the header.
  • Use the same slots in the same order across a set of cards so users can scan them.
  • Use __footer for metadata such as last updated and collaborators.
Don’t
  • Don't nest cards inside cards, except a specimen frame on a docs page.
  • Don't make a card clickable when it holds several unrelated actions.
  • Don't use elevation to show selection; use data-state="selected".

Accessibility

Keyboard

Card keyboard
Keys Action
Tab / Shift+Tab Moves to the card's open control, then to each button inside it.
Enter Opens the card when its main control is focused.

Roles and names

  • A standalone card is an article; in a set, render the cards as list items so users hear the count.
  • __title is a div; the binding should render it as a heading at the right level so heading navigation finds each card.
  • A clickable card must have one real link or button, normally on the title, whose name is the title; stretch its click area over the card in CSS rather than giving the article a role.
  • The specimen puts tabindex="0" on the article; a focusable article has no role or action, so the binding must not rely on it.
  • Selection must be exposed, for example aria-pressed or aria-selected on the main control within a selectable group, not only data-state.

Focus

  • Inner buttons such as More stay separate Tab stops after the card's main control.
  • Focus shows the shared focus ring on the main control; when the click area is stretched, draw the ring around the whole card.
  • After a card is moved or removed, move focus to the next card.

Other requirements

  • Hover adds a fill, border and shadow; keyboard focus needs its own visible ring (2.4.7).
  • The selected border and fill need 3:1 against the page (1.4.11).
  • Media images need alt text, or alt="" when decorative.
  • Cards must reflow into one column at 320px width (1.4.10).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Card test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (2 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (5 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- card --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Card package
Source css/classic/components/content.css
Specimens also use Avatar · Box · Button · Chip · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes