Kbd

/*
 * Kbd — element (interactive)
 *
 * Inline keyboard key indicator. CSS-only — no JavaScript, no tweak
 * slots. Uses native <kbd> for semantics.
 *
 *   <kbd class="kbd">⌘</kbd>
 *   <kbd class="kbd">Enter</kbd>
 *   <kbd class="kbd -muted">Esc</kbd>
 *
 * Compound key combos chain <kbd> elements with a separator authored
 * by the consumer:
 *
 *   <kbd class="kbd">⌘</kbd>+<kbd class="kbd">K</kbd>
 */

@layer malevich.components {
  .kbd {
    display: inline-flex;
    align-items: center;
    justify-content: center;

    min-inline-size: var(--size-control-s);
    padding-block: var(--space-inset-element-s);
    padding-inline: var(--space-inset-element-m);

    background-color: var(--color-surface-raised);
    color: var(--color-ink-strong);

    border: var(--border-width-hairline) solid var(--color-border-default);
    border-radius: var(--radius-tag);

    box-shadow: var(--shadow-flat);

    font-family: var(--font-mono-m-family);
    font-size: var(--font-mono-m-size);
    font-weight: var(--font-mono-m-weight);
    line-height: var(--font-mono-m-line-height);
    letter-spacing: var(--font-mono-m-letter-spacing);

    white-space: nowrap;
    user-select: none;
  }

  .kbd.-muted {
    background-color: var(--color-surface-canvas);
    color: var(--color-ink-regular);
    border-color: var(--color-border-muted);
  }

  .kbd.-strong {
    background-color: var(--color-ink-strong);
    color: var(--color-ink-inverse);
    border-color: var(--color-ink-strong);
  }
}

This component is pure CSS — no JavaScript required.

# Kbd — AGENTS.md

> Auto-generated from `kbd.docs.md` + the modifier applicability matrix.
> Edit those source files; this file regenerates on build.

## Identity

- **Component:** `kbd`
- **Layer:** elements
- **Status:** stable
- **Last updated:** 2026-05-18

## Summary

Use a `<kbd>` whenever documenting a keyboard shortcut, key

## Variants

| Variant | Class              | Use for                                |
|---------|--------------------|----------------------------------------|
| Default | `.kbd`             | Standard inline key indicator          |
| Muted   | `.kbd.-muted`      | De-emphasized (within muted text runs) |
| Strong  | `.kbd.-strong`     | Inverted, for high contrast contexts   |

## Modifier applicability

Per ADR-0007. Modifiers attach via `data-{category}="value"` attributes.

| Category | Accepts |
|---|---|
| `background` | — |
| `surface` | `flat` |
| `effect` | — |
| `shader` | — |
| `rhythm` | — |
| `motion` | — |
| `behavior` | `copyable` |

## Anatomy

```html
<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 consumed

### 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 contract

`<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>`.

## Guidance

### 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.