Kbd

Use Kbd to show individual keys or labels (for example Ctrl, ⌘, or Enter). Compose KbdGroup when you need a chord such as Ctrl + B—it inserts a configurable separator between child Kbd elements. The theme sets monospace typography for kbd elements so shortcuts stay readable alongside body text.

Installation

The components are exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use Kbd for a single key. Wrap multiple Kbd nodes in KbdGroup when showing chords or sequences:

KbdGroup (optional)
├── Kbd
└── Kbd

KbdGroup renders an inline flex row and inserts separator (default ' + ') between children. Behavior follows the HTML <kbd> element and a <span> wrapper—there is no Radix primitive.

Usage

import { Kbd, KbdGroup } from '@by/experience-system';

Kbd and KbdGroup are client components ('use client'). Use them inside a Client Component or a dynamic import when using the Next.js App Router.

<KbdGroup>
  <Kbd>Ctrl</Kbd>
  <Kbd>B</Kbd>
</KbdGroup>

Examples

Key group

Use KbdGroup for shortcuts that combine multiple keys. The default separator is ' + '; override separator for a different glyph or spacing.

Sizes

Use size to match density: small (compact UI, badges in buttons), medium (default), or large for emphasis.

With button

Place a small Kbd inside Button (for example outline) to show an activation key without overpowering the label.

API Reference

Pieces are implemented in packages/experience-system/src/components/Kbd/ (Kbd.tsx, variants.ts). There is no third-party primitive wrapper—the API is HTML kbd / span plus Experience System variants.

Kbd

Renders a styled <kbd> with data-slot="kbd". Forwards standard React HTMLAttributes<HTMLElement> (see MDN <kbd>).

KbdGroup

Renders <span data-slot="kbd-group"> with inline flex layout. Inserts separator between each child Kbd. Forwards React.HTMLAttributes<HTMLSpanElement>.

Accessibility

• Treat Kbd content as visible shortcut hints; screen readers still read the surrounding sentence—avoid relying on Kbd alone for critical instructions.
• KbdGroup marks separators with aria-hidden so they are not announced separately; ensure prose near the group explains the shortcut.

Source in the repo: packages/experience-system/src/components/Kbd/Kbd.tsx and variants.ts. Agent-oriented contracts: packages/experience-system/src/components/Kbd/Kbd.instructions.md.