@astryxdesign/core 0.6.2-canary.bfee8a4 → 0.6.2-canary.c8d5849

package/src/Collapsible/Collapsible.doc.mjs

@@ -82,6 +82,17 @@ export const docs = {
     {name: 'CollapsibleGroup'},
   ],
   usage: {
+    accessibility: [
+      {
+        name: 'Trigger label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Pointer down'],
+        description:
+          'The trigger text must have at least 4.5:1 contrast with the surface behind it. For Pointer down, measure against the pressed overlay the trigger row paints while it is pressed.',
+      },
+    ],
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior. For custom collapsible components, use the `useCollapsible` hook directly (`astryx hook useCollapsible`).',
     bestPractices: [
       { guidance: true, description: 'Use hasDividers on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.' },

package/src/Collapsible/Collapsible.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {Collapsible} from './Collapsible';
 import {CollapsibleGroup} from './CollapsibleGroup';
 
@@ -615,3 +616,23 @@ describe('Collapsible', () => {
     });
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay on the trigger row while it is pressed', () => {
+    render(
+      <Collapsible trigger="Details">
+        <p>Body</p>
+      </Collapsible>,
+    );
+    expect(hasPressedArm(screen.getByRole('button'))).toBe(true);
+  });
+
+  it('does not press a disabled trigger', () => {
+    render(
+      <Collapsible trigger="Details" isDisabled>
+        <p>Body</p>
+      </Collapsible>,
+    );
+    expect(hasPressedArm(screen.getByRole('button'))).toBe(false);
+  });
+});

package/src/Collapsible/Collapsible.tsx

