@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/src/PowerSearch/PowerSearch.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When PowerSearch.tsx changes, update tests to match
  */
 
-import {useState} from 'react';
+import {StrictMode, useState} from 'react';
 import {describe, it, expect, vi, beforeAll, afterAll, afterEach} from 'vitest';
 import {
   render,
@@ -476,6 +476,37 @@ describe('PowerSearch', () => {
       });
     });
 
+    it('does not announce the result count present on mount under StrictMode, only a later change', async () => {
+      // StrictMode replays the mount effects: a mounted-flag guard is reset by
+      // the replay and speaks the initial count unprompted; comparing against
+      // the last announced text does not.
+      const {rerender} = render(
+        <StrictMode>
+          <PowerSearch
+            config={config}
+            filters={[]}
+            onChange={() => {}}
+            resultCount={12}
+          />
+        </StrictMode>,
+      );
+      await new Promise(resolve => setTimeout(resolve, 20));
+      expect(politeRegion()?.textContent ?? '').toBe('');
+      rerender(
+        <StrictMode>
+          <PowerSearch
+            config={config}
+            filters={[]}
+            onChange={() => {}}
+            resultCount={1}
+          />
+        </StrictMode>,
+      );
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('1 result');
+      });
+    });
+
     it('announces "1 result" (singular) for a single match', async () => {
       const {rerender} = render(
         <PowerSearch
@@ -881,6 +912,51 @@ describe('field menu grouping', () => {
   });
 });
 
+describe('field menu highlight under a resting pointer', () => {
+  it('keeps the first field highlighted when the menu opens under the pointer', async () => {
+    const user = userEvent.setup();
+    render(<PowerSearchWrapper config={config} />);
+    const input = screen.getByRole('combobox', {name: 'Search'});
+
+    // Open the field menu from the keyboard; the option that lands under a
+    // resting pointer receives mouseenter but no mousemove.
+    await user.tab();
+    const status = await screen.findByRole('option', {
+      name: 'Status',
+      hidden: true,
+    });
+    const title = screen.getByRole('option', {name: 'Title', hidden: true});
+    expect(input.getAttribute('aria-activedescendant')).toBe(title.id);
+
+    fireEvent.mouseEnter(status);
+    expect(input.getAttribute('aria-activedescendant')).toBe(title.id);
+
+    // Enter acts on the highlighted first field, not the one under the
+    // pointer.
+    await user.keyboard('{Enter}');
+    expect(
+      await screen.findByRole('button', {name: 'Apply', hidden: true}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('combobox', {name: 'Field', hidden: true}),
+    ).toHaveTextContent('Title');
+  });
+
+  it('moves the highlight when the pointer moves over a field', async () => {
+    const user = userEvent.setup();
+    render(<PowerSearchWrapper config={config} />);
+    const input = screen.getByRole('combobox', {name: 'Search'});
+
+    await user.tab();
+    const status = await screen.findByRole('option', {
+      name: 'Status',
+      hidden: true,
+    });
+    fireEvent.mouseMove(status);
+    expect(input.getAttribute('aria-activedescendant')).toBe(status.id);
+  });
+});
+
 describe('field menu after the search source changes', () => {
   it('opens the new field menu on the first click after a config change', async () => {
     const user = userEvent.setup();

package/src/PowerSearch/PowerSearch.tsx

@@ -1057,15 +1057,17 @@ export function PowerSearch({
   // Announce result-count changes to screen readers through a polite live
   // region, mirroring the way Typeahead announces its dropdown result count.
   // The count is otherwise only shown visually and stays silent to assistive
-  // tech. Skip the first run so the count already present on mount isn't
-  // announced unprompted — only user-driven changes are spoken.
+  // tech. Only a change after mount is spoken: the guard compares against the
+  // last announced text rather than a mounted flag, so StrictMode's effect
+  // replay (which resets a flag and would speak the count present on mount
+  // unprompted) announces nothing until the count changes.
   const announce = useAnnounce();
-  const hasMountedRef = useRef(false);
+  const announcedResultCountRef = useRef(resultCountText);
   useEffect(() => {
-    if (!hasMountedRef.current) {
-      hasMountedRef.current = true;
+    if (resultCountText === announcedResultCountRef.current) {
       return;
     }
+    announcedResultCountRef.current = resultCountText;
     if (resultCountText != null) {
       announce(resultCountText);
     }

package/src/ProgressBar/ProgressBar.test.tsx

@@ -10,6 +10,7 @@
 import {describe, it, expect, beforeAll} from 'vitest';
 import {render, screen, waitFor} from '@testing-library/react';
 import {ProgressBar} from './ProgressBar';
+import {getForcedColorsRules} from '../__tests__/forcedColors';
 
 // A labeled mark wraps the tick in a lazily-loaded Tooltip (React.lazy +
 // Suspense). Preload that chunk once so the Tooltip (and its
@@ -838,3 +839,14 @@ describe('ProgressBar theme target names', () => {
     expect(container.querySelector('.astryx-progressbar-mark')).toBeNull();
   });
 });
+
+// jsdom cannot emulate forced colors, so this asserts the compiled rule the
+// status fill relies on (architecture:theme-tokens INV11).
+describe('ProgressBar forced colors', () => {
+  it('keeps a visible boundary on the status fill', () => {
+    render(<ProgressBar value={40} variant="error" label="Upload" />);
+    const css = getForcedColorsRules();
+    expect(css).toContain('outline-style: solid;');
+    expect(css).toContain('outline-color: canvastext;');
+  });
+});

package/src/ProgressBar/ProgressBar.tsx

@@ -237,6 +237,15 @@ const styles = stylex.create({
   },
   fill: {
     height: '100%',
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
     borderRadius: radiusVars['--radius-full'],
     transitionProperty: 'width',
     transitionDuration: durationVars['--duration-medium'],
@@ -244,6 +253,15 @@ const styles = stylex.create({
   },
   indeterminateFill: {
     height: '100%',
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
     width: '40%',
     borderRadius: radiusVars['--radius-full'],
     animationName: {

package/src/ProgressBar/__tests__/ProgressBar.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/progressbar\.|packages/core/src/ProgressBar/|packages/lab/src/CircularProgress/|apps/storybook/stories/ProgressbarA11y)
 
 /**
  * @file ProgressBar.a11y.chromium.spec.ts

package/src/RadioList/RadioList.test.tsx

@@ -16,9 +16,10 @@ import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {
-  hasPressedArm,
   hasReleaseFade,
   readsPressStrength,
+  rulesDeclaredFor,
+  rulesWithSelector,
 } from '../__tests__/pressState';
 import {RadioList} from './RadioList';
 import {RadioListItem} from './RadioListItem';
@@ -884,6 +885,26 @@ describe('forced colors (WCAG 1.4.11)', () => {
   });
 });
 
+/** Does the element's own CSS paint the row's mouse press (`--_radio-row-press`)? */
+function readsRowPress(el: Element): boolean {
+  return rulesDeclaredFor(el).some(rule =>
+    rule.includes('var(--_radio-row-press'),
+  );
+}
+
+/**
+ * Does the row declare the mouse press's paint while pressed, but not while a
+ * nested link or button is the pressed one?
+ */
+function declaresRowPress(el: Element): boolean {
+  return rulesWithSelector(el, ':active').some(
+    rule =>
+      rule.includes('--_radio-row-press:') &&
+      rule.includes('var(--color-overlay-pressed)') &&
+      /:not\(:has\(a:active, ?button:active/.test(rule),
+  );
+}
+
 describe('pressed state', () => {
   it('paints the pressed overlay over the radio indicator while the row is pressed', () => {
     const {container} = render(
@@ -894,10 +915,14 @@ describe('pressed state', () => {
     );
     const circle = container.querySelector('.astryx-radio-indicator');
     const wrapper = circle?.parentElement?.parentElement;
-    if (wrapper == null) {
-      throw new Error('the radio has no indicator wrapper to press');
+    const row = circle?.closest('[data-astryx-pressable]');
+    if (wrapper == null || row == null) {
+      throw new Error('the radio has no pressable row or indicator wrapper');
     }
-    expect(hasPressedArm(wrapper)).toBe(true);
+    // The row declares the mouse press's paint while it is pressed, and the
+    // layer over the circle reads it.
+    expect(declaresRowPress(row)).toBe(true);
+    expect(readsRowPress(wrapper)).toBe(true);
   });
 
   it('does not expose a pressed arm on a disabled radio', () => {
@@ -908,10 +933,12 @@ describe('pressed state', () => {
     );
     const circle = container.querySelector('.astryx-radio-indicator');
     const wrapper = circle?.parentElement?.parentElement;
-    if (wrapper == null) {
-      throw new Error('the radio has no indicator wrapper');
+    const row = wrapper?.closest('.astryx-item');
+    if (wrapper == null || row == null) {
+      throw new Error('the radio has no row or indicator wrapper');
     }
-    expect(hasPressedArm(wrapper)).toBe(false);
+    expect(declaresRowPress(row)).toBe(false);
+    expect(readsRowPress(wrapper)).toBe(false);
   });
 
   it('fades the touch press out from the row, with the overlay reading its strength', () => {

package/src/RadioList/RadioListItem.press.source-build.test.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file RadioListItem.press.source-build.test.mjs
+ * @input Uses Babel, the StyleX plugin as the package stylesheet compiles it,
+ *   and the RadioListItem source
+ * @output Verifies the shipped mouse press reaches the radio circle through an
+ *   inherited custom property, with no `:has()` ancestor scan
+ * @position Regression test for the compiled CSS of the RadioListItem module
+ *
+ * The circle's pressed layer once read the row through
+ * `.layer:where(.row:active:not(:has(...)) *)`. That shape makes the browser
+ * restyle everything under the row on every DOM change. The row now declares
+ * the press's paint under a `:has()` on itself, and the layer reads it.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {transformAsync} from '@babel/core';
+import stylexBabelPlugin from '@stylexjs/babel-plugin';
+import {describe, expect, it} from 'vitest';
+import stylexResolution from '../../../../scripts/stylex-module-resolution.cjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function compiledCss(fileName) {
+  const file = path.join(__dirname, fileName);
+  const result = await transformAsync(await fs.readFile(file, 'utf8'), {
+    babelrc: false,
+    configFile: false,
+    filename: file,
+    presets: [
+      ['@babel/preset-typescript', {isTSX: true, allExtensions: true}],
+      ['@babel/preset-react', {runtime: 'automatic'}],
+    ],
+    plugins: [
+      [
+        stylexBabelPlugin,
+        {
+          dev: false,
+          runtimeInjection: false,
+          genConditionalClasses: true,
+          treeshakeCompensation: true,
+          unstable_moduleResolution: stylexResolution.stylexModuleResolution,
+        },
+      ],
+    ],
+  });
+  return stylexBabelPlugin.processStylexRules(
+    result?.metadata?.stylex ?? [],
+    false,
+  );
+}
+
+/** Every selector in `css`, one per rule. */
+function selectorsOf(css) {
+  return [...css.matchAll(/([^{}]+)\{[^{}]*\}/g)].map(match => match[1].trim());
+}
+
+describe('the shipped RadioListItem mouse press', () => {
+  it('ships no :has() followed by a descendant *', async () => {
+    const selectors = selectorsOf(await compiledCss('RadioListItem.tsx'));
+    expect(
+      selectors.filter(selector => /:has\([^{]*\)[^{,]* \*/.test(selector)),
+    ).toEqual([]);
+  });
+
+  it('keeps the nested-control exclusion on the row itself', async () => {
+    const css = await compiledCss('RadioListItem.tsx');
+    const press = [...css.matchAll(/([^{}]+)\{([^{}]*)\}/g)].filter(match =>
+      match[2].includes('--_radio-row-press:'),
+    );
+    expect(press.length).toBeGreaterThan(0);
+    for (const [, selector] of press) {
+      expect(selector).toMatch(/:active:not\(:has\(a:active/);
+      expect(selector).not.toMatch(/ \*/);
+    }
+  });
+});

package/src/RadioList/RadioListItem.tsx

@@ -38,6 +38,10 @@ import {themeProps} from '../utils/themeProps';
 // that paints it. See interactionOverlay.stylex.ts.
 const pressedOverlayImage = 'var(--_press-paint-image)';
 
+// The mouse press's paint, declared on the row and inherited by the layer
+// over the circle. Internal: not a theme hook.
+const ROW_PRESS = '--_radio-row-press';
+
 const styles = stylex.create({
   radioWrapper: {
     position: 'relative',
@@ -48,8 +52,10 @@ const styles = stylex.create({
     isolation: 'isolate',
   },
   // The row remains the large press target, but nested links and buttons keep
-  // their independent action and do not make the radio appear pressed. This
-  // owner-drawn layer also survives a theme replacing the indicator component.
+  // their independent action and do not make the radio appear pressed: the
+  // row declares the mouse press's paint (`rowStyles.press`) and this layer
+  // reads it. This owner-drawn layer also survives a theme replacing the
+  // indicator component.
   // Two pointers, two press models (see interactionOverlay.stylex.ts): a
   // mouse keeps `:active`; under a coarse pointer that arm is dropped and the
   // touch press controller writes `data-astryx-press` on the row, which this layer
@@ -63,16 +69,7 @@ const styles = stylex.create({
       inset: 0,
       borderRadius: radiusVars['--radius-full'],
       pointerEvents: 'none',
-      backgroundColor: {
-        default: 'transparent',
-        [stylex.when.ancestor(
-          ':active:not(:has(a:active,button:active,[role="button"]:active,[role="link"]:active))',
-          indicatorScope,
-        )]: {
-          default: colorVars['--color-overlay-pressed'],
-          '@media (pointer: coarse)': 'transparent',
-        },
-      },
+      backgroundColor: `var(${ROW_PRESS}, transparent)`,
       // The touch press, as an image layer over the colour: an image change is
       // discrete, so no transition can delay the onset, and the strength the
       // row's `pressedAlpha` arms own (1 while on, 1 → 0 over the release) is
@@ -152,6 +149,22 @@ const rowStyles = stylex.create({
     // circle reads it.
     backgroundImage: 'none',
   },
+  // The mouse press (a finger's lives on `data-astryx-press`): the row is
+  // pressed, but not through a nested link or button, which keep their own
+  // action. The `:has()` is on the row itself and reaches no descendant
+  // selector, so a change inside the row re-checks the row alone; the circle's
+  // layer reads the paint through inheritance rather than a relation that
+  // would restyle everything under the row.
+  press: {
+    [ROW_PRESS]: {
+      default: null,
+      ':active:not(:has(a:active,button:active,[role="button"]:active,[role="link"]:active))':
+        {
+          default: colorVars['--color-overlay-pressed'],
+          '@media (pointer: coarse)': 'transparent',
+        },
+    },
+  },
 });
 
 export interface RadioListItemProps extends BaseProps<HTMLDivElement> {
@@ -387,6 +400,7 @@ export function RadioListItem({
           // styles so it wins within the base layer; a `radio-list-item` theme
           // still overrides it from the higher `astryx-theme` layer.
           rowStyles.root,
+          !isDisabled && rowStyles.press,
           xstyle,
         ] as StyleXStyles
       }

package/src/RadioList/__tests__/RadioGroup.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file RadioGroup.a11y.chromium.spec.ts

package/src/Resizable/__tests__/ResizeHandle.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/window-splitter|internal/a11y-spec/src/harness|packages/core/src/Resizable/|apps/storybook/stories/WindowSplitterA11y)
 
 /**
  * @file ResizeHandle.a11y.chromium.spec.ts

package/src/ScrollableArea/ScrollableArea.spec.md

@@ -75,7 +75,7 @@ shared behavior hook, not the exclusive owner of that behavior.
 | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------- |
 | FR1 | The root MUST remain the one native viewport and receive the public ref, standard container sizing props, and styling inputs through StyleX.                                                                                                                                                                                                                                                                                                   | `spec:AST-025` IR3–IR4           | implemented                         |
 | FR2 | The inner content wrapper MUST be a real normal-flow block box observed with the viewport, use a 100% minimum size, and use max-content inline sizing only when inline scrolling is requested. Children participate in that box rather than the viewport's flex/grid formatting context, and the minimum block size does not create a definite percentage-height basis; structures that must preserve those semantics adopt the hook directly. | `spec:AST-025` FR5–FR6           | implemented                         |
-| FR3 | Native scrollbar behavior MUST remain authoritative; the default thumb uses `--color-neutral`, the track is transparent, and forced colors restore platform presentation.                                                                                                                                                                                                                                                                      | `spec:AST-025` FR15              | implemented                         |
+| FR3 | Native scrollbar behavior MUST remain authoritative; with a fine pointer the default thumb uses `--color-neutral` and the track is transparent, while a coarse primary pointer and forced colors restore platform presentation.                                                                                                                                                                                                                | `spec:AST-025` FR15              | implemented                         |
 | FR4 | Scroll-state container queries MAY enhance descendant stuck/edge presentation, but hook state MUST remain the cross-browser source of truth.                                                                                                                                                                                                                                                                                                   | `spec:AST-025` platform support  | implemented progressively           |
 | FR5 | The content box MUST apply and publish logical padding with edge-over-axis-over-uniform precedence, defaulting every published edge to zero. `isFullBleed` MUST let only the viewport consume inherited inset; nested content continues to read the content box's published values.                                                                                                                                                            | `architecture:container-padding` | implemented                         |
 | FR6 | A fitting viewport MUST use `clip` on both physical axes so it prevents paint overflow without capturing native Sticky. Excess requested-axis geometry MUST activate the writing-mode-resolved `auto`/`hidden` pair. `stickyContainment="always"` MUST explicitly retain that pair while fitting.                                                                                                                                              | `spec:AST-025` FR21              | implemented                         |
@@ -95,6 +95,7 @@ shared behavior hook, not the exclusive owner of that behavior.
 | overflowing                    | named tab stop; per-axis logical edge state                                                             | one or both requested axes |
 | overflow removed while focused | remove future tab stop without moving focus                                                             | current focus remains      |
 | forced colors                  | native platform scrollbar presentation                                                                  | platform rendering         |
+| coarse primary pointer         | native platform scroll indicator                                                                        | platform rendering         |
 
 ### Transformation and precedence order
 
@@ -114,10 +115,10 @@ shared behavior hook, not the exclusive owner of that behavior.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ----------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Viewport         | platform scrollbar with token-colored thumb and transparent track | `spec:AST-025`           | supporting     | FR1, FR3           |
-| Content box      | no independent paint by default                                   | caller content           | structural     | FR2                |
+| Anatomy or state | Design requirement                                                                 | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Viewport         | platform scrollbar; with a fine pointer, token-colored thumb and transparent track | `spec:AST-025`           | supporting     | FR1, FR3           |
+| Content box      | no independent paint by default                                                    | caller content           | structural     | FR2                |
 
 ### Theming anatomy
 

package/src/ScrollableArea/ScrollableArea.test.tsx

@@ -278,6 +278,11 @@ describe('ScrollableArea', () => {
     expect(source).toContain("'@media (forced-colors: active)': 'auto'");
   });
 
+  it("keeps the platform's own scroll indicator on touch screens", () => {
+    const source = stylesSource();
+    expect(source).toContain("'@media (pointer: coarse)': 'auto'");
+  });
+
   it('guards scroll-state query containment as a progressive enhancement', () => {
     const source = stylesSource();
     expect(source).toContain("'@supports (container-type: scroll-state)'");

package/src/ScrollableArea/ScrollableArea.tsx

@@ -52,6 +52,10 @@ const styles = stylex.create({
     WebkitOverflowScrolling: 'touch',
     scrollbarColor: {
       default: `${colorVars['--color-neutral']} transparent`,
+      // Touch screens keep the platform's own scroll indicator, which iOS
+      // shows only while scrolling, as UIScrollView does. A custom colour
+      // turns it into a faint bar that also shows in the gap a pull opens.
+      '@media (pointer: coarse)': 'auto',
       '@media (forced-colors: active)': 'auto',
     },
     scrollbarWidth: 'auto',

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.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([]);
   });
 });