Chips
Overview
Chips are compact tokens that label a thing — a dependent’s relationship to the employee, a coverage tier, a "pending approval" status on an election. They carry more visual weight than plain text, so use them where the label is doing real work.
A chip has two independent axes: a context sets the color (chip-primary, chip-success, …) and a treatment sets how that color is applied (tonal, chip-solid, chip-outline). Any context works in any treatment.
Guidelines
Dos
- Use chips to display status, categories, or lightweight attributes.
- Group multiple chips in a
chip-containerso they wrap and space consistently. - Keep chip text short and scannable — one or two words.
- Stay on the tonal treatment unless there is a reason not to.
- Use an
<a>when the chip navigates to the thing it names, and a<button>when pressing it acts on that thing.
Don’ts
- Don’t use chips for primary actions or workflows — that is a button.
- Don’t reach for
chip-solidby default. A row of solid chips competes with the content it is supposed to label. - Don’t use
chip-pillon anything that is not a chip. Chips are the one deliberate exception to this theme’s 4px radius. - Don’t introduce custom chip colors outside the five contexts.
- Don’t expect a removable chip to work here — build the remove control beside the chip instead.
Variants
| Variant | Description | Example use |
|---|---|---|
| Default | Neutral chip for general labeling | Metadata, tags |
| Primary | Brand-emphasized chip | Highlighted category |
| Info | Informational or descriptive status | Details, relationship |
| Success | Positive or completed status | Elected, Active |
| Warning | Cautionary or pending status | Pending approval |
| Danger | Error or blocked status | Waived, Declined |
Treatments
The treatment is a second class alongside the context, so chip-solid chip-success is a solid green chip. Tonal is the default and needs no class of its own.
| Treatment | Class | Looks like | Reach for it when |
|---|---|---|---|
| Tonal (default) | — | Light tint fill, darker ink, hairline border | A row of tags. It labels content rather than competing with it. |
| Solid | chip-solid | Saturated fill, white ink | A status that has to carry across a dense list. |
| Outline | chip-outline | Border alone, no fill | The quietest token. |
Warning chips take orange ink
Chip text is 12px, so it is normal-size text and gets no large-text discount — every pairing needs 4.5:1, and the yellow ramp cannot carry it (yellow 700 on yellow 50 is 3.95:1). This theme already resolves warning to orange, so warning chips take orange ink on the yellow tint the theme pairs with it: 7.42:1 tonal, 4.67:1 solid.
Modifiers
Chip container
When several chips appear together, wrap them in a chip-container. It lays them out in a wrapping flex row with a 4px gap, so a row grows down the page as more are assigned.
Pill
chip-pill renders the chip fully rounded, and works with any context and treatment.
Tonal
The default treatment. One class per chip — the context alone.
Solid
A saturated fill with white ink, for a status that has to carry across a dense list.
Outline
The hairline border alone — the quietest of the three.
Pill
With an icon
Add an icon class to the chip itself. The chip is an inline flex row with a 6px gap, so the glyph sits ahead of the text without extra markup.
Interactive chips
The whole chip is the control — a filter token that toggles, or a link to the thing the chip names. Hover shifts the fill by one step rather than switching treatment, so the chip stays recognizable while reading as clickable. Both roots get a focus ring, and a <button> supports disabled.
In context
Related
- Benefits chips — the same vocabulary in the benefits theme, plus the removable variant.
- Employee sticky footer — uses the same five contexts for its icon disc.