Kbd

Inline keyboard key indicator. Uses the native <kbd> element for semantic correctness; screen readers may announce its content as a key press depending on the user agent.

When to use

Use a <kbd> whenever documenting a keyboard shortcut, key combination, or hotkey in prose, tables, or tooltips.

For chord shortcuts, chain <kbd> elements with a literal separator (+, -, or a non-breaking space). The component does not own the separator — the consumer authors it explicitly so the rendered combo matches the convention of the surrounding documentation.

Variants

Anatomy

<kbd class="kbd">⌘</kbd>
<kbd class="kbd">Enter</kbd>
<kbd class="kbd -muted">Esc</kbd>
<kbd class="kbd -strong">Tab</kbd>

<!-- Combo -->
<kbd class="kbd">⌘</kbd>+<kbd class="kbd">K</kbd>

<!-- Three-key combo -->
<kbd class="kbd">⌘</kbd>+<kbd class="kbd">Shift</kbd>+<kbd class="kbd">P</kbd>

Tokens used

From semantic tier

• --color-surface-raised — default background
• --color-surface-canvas — muted variant background
• --color-ink-strong — default text, strong variant background
• --color-ink-inverse — strong variant text
• --color-ink-regular — muted variant text
• --color-border-default — default border
• --color-border-muted — muted variant border
• --space-inset-element-s — vertical padding
• --space-inset-element-m — horizontal padding
• --size-control-s — minimum inline size
• --radius-tag — corner radius
• --border-width-hairline — border thickness
• --shadow-flat — neutral shadow slot
• --font-mono-m-* — typography (family, size, weight, line-height, letter-spacing)

Accessibility

<kbd> carries an implicit role and is the correct semantic element for keyboard input.

The component sets user-select: none so accidental selection during prose copying does not include the key indicator markup. Authors who need users to copy the key text (e.g. a tutorial that asks readers to paste a shortcut name) should override this with a local style.

The component does NOT default to data-copyable="true". Copying a keyboard shortcut name is rare and the copy button would clutter inline prose. Authors who want copy support opt in explicitly: <kbd class="kbd" data-copyable="true">⌘K</kbd>.

Edge cases

• Long key names ("Backspace"): the component grows horizontally via min-inline-size: var(--size-control-s). No truncation.
• Modifier symbols ("⌘", "⌃", "⌥"): render directly via the monospace font. No conversion logic; consumers pass the symbol they want displayed.
• Inline-flex baseline: the element aligns to the surrounding text baseline. Use a <kbd> inside <p>, <li>, or <td> without layout adjustment.

Do

• Use <kbd> as the tag, never <span> or <code>.
• Author separators between keys explicitly so docs match local convention.
• Use .-strong when placing <kbd> on a dark or accent surface for contrast.

Don't

• Don't wrap multi-key combos in a single <kbd> (e.g. <kbd>⌘K</kbd>). Use one <kbd> per key so screen readers can announce them as separate keys.
• Don't override the monospace font — the convention is a recognition cue for readers scanning prose for shortcuts.