Role and semantics
Section titled “Role and semantics”- A Card with a
Card.Titleis a<section>linked to the title witharia-labelledby; screen readers announce it as a region named by its title and list it among landmarks. - A Card without a title is a plain
<div>with no role. Card.Titleis a real heading (h3by default). Match the page outline withlevel.- For cards in a list, render the root as a list item with
render={<li />}and put the cards in a<ul>.
Keyboard
Section titled “Keyboard”| Key | Behaviour |
|---|---|
| Tab | A static card takes no focus. In an interactive card, Card.Link takes focus first, then the controls in Card.Actions and Card.Footer in order. |
| Enter | Opens the link while Card.Link has focus. |
In an interactive card focus is on Card.Link; the ring is drawn around the card, not the link, 2 px wide and 2 px away (has-focus-visible). The focused target and the clickable area look the same. The ring shows for keyboard focus only.
Screen reader output
Section titled “Screen reader output”| Example | Read |
|---|---|
| Titled card | “Card title, region”, then the heading: “Card title, heading level 3” |
| Interactive card | “Card title, region”; in the heading “Card title, link” |
| Card without a title | No region is announced; the content is read in flow |
The link’s name is the title text. The rest of the card (description, status) is not added to the link name, so it stays short in the links list. When the link needs a description, link it to the description with aria-describedby.
Contrast
Section titled “Contrast”Text is at least 4.5:1 in every brand and mode; values are computed from the bigbang and fixture token output.
| Pair | Light mode | Dark mode |
|---|---|---|
color-text-default / color-surface-raised |
16.71:1 | 15.44:1 |
color-text-subtle / color-surface-raised |
9.07:1 | 9.23:1 |
color-text-default / color-surface-layer-1 |
15.44:1 | 15.44:1 |
color-text-subtle / color-surface-layer-1 |
8.38:1 | 9.23:1 |
color-focus-ring / color-surface-default (lowest) |
5.97:1 | 8.09:1 |
The card border (color-border-subtle, 1.22:1) is decorative: it is not needed to identify the card, the content and title do that (WCAG 1.4.11 does not require it).
WCAG 2.2
Section titled “WCAG 2.2”| Criterion | How Card meets it | What the product team does |
|---|---|---|
| 1.3.1 Info and relationships | A titled card is a section with aria-labelledby; the title is a real heading. |
Keep the heading order with level; make cards in a list <ul>/<li>. |
| 1.4.11 Non-text contrast | The focus ring is at least 5.97:1. The border is decorative. | Do not put status in the border colour; use a Badge. |
| 2.1.1 Keyboard | An interactive card’s one target is a link; it works with Tab and Enter. | Do not make the root clickable with onClick; use Card.Link. |
| 2.4.4 Link purpose | The link name is the title. | Write a meaningful title; never “More”. |
| 2.4.7 Focus visible | The ring is around the card. | Do not remove outline with className. |
| 2.5.8 Target size | The target of an interactive card is the whole card. | Give actions inside the card at least 24 px targets (Button sm is 32 px). |