PDS proposals
← All proposals

Badge

A copy of the PDS v2 Badge (pds-badge, same class names, props and CSS) with one addition: color='agentic-filled', the AI gradient as the fill, for denoting an agentic category.

Extends a PDS componentOpen in Storybook

proposals/Badge/HANDOFF.md69 lines · View on GitHub

Handoff: Badge

What and why

One addition to the existing PDS v2 Badge: color='agentic-filled', the AI gradient (--pds-gradient-ai-active) as the badge fill, for denoting an agentic category (for example a "Zappy" or "Agent" label). Everything else is the v2 Badge (v2.0.0-beta.12), unchanged. The Section Message proposal uses it for its agentic type. Figma: Badge page (2 stories, light only; captures of Storybook, with the library's zappy icon swapped in). Context: context.md.

Exploration and decisions

  • Started from an unchanged copy of the v2 Badge so the port is mostly a one-value addition.
  • An agentic border variant (AI gradient border on a surface fill) was tried and removed at the designer's request; only the filled treatment remains.
  • agentic-filled fills with --pds-gradient-ai-active, the same gradient used for the agentic border elsewhere, and takes --pds-color-foreground-reverse for text: white in light mode, dark in dark mode, a semantic token instead of a raw white. Static, no border, no muted twin.
  • ai-active (the existing animated gradient fill) keeps its #fff foreground as in v2: no white-on-gradient token exists.
  • Chosen over a muted discovery fill by the designer.

Full list and reasons: decisions.md.

API

Identical to v2 Badge, plus one color value.

Prop Type Default Purpose
className string none Additional class names.
color BadgeColor 'brand-muted' Badge color: a solid and a -muted variant of each color, plus ai-active and the new agentic-filled. Required in the type.
iconName icon name none Optional leading icon, sized to fit size and colored to match the foreground.
label ReactNode none (required) Badge content.
size 'xs' | 's' | 'm' 's' Badge size.

New: 'agentic-filled' added to BadgeColor. Stories: Agentic, AllSizesWithIcons.

Tokens used

The v2 Badge's own tokens (every --pds-color-badge-* background and foreground pair, --pds-spacing-*, --pds-typography-fw-medium and --pds-typography-size-*), plus the three the addition uses:

  • --pds-gradient-ai-active
  • --pds-color-foreground-reverse
  • (--pds-gradient-ai-active-badge, already used by v2 ai-active)

Full list: npm run check:tokens -- --report Badge.

Impact

From impact.md: no existing component is changed. The addition is opt-in: .pds-badge--agentic-filled only applies where that class is added, so every existing Badge is unaffected. No --pds-* token is redefined. SectionMessage uses the new color (its agentic type); port Badge first.

Reused vs net-new

  • Reused: the v2 Badge in full (markup, sizes, colors, icon handling), the local Icon wrapper.
  • Net-new: .pds-badge--agentic-filled and the agentic-filled value of color. No custom CSS variables beyond v2's. Raw values kept, same as v2: #fff (the ai-active foreground) and 1.875rem (the m height). Details in custom.md.

Accessibility

Unchanged from the v2 Badge: a span with the label as text; the icon is decorative. Contrast to check: white text on the light blue and pink stops of the gradient is low contrast in light mode (not measured yet; the ai-active fill uses a darker gradient for this reason). Dark mode gets dark text. The a11y panel has not been run, and light and dark were not checked by eye in a session.

Decisions and open questions

For the engineer or designer to settle:

  • Contrast of the light-mode white text on agentic-filled: use the darker ai-active gradient (--pds-gradient-ai-active-badge), dark text, or accept?
  • Should the agentic colors animate like ai-active? Currently static.
  • Does agentic-filled need a muted twin? None exists.

Port notes

Changes the existing PDS Badge (src/components/badges/Badge/): add 'agentic-filled' to BadgeColor and the .pds-badge--agentic-filled rule to badge.css. No generator needed. Differences from v2 to undo: the local mergeClasses stand-in (use @libs/components/utils), the local Icon wrapper and IconProps['iconName'] (use @components/icons/Icon/Icon and PDSIcon), and IconSize imported from the package (use @libs/types/custom-types).

Preview

npm run storybook, story Component Proposals / Badge. Figma: https://www.figma.com/design/AMGWJbraJoi2PKWnxo29Ah/PDS-Proposals?node-id=363-43, page Badge.