Skip to main content
Digitaltableteur

Design system components

Kbd

Inline keyboard-key indicator rendered as a semantic kbd keycap.

Status: stable. Group: display. Markdown version: /design-system/components/kbd.md

When to use

Kbd marks keyboard input inline: a single keycap per component, composed into chords with literal separators between siblings. It is purely presentational text with correct kbd semantics, sized to sit inside prose, tooltips, and menu hints.

When not to use

The contract records no forbidden uses.

Look-alikes

  • Code: Do not use for keyboard keys; that is Kbd.

Props

Kbd props
PropTypeDefaultDescriptionRequired
size"sm" | "md" | "lg"mdSize token. Defaults to "md".No
variant"primary" | "secondary"primaryVisual style. primary is a filled light-gray keycap with a bottom edge that reads like a physical key; secondary is the flatter outlined chip. Defaults to "primary".No

Variants

  • Available variants: primary, secondary (default primary).
  • Available sizes: sm, md, lg (default md).

Invalid combinations

The contract records no invalid combinations.

Keyboard

The contract records no keyboard interaction.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

Kbd rules
LevelRuleHow it is checked
MUSTARIA: None; static text semantics via the kbd element.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTRequired stories produce no axe violations at the configured severity.Automated by npm run test:stories:matrix:ci. WCAG 2.5.8.
MUSTThe accessibility tree (role, name, state) matches the committed snapshot for every required story.Automated by npm run test:stories:matrix:ci. WCAG 1.3.1, 4.1.2.
MUSTThe component remains legible and operable under a real browser forced-colors: active pass.Automated by npm run test:stories:hc.
MUSTA human completed an end-to-end accessibility review of this component.Manual review, last on 2026-11-04.
SHOULDOne key per Kbd; write chords as <Kbd>⌘</Kbd> + <Kbd>K</Kbd> so screen readers hear the separator.Not stated in the contract.
SHOULDMatch size to the surrounding text scale; sm inside Tooltip and menu hints, md in prose.Not stated in the contract.
SHOULDUse platform-correct symbols (⌘/Ctrl) from your own platform detection; Kbd renders what you pass.Not stated in the contract.
SHOULDPair every shortcut hint with a clickable way to do the same action; the hint is an accelerator, not the affordance.Not stated in the contract.
SHOULD NOTDo not make Kbd interactive; it is not a button and never receives focus.Not stated in the contract.
SHOULD NOTDo not put full words or phrases in one keycap except actual key names (Esc, Enter, Space).Not stated in the contract.

Install and import

  • Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
  • Import: import { Kbd } from "@digitaltableteur/react";
  • Entry point: @digitaltableteur/react/typography exports it too.
  • Styles: import @digitaltableteur/react/style.css once at the app boundary.
  • Also available as the custom element <dt-kbd>; see the custom elements manifest.

Links