StatCard

Role and semantics

• A StatCard with a label is a role="group" linked to its label with aria-labelledby; screen readers say “Total items, group”.
• Label, value, change and period sit in the DOM in that order and read as one sentence. There is no second hidden sentence and no repeated text.
• The direction of the change is not given by colour alone: the arrow icon is visual (aria-hidden) and the direction is read as a word (“increase”, “decrease”, “no change”).
• While loading, the root is aria-busy="true" and the value holds a hidden “Loading” text.
• Without a value, — is visual and the reason (“no information”) is read. In hidden mode •••• is visual and “Hidden” is read.
• When the StatCard.Trend content has no role="img" or aria-label, it counts as decoration and is aria-hidden.

Keyboard

A StatCard is static and takes no focus. Only interactive elements you put in info or trend enter the tab order.

Focus

StatCard has no focus ring of its own. Controls you put inside carry their own rings; the tile does not clip them with overflow.

Screen reader output

Example	Read
Increase	“Total items, group”, “Total items”, “1.280”, “increase 8 %”, “vs last month”
Decrease, positive	“decrease 5 %”; the meaning colour is not read, the direction is a word
Loading	“Total items, group”, “Loading”; the root is busy
No data	“Active users”, “no information”
Hidden	“Completion rate”, “Hidden”
Decorative trend	Not read

Replace the words with delta.label, loadingLabel, hiddenLabel and noDataLabel; the defaults are library strings.

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-data-positive / color-surface-raised	7.11:1	9.07:1
color-data-negative / color-surface-raised	7.48:1	7.94:1
color-data-positive / color-surface-layer-1 (filled)	6.57:1	9.07:1
color-data-negative / color-surface-layer-1 (filled)	6.91:1	7.94:1

WCAG 2.2

Criterion	How StatCard meets it	What the product team does
1.1.1 Non-text content	The arrow and the trend are decoration (aria-hidden); the direction is a word.	For a meaningful trend, give it role="img" and an aria-label.
1.3.1 Info and relationships	The group is named by its label; parts sit in reading order.	Use StatCard.Label when you build a custom layout from parts.
1.4.1 Use of colour	The direction is also given by the arrow and the word.	When sentiment and direction differ, write the period clearly.
1.4.3 Contrast	Text and data colours are at least 6.57:1.	Do not pass custom colours.
4.1.3 Status messages	aria-busy and a hidden text while loading.	If you must announce that a loaded value changed at page level, use a live region.