Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(SelectableCard): stop recommending it for single-select groups (#8419)

Cindy Zhangc4f6253e544e
diff --git a/.changeset/selectablecard-not-single-select-docs.md b/.changeset/selectablecard-not-single-select-docs.md
new file mode 100644
index 0000000000..7ee27dd3ce
--- /dev/null
+++ b/.changeset/selectablecard-not-single-select-docs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] SelectableCard's guidance no longer recommends it for single-select groups. Each card is a checkbox, so a single-select set built from it is announced as multi-select, with one tab stop per card and no arrow-key navigation between them. Its guidance now covers multi-select groups only.
+
+@cixzhang
diff --git a/packages/core/src/SelectableCard/SelectableCard.doc.mjs b/packages/core/src/SelectableCard/SelectableCard.doc.mjs
index 67d1adc0e0..45ce06ae6d 100644
--- a/packages/core/src/SelectableCard/SelectableCard.doc.mjs
+++ b/packages/core/src/SelectableCard/SelectableCard.doc.mjs
@@ -10,10 +10,11 @@ export const docs = {
usage: {
description: 'A card that toggles between selected and unselected states with an accent border. For navigation use ClickableCard.',
bestPractices: [
- {guidance: true, description: 'Use for plan pickers, filter chips, or option grids.'},
- {guidance: true, description: 'For single-select track one ID; for multi-select use a Set.'},
+ {guidance: true, description: 'Use for multi-select choices: filter chips, feature add-ons, or option grids where several can be on.'},
+ {guidance: true, description: 'Use for multi-select groups; track the selected IDs in a Set.'},
{guidance: true, description: 'When focused, toggle selection with Space or Enter.'},
{guidance: false, description: 'Use for navigation; use ClickableCard for that.'},
+ {guidance: false, description: 'Use for a single-select group: each card is a checkbox, so assistive technology announces a multi-select group with one tab stop per card.'},
],
anatomy: [
{name: 'Container', required: true, description: 'Interactive div with accent border on selection.'},
@@ -65,10 +66,11 @@ export const docsDense = {
usage: {
description: 'Card toggling between selected/unselected states w/ accent border. For navigation use ClickableCard instead.',
bestPractices: [
- {guidance: true, description: 'Use for plan pickers, filter chips, option grids.'},
- {guidance: true, description: 'For single-select track one ID; for multi-select use a Set.'},
+ {guidance: true, description: 'Use for multi-select choices: filter chips, add-ons, option grids.'},
+ {guidance: true, description: 'Use for multi-select groups; track selected IDs in a Set.'},
{guidance: true, description: 'When focused, toggle selection with Space or Enter.'},
{guidance: false, description: 'Use for navigation; use ClickableCard instead.'},
+ {guidance: false, description: 'Use for single-select: each card is a checkbox, so screen readers announce multi-select.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/SelectableCard/SelectableCard.tsx b/packages/core/src/SelectableCard/SelectableCard.tsx
index 0a41a28326..1d6dce18ee 100644
--- a/packages/core/src/SelectableCard/SelectableCard.tsx
+++ b/packages/core/src/SelectableCard/SelectableCard.tsx
@@ -334,17 +334,17 @@ export interface SelectableCardProps extends Omit<BaseProps, 'onChange'> {
* the accessible role, label, and checked state. The card surface
* is a plain <div> — no role or tabIndex on the container.
*
- * @compositionHint Use for multi-select or single-select card groups.
- * Manage selection state externally — use a Set for multi-select
- * or a single value for radio-style selection.
+ * @compositionHint Use for multi-select card groups, managing selection
+ * state externally in a Set. Not for single-select: each card is a
+ * checkbox, so assistive technology announces a multi-select group.
* For navigation/action cards, use ClickableCard instead.
*
* @example
* ```
* <SelectableCard
* label="Option A"
- * isSelected={selected === 'a'}
- * onChange={() => setSelected('a')}>
+ * isSelected={selected.has('a')}
+ * onChange={isSelected => toggle('a', isSelected)}>
* <Text type="body" weight="bold">Option A</Text>
* </SelectableCard>
* ```