@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/SegmentedControl/SegmentedControl.test.tsx

@@ -849,3 +849,49 @@ describe('pressed state', () => {
     );
   });
 });
+
+describe("SegmentedControl keeps a caller's aria-describedby", () => {
+  it('describes the radiogroup by the caller ids', () => {
+    render(
+      <>
+        <span id="caller-help">Applies to every board</span>
+        <SegmentedControl
+          value="grid"
+          onChange={() => {}}
+          label="View mode"
+          aria-describedby="caller-help">
+          <SegmentedControlItem value="grid" label="Grid" />
+        </SegmentedControl>
+      </>,
+    );
+    expect(screen.getByRole('radiogroup')).toHaveAccessibleDescription(
+      'Applies to every board',
+    );
+  });
+
+  it('describes the disabled radiogroup by the caller ids and then the reason', () => {
+    render(
+      <>
+        <span id="caller-help">Applies to every board</span>
+        <SegmentedControl
+          value="grid"
+          onChange={() => {}}
+          label="View mode"
+          isDisabled
+          disabledMessage="Choose a project to switch views"
+          aria-describedby="caller-help">
+          <SegmentedControlItem value="grid" label="Grid" />
+        </SegmentedControl>
+      </>,
+    );
+    const ids = screen
+      .getByRole('radiogroup')
+      .getAttribute('aria-describedby')
+      ?.split(' ');
+    expect(ids).toHaveLength(2);
+    expect(ids?.[0]).toBe('caller-help');
+    expect(document.getElementById(ids?.[1] ?? '')).toHaveTextContent(
+      'Choose a project to switch views',
+    );
+  });
+});

package/src/SegmentedControl/SegmentedControl.tsx

