Skip to content

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.md
new file mode 100644
index 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).
+@cixzhang
diff --git a/packages/core/src/Kbd/Kbd.test.tsx b/packages/core/src/Kbd/Kbd.test.tsx
index 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.tsx
index 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 (
<span
ref={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>
))}