Badge
Badge is a small label that marks status, category or count next to the thing it describes.
Preview
A compact status or count marker that attaches to something else. Dot for presence, Circle for a count, Pill for a label.
Three types, one shell. Pill and Circle share one inner wrapper, a 12/16 Regular label padded 4 either side, and differ only in outer sizing: Pill hugs the wrapper, Circle is pinned to 20 square. Dot has no children, just a 6 by 6 filled box. The text property does nothing on a Dot, and a Circle holding three digits pushes past its edge.
Type
Pill hugs its label, Circle is pinned square at 20, Dot drops the label for a 6px mark. All three take radius full.
The pill's 25 is arithmetic, not a set width: 2 outer, 4 wrapper, a 13 wide label, the same back out. Circle's box is pinned to 20 while the wrapper inside measures 21. Two digits fit, three do not, so a count badge caps at 99 and prints a plus. Dot keeps padding 6 and 8 from when it was a shrunken pill; with no children it does nothing.
State
Ten states, each mapped to a token family, not a colour, in both styles. Color fills base-500 with a static white label, white in both themes. Soft fills light-200 with a dark-950 label, an alpha tint in dark, so the badge stays translucent. Neutral reads no state family: bg/strong-950 filled, bg/soft-100 soft.
Cells read in the order named above, five to a row. Neutral is not a state family, and it is the only badge whose Color fill and label invert with the theme: it prints text/white-0, which flips to #0E0E0F in dark, giving a white pill with dark text. The nine coloured states print static/static-white-0 and hold white on their fill in both modes.
Properties
Three variant axes and one text property. Dot ignores the text, it has no label to put it in.
Badge ships 60 variants: 10 states by 3 types by 2 styles, no holes. That is the second largest complete matrix in the library, behind Button at 288. Badge Number is the only content property, and it reaches Pill and Circle. A Dot has no text node, so setting it there does nothing. No size axis, no icon: a badge is 20 tall or 6 across, everything else is colour.
Tokens
Four roles, read by nine of the ten states from their own family. Success stands in for all nine, resolved to the primitive underneath.
Radius is dimensions/radius/full on all three types. Swap success for any of the other eight families and the four roles hold: base-500 filled, static white on it, light-200 soft, dark-950 on that. Neutral is the exception, reading bg and text because there is no state/neutral family. In dark, light-200 is an alpha, not a solid, so a soft badge sits translucent over whatever it is pinned to.
Guidelines
Pick the type by what you have to say. A dot means something is there, a circle how many, a pill what it is.
Do not run a sentence through a badge, or stack three of them. At 20 tall it marks something else, it is not a label of its own.
The component description names the native homes: a badge on a tab item or a label on iOS, Badge on Android. Both expect it attached to something. Pin it to the thing it describes; do not let it float in a row of its own. If what you have to say is a sentence, use a Chip or an Alert, not a 20 tall marker carrying a 12 line.