@@ -48,6 +48,7 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 
 const styles = stylex.create({
   root: {
@@ -411,6 +412,10 @@ export function Collapsible({
           focusOutlineProps.focusVisible(
             styles.trigger,
             density != null && triggerDensity[density],
+            // The system's pressed overlay on the disclosure row. The trigger
+            // has no hover surface of its own, so this is the one background
+            // it paints, and only while it is pressed.
+            !isDisabled && interactionOverlayStyles.pressedBackgroundColor,
             isDisabled && styles.triggerDisabled,
           ),
         )}>

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -73,9 +73,14 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     color: colorVars['--color-text-primary'],
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     padding: 0,

package/src/ComplexSelector/ComplexSelector.tsx

@@ -65,9 +65,14 @@ const styles = stylex.create({
     paddingBlock: spacingVars['--spacing-2'],
     paddingInline: spacingVars['--spacing-3'],
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-label-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-label-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateInput/DateInput.tsx

@@ -99,9 +99,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateInput/NativeDateField.tsx

@@ -100,10 +100,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
-    // Below 16px iOS zooms the page when the field takes focus.
+    // Below 16px iOS zooms the page when the field takes focus. Only iOS
+    // WebKit implements -webkit-touch-callout, so the coarse-pointer floor is
+    // keyed to iOS alone.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],
@@ -112,11 +116,20 @@ const styles = stylex.create({
     // A date control's intrinsic height comes from its inner edit fields, not
     // from `line-height`, so it renders ~2px taller than a text input and its
     // value sits off the shared baseline inside the same flex row. One line
-    // box is exactly what the text field occupies.
-    height: stylex.firstThatWorks(
-      '1lh',
-      `calc(max(1rem, ${typeScaleVars['--text-body-size']}) * ${typeScaleVars['--text-body-leading']})`,
-    ),
+    // box is exactly what the text field occupies. The calc fallback mirrors
+    // the iOS-only floor above; browsers with `1lh` track it for free.
+    height: {
+      default: stylex.firstThatWorks(
+        '1lh',
+        `calc(${typeScaleVars['--text-body-size']} * ${typeScaleVars['--text-body-leading']})`,
+      ),
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': stylex.firstThatWorks(
+          '1lh',
+          `calc(max(1rem, ${typeScaleVars['--text-body-size']}) * ${typeScaleVars['--text-body-leading']})`,
+        ),
+      },
+    },
     // iOS gives date controls their own button-like chrome, with inner
     // spacing and a centred value that no reset of ours can reach.
     WebkitAppearance: 'none',
@@ -187,9 +200,12 @@ const styles = stylex.create({
     // covers — one line of that leading fills its height exactly, which puts
     // the glyphs on the input's own baseline.
     display: 'block',
+    // ...with the input's own iOS floor, so the two baselines stay shared.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     // A tap has to reach the control underneath — that is what raises the

package/src/DateInput/TouchDateField.tsx

@@ -194,10 +194,14 @@ const styles = stylex.create({
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
     // Below 16px iOS zooms the page on focus. The field is focusable even
-    // though it is not typable, so it needs the same floor DateInput has.
+    // though it is not typable, so it needs the same floor DateInput has —
+    // keyed to iOS alone, since only iOS WebKit implements
+    // -webkit-touch-callout.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateRangeInput/DateRangeInput.tsx

@@ -92,9 +92,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateTimeInput/DateTimeInput.tsx

@@ -173,9 +173,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateTimeInput/TouchDateTimeField.tsx

@@ -182,9 +182,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateTimeInput/nativePickerSegmentStyles.ts

@@ -42,21 +42,34 @@ export const nativePickerSegmentStyles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
-    // Below 16px iOS zooms the page when the field takes focus.
+    // Below 16px iOS zooms the page when the field takes focus. Only iOS
+    // WebKit implements -webkit-touch-callout, so the coarse-pointer floor is
+    // keyed to iOS alone.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],
     backgroundColor: 'transparent',
     outline: 'none',
     // Native date/time controls size from their internal edit fields. Pin the
-    // box to one text line so both segments stay aligned.
-    height: stylex.firstThatWorks(
-      '1lh',
-      `calc(max(1rem, ${typeScaleVars['--text-body-size']}) * ${typeScaleVars['--text-body-leading']})`,
-    ),
+    // box to one text line so both segments stay aligned. The calc fallback
+    // mirrors the iOS-only floor above; browsers with `1lh` track it for free.
+    height: {
+      default: stylex.firstThatWorks(
+        '1lh',
+        `calc(${typeScaleVars['--text-body-size']} * ${typeScaleVars['--text-body-leading']})`,
+      ),
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': stylex.firstThatWorks(
+          '1lh',
+          `calc(max(1rem, ${typeScaleVars['--text-body-size']}) * ${typeScaleVars['--text-body-leading']})`,
+        ),
+      },
+    },
     WebkitAppearance: 'none',
     appearance: 'none',
     // DateTimeInput renders its own calendar/clock affordances.
@@ -101,9 +114,12 @@ export const nativePickerSegmentStyles = stylex.create({
     insetInlineEnd: 0,
     insetBlock: 0,
     display: 'block',
+    // The same iOS-only floor as the input it covers, shared baselines.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     pointerEvents: 'none',

package/src/Field/PanelSearchInput.tsx

@@ -119,10 +119,13 @@ const styles = stylex.create({
     color: colorVars['--color-text-primary'],
     fontFamily: typographyVars['--font-family-body'],
     // Matches the option rows below it, so the query reads as the first line of
-    // the list. The coarse-pointer floor keeps iOS from zooming on focus.
+    // the list. The floor keeps iOS from zooming on focus — keyed to iOS
+    // alone, since only iOS WebKit implements -webkit-touch-callout.
     fontSize: {
       default: typeScaleVars['--text-label-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-label-leading'],
     // The field draws the focus ring (see `field`), so the bare input must not

package/src/FieldStatus/__tests__/StatusMessage.a11y.states.ts

@@ -256,7 +256,7 @@ export const CORE_STATUS_MESSAGE_BINDING_STATES = [
       minValue: 0,
       maxValue: 100,
     },
-    focusSelector: '[role="progressbar"] [tabindex="0"]',
+    focusSelector: '[tabindex="0"]',
     storyId: 'a11y-status-message-pattern--progress-mark-focused-update',
   },
 ] as const satisfies ReadonlyArray<CoreStatusMessageBindingDefinition>;

package/src/FileInput/FileInput.tsx

@@ -231,9 +231,14 @@ const styles = stylex.create({
   },
   placeholderText: {
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-secondary'],
@@ -242,9 +247,13 @@ const styles = stylex.create({
   },
   fileNameText: {
     fontFamily: typographyVars['--font-family-body'],
+    // ...and the filename beside it keeps the same floor, so both lines the
+    // control shows stay the same size.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

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/Layout/LayoutFooter.doc.mjs

@@ -8,6 +8,23 @@ export const docs = {
   displayName: 'Layout Footer',
   isHiddenFromOverview: true,
   description: 'Bottom bar for action bars, pagination, and status bars.',
+  playground: {
+    defaults: {
+      children: 'Footer content: status bar or actions',
+      hasDivider: true,
+    },
+    wrapper: {
+      component: 'Layout',
+      slotProp: 'footer',
+      props: {
+        content: {
+          __element: 'LayoutContent',
+          props: {},
+          children: 'Main content area',
+        },
+      },
+    },
+  },
   props: [
     {
       name: 'children',