@@ -27,6 +27,7 @@ import type {
   SegmentedControlLayout,
 } from './SegmentedControlContext';
 import {mergeProps, composeEventHandlers} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 import {useSize} from '../SizeContext/SizeContext';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -173,6 +174,7 @@ export function SegmentedControl({
   onKeyDown: onKeyDownProp,
   onFocus: onFocusProp,
   onBlur: onBlurProp,
+  'aria-describedby': ariaDescribedByProp,
   ...rest
 }: SegmentedControlProps) {
   const size = useSize(sizeProp, 'md');
@@ -281,9 +283,11 @@ export function SegmentedControl({
         role="radiogroup"
         aria-label={label}
         aria-disabled={isDisabled || undefined}
-        aria-describedby={
-          showsDisabledMessage ? disabledMessageTooltip.describedBy : undefined
-        }
+        // A caller aria-describedby comes before the disabled reason.
+        aria-describedby={joinAriaIDs(
+          ariaDescribedByProp,
+          showsDisabledMessage ? disabledMessageTooltip.describedBy : undefined,
+        )}
         onKeyDown={handleContainerKeyDown}
         onFocus={handleContainerFocus}
         onBlur={composeEventHandlers(onBlurProp, hint.onBlur)}

package/src/SegmentedControl/SegmentedControlItem.spec.md

@@ -0,0 +1,206 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:SegmentedControlItem
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-28
+owners: [cixzhang]
+review_triggers:
+  [
+    public-api,
+    behavior,
+    layout,
+    interaction,
+    motion,
+    theming,
+    styling,
+    accessibility,
+    visual,
+    react-runtime,
+    compatibility,
+  ]
+verified_by:
+  [
+    packages/core/src/SegmentedControl/SegmentedControl.test.tsx,
+    packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx,
+    packages/core/src/RadioList/__tests__/RadioGroup.a11y.chromium.spec.ts,
+    packages/core/src/__tests__/PressedState.a11y.chromium.spec.ts,
+  ]
+modules: []
+families: []
+design_specs: [design:user-states]
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-020, spec:AST-085, spec:AST-102]
+---
+
+# SegmentedControlItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                  |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. SegmentedControlItem takes `value`, `label`, `isLabelHidden`, `icon`, `isDisabled`, and base props, and must sit inside a SegmentedControl.                                                                                                                                                                                                 |
+| Behavior                | One segment: a `<button role="radio">` with `aria-checked`. A click, or Space or Enter on the focused segment, selects it unless it is selected, disabled, or the caller's `onClick` prevents default.                                                                                                                                                    |
+| End-user impact         | People see the selected segment raised and bold, and pick another with one click. Icon-only segments are still named. A disabled selected segment drops out of the tab order.                                                                                                                                                                             |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                     |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A disabled selected segment leaves the tab order, a caller `onClick` runs while disabled or cannot veto a press while focused, a caller `className` is replaced, segments hold a fixed height, and a truncated `sm` segment can be under 24 px wide; all are listed under Current-state impact. |
+| Review checks           | Reject a segment without a name, a click that selects a disabled segment, press paint on the selected or a disabled segment, or a lost forced-colors selected state.                                                                                                                                                                                      |
+| Governing rules         | `component:SegmentedControl`; WAI-ARIA radio pattern; `spec:AST-020` FR9, FR15, DEC-5; `spec:AST-085` FR1, FR2; `spec:AST-102` FR4; `design:user-states` DR1–DR3 (pressed overlay, disabled non-response, and selected-segment exception); `architecture:public-component-api` INV5, INV6; WCAG 1.4.11.                                                   |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+SegmentedControlItem is one choice in a SegmentedControl. It owns the
+segment's radio semantics, click selection, naming, label and icon rendering,
+item disabled state, and the segment's paint. Consumer usage lives in
+`SegmentedControlItem.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; label visible, enabled
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
+- Controlled/uncontrolled behavior: controlled by the parent's `value`
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The segment button, its radio role, checked and disabled state, and name.
+- Click selection and `onClick` composition.
+- Label and icon rendering, truncation, and segment paint per size and state.
+
+**Does not own / non-goals**
+
+- Tab stop, arrow navigation, selection-follows-focus, group disabled state,
+  and the theming anatomy map — owned by `component:SegmentedControl`. The
+  `segmented-control-item` target is declared in SegmentedControl's consumer
+  docs and mapped in its record.
+- Icon artwork — owned by the caller.
+- Use outside SegmentedControl — not supported.
+
+## Public concepts
+
+| Concept  | Closed values or states   | Meaning                                            | Availability by variant/orientation/state | Default  | Owner                            | Stability | Invalid-value behavior              |
+| -------- | ------------------------- | -------------------------------------------------- | ----------------------------------------- | -------- | -------------------------------- | --------- | ----------------------------------- |
+| Value    | string                    | The value this segment selects.                    | Always.                                   | required | `component:SegmentedControlItem` | Stable    | TypeScript rejects a missing value. |
+| Label    | string; visible or hidden | Visible text, or the name of an icon-only segment. | Always.                                   | visible  | `component:SegmentedControlItem` | Stable    | TypeScript rejects a missing label. |
+| Disabled | off, item, group          | Blocks selection.                                  | Always.                                   | off      | `component:SegmentedControlItem` | Stable    | Not applicable.                     |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                                                                        |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| FR1 | Each segment renders one `<button type="button" role="radio">` with `aria-checked` true when its `value` equals the group value, `data-value`, and the `segmented-control-item` target reflecting `data-size`, `data-selected`, and `data-disabled`. A forwarded prop cannot override the role.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | WAI-ARIA radio pattern; current source and tests                             |
+| FR2 | A click, including one from Space or Enter on the focused segment (native button activation; `spec:AST-020` FR15), runs the caller `onClick` first; unless it prevents default, an enabled, unselected segment passes its value to the group's `onChange`. Clicking the selected segment does nothing. The caller's `preventDefault()` MUST veto every press. Implementation gap: a press while focus is already in the group selects through `component:SegmentedControl` FR3 before the click, so the veto does not apply to it.                                                                                                                                                                                                                                                            | `spec:AST-020` FR15; current tests                                           |
+| FR3 | The segment renders its icon (sized to the segment size) followed by its label. With `isLabelHidden`, the label is not rendered and becomes `aria-label`, and the segment does not shrink. A visible label truncates with an ellipsis when the segment is narrower than it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current tests                                                                |
+| FR4 | A segment disabled by its own `isDisabled` or by the group sets `aria-disabled`, refuses selection, shows disabled text color, and shows no hover or press paint. A disabled selected segment MUST keep the Tab stop (`spec:AST-085` FR1); for a value that matches no segment, `component:SegmentedControl` FR2 places the stop. Implementation gap: a disabled selected segment leaves the tab order, except in a group disabled with a reason when it is not itself `isDisabled`, and a caller `onClick` still runs on a disabled segment (`spec:AST-085` FR2).                                                                                                                                                                                                                            | `spec:AST-085` FR1, FR2; current tests                                       |
+| FR5 | The selected segment paints a raised surface with a low shadow and semibold primary text; under forced colors it paints `Highlight` with `HighlightText`. Unselected enabled segments paint the shared hover tint and, under `design:user-states` DR1 and DR2, the pressed overlay; the selected segment keeps its raised surface during a press (DR3).                                                                                                                                                                                                                                                                                                                                                                                                                                       | WCAG 1.4.11; `design:user-states` DR1–DR3; current tests                     |
+| FR6 | Segment height is the element height for the size minus 4 CSS px (24, 28, or 32) as a minimum that grows with a set text size under `spec:AST-102` FR4 (implementation gap: the height is fixed), with corners concentric with the control; `sm` uses supporting text and tighter padding. Keyboard focus paints the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `architecture:interaction-modality` INV1; current source; `spec:AST-102` FR4 |
+| FR7 | The segment owns `role`, `aria-checked`, `aria-disabled`, `aria-label` (set from the label when hidden), `tabIndex`, `type`, `data-value`, and `data-size`, and writes `data-selected`, `data-disabled`, and the press marker `data-astryx-pressable` in their own states; a caller value for an owned attribute is replaced, while a caller `data-selected`, `data-disabled`, or `data-astryx-pressable` passes through on segments outside that state. `ref`, other `data-*`, `style`, other ARIA such as `aria-describedby`, and other base props reach the button; `xstyle` composes last. Caller `className` MUST compose with the component's classes (`architecture:public-component-api` INV5, INV6). Implementation gap: the component's merged class replaces a caller `className`. | `architecture:public-component-api` INV5, INV6; current tests                |
+
+### Allowed variation
+
+- **AV1 — Content.** Label text and icon vary within their types.
+
+### Representative states
+
+| State      | Required invariant                                                  | Allowed variation |
+| ---------- | ------------------------------------------------------------------- | ----------------- |
+| Unselected | `aria-checked="false"`; hover and press overlay.                    | Icon.             |
+| Selected   | `aria-checked="true"`; raised; bold; Highlight under forced colors. | —                 |
+| Icon-only  | Named by `aria-label`; does not shrink.                             | —                 |
+| Disabled   | `aria-disabled`; no paint feedback; no selection.                   | Item or group.    |
+
+### Transformation and precedence order
+
+- **ORD1 — Click.** Caller `onClick`, then selection unless prevented,
+  disabled, or already selected; today a press while focus is in the group
+  selects through focus first (FR2 gap).
+
+### Performance and resources
+
+- **PR1 — Bounded resources.** No state, effect, or listener of its own; press
+  feedback shares the press controller's window and document listeners.
+
+## Accessibility contract
+
+- **AR1 — Radio semantics.** Each segment exposes the radio role, checked
+  state, disabled state, and a name (FR1, FR3).
+- **AR2 — Target size.** The smallest segment is 24 CSS px tall. A labelled
+  `sm` segment that truncates under `component:SegmentedControl` FR5 can shrink
+  below 24 CSS px wide, short of WCAG 2.5.8 (implementation gap).
+- **AR3 — Non-color state.** FR5.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Segment          | Transparent button; raised surface when selected. | Current source           | Prominent      | FR1, FR5, FR6      |
+| Label            | Medium text; semibold when selected; truncates.   | Current source           | Prominent      | FR3, FR5           |
+| Icon             | Caller artwork sized to the segment.              | Current source           | Supporting     | FR3                |
+
+The target mapping for these parts lives in `component:SegmentedControl`'s
+theming anatomy.
+
+## Family and system relationships
+
+- `component:SegmentedControl` supplies the value, size, layout, and group
+  disabled state, and owns keyboard navigation.
+- `spec:AST-085` owns disabled focusability; FR4 records the gap.
+- `design:user-states` owns the pressed treatment.
+
+## Verification map
+
+| Contract | Verification                                                                                                                                                                                                       | Representative states                         | Mutation or failure expectation                                                                                                                                                                                                                                                                                                 | Audit section                              |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| FR1      | `SegmentedControl.test.tsx` aria-checked and data-testid cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-option-*` states                           | Selection change; data-testid                 | Stale `aria-checked` fails. Evidence gap: no test passes `role` to a segment; the role-override case covers the radiogroup.                                                                                                                                                                                                     | `audit:SegmentedControlItem/accessibility` |
+| FR2      | `SegmentedControl.test.tsx` click and onClick-composition cases                                                                                                                                                    | Click; selected click; prevented click        | A selected or prevented click that selects fails. Evidence gap: no test covers a press while focus is already in the group.                                                                                                                                                                                                     | `audit:SegmentedControlItem/behavior`      |
+| FR3      | `SegmentedControl.test.tsx` icon, icon-only, and truncation cases                                                                                                                                                  | Icon and label; icon-only; long label         | A missing name, or an icon that truncates, fails.                                                                                                                                                                                                                                                                               | `audit:SegmentedControlItem/anatomy`       |
+| FR4      | `SegmentedControl.test.tsx` disabled cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-option-disabled` and `segmented-option-group-disabled*` states | Item and group disabled                       | A disabled segment that selects fails. Evidence gap: no test asserts the disabled text color, absent hover paint, or the caller `onClick` while disabled. The `segmented-option-group-disabled` state declares a checked, group-disabled segment with `tabReachable: false`, asserting the current FR4 gap pending conformance. | `audit:SegmentedControlItem/accessibility` |
+| FR5      | `SegmentedControl.test.tsx` forced-colors and pressed-state cases; `PressedState.a11y.chromium.spec.ts` segmented-control cases                                                                                    | Selected under forced colors; press; disabled | Lost forced-colors state, or press paint on a disabled segment, fails. Evidence gap: no test asserts the raised selected surface or the hover tint.                                                                                                                                                                             | `audit:SegmentedControlItem/visual`        |
+| FR6, FR7 | Evidence gap: no test of segment heights, text growth, focus outline, `ref`, or `xstyle` order                                                                                                                     | —                                             | —                                                                                                                                                                                                                                                                                                                               | `audit:SegmentedControlItem/layout`        |
+
+## Current-state impact
+
+- **Narrow target (AR2).** A labelled `sm` segment that truncates can shrink
+  below 24 CSS px wide, short of WCAG 2.5.8.
+- **Press veto (FR2).** A caller `onClick` cannot veto a press made while focus
+  is already in the group, which selects before the click.
+- **Caller className (FR7).** A caller `className` on a segment is replaced by
+  the component's class, against `architecture:public-component-api` INV5 and
+  INV6.
+- **Caller onClick while disabled (FR4).** A disabled segment still runs a
+  caller's `onClick`, against `spec:AST-085` FR2.
+- **Fixed height (FR6).** Segments hold a fixed height instead of growing with
+  a set text size, against `spec:AST-102` FR4.
+- **Disabled selected segment (FR4).** A disabled selected segment leaves the
+  tab order, except in a group disabled with a reason when it is not itself
+  `isDisabled`, against `spec:AST-085` FR1.
+
+## Decision log
+
+No component-local decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/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.'},
@@ -39,8 +40,7 @@ export const docs = {
     targets: [{className: 'astryx-selectable-card', visualProps: ['selected', 'variant']}],
     vars: [
       {name: '--selectable-card-ring-color', description: 'Colour of the selection ring drawn for a variant a theme added. The built-in variants each ring in their own border token and ignore this; a theme that adds a variant sets it in the same rule as that variant\'s `backgroundColor`, because no token the component could pick is guaranteed to contrast with a fill it cannot know.', default: 'var(--color-accent)'},
-      {name: '--_press-overlay', description: 'Fill of the ::after interaction overlay: transparent at rest, the hover overlay token on hover (hover-capable pointers), the pressed overlay token while pressed (`:active` on a mouse; `data-astryx-press="on"` written by the touch press controller under a finger) and the hover token for the release fade. Set on the card element by its own interaction arms.', default: 'transparent', private: true},
-      {name: '--_press-overlay-transition', description: 'Duration of the overlay\'s background-color transition: the fast duration token, except 0s while a believed touch press paints so it lands on the first frame.', default: 'var(--duration-fast)', private: true},
+      {name: '--_press-overlay', description: 'Colour of the ::after interaction overlay for the hover and mouse states: transparent at rest, the hover overlay token on hover (hover-capable pointers), the pressed overlay token while a mouse holds `:active`. A press the touch press controller paints (`data-astryx-press`) is the overlay\'s image instead, at the press\'s strength, and the colour yields to it. Set on the card element by its own interaction arms.', default: 'transparent', private: true},
     ],
   },
   playground: {
@@ -66,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: {

package/src/SelectableCard/SelectableCard.spec.md

@@ -0,0 +1,230 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:SelectableCard
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-28
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx,
+    packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts,
+    packages/core/src/__tests__/CardPress.a11y.chromium.spec.ts,
+    .github/visual-baseline/manifest.json,
+    packages/core/src/SelectableCard/SelectableCard.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/SelectableCard.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-009, spec:AST-020, spec:AST-085]
+---
+
+# SelectableCard component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                    |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | A Card that toggles a controlled `isSelected` through `onChange`, named by a required `label`, with `isDisabled` and Card's `variant`, `elevation`, `padding`, and sizing.                                  |
+| Behavior                | A visually hidden native checkbox carries the role, name, and checked state; the whole surface toggles; selection draws an inset ring without moving layout.                                                |
+| End-user impact         | Screen-reader users hear a named checkbox and its state; pointer users click anywhere on the card; disabled cards stay discoverable by keyboard.                                                            |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                                |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact.                                                                   |
+| Review checks           | Reject a toggle that fires twice for one press, a disabled card that toggles or leaves the tab order, a ring that shifts layout, or a nested control that toggles the card.                                 |
+| Governing rules         | `spec:AST-085/FR1,FR2,FR5,FR6`; `spec:AST-020/FR9`; `architecture:interaction-modality/INV3`; `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV7,INV8`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+SelectableCard turns a Card into one checkbox option for multi-select card
+groups; each card is a checkbox, so single-select groups are out of scope. It owns the hidden checkbox semantics, whole-surface
+toggling, and the selection ring; the caller owns the selection state.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
+- Controlled/uncontrolled behavior: controlled only; `isSelected` and
+  `onChange` are required
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Two focus indicators on nested controls (FR4, AR2).** The card draws its
+  outline whenever any descendant has `:focus-visible`, so focusing a nested
+  control shows the card outline and the control's own, where
+  `architecture:interaction-modality` INV3 allows one indicator per focus move.
+- **Disabled state not reflected on the target (FR5).** The
+  `selectable-card` target carries no disabled state, so a theme cannot style it
+  there, where `architecture:component-theming-surface` INV6 keeps state on the
+  owning target.
+
+## Ownership boundary
+
+**Owns**
+
+- The hidden native checkbox, its name, checked state, and disabled state.
+- Toggling from the card surface, the checkbox, and Enter, and suppressing
+  toggles from nested interactive content.
+- The selection ring, the selected border color, hover and pressed overlays,
+  the delegated focus indicator, and the disabled treatment.
+- The `selectable-card` target and the public `--selectable-card-ring-color`
+  variable.
+
+**Does not own / non-goals**
+
+- Card surface paint, padding, radius, elevation, and sizing — owned by
+  `component:Card`.
+- Group semantics and which options are selected — owned by the product
+  callsite. Single-select groups need a radio pattern, which SelectableCard
+  does not provide.
+- Navigation and one-shot actions — owned by `component:ClickableCard`.
+
+## Public concepts
+
+| Concept   | Closed values or states        | Meaning                                                 | Availability by variant/orientation/state | Default   | Owner                      | Stability | Invalid-value behavior                                                                                               |
+| --------- | ------------------------------ | ------------------------------------------------------- | ----------------------------------------- | --------- | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------- |
+| Selection | selected; unselected           | Controlled checked state, reflected as `data-selected`. | Always                                    | Required  | `component:SelectableCard` | Stable    | —                                                                                                                    |
+| Disabled  | enabled; disabled              | Blocks toggling while keeping the checkbox focusable.   | Always                                    | enabled   | `component:SelectableCard` | Stable    | —                                                                                                                    |
+| Variant   | Card variants; theme additions | Card paint and the matching selection ring color.       | Always                                    | `default` | `component:Card`           | Stable    | A theme-added variant rings in `--selectable-card-ring-color` (default `--color-accent`) and keeps its border color. |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | SelectableCard renders `component:Card` with the given `variant`, `elevation`, `padding`, and sizing. The root also carries the `selectable-card` target reflecting `variant` and `selected`, and the first child is a visually hidden native `input type="checkbox"` named by `label` with `checked` equal to `isSelected`.                                                                                                                                                                                                                                                                            | Current source and tests |
+| FR2 | While enabled, a click on the card surface, a click or Space on the checkbox, or Enter on the checkbox calls `onChange(!isSelected)` exactly once. A click that belongs to nested interactive content or selected text does not toggle. A caller `onClick` runs after the toggle for a surface click, before it for a click or Space on the checkbox, and not at all for Enter; it also runs for clicks that do not toggle. A caller `onMouseUp` runs after the card's own handling.                                                                                                                    | Current source and tests |
+| FR3 | Selection adds a 2px inset ring through Card's ring variable, so layout does not move, and composes with any elevation shadow. `default`, `transparent`, and `muted` ring in `--color-accent`; each palette variant rings in its `--color-border-<name>`; a theme-added variant rings in `--selectable-card-ring-color`. Selection also colors the border in the ring color where Card draws one, which is only the `default` variant.                                                                                                                                                                  | Current source and tests |
+| FR4 | While enabled, the surface paints the shared hover overlay under a hover-capable pointer and the pressed overlay for mouse and touch presses. Keyboard focus on the hidden checkbox shows one indicator on the card root (`architecture:interaction-modality` INV3). Implementation gap: the root outlines while any descendant has `:focus-visible`, so focusing a nested control draws both the card outline and the control's own (Current-state impact).                                                                                                                                            | Current source and tests |
+| FR5 | `isDisabled` dims the card to half opacity, removes the card's own click and mouseup handling and the caller's `onClick` and `onMouseUp` (other caller event props still reach the root) and the hover and pressed overlays (`spec:AST-085` FR6), and keeps the checkbox focusable with `aria-disabled="true"`; no click, Space, or Enter calls `onChange`. The disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `selectable-card` target reflects `variant` and `selected` but not the disabled state (Current-state impact). | Current source and tests |
+| FR6 | `ref` reaches the Card root. Supported DOM, ARIA, data, and event props reach the root; `xstyle`, `className`, and `style` merge after the component's interactive styles.                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Content.** Caller content, including nested controls, keeps its own
+  semantics and interaction.
+- **AV2 — Theme paint.** A theme may restyle `selectable-card` per `variant` and
+  `selected`, and set the ring color for an added variant.
+
+### Representative states
+
+| State          | Required invariant                                                                                | Allowed variation |
+| -------------- | ------------------------------------------------------------------------------------------------- | ----------------- |
+| Unselected     | Unchecked named checkbox; no ring.                                                                | Variant.          |
+| Selected       | Checked; inset ring in the variant's color, and a matching border on `default`; layout unchanged. | Elevation.        |
+| Keyboard focus | Focus outline on the card root.                                                                   | —                 |
+| Disabled       | Focusable checkbox with `aria-disabled`; no toggle; half opacity.                                 | Selection.        |
+| Nested control | Activating the nested control does not toggle the card.                                           | Control type.     |
+
+### Transformation and precedence order
+
+- **ORD1 — Toggle.** Disabled → nothing runs, caller `onClick` and
+  `onMouseUp` included; nested interactive target or selection → no toggle,
+  caller handlers still run; otherwise one `onChange(!isSelected)`, with a
+  caller `onClick` after it for a surface click, before it for a click or
+  Space on the checkbox, and not at all for Enter.
+- **ORD2 — Ring color.** Built-in variant mapping → `--selectable-card-ring-color`
+  for a theme-added variant.
+
+### Performance and resources
+
+- **PR1 — Shared resources only.** SelectableCard installs the shared press
+  controller on mount and marks its root as a press surface only while
+  enabled; it adds no listener, observer, or timer of its own.
+
+## Accessibility contract
+
+- **AR1 — Native checkbox.** The hidden checkbox supplies the role, name, and
+  checked state; the card root adds no role or tab stop of its own, except
+  that a fixed-height card whose content overflows is a scroll container that
+  browsers may make an unnamed tab stop (`component:Card` AR1).
+- **AR2 — Delegated focus indicator.** Keyboard focus on the hidden checkbox is
+  shown on the visible card root (`architecture:interaction-modality` INV3).
+  Implementation gap: a focused nested control shows a second outline.
+- **AR3 — Focusable disabled.** A disabled card keeps its tab stop, exposes
+  `aria-disabled`, and blocks every toggle path (`spec:AST-085` FR1, FR2, FR5).
+- **AR4 — Persistent selection.** Selection changes the
+  checked state for assistive technology and draws a ring (and, on `default`,
+  a border) that persists under hover and press, which still paint their
+  overlays.
+- **AR5 — Pointer cancellation.** A press that slides off the card before the
+  lift does not toggle it (`spec:AST-020` FR9; WCAG 2.2 2.5.2).
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Container        | Interactive card with an inset ring on selection. | Current source and docs  | Prominent      | FR1, FR3–FR5       |
+| Content          | Caller content inside the card.                   | Current source and docs  | Prominent      | FR2, AV1           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Container": {"target": "selectable-card"},
+  "Content": {
+    "none": {
+      "reason": "intentional: caller content keeps its own styling and has no component-owned paint target"
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- `component:Card` supplies paint, padding, and the ring and elevation
+  variables SelectableCard sets.
+- `spec:AST-085` owns focusable disabled controls; AR3 records conformance.
+- `spec:AST-020` FR9 excludes SelectableCard from the slide-off exception;
+  AR5 applies it.
+- `architecture:component-theming-surface` sets the rules the
+  `selectable-card` target follows and requires a safe baseline for the
+  extensible `variant`, which `--selectable-card-ring-color` satisfies.
+
+## Verification map
+
+| Contract            | Verification                                                                                                                         | Representative states                                                            | Mutation or failure expectation                                                                                                                                                                                                                                                              | Audit section                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1, FR2            | `SelectableCard.test.tsx` surface, checkbox, Enter, and Space tests                                                                  | Unselected, selected                                                             | A missed toggle, a wrong `onChange` value, or a doubled toggle from Space fails. Gap: surface-click tests assert only the value, not the call count, and no test asserts the `selectable-card` target or its reflection, or the order of a caller `onClick` or `onMouseUp`.                  | `audit:SelectableCard/behavior` |
+| FR3                 | `SelectableCard.test.tsx` elevation tests; stable visual baseline `core-selectablecard--single-select`; `SelectableCard.stories.tsx` | Selected with elevation; one selected default card beside unselected ones        | A lost elevation while selected fails; a changed default ring or border comes back changed for review. Gap: palette and theme-added ring colors have no automated check.                                                                                                                     | `audit:SelectableCard/theming`  |
+| FR4                 | `SelectableCard.test.tsx` touch-press test; `CardPress.a11y.chromium.spec.ts` on `core-selectablecard--single-select`                | Rest; desktop hover and mouse press; touch press                                 | A hover that does not paint over rest, a mouse press that does not paint over hover, or a touch press that does not match the desktop press or fade fails. Gap: the focus outline, and the double indicator on nested controls, have no automated check.                                     | `audit:SelectableCard/design`   |
+| FR5, AR3            | `SelectableCard.test.tsx` disabled tests; `Checkbox.a11y.chromium.spec.ts` `card-disabled` state                                     | Disabled click, Enter, Space                                                     | A toggle while disabled, or a disabled card that leaves keyboard reach, fails. Gap: the half opacity, the removed overlays, and the missing disabled reflection on the target have no automated check.                                                                                       | `audit:SelectableCard/a11y`     |
+| FR2 (nested)        | Shared clickable-container hook tests in other components                                                                            | Card with a nested control or selected text                                      | Gap: no SelectableCard test or story covers nested-control or selection suppression.                                                                                                                                                                                                         | `audit:SelectableCard/behavior` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                        | Consumer anatomy and current target                                              | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                | `audit:SelectableCard/theming`  |
+| AR1, AR2, AR4       | `SelectableCard.test.tsx` checkbox tests; `Checkbox.a11y.test.tsx` and `Checkbox.a11y.chromium.spec.ts` SelectableCard states        | Unchecked, checked, disabled (`card-unchecked`, `card-checked`, `card-disabled`) | A lost checkbox role or name, a wrong checked state, or a disabled card that is not exposed as unavailable or not reachable fails, including at the accessibility tree. Gap: no test asserts that the root adds no role or tab stop, the root focus outline, or the ring winning over hover. | `audit:SelectableCard/a11y`     |
+| FR6, PR1            | Source review                                                                                                                        | Ref; caller props                                                                | Gap: no test asserts ref or passthrough routing, or fails if SelectableCard adds its own listener or timer.                                                                                                                                                                                  | `audit:SelectableCard/behavior` |
+| AR5                 | `Checkbox.a11y.chromium.spec.ts` aborted-press check on the SelectableCard states                                                    | Press that slides off the card before the lift                                   | A toggle after a slide-off lift fails.                                                                                                                                                                                                                                                       | `audit:SelectableCard/a11y`     |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/SelectableCard/SelectableCard.test.tsx

@@ -11,7 +11,12 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {SelectableCard} from './SelectableCard';
-import {hasReleaseFade, readsPressStrength} from '../__tests__/pressState';
+import {
+  afterPaintsPress,
+  hasReleaseFade,
+  pressArmsShadowedByDefault,
+  readsPressStrength,
+} from '../__tests__/pressState';
 
 describe('SelectableCard', () => {
   it('renders children', () => {
@@ -202,5 +207,10 @@ describe('SelectableCard pressed state (touch)', () => {
     expect(hasReleaseFade(card)).toBe(true);
     expect(readsPressStrength(card, '[data-astryx-press="on"]')).toBe(true);
     expect(readsPressStrength(card)).toBe(true);
+    expect(afterPaintsPress(card, '[data-astryx-press="on"]')).toBe(true);
+    expect(afterPaintsPress(card)).toBe(true);
+    // In a layered stylesheet a press arm on a custom property the card also
+    // declares without it never applies.
+    expect(pressArmsShadowedByDefault(card)).toEqual([]);
   });
 });