Add `RadioCard` to `@wordpress/ui`

[jameskoster]

Follow up to #76104

Summary

This issue proposes adding a new RadioCard (name TBD) component to the @wordpress/ui package. RadioCard is a high-emphasis, low-density single-select control — a visually rich alternative to RadioControl for contexts where each option benefits from more prominent presentation (e.g. card-like styling with borders, visuals, and supplementary content).

Motivation

RadioControl works well for compact, text-only option lists, but product UIs often require more emphasis per option, e.g.:

• Template selection — options carry thumbnails in a grid layout (example)
• Credit card / payment method selectors — options carry logos, card names, and supplementary detail
• Plan or tier selectors — options carry feature summaries or pricing breakdowns

Design

RadioCard.Root

The group container. Renders a radiogroup role.

RadioCard.Item

An individual radio card option. Renders a styled card (<Card />?) with a hidden <input type="radio">

RadioCard.Label (required)

The primary text label for the option. Maps to the accessible name of the radio input. Must always be present — a RadioCard.Visual alone is not sufficient.

RadioCard.Description

Supporting text for the label.

RadioCard.Visual

A small decorative element region (icon, logo, thumbnail, status glyph) rendered adjacent to the label.

Constraints:

• Intended for small presentational content only
• Must not replace the primary RadioCard.Label
• Purely decorative visuals should be hidden from assistive technologies (aria-hidden)
• Any meaning conveyed visually must also be present in text (via label or supporting content)
• Rich supplementary content belongs in RadioCard.SupportingContent, not here

RadioCard.SupportingContent

An optional region for rich supplementary content below the primary label.

Constraints:

• May contain non-interactive content: text, badges, images, icons, layout primitives
• Must not replace or obscure RadioCard.Label
• Must follow the primary label in DOM order
• Interactive elements are not permitted within this region
• Meaningful content should be associated to the radio as descriptive text (aria-describedby); purely decorative content should be hidden from assistive technologies

Examples

Layout

• Default: vertical stack
• Horizontal: row, items sized to content or equal-width
• Grid / wrapping row: essential for tile/template-selection UIs

cc @WordPress/gutenberg-design for any feedback.

[akash-aman]

Few Questions regrading implementation

1. Implementation foundation : Ariakit or custom?
The @wordpress/ui package uses Ariakit under the hood for many components (e.g., Tabs, DropdownMenu). Should RadioCard be built on top of Ariakit's RadioGroup/Radio primitives, or is a different foundation preferred?

2. Scope of initial PR
Would you prefer a minimal first PR (e.g., just Root, Item, Label with basic vertical layout and controlled/uncontrolled support) followed by incremental additions (Description, Visual, SupportingContent, grid layout)? Or a complete implementation in one go?

3. Design specs & first consumer
Are there Figma mockups or design tokens available for the selected/focus/disabled states? And is the template selector in @wordpress/edit-site the intended first integration point, or should the initial PR be a standalone component only?

[ciampo]

@akash-aman I appreciate the willingness to help, but it's clear that you (and the AI tools you're using) lack some basic context and the ability to correctly understand the package's tech stack.

The component should be based on base-ui's Radio component, and should use other components from @wordpress/ui (such as Text) and DS tokens from @wordpress/theme.

Although the specs are still a WIP, I don't think this is ready for implementation.

[akash-aman]

Thank you for the clarification. I was exploring details regarding the tech stack and spec status. Appreciate you confirming the use of base-ui and the @wordpress/theme tokens.

I will hold off on the implementation for now until the specs are finalized.

[jameskoster]

This UI in the experimental Dashboard project would be another consumer of this component:

[jasmussen]

Nice.

Do we have/should we have guidance on OK/Cancel patterns?

I feel like we have this precise interface in a few locations, and that they should all be the same. And is that bordered or text-only style for the cancel button?

[jameskoster]

Yes, at minimum we should provide guidance for action button groups. It may even be something we can codify or enforce through linting. This is probably worth reviewing more holistically in a separate issue, as there are currently inconsistencies across patterns—for example, Notices use a different action order than page headers, dialogs, and others. The guidance for Card footers is also unclear: should their actions follow the Notice pattern, align with Dialogs, or should we define a single approach across all surfaces?

[jasmussen]

Yes, valid. Not a strong opinion on precisely what we do, but a soft opinion is that "cancel" should be text-only/tertiary. Up to you all.