GrBadge

dark switches the soft tinted background for a solid fill.

The fill goes through the per-component layer --gr-badge-{tone}-bg/-fg rather than straight from the tone role, because the weight the themes need is different. In the light theme --gr-{tone} is a bright fill under dark text, and a filled badge read as a heavy, almost black plate; there the layer moves it to -solid/-solid-fg — a button-weight fill under light text, the same one solid buttons use. In the dark theme a pastel fill with dark text is the regular convention of the package, and the layer leaves the roles as they are.

The values of the layer live in the themes of the component (GrBadge/themes/{light,dark}.css), so a badge can be recoloured without touching the tone roles as a whole.

A saturated tone as the text colour on its own light background gives 2.24:1; the -text role gives 6.78:1. That is why the soft weight colours text with -text roles only.

Both guarantees are held by the grBadgeContrast.test.ts gate, and neither is formal:

• text contrast — the AA threshold of 4.5:1. There is no large-text concession here: a badge is set at 11–14px;
• the visibility of the plate itself is measured as the perceptual distance to the page background (ΔE, noticeability threshold 2.3). A contrast rule alone is not enough for this: the 3:1 of WCAG 1.4.11 is not met even by the regular --gr-muted/--gr-brd pair, and a badge could end up indistinguishable from the page while formally breaking nothing.

On tone roles and their suffixes — ../theming.md.

radius is round (the default), semi or square. semi has its own ladder across the size steps — 3/3/5/7 px through --gr-badge-semi-radius-*: the badge rounds more slowly than it grows, otherwise at lg it would turn into a pill sooner than the layout wants it to.

<GrBadge radius="semi" size="lg">
SKU-14920
</GrBadge>

The height of the badge is held by an inner wrapper (min-height: 1lh — the height of the line box at leading-none), while the text itself is trimmed to cap height (text-box-trim) and centred inside that height. The label then sits level regardless of whether it has descenders: “Paid” and “Awaiting payment” sit the same.

The trimming lives on a nested node rather than on the text itself, and that is not a matter of style: text-box-trim shrinks the line box, and hung directly on the text it would drag the height of the whole badge down with it.

<GrBadge tone="neutral" dot="success">
  Active
</GrBadge>

<GrBadge tone="success" dot>
  Paid
</GrBadge>

dot puts a circle before the label. A tone name colours the marker separately from the plate — the pattern exists for the sake of that pair: in a list of a dozen rows coloured plates compete for attention, while a grey plate with a coloured dot reads row by row. A boolean value takes the tone of the badge itself.

The marker is decorative (aria-hidden): the meaning is carried by the word beside it. There is no dot without a label here on purpose — it would report the state by colour alone. A label on top of someone else’s control is GrBadgeWrap, a status on an avatar is GrAvatar.

Why the marker is coloured by the badge layer rather than by the tone role

The tone role taken directly does not work in either look, and both branches are measured by the gate:

The reason is that --gr-{tone} in the light theme is a bright fill under dark text rather than a colour for small graphics. The per-component layer --gr-badge-{tone}-bg means precisely “the saturated weight that reads in this theme”, and on it all 128 pairs of “marker tone × badge tone × theme” pass.

The threshold for the marker is 3:1 (WCAG 1.4.11), not 4.5:1: the circle is recognised by shape and position, not by letterform.

On a fill (dark) the marker is always the colour of the text. The surface of a filled badge is taken from the same layer, so a marker of a named tone would merge with it into a single colour; a named tone is ignored there with a warning in dev.

The marker and the icon slot occupy the same place, so they exclude each other: if both are passed, the icon is drawn — it carries more than a colour does.

A status often consists of more than a word: “parsing” without a spinner reads as a final state rather than as work in progress.

<GrBadge tone="warning">
  <template #icon>
    <IconLoader class="h-full w-full animate-spin" />
  </template>
  Recognising
</GrBadge>

The size is held by the slot wrapper, and the content stretches to it (h-full w-full) — the same device as in GrChip, and for the same reason: the icon scale has to follow the size of the badge rather than the markup at the call site. It grows more slowly than the type: at the lower steps an icon matched one-to-one with the text would blow out a narrow plate.

The icon is a sibling of the trimmed text, not its content: text-box-trim lives on the nested node of the label and does not reach the icon, so the icon does not stretch the height of the plate.

Do not put GrProgressCircle here: a circular indicator is on the widget scale, its lowest step is 2rem, and it does not fit into the line of a badge — the arc runs outside the background and pushes the text out. A spinner here is an ordinary icon with animate-spin.

The slot does not make the badge interactive: it is still a label. If you need a dismissible or selectable tag, that is GrChip, with its own role and its own keyboard.

size takes its type size from the control scale --gr-control-text-* rather than the content one: a badge more often stands in a row with buttons and fields than inside a paragraph. The scales and the difference between them — ../sizes.md.

tone, size and radius are read from GrConfigProvider, so the look of badges is set once for the whole application.