An open source design system that's fully customizable and agent ready
TypeScript
fix(kbd): expose a spoken accessible name instead of being fully aria-hidden (obs-1) (#3411)
Cindy Zhanga4a883f81592
diff --git a/.changeset/kbd-accessible-name.md b/.changeset/kbd-accessible-name.mdnew file mode 100644index 0000000000..7e06e2e7f4--- /dev/null+++ b/.changeset/kbd-accessible-name.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] Kbd: the component is no longer entirely `aria-hidden`. It now exposes a spoken accessible name (e.g. "Command + K") built from screen-reader-friendly key labels, while the visual glyphs (⌘, ⇧, ↵, …) are hidden from assistive tech. Previously any shortcut communicated only via `Kbd` — including CommandPalette's footer hints — was invisible to screen-reader users (#3343).+@cixzhangdiff --git a/packages/core/src/Kbd/Kbd.test.tsx b/packages/core/src/Kbd/Kbd.test.tsxindex 130861ed0d..48a811b5ba 100644--- a/packages/core/src/Kbd/Kbd.test.tsx+++ b/packages/core/src/Kbd/Kbd.test.tsx@@ -72,10 +72,28 @@ describe('Kbd', () => {expect(screen.getByText('Esc')).toBeInTheDocument();});- it('is aria-hidden', () => {- const {container} = render(<Kbd keys="mod+k" />);- const wrapper = container.firstChild as HTMLElement;- expect(wrapper.getAttribute('aria-hidden')).toBe('true');+ 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+ // (jsdom is non-Mac, so mod → "Control").+ const img = screen.getByRole('img');+ expect(img).toHaveAttribute('aria-label', 'Control + Shift + K');+ // The visual glyph elements are hidden from assistive tech.+ const glyphs = img.querySelectorAll('kbd');+ glyphs.forEach(g => expect(g).toHaveAttribute('aria-hidden', 'true'));+ expect(img).not.toHaveAttribute('aria-hidden');+ });++ it('uses "Command" in the accessible name for mod on Mac', () => {+ Object.defineProperty(navigator, 'platform', {+ value: 'MacIntel',+ configurable: true,+ });+ render(<Kbd keys="mod+k" />);+ expect(screen.getByRole('img')).toHaveAttribute(+ 'aria-label',+ 'Command + K',+ );});it('uppercases unknown keys', () => {diff --git a/packages/core/src/Kbd/Kbd.tsx b/packages/core/src/Kbd/Kbd.tsxindex f69c4578fb..929e88a5a4 100644--- a/packages/core/src/Kbd/Kbd.tsx+++ b/packages/core/src/Kbd/Kbd.tsx@@ -87,6 +87,33 @@ function getKeyDisplay(key: string, isMac: boolean): string {return KEY_DISPLAY[key] ?? key.toUpperCase();}+/**+ * Spoken-word labels for screen readers. The visual `KEY_DISPLAY` uses glyphs+ * (⌘, ⇧, ↵, …) 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',+};++function getKeyLabel(key: string, isMac: boolean): string {+ if (key === 'mod') {+ return isMac ? 'Command' : 'Control';+ }+ return KEY_LABEL[key] ?? key.toUpperCase();+}+function subscribeToPlatformChanges(): () => void {return () => {};}@@ -155,19 +182,24 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {const parts = keys.split('+').map(key => key.trim().toLowerCase());+ // 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(' + ');+return (<spanref={ref}+ role="img"+ aria-label={accessibleName}{...rest}{...mergeProps(themeProps('kbd'),stylex.props(styles.wrapper, xstyle),className,style,- )}- aria-hidden="true">+ )}>{parts.map(key => (- <kbd key={key} {...stylex.props(styles.kbd)}>+ <kbd key={key} aria-hidden="true" {...stylex.props(styles.kbd)}>{getKeyDisplay(key, isMac)}</kbd>))}