# Kbd

A keyboard key: a small raised square with the key's symbol in the label face.

Block: `smbk-kbd`. Status: candidate. Figma: the Figma file, https://www.figma.com/community/file/1688324308358870630. Desktop and mobile: differ by presentation only.

## Options

| Axis | Values | Default | Meaning |
|---|---|---|---|
| `size` | `lg`, `md`, `sm` | `lg` | Figma calls these Large, Medium and Small. |



## Markup

```html
<kbd class="smbk-kbd smbk-kbd--size-lg">⌘</kbd>
```

## React

```tsx
import { Kbd } from './design-system/components/kbd/kbd.js';

<Kbd size="lg">⌘</Kbd>
```

## Stylesheet

```css
/* smbk-kbd — Kbd. Figma "Kbd" 888:8. A raised keycap.
 * Its height is a display size step; its width hugs the key text and the side
 * padding, so one glyph gives a near-square cap and a word or a shortcut
 * widens it. */

/* An inline flex box: the key's line is centered in the fixed height, inside the hairline edge. */
.smbk-kbd {
  box-sizing: border-box;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  height: var(--smbk-size-mark-lg);
  padding: 0 var(--smbk-space-inset-sm);
  text-align: center;
  border: var(--smbk-border-width-hairline) solid var(--smbk-color-border-rim-subtle);
  border-radius: var(--smbk-radius-control-xs);
  background: var(--smbk-color-surface-raised);
  color: var(--smbk-color-text-subtle);
  box-shadow: var(--smbk-elevation-raised);
  font-family: var(--smbk-typography-code-md-font-family);
  font-size: var(--smbk-typography-code-md-font-size);
  font-weight: var(--smbk-typography-code-md-font-weight);
  line-height: var(--smbk-typography-code-md-line-height);
  letter-spacing: var(--smbk-typography-code-md-letter-spacing);
  white-space: nowrap;
}

/* Keys are set in the code face, as Figma's Code styles: Code MD on the large key, Code SM on the others. */
.smbk-kbd--size-md,
.smbk-kbd--size-sm {
  font-family: var(--smbk-typography-code-sm-font-family);
  font-size: var(--smbk-typography-code-sm-font-size);
  font-weight: var(--smbk-typography-code-sm-font-weight);
  line-height: var(--smbk-typography-code-sm-line-height);
  letter-spacing: var(--smbk-typography-code-sm-letter-spacing);
}

/* Each size has its own height; the line stays centered in it. */
.smbk-kbd--size-md {
  height: var(--smbk-size-mark-md);
}

.smbk-kbd--size-sm {
  height: var(--smbk-size-mark-sm);
  padding: 0 var(--smbk-space-inset-xs);
}
```

## Tokens it reads

```json
{
  "size": {
    "mark": {
      "lg": {
        "$type": "dimension",
        "$value": "{{size.24}}",
        "$description": "Small fixed marks inside components (dots, bars, keys), large."
      },
      "md": {
        "$type": "dimension",
        "$value": "{{size.20}}",
        "$description": "Small fixed marks inside components (dots, bars, keys), medium."
      },
      "sm": {
        "$type": "dimension",
        "$value": "{{size.16}}",
        "$description": "Small fixed marks inside components (dots, bars, keys), small."
      }
    }
  },
  "space": {
    "inset": {
      "sm": {
        "$type": "dimension",
        "$value": "{{space.6}}",
        "$description": "Padding inside a component, small."
      },
      "xs": {
        "$type": "dimension",
        "$value": "{{space.4}}",
        "$description": "Padding inside a component, extra small."
      }
    }
  },
  "border-width": {
    "hairline": {
      "$type": "dimension",
      "$value": "{{border-width.1}}",
      "$description": "Thin lines: dividers and almost every edge."
    }
  },
  "color": {
    "border": {
      "rim-subtle": {
        "$type": "color",
        "$value": "{{color.alpha.white.20}}",
        "$description": "A fainter light rim."
      }
    },
    "surface": {
      "raised": {
        "$type": "color",
        "$value": "{{color.grey.50}}",
        "$description": "One floor above default: popovers, raised panels."
      }
    },
    "text": {
      "subtle": {
        "$type": "color",
        "$value": "{{color.grey.700}}",
        "$description": "Secondary text: descriptions, metadata."
      }
    }
  },
  "radius": {
    "control": {
      "xs": {
        "$type": "dimension",
        "$value": "{{radius.2}}",
        "$description": "Corners of controls, extra small."
      }
    }
  },
  "elevation": {
    "raised": {
      "$type": "shadow",
      "$value": {
        "light": "0px 2px 8px 1px #373d431a, 0px 1px 2px 0px #373d431a",
        "dark": "0px 2px 8px 1px #00000026, 0px 1px 2px 0px #00000026"
      }
    }
  },
  "typography": {
    "code-md": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Geist Mono, Geist Mono Fallback, ui-monospace, monospace",
        "fontSize": "14px",
        "fontWeight": 400,
        "lineHeight": 1.6,
        "letterSpacing": "0px"
      },
      "$description": "Code MD: the code block and larger keys. Geist Mono with its own line height, 160%, so lines of code read apart."
    },
    "code-sm": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Geist Mono, Geist Mono Fallback, ui-monospace, monospace",
        "fontSize": "12px",
        "fontWeight": 400,
        "lineHeight": 1.5,
        "letterSpacing": "0px"
      },
      "$description": "Code SM: keys (Kbd) and short code in a line of text. Geist Mono."
    }
  }
}
```

## Purpose

A keyboard key, drawn as a small raised keycap, for showing shortcuts in menus, tooltips, search fields and help text. It is the one place a single character is set in the label face at a fixed height.

## Anatomy

One element, the keycap, holding the key's symbol or name. Its height is fixed by the size; its width is the text plus the side padding, so it is near square for one character and grows to fit a word or a shortcut.

## When to use

- A shortcut beside a menu item or in a tooltip.
- A sequence of keys in help text, one keycap per key.

## When not to use

- For a [badge](badge.md) or a [tag](tag.md) that happens to be small. Those have their own components.
- For a [button](button.md). A keycap is not pressed.

## Behavior

None.

## Accessibility

### What it does for you

- It is a real keyboard element, which assistive technology announces as keyboard input.
- It takes no focus and no keys, since a keycap is not pressed.

### What you must do

- Give a symbol such as the command glyph a readable name through a `title` or surrounding text, because a symbol alone may be read as nothing.

### How to test

- With a screen reader, read a shortcut: each key is read as keyboard input, and a symbol is read by its name.
- With text at 200% and the page 320 pixels wide, each keycap's text stays whole.
- In a forced-color mode, the key's text stays visible.

## Usage rules

### Do

- In help text, use one keycap per key and write the joining plus sign outside them.
- Where one keycap stands for a whole shortcut, as in the search field's key hint, put a space between the keys: "⌘ K".

### Don't

- Put an icon in a keycap. The Phosphor set has no key glyphs, and the label face is the design.