# Keyboard key

> Shows a key or a shortcut, in three weights: the quiet cap in the screenplay’s element strip, the raised cap on a shortcut sheet, and plain text at the end of a menu row.

Source: https://kwark.space/designSystem/components/keyboard-key

## Usage

### What it is
The way Kwark writes a key on screen. It appears where people learn shortcuts without being taught: beside the screenplay's element buttons, at the end of desktop menu rows (Decision 0015), on the shortcut sheet, and in help text.

### Three weights, three places
| Weight | Class | Where | Why it looks like that |
|---|---|---|---|
| Quiet cap | `kw-kbd` | The screenplay's element strip | It sits beside the word on every button; it must not shout |
| Raised cap | `kw-keycap` | Shortcut sheets, help, the command palette foot | It is being read as an instruction; one cap per key |
| Plain text | `.kw-menu-item kbd` | Desktop menu rows | Menus are dense; the shortcut aligns at the row's end |

### Platform
- On Apple devices use the symbols ⌘ ⇧ ⌥ ⌃ in that order, run together in a menu (*⇧⌘S*) and as separate caps on a sheet.
- Elsewhere use words joined by separate caps: **Ctrl** **Shift** **S**. Never show ⌘ to a Windows user.
- Single letters are capitals (*S*), as printed on the key.

### When not to use
- On phones, where there is no keyboard to press. Shortcut caps are hidden under a thumb.
- To style a chip or a tag. A key is a key.

## Style

### Anatomy

**Quiet cap** (`kw-kbd`, the element strip)
1. 1px `--k-line`, 4px corners, 2px 4px padding, no fill.
2. 11px (`--k-fs-dense`) in `--k-text-2` at 75%. The app draws 9px; the system keeps the 11px floor.

**Raised cap** (`kw-keycap`)
1. At least 22 × 22px, 6px padding, 5px corners, `--k-surface`, 1px `--k-line-strong` with a 2px foot.
2. Poppins 500 12px tabular in `--k-text`; caps for a combination sit 3px apart (`kw-keys`).
3. Small (`--sm`, palette foot): 18px, a 1px foot, `--k-line`, 11px `--k-text-2`.

**Menu text**: Poppins 500 12px `--k-text-2`, 0.04em tracking, 16px from the label, at the row's end.

**Sheet row**: at least 40px, 6px 8px 6px 10px, `--k-bg`, 1px `--k-line`, 6px corners, the action left and the keys right (`.kcal-kbd-row`).

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-line-strong` | var(--k-text-2) | var(--k-text-2) |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-bg` | #f8fafc | #191919 |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-radius-control` | 6px |  |
| `--k-fs-meta` | 12px |  |
| `--k-fs-dense` | 11px |  |
| `--k-fs-body` | 14px |  |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-kbd-strip" role="toolbar" aria-label="Screenplay elements">
  <button type="button" aria-pressed="true">Scene heading <kbd class="kw-kbd">⇧⌘1</kbd></button>
  <button type="button" aria-pressed="false">Action <kbd class="kw-kbd">⇧⌘2</kbd></button>
  <button type="button" aria-pressed="false">Character <kbd class="kw-kbd">⇧⌘3</kbd></button>
  <button type="button" aria-pressed="false">Dialogue <kbd class="kw-kbd">⇧⌘4</kbd></button>
</div>
<ul class="kw-kbd-sheet" aria-label="Calendar shortcuts">
  <li>New event <kbd class="kw-keycap">N</kbd></li>
  <li>Today <kbd class="kw-keycap">T</kbd></li>
  <li>Previous and next week <span class="kw-keys"><kbd class="kw-keycap">←</kbd><kbd class="kw-keycap">→</kbd></span></li>
  <li>Keep a restore point <span class="kw-keys"><kbd class="kw-keycap">⇧<span class="kw-visually-hidden"> Shift</span></kbd><kbd class="kw-keycap">⌘<span class="kw-visually-hidden"> Command</span></kbd><kbd class="kw-keycap">S</kbd></span></li>
</ul>
<p class="kw-kbd-inline" style="margin:0">Press <span class="kw-keys"><kbd class="kw-keycap">⌘<span class="kw-visually-hidden"> Command</span></kbd><kbd class="kw-keycap">S</kbd></span> and Kwark says <em>Saved</em>. On Windows and Linux it is <span class="kw-keys"><kbd class="kw-keycap">Ctrl</kbd><kbd class="kw-keycap">S</kbd></span>.</p>
<div class="kw-menu kw-menu--app" role="menu" aria-label="File">
  <button class="kw-menu-item" role="menuitem" type="button"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"/><path d="M3 3v5h5M12 7v5l3 2"/></svg><span>Keep a restore point</span><kbd>⇧⌘S</kbd></button>
  <button class="kw-menu-item" role="menuitem" type="button"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 9V3h12v6M6 18H4a2 2 0 0 1-2-2v-5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2h-2"/><path d="M6 14h12v7H6z"/></svg><span>Print…</span><kbd>⌘P</kbd></button>
</div>
```

Three places in the app: the screenplay's element strip (`kbd` with a 1px line, 4px corners, no fill), the calendar's shortcut sheet (`.kcal-kbd` in `ProjectCalendarModule/CalendarTeams.css`: mono, `--k-surface`, a 1px `--k-line-strong` border, 2px 6px), and menu rows (`.ui-menu__keys`, plain 12px text). The system's raised cap (`kw-keycap`) uses Poppins with tabular figures instead of the mono face, and a 2px foot so it reads as a key.

## Accessibility

### ARIA
- Use `<kbd>` for every key. For a combination, nest one `<kbd>` per key inside the group.
- Screen readers say the symbol's Unicode name or nothing at all, so add a visually hidden word after each symbol: *⌘ Command*, *⇧ Shift*.
- A control's shortcut goes in `aria-keyshortcuts` (*Meta+Shift+S*) on the control itself; the visible cap is for sighted people.

### Contrast
Raised caps are `--k-text` on `--k-surface`. The quiet cap's 75% text is decorative beside a full-contrast label, and the shortcut is also in the menu.

## For agents

### Rules

- **Must** use kbd for keys, one per key in a combination, with a hidden word after every symbol.
- **Must** show platform-correct modifiers: ⌘ ⇧ ⌥ on Apple devices, Ctrl, Shift, Alt words elsewhere.
- **Always** list the same shortcut in the desktop menu row as on the sheet and in tooltips.
- **Never** show keyboard shortcuts on phones.
- **Never** go under 11px for a key, even where the app draws 9px today.

### AI readiness test

**Task:** Document the screenplay element shortcuts on the Help page for both platforms.

**Give the agent:** This page, Menus and shortcuts pattern, Screenplay elements.

**Constraint:** Readers use Mac and Windows; some use screen readers.

**A reliable answer:**
- A sheet with one raised cap per key
- ⇧⌘1 on Mac and Ctrl Shift 1 elsewhere
- Hidden words "Shift" and "Command"
- Same shortcuts as the element strip and Format menu
- Hidden on phones
