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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/packages/core/src/SelectableCard/SelectableCard.doc.mjs b/packages/core/src/SelectableCard/SelectableCard.doc.mjsindex 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.tsxindex 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>* ```