@astryxdesign/core 0.6.2-canary.6203871 → 0.6.2-canary.7cce14f

package/dist/Kbd/Kbd.d.ts

@@ -1,7 +1,7 @@
 /**
  * @file Kbd.tsx
- * @input Uses React, StyleX, theme tokens
- * @output Exports Kbd component and KbdProps
+ * @input Uses React, StyleX, theme tokens, shortcut key names and aliases
+ * @output Exports Kbd component and KbdProps with canonical shortcut labels
  * @position Core implementation; renders styled keyboard shortcut indicators
  *
  * SYNC: When modified, update:
@@ -14,7 +14,9 @@ export interface KbdProps extends BaseProps<HTMLSpanElement> {
     ref?: React.Ref<HTMLSpanElement>;
     /**
      * Keyboard shortcut string. Use "+" to separate keys.
-     * Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape.
+     * Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape,
+     * tab, up, down, left, and right.
+     * Aliases: "esc" for "escape" and "return" for "enter".
      * Use "plus" to render a literal "+" key (e.g. "shift+plus").
      *
      * @example

package/dist/Kbd/Kbd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Kbd.d.ts","sourceRoot":"","sources":["../../src/Kbd/Kbd.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAIlD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA0G5C,MAAM,WAAW,QAAS,SAAQ,SAAS,CAAC,eAAe,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAAC,EAAE,QAAQ,qBAgC3E;yBAhCe,GAAG"}
+{"version":3,"file":"Kbd.d.ts","sourceRoot":"","sources":["../../src/Kbd/Kbd.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAIlD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA+G5C,MAAM,WAAW,QAAS,SAAQ,SAAS,CAAC,eAAe,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC;;;;;;;;;;;;;;OAcG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAAC,EAAE,QAAQ,qBA6C3E;yBA7Ce,GAAG"}

package/dist/Kbd/Kbd.js

@@ -4,8 +4,8 @@
 
 /**
  * @file Kbd.tsx
- * @input Uses React, StyleX, theme tokens
- * @output Exports Kbd component and KbdProps
+ * @input Uses React, StyleX, theme tokens, shortcut key names and aliases
+ * @output Exports Kbd component and KbdProps with canonical shortcut labels
  * @position Core implementation; renders styled keyboard shortcut indicators
  *
  * SYNC: When modified, update:
@@ -35,26 +35,20 @@ const styles = {
  * Note: `mod` is not in this map — it resolves dynamically via platform
  * detection inside the component.
  */
-const KEY_DISPLAY = {
-  ctrl: '\u2303',
-  // ⌃
-  alt: '\u2325',
-  // ⌥
-  shift: '\u21E7',
-  // ⇧
-  enter: '\u21B5',
-  // ↵
-  backspace: '\u232B',
-  // ⌫
-  escape: 'Esc',
-  tab: '\u21E5',
-  // ⇥
-  up: '\u2191',
-  down: '\u2193',
-  left: '\u2190',
-  right: '\u2192',
-  plus: '+'
-};
+const KEY_DISPLAY = new Map([['ctrl', '\u2303'],
+// ⌃
+['alt', '\u2325'],
+// ⌥
+['shift', '\u21E7'],
+// ⇧
+['enter', '\u21B5'],
+// ↵
+['backspace', '\u232B'],
+// ⌫
+['escape', 'Esc'], ['tab', '\u21E5'],
+// ⇥
+['up', '\u2191'], ['down', '\u2193'], ['left', '\u2190'], ['right', '\u2192'], ['plus', '+']]);
+const KBD_KEY_ALIASES = new Map([['esc', 'escape'], ['return', 'enter']]);
 
 /**
  * Resolves a key name to its display string. Handles the platform-aware
@@ -65,7 +59,7 @@ function getKeyDisplay(key, isMac) {
   if (key === 'mod') {
     return isMac ? '\u2318' : 'Ctrl';
   }
-  return KEY_DISPLAY[key] ?? key.toUpperCase();
+  return KEY_DISPLAY.get(key) ?? key.toUpperCase();
 }
 
 /**
@@ -73,25 +67,12 @@ function getKeyDisplay(key, isMac) {
  * (⌘, ⇧, ↵, …) that assistive tech cannot announce meaningfully, so the
  * accessible name for the shortcut is built from these words instead.
  */
