KBD

1import { Kbd } from '@/ui/Display'23<Kbd>⌘</Kbd> <Kbd>K</Kbd>45// A chord needs ONE accessible name. Three kbd elements announce as three6// unrelated keys.7function Shortcut({ keys }: { keys: string[] }) {8  return (9    <span role="img" aria-label={keys.map(spoken).join(' ')} className="inline-flex gap-1">10      {keys.map((k) => <Kbd key={k}>{k}</Kbd>)}11    </span>12  )13}1415const SPOKEN: Record<string, string> = {16  '⌘': 'Command', '⇧': 'Shift', '⌥': 'Option', '⌃': 'Control',17  '⌫': 'Backspace', '↵': 'Enter', '↑': 'Up arrow', '↓': 'Down arrow',18}19const spoken = (k: string) => SPOKEN[k] ?? k2021// Detect once at startup, not per render.22const isMac = typeof navigator !== 'undefined' &&23  /Mac|iPod|iPhone|iPad/.test(navigator.platform ?? navigator.userAgent)2425// One definition, two renderings. Modifier order follows what the OS prints:26// Control, Option, Shift, Command on macOS.27export function keysFor(shortcut: Shortcut) {28  return isMac ? shortcut.mac : shortcut.win29}3031// The visual keycap is for sighted users. THIS is what a screen reader queries.32<button aria-keyshortcuts="Meta+K" onClick={openPalette}>33  Search <Shortcut keys={keysFor(PALETTE)} />34</button>

<!-- In prose: sized relative to the text so it never disturbs the leading. -->
<p>Press <kbd>⌘</kbd> <kbd>K</kbd> to open the command palette.</p>

<!-- A chord: one name for the whole thing. -->
<span role="img" aria-label="Command Shift D">
  <kbd>⌘</kbd>
  <kbd>⇧</kbd>
  <kbd>D</kbd>
</span>

<!-- With a joiner in dense prose. The + is punctuation, not content. -->
<span role="img" aria-label="Control Shift D">
  <kbd>Ctrl</kbd>
  <span aria-hidden="true">+</span>
  <kbd>Shift</kbd>
  <span aria-hidden="true">+</span>
  <kbd>D</kbd>
</span>

<!-- The real mechanism sits on the control, not on the keycap. -->
<button type="button" aria-keyshortcuts="Meta+K">
  Search
  <span role="img" aria-label="Command K"><kbd>⌘</kbd><kbd>K</kbd></span>
</button>

kbd {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  /* Square for a single letter, wide for "Esc". Without the minimum, "K"
     is a narrow sliver beside "Shift". */
  min-inline-size: 1.35em;
  block-size: 1.35em;
  padding-inline: 5px;

  border: 1px solid var(--ds-border);
  /* The one detail that makes it read as a physical key. */
  border-block-end-width: 2px;
  border-radius: 5px;                /* tighter than a button */

  background: var(--ds-surface-raised);
  color: var(--ds-fg-secondary);

  /* Sans, NOT mono: monospace means "these literal characters", and a key
     is a physical object. */
  font-family: inherit;
  font-size: 0.85em;                 /* relative, so it scales with the text */
  font-weight: 500;
  line-height: 1;
  white-space: nowrap;
}

/* A chord is one unit: tight inside, looser to the text around it. */
.ds-shortcut { display: inline-flex; gap: 4px; margin-inline: 2px; }

/* On an inverted surface the light-surface tokens produce an invisible key. */
[role='tooltip'] kbd,
.ds-inverted kbd {
  border-color: rgb(255 255 255 / 0.25);
  background: rgb(255 255 255 / 0.1);
  color: inherit;
}

/* The fill is dropped here, so the border must be a real border. */
@media (forced-colors: active) {
  kbd { border: 1px solid; background: transparent; }
}

/* No keyboard, no use for a key hint. */
@media (pointer: coarse) {
  .ds-shortcut--hint { display: none; }
}