Accessibility

A pill button is a native <button> — a text label, optionally with a leading or trailing icon — so it carries button semantics and keyboard operation for free, and meets WCAG 2.1 AA. Its accessibility hinges on two things: a clear accessible name, and — when the pill is used as a filter or toggle — a selected / pressed state that is exposed to assistive technology, not just shown visually.

For designers

• The label and every state — rested, hover, selected, disabled — must maintain accessible contrast on every supported surface, including the on-overlay variants placed over imagery. Source: WCAG 1.4.3 Contrast (Minimum).
• The selected state must never be conveyed by colour alone — pair the fill change with a shape, weight, or icon cue so the choice reads without relying on hue. Source: WCAG 1.4.1 Use of Color.
• Focus styles must stay visible, meet contrast requirements on every supported surface, and be clearly distinguishable from hover and from the selected state. Source: WCAG 2.4.7 Focus Visible.
• Use semantic colour tokens (e.g. foreground/neutral/default) rather than fixed values, so the pill adapts correctly across themes and surfaces.
• Keep the interactive target comfortable even when the visual pill is small — add invisible padding rather than shrinking the hit area, and keep adjacent pills spaced so their targets don’t overlap. Source: WCAG 2.5.8 Target Size (Minimum).

For developers

Use a native <button>, never a styled <div> or <span> — the native element is focusable, operable with Enter and Space, and announced as a button without extra ARIA. The accessible name comes from the visible text; keep that text present even when an icon is paired with it. When the pill acts as a filter or toggle, reflect its selected state to assistive technology with aria-pressed (or aria-selected in a listbox-style filter group) — the is-selected visual alone is not announced. Keep decorative icons out of the accessibility tree with aria-hidden="true". Interactive targets must be at least 44 px high for comfortable touch use — comfortably clearing the WCAG AA minimum. Source: WCAG 2.5.8 Target Size (Minimum). Each element’s role, accessible name, and state are in the Labelling elements section below.

Labelling elements

Give every element the role, name, and state assistive technology needs.

Button

The native <button> takes its accessible name from its visible text content — keep that text self-describing (e.g. Electric, Apply filter) so it stands on its own. Don’t replace the text with an icon alone; if a design ever calls for an icon-only pill, give it an explicit aria-label.

Icon

A leading or trailing icon is decorative — mark it aria-hidden="true" so it never adds noise to the accessible name. The label text alone must carry the meaning.

Selected / pressed state

When the pill is a filter or toggle, expose its state with aria-pressed="true"/"false" (or aria-selected inside a listbox-style filter group), kept in sync with the visual is-selected treatment. Without it, screen-reader users hear a plain button and miss the choice.

Disabled

Use the native disabled attribute rather than a .is-disabled class — it removes the pill from the tab order and announces it as unavailable. Keep the disabled pill visible so its presence in the set stays discoverable.

Source: WCAG 4.1.2 Name, Role, Value.