-const KEY_LABEL = {
-  ctrl: 'Control',
-  alt: 'Alt',
-  shift: 'Shift',
-  enter: 'Enter',
-  backspace: 'Backspace',
-  escape: 'Escape',
-  tab: 'Tab',
-  up: 'Up arrow',
-  down: 'Down arrow',
-  left: 'Left arrow',
-  right: 'Right arrow',
-  plus: 'Plus'
-};
+const KEY_LABEL = new Map([['ctrl', 'Control'], ['alt', 'Alt'], ['shift', 'Shift'], ['enter', 'Enter'], ['backspace', 'Backspace'], ['escape', 'Escape'], ['tab', 'Tab'], ['up', 'Up arrow'], ['down', 'Down arrow'], ['left', 'Left arrow'], ['right', 'Right arrow'], ['plus', 'Plus']]);
 function getKeyLabel(key, isMac) {
   if (key === 'mod') {
     return isMac ? 'Command' : 'Control';
   }
-  return KEY_LABEL[key] ?? key.toUpperCase();
+  return KEY_LABEL.get(key) ?? key.toUpperCase();
 }
 function subscribeToPlatformChanges() {
   return () => {};
@@ -123,24 +104,37 @@ export function Kbd({
   ...rest
 }) {
   const isMac = useSyncExternalStore(subscribeToPlatformChanges, isApplePlatform, getServerPlatformSnapshot);
-  const parts = keys.split('+').map(key => key.trim().toLowerCase());
+  const keyOccurrences = new Map();
+  const parts = keys.split('+').map(key => key.trim().toLowerCase()).map(sourceKey => {
+    const occurrence = keyOccurrences.get(sourceKey) ?? 0;
+    keyOccurrences.set(sourceKey, occurrence + 1);
+    return {
+      key: KBD_KEY_ALIASES.get(sourceKey) ?? sourceKey,
+      reactKey: `${sourceKey}:${occurrence}`
+    };
+  });
 
   // Screen-reader name: the joined spoken labels (e.g. "Command + K"), since
   // the visual glyphs below are announced meaninglessly by assistive tech.
-  const accessibleName = parts.map(key => getKeyLabel(key, isMac)).join(' + ');
+  const accessibleName = parts.map(({
+    key
+  }) => getKeyLabel(key, isMac)).join(' + ');
   return /*#__PURE__*/_jsx("span", {
     ...rest,
     ref: ref,
     role: "img",
     "aria-label": accessibleName,
     ...mergeProps(themeProps('kbd'), stylex.props(styles.wrapper, xstyle), className, style),
-    children: parts.map(key => /*#__PURE__*/_jsx("kbd", {
+    children: parts.map(({
+      key,
+      reactKey
+    }) => /*#__PURE__*/_jsx("kbd", {
       "aria-hidden": "true",
       ...{
         className: "x3nfvp2 x6s0dn4 xl56j7k x16asifk x1grt7ep x7a5moj xx3sua9 x17x4s8c xlxy82 x1q0q8m5 xib2hle xv1l7n4 x9ynric x141an7d x1e4wzip x1ltkj2j x87ps6o"
       },
       children: getKeyDisplay(key, isMac)
-    }, key))
+    }, reactKey))
   });
 }
 Kbd.displayName = 'Kbd';

package/dist/SideNav/SideNav.d.ts

@@ -7,7 +7,8 @@
  * Sidebar navigation container with five zones: header + topContent (sticky together),
  * children (scrollable), footer, and footerIcons (sticky bottom).
  *
- * Supports optional resize via drag handle at the inline-end edge.
+ * Supports optional resize via a drag handle at the inline-end edge. The
+ * resizable wrapper clips handle overflow while keeping its focus ring inside.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/SideNav/SideNav.doc.mjs

package/dist/SideNav/SideNav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SideNav.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNav.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAA2C,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACrC,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,2BAA2B,CAAC;AA4O/D,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC1D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;IAEvD;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;OAEG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IAEtC;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,wBAAwB,CAAC;CAClD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,EACtB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,MAAM,EACN,WAAW,EACX,WAAmB,EACnB,SAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,SAAS,EACT,GAAG,KAAK,EACT,EAAE,YAAY,+BA0Qd;yBAzRe,OAAO"}
+{"version":3,"file":"SideNav.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNav.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAA2C,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACrC,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,2BAA2B,CAAC;AAsP/D,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC1D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;IAEvD;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;OAEG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IAEtC;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,wBAAwB,CAAC;CAClD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,EACtB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,MAAM,EACN,WAAW,EACX,WAAmB,EACnB,SAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,SAAS,EACT,GAAG,KAAK,EACT,EAAE,YAAY,+BA2Qd;yBA1Re,OAAO"}

package/dist/SideNav/SideNav.js

@@ -11,7 +11,8 @@
  * Sidebar navigation container with five zones: header + topContent (sticky together),
  * children (scrollable), footer, and footerIcons (sticky bottom).
  *
- * Supports optional resize via drag handle at the inline-end edge.
+ * Supports optional resize via a drag handle at the inline-end edge. The
+ * resizable wrapper clips handle overflow while keeping its focus ring inside.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/SideNav/SideNav.doc.mjs
@@ -23,7 +24,7 @@
 import { useCallback, useImperativeHandle, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
-import { spacingVars } from "../theme/tokens.stylex.js";
+import { focusVars, spacingVars } from "../theme/tokens.stylex.js";
 import { mergeProps } from "../utils/index.js";
 import { SideNavCollapseContext } from "./SideNavCollapseContext.js";
 import { SideNavCollapseButton } from "./SideNavCollapseButton.js";
@@ -100,6 +101,10 @@ const styles = {
     kzqmXN: "xhgvbfk",
     $$css: true
   },
+  resizableHandle: {
+    kInvED: "x1wfwxd8 x1l5jwag",
+    $$css: true
+  },
   topbar: {
     k1xSpc: "x78zum5",
     kXwgrk: "x1q0g3np",
@@ -400,7 +405,7 @@ export function SideNav({
   // the panel's overflow: clip bounds.
   const content = showResizeHandle ? /*#__PURE__*/_jsxs("div", {
     ...{
-      className: "x1n2onr6 x78zum5 x2lah0s x5yr21d"
+      className: "x1n2onr6 x78zum5 x2lah0s x5yr21d x7giv3"
     },
     children: [navElement, /*#__PURE__*/_jsx(ResizeHandle, {
       "data-testid": "astryx-sidenav-resize-handle",
@@ -408,6 +413,7 @@ export function SideNav({
       position: "overlay",
       pillPlacement: "end",
       isAlwaysVisible: false,
+      xstyle: styles.resizableHandle,
       resizable: resizableHook.props,
       label: t('@astryx.sideNav.resizeSidebar')
     })]

package/dist/astryx.css

@@ -1365,6 +1365,7 @@
   .xx47ajj:focus-visible:not(#\#):not(#\#):not(#\#){outline-color:var(--focus-outline-color)}
   .x7s97pk:focus-visible:not(#\#):not(#\#):not(#\#){outline-offset:2px}
   .x1nw7mhf:focus-visible:not(#\#):not(#\#):not(#\#){outline-offset:calc(-1 * var(--focus-outline-width))}
+  .x1l5jwag:focus-visible:not(#\#):not(#\#):not(#\#){outline-offset:calc(0px - var(--focus-outline-width))}
   .x13aywxo:focus-visible:not(#\#):not(#\#):not(#\#){outline-offset:var(--button-focus-offset)}
   .x1vwwbsn:focus-visible:not(#\#):not(#\#):not(#\#){outline-offset:var(--focus-outline-offset)}
   .xwz5zln.xwz5zln:where(.x1iwu4tg:has(:focus-visible) *):not(#\#):not(#\#):not(#\#){outline-offset:var(--focus-outline-offset)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.6.2-canary.6203871",
+  "version": "0.6.2-canary.7cce14f",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -672,8 +672,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.6.2-canary.6203871",
-    "@astryxdesign/cli": "0.6.2-canary.6203871",
+    "@astryxdesign/a11y-spec": "0.6.2-canary.7cce14f",
+    "@astryxdesign/cli": "0.6.2-canary.7cce14f",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

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

@@ -21,7 +21,13 @@
  *   ./Button.a11y.known-failures.ts, both shared with the jsdom lane.
  */
 
-import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
 import {
   BUTTON_PATTERN,
   blockingResults,
@@ -93,6 +99,14 @@ async function activationsOn(page: Page): Promise<number> {
   return Number(raw ?? '0');
 }
 
+function pointerTargetFor(
+  page: Page,
+  state: ButtonBindingRow,
+): Locator | undefined {
+  const selector = (state as ButtonBindingState).pointerTargetSelector;
+  return selector == null ? undefined : page.locator(selector).first();
+}
+
 async function runState(
   page: Page,
   cdp: CDPSession,
@@ -111,6 +125,7 @@ async function runState(
       return createChromiumHarness({
         page,
         subject: page.locator('#storybook-root').getByRole('button').first(),
+        pointerTarget: pointerTargetFor(page, state),
         cdp,
       });
     },
@@ -306,6 +321,7 @@ test('every expectation is exercised by at least one bound state', async ({
               .locator('#storybook-root')
               .getByRole('button')
               .first(),
+            pointerTarget: pointerTargetFor(page, state),
             cdp,
           });
         },

package/src/Button/__tests__/Button.a11y.known-failures.ts

@@ -83,33 +83,4 @@ export const BUTTON_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
     userImpact: 'The same, from an icon button.',
     reason: 'Inherited from Button, as above.',
   },
-
-  // ---- ClickableCard's role-bearing element cannot be clicked -------------
-  {
-    expectation: 'button.action.survives-an-aborted-press',
-    binding: 'ClickableCard',
-    state: 'clickable-card',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'a pointer press cannot land on this control: something else is on top of it at its own centre, so there is no press here to abort',
-    standardsReference: 'WCAG 2.2 2.5.2 Pointer Cancellation (Level A)',
-    userImpact:
-      'The same defect seen from the other side: pointer cancellation cannot be demonstrated on a control no pointer press can land on. Recorded rather than reported green — a serene pass here would claim an outcome nobody observed.',
-    reason:
-      'Same cause as the record above. It is a second record rather than a wider one because a known failure names exactly one outcome, and these two would be fixed and verified separately.',
-  },
-  {
-    expectation: 'button.action.runs-on-pointer',
-    binding: 'ClickableCard',
-    state: 'clickable-card',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'a pointer could not reach this control within 2000ms: the browser never found it visible, stable, and able to receive a pointer event. Something is covering it, or it is clipped to nothing.',
-    standardsReference:
-      'Current Astryx buttons family FR2 and WAI-ARIA APG Button operability requirement; supports WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
-    userImpact:
-      "Anyone whose tooling acts on the accessible object rather than on pixels — a speech-input user saying the card's name, or assistive technology dispatching a click at the element it is told is the button — aims at a 1×1 control the card's own content paints over. A sighted mouse user is unaffected: they click the card surface, which handles it.",
-    reason:
-      'ClickableCard deliberately splits the surface that takes the click from the hidden button that carries the role and name. Reconciling the two is a design-system decision, not a change this contract should make.',
-  },
 ];

package/src/Button/__tests__/Button.a11y.renders.tsx

@@ -88,12 +88,19 @@ export const BUTTON_STATE_RENDERS: Record<ButtonStateId, StateRender> = {
   ),
 
   'clickable-card': activate => (
-    <ClickableCard label="Open billing settings" onClick={activate}>
+    <ClickableCard
+      data-a11y-pointer-target
+      label="Open billing settings"
+      onClick={activate}>
       <div>Billing</div>
     </ClickableCard>
   ),
   'clickable-card-disabled': activate => (
-    <ClickableCard label="Open billing settings" isDisabled onClick={activate}>
+    <ClickableCard
+      data-a11y-pointer-target
+      label="Open billing settings"
+      isDisabled
+      onClick={activate}>
       <div>Billing</div>
     </ClickableCard>
   ),

package/src/Button/__tests__/Button.a11y.states.ts

@@ -92,6 +92,13 @@ export interface ButtonBindingState {
    * typo here is reported as a stale inventory, not as a standards failure.
    */
   readonly visibleLabel: string | null;
+  /**
+   * The surface that receives pointer input when it is not the role-bearing
+   * element. ClickableCard keeps its button/link hidden for role, name, and
+   * keyboard focus, and takes the pointer on the card surface; a binding that
+   * aimed the pointer at the hidden control would be testing the wrong surface.
+   */
+  readonly pointerTargetSelector?: string;
   /** The checked-in Storybook story the Chromium lane drives. */
   readonly storyId: string;
   /**
@@ -220,6 +227,7 @@ export const BUTTON_BINDING_STATES = [
       "a card whose whole surface performs an action, through the hidden button that carries the card's role and name",
     facts: facts(),
     visibleLabel: null,
+    pointerTargetSelector: '[data-a11y-pointer-target]',
     storyId: 'a11y-button-pattern--clickable-card-default',
   },
   {
@@ -228,6 +236,7 @@ export const BUTTON_BINDING_STATES = [
     summary: 'a disabled action card',
     facts: facts({operable: false, focusable: false, unavailable: true}),
     visibleLabel: null,
+    pointerTargetSelector: '[data-a11y-pointer-target]',
     storyId: 'a11y-button-pattern--clickable-card-disabled',
   },
 

package/src/ClickableCard/ClickableCard.test.tsx

@@ -2,6 +2,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {ClickableCard} from './ClickableCard';
 
 describe('ClickableCard', () => {
@@ -47,6 +48,47 @@ describe('ClickableCard', () => {
     expect(handleClick).toHaveBeenCalledTimes(1);
   });
 
+  it('calls onClick once when the accessible control itself is clicked', () => {
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleClick}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    // Pointer activation aimed at the element carrying the role — what
+    // speech input, assistive technology, and automation dispatch.
+    fireEvent.click(screen.getByRole('button', {name: 'Test card'}));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes the card surface as currentTarget for surface clicks', () => {
+    const seen: EventTarget[] = [];
+    render(
+      <ClickableCard
+        label="Test card"
+        onClick={e => seen.push(e.currentTarget)}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    fireEvent.click(screen.getByText('Content'));
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toBe(screen.getByText('Content').parentElement);
+  });
+
+  it('calls onClick exactly once when the surface of an href card is clicked without preventDefault', () => {
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Nav card" href="/settings" onClick={handleClick}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    // The container hook proxies the surface click to the link with
+    // `link.click()`; that synthetic click bubbles back through the card and
+    // must not run the consumer callback a second time.
+    fireEvent.click(screen.getByText('Content'));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
   it('does NOT call onClick when a nested button is clicked', () => {
     const handleCardClick = vi.fn();
     const handleButtonClick = vi.fn();
@@ -86,25 +128,80 @@ describe('ClickableCard', () => {
     expect(link).toHaveAttribute('target', '_blank');
   });
 
-  it('disabled button is disabled', () => {
+  it('disabled button is disabled and the surface runs nothing', () => {
     const handleClick = vi.fn();
     render(
       <ClickableCard label="Disabled" onClick={handleClick} isDisabled>
-        Content
+        <span>Content</span>
       </ClickableCard>,
     );
     const button = screen.getByRole('button', {name: 'Disabled'});
     expect(button).toBeDisabled();
+    fireEvent.click(screen.getByText('Content'));
+    fireEvent.click(button);
+    expect(handleClick).not.toHaveBeenCalled();
   });
 
-  it('disabled link has aria-disabled', () => {
+  it('disabled link has aria-disabled, leaves the tab order, and the surface runs nothing', () => {
+    const handleClick = vi.fn();
     render(
-      <ClickableCard label="Disabled link" href="/settings" isDisabled>
-        Content
+      <ClickableCard
+        label="Disabled link"
+        href="/settings"
+        onClick={handleClick}
+        isDisabled>
+        <span>Content</span>
       </ClickableCard>,
     );
     const link = screen.getByRole('link', {name: 'Disabled link'});
     expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).toHaveAttribute('tabindex', '-1');
+    fireEvent.click(screen.getByText('Content'));
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('runs onClick once from the keyboard via the hidden button', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleClick}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    await user.tab();
+    expect(screen.getByRole('button', {name: 'Test card'})).toHaveFocus();
+    await user.keyboard('{Enter}');
+    await user.keyboard(' ');
+    expect(handleClick).toHaveBeenCalledTimes(2);
+  });
+
+  it('does NOT call onClick when a nested input is clicked', () => {
+    const handleCardClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleCardClick}>
+        <input aria-label="Quantity" readOnly value="1" />
+      </ClickableCard>,
+    );
+    fireEvent.click(screen.getByRole('textbox', {name: 'Quantity'}));
+    expect(handleCardClick).not.toHaveBeenCalled();
+  });
+
+  it('does NOT call onClick when text inside the card is selected', () => {
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleClick}>
+        <span>Selectable body text</span>
+      </ClickableCard>,
+    );
+    const text = screen.getByText('Selectable body text');
+    const range = document.createRange();
+    range.selectNodeContents(text);
+    const selection = document.getSelection()!;
+    selection.removeAllRanges();
+    selection.addRange(range);
+    fireEvent.click(text);
+    expect(handleClick).not.toHaveBeenCalled();
+    selection.removeAllRanges();
   });
 
   describe('elevation', () => {

package/src/Kbd/Kbd.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
       name: 'keys',
       type: 'string',
       description:
-        'Keyboard shortcut string. Use "+" to separate keys. Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right.',
+        'Keyboard shortcut string. Use "+" to separate keys. Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right, plus. Aliases: esc for escape and return for enter.',
       required: true,
     },
     {
@@ -72,7 +72,7 @@ export const docsZh = {
       name: 'keys',
       type: 'string',
       description:
-        '键盘快捷键字符串。使用 "+" 分隔各按键。特殊按键：mod（Mac 上为 Cmd）、ctrl、alt、shift、enter、backspace、escape、tab、up、down、left、right。',
+        '键盘快捷键字符串。使用 "+" 分隔各按键。特殊按键：mod（Mac 上为 Cmd）、ctrl、alt、shift、enter、backspace、escape、tab、up、down、left、right、plus。别名：esc 等同于 escape，return 等同于 enter。',
       required: true,
     },
     {
@@ -122,7 +122,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    keys: 'Shortcut string. "+" separates keys. Special: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right.',
+    keys: 'Shortcut string. "+" separates keys. Special: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right, plus. Aliases: esc for escape, return for enter.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
     className: 'CSS class for root element. Prefer xstyle; className for non-StyleX integration.',
     style: 'Inline styles for root element. Prefer xstyle; inline styles bypass StyleX optimization.',

package/src/Kbd/Kbd.test.tsx

@@ -10,13 +10,14 @@
  */
 
 import {render, screen} from '@testing-library/react';
-import {describe, it, expect, afterEach} from 'vitest';
+import {describe, it, expect, afterEach, vi} from 'vitest';
 import {Kbd} from './Kbd';
 
 describe('Kbd', () => {
   const originalPlatform = navigator.platform;
 
   afterEach(() => {
+    vi.restoreAllMocks();
     // Restore platform after any test that spoofs it \u2014 ensures no
     // test pollution even if an assertion fails mid-test.
     Object.defineProperty(navigator, 'platform', {
@@ -72,6 +73,61 @@ describe('Kbd', () => {
     expect(screen.getByText('Esc')).toBeInTheDocument();
   });
 
+  it.each([
+    {alias: 'esc', display: 'Esc', label: 'Escape'},
+    {alias: 'return', display: '\u21B5', label: 'Enter'},
+  ])('normalizes the $alias key alias', ({alias, display, label}) => {
+    render(<Kbd keys={alias} />);
+    expect(screen.getByText(display)).toBeInTheDocument();
+    expect(screen.getByRole('img')).toHaveAttribute('aria-label', label);
+  });
+
+  it.each([
+    {alias: 'esc', canonical: 'escape'},
+    {alias: 'return', canonical: 'enter'},
+  ])('$alias renders identically to $canonical', ({alias, canonical}) => {
+    const {container, rerender} = render(<Kbd keys={canonical} />);
+    const text = container.textContent;
+    const label = screen.getByRole('img').getAttribute('aria-label');
+    rerender(<Kbd keys={alias} />);
+    expect(container.textContent).toBe(text);
+    expect(screen.getByRole('img').getAttribute('aria-label')).toBe(label);
+  });
+
+  it.each([
+    {keys: 'ctrl + ESC', display: 'Esc', label: 'Control + Escape'},
+    {keys: 'shift + RETURN', display: '\u21B5', label: 'Shift + Enter'},
+  ])('normalizes aliases inside the $keys combo', ({keys, display, label}) => {
+    render(<Kbd keys={keys} />);
+    expect(screen.getByText(display)).toBeInTheDocument();
+    expect(screen.getByRole('img')).toHaveAttribute('aria-label', label);
+  });
+
+  it('keeps child keys unique after alias normalization', () => {
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => {});
+    const {container} = render(
+      <Kbd keys="escape+esc+ESC+enter+return+return" />,
+    );
+    expect(consoleError).not.toHaveBeenCalled();
+    expect(
+      Array.from(container.querySelectorAll('kbd'), key => key.textContent),
+    ).toEqual(['Esc', 'Esc', 'Esc', '↵', '↵', '↵']);
+  });
+
+  it.each(['constructor', '__proto__'])(
+    'renders the unknown %s key without consulting object prototypes',
+    key => {
+      render(<Kbd keys={key} />);
+      expect(screen.getByText(key.toUpperCase())).toBeInTheDocument();
+      expect(screen.getByRole('img')).toHaveAttribute(
+        'aria-label',
+        key.toUpperCase(),
+      );
+    },
+  );
+
   it('exposes a spoken accessible name and hides the glyphs (obs-1)', () => {
     render(<Kbd keys="mod+shift+k" />);
     // The wrapper carries a screen-reader name built from spoken key labels

package/src/Kbd/Kbd.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file Kbd.tsx
- * @input Uses React, StyleX, theme tokens
- * @output Exports Kbd component and KbdProps
+ * @input Uses React, StyleX, theme tokens, shortcut key names and aliases
+ * @output Exports Kbd component and KbdProps with canonical shortcut labels
  * @position Core implementation; renders styled keyboard shortcut indicators
  *
  * SYNC: When modified, update:
@@ -61,20 +61,25 @@ const styles = stylex.create({
  * Note: `mod` is not in this map — it resolves dynamically via platform
  * detection inside the component.
  */
-const KEY_DISPLAY: Record<string, string> = {
-  ctrl: '\u2303', // ⌃
-  alt: '\u2325', // ⌥
-  shift: '\u21E7', // ⇧
-  enter: '\u21B5', // ↵
-  backspace: '\u232B', // ⌫
-  escape: 'Esc',
-  tab: '\u21E5', // ⇥
-  up: '\u2191',
-  down: '\u2193',
-  left: '\u2190',
-  right: '\u2192',
-  plus: '+',
-};
+const KEY_DISPLAY = new Map<string, string>([
+  ['ctrl', '\u2303'], // ⌃
+  ['alt', '\u2325'], // ⌥
+  ['shift', '\u21E7'], // ⇧
+  ['enter', '\u21B5'], // ↵
+  ['backspace', '\u232B'], // ⌫
+  ['escape', 'Esc'],
+  ['tab', '\u21E5'], // ⇥
+  ['up', '\u2191'],
+  ['down', '\u2193'],
+  ['left', '\u2190'],
+  ['right', '\u2192'],
+  ['plus', '+'],
+]);
+
+const KBD_KEY_ALIASES = new Map<string, string>([
+  ['esc', 'escape'],
+  ['return', 'enter'],
+]);
 
 /**
  * Resolves a key name to its display string. Handles the platform-aware
@@ -85,7 +90,7 @@ function getKeyDisplay(key: string, isMac: boolean): string {
   if (key === 'mod') {
     return isMac ? '\u2318' : 'Ctrl';
   }
-  return KEY_DISPLAY[key] ?? key.toUpperCase();
+  return KEY_DISPLAY.get(key) ?? key.toUpperCase();
 }
 
 /**
@@ -93,26 +98,26 @@ function getKeyDisplay(key: string, isMac: boolean): string {
  * (⌘, ⇧, ↵, …) that assistive tech cannot announce meaningfully, so the
  * accessible name for the shortcut is built from these words instead.
  */
-const KEY_LABEL: Record<string, string> = {
-  ctrl: 'Control',
-  alt: 'Alt',
-  shift: 'Shift',
-  enter: 'Enter',
-  backspace: 'Backspace',
-  escape: 'Escape',
-  tab: 'Tab',
-  up: 'Up arrow',
-  down: 'Down arrow',
-  left: 'Left arrow',
-  right: 'Right arrow',
-  plus: 'Plus',
-};
+const KEY_LABEL = new Map<string, string>([
+  ['ctrl', 'Control'],
+  ['alt', 'Alt'],
+  ['shift', 'Shift'],
+  ['enter', 'Enter'],
+  ['backspace', 'Backspace'],
+  ['escape', 'Escape'],
+  ['tab', 'Tab'],
+  ['up', 'Up arrow'],
+  ['down', 'Down arrow'],
+  ['left', 'Left arrow'],
+  ['right', 'Right arrow'],
+  ['plus', 'Plus'],
+]);
 
 function getKeyLabel(key: string, isMac: boolean): string {
   if (key === 'mod') {
     return isMac ? 'Command' : 'Control';
   }
-  return KEY_LABEL[key] ?? key.toUpperCase();
+  return KEY_LABEL.get(key) ?? key.toUpperCase();
 }
 
 function subscribeToPlatformChanges(): () => void {
@@ -127,7 +132,9 @@ export interface KbdProps extends BaseProps<HTMLSpanElement> {
   ref?: React.Ref<HTMLSpanElement>;
   /**
    * Keyboard shortcut string. Use "+" to separate keys.
-   * Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape.
+   * Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape,
+   * tab, up, down, left, and right.
+   * Aliases: "esc" for "escape" and "return" for "enter".
    * Use "plus" to render a literal "+" key (e.g. "shift+plus").
    *
    * @example
@@ -163,11 +170,24 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
     getServerPlatformSnapshot,
   );
 
-  const parts = keys.split('+').map(key => key.trim().toLowerCase());
+  const keyOccurrences = new Map<string, number>();
+  const parts = keys
+    .split('+')
+    .map(key => key.trim().toLowerCase())
+    .map(sourceKey => {
+      const occurrence = keyOccurrences.get(sourceKey) ?? 0;
+      keyOccurrences.set(sourceKey, occurrence + 1);
+      return {
+        key: KBD_KEY_ALIASES.get(sourceKey) ?? sourceKey,
+        reactKey: `${sourceKey}:${occurrence}`,
+      };
+    });
 
   // Screen-reader name: the joined spoken labels (e.g. "Command + K"), since
   // the visual glyphs below are announced meaninglessly by assistive tech.
-  const accessibleName = parts.map(key => getKeyLabel(key, isMac)).join(' + ');
+  const accessibleName = parts
+    .map(({key}) => getKeyLabel(key, isMac))
+    .join(' + ');
 
   return (
     <span
@@ -181,8 +201,8 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
         className,
         style,
       )}>
-      {parts.map(key => (
-        <kbd key={key} aria-hidden="true" {...stylex.props(styles.kbd)}>
+      {parts.map(({key, reactKey}) => (
+        <kbd key={reactKey} aria-hidden="true" {...stylex.props(styles.kbd)}>
           {getKeyDisplay(key, isMac)}
         </kbd>
       ))}

package/src/SideNav/SideNav.doc.mjs

@@ -25,7 +25,7 @@ export const docs = {
       {className: 'astryx-side-nav-section'},
     ],
   },
-  description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode.',
+  description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible and resizable modes.',
   props: [
     {
       name: 'header',

package/src/SideNav/SideNav.test.tsx

@@ -989,6 +989,16 @@ describe('SideNav resizable', () => {
     ).toBeInTheDocument();
   });
 
+  it('clips the overlay drag handle within the resizable nav bounds', () => {
+    render(<SideNav resizable>Content</SideNav>);
+    const nav = screen.getByRole('navigation');
+    const container = nav.parentElement;
+    const handle = screen.getByTestId('astryx-sidenav-resize-handle');
+
+    expect(container).toContainElement(handle);
+    expect(getComputedStyle(container!).overflow).toBe('clip');
+  });
+
   it('does not render drag handle without resizable', () => {
     render(<SideNav>Content</SideNav>);
     expect(

package/src/SideNav/SideNav.tsx

@@ -11,7 +11,8 @@
  * Sidebar navigation container with five zones: header + topContent (sticky together),
  * children (scrollable), footer, and footerIcons (sticky bottom).
  *
- * Supports optional resize via drag handle at the inline-end edge.
+ * Supports optional resize via a drag handle at the inline-end edge. The
+ * resizable wrapper clips handle overflow while keeping its focus ring inside.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/SideNav/SideNav.doc.mjs
@@ -25,7 +26,7 @@ import {useCallback, useImperativeHandle, useRef, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
-import {spacingVars} from '../theme/tokens.stylex';
+import {focusVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {
   SideNavCollapseContext,
@@ -241,6 +242,16 @@ const styles = stylex.create({
     display: 'flex',
     flexShrink: 0,
     height: '100%',
+    overflow: 'clip',
+  },
+  resizableHandle: {
+    // Keep the shared ring inside the clipping boundary. The wrapper cannot
+    // use overflow-clip-margin: that paint allowance also contributes the
+    // overlay's half-pixel spill to AppShell's scrollable overflow.
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': `calc(0px - ${focusVars['--focus-outline-width']})`,
+    },
   },
   // Topbar mode — horizontal layout for mobile top bar
   topbar: {
@@ -658,6 +669,7 @@ export function SideNav({
         position="overlay"
         pillPlacement="end"
         isAlwaysVisible={false}
+        xstyle={styles.resizableHandle}
         resizable={resizableHook.props}
         label={t('@astryx.sideNav.resizeSidebar')}
       />