Kbd | Quartz design system

Examples

Under a data grid

Arrows move, edits, Esc cancels, C copies the cell.

In a sentence

Press K to search conversations.

In a button hint

When to use it

Use: A hint, menu item or tooltip names the shortcut for an action.
Use: Docs or onboarding tell the person which key to press.
Not for: The text is code to type, not a key to press. Use Code block.
Not for: The shortcut is the only way to do the action. Add a visible control and name the shortcut beside it.

8 rules

Must: Pass keys="mod+k" for a modifier shortcut instead of choosing the command or Ctrl glyph yourself. Because a hand-picked glyph flashes Ctrl to a Mac user at hydration and has no spoken name.
Must: Set aria-keyshortcuts on the control with both forms (Meta+K Control+K). Because a Kbd beside the control is only text; aria-keyshortcuts is what a screen reader reports on the control.
Should: Use the platform's label: Esc, Enter, Tab, Space, arrows as up, down, left, right, letters upper-case.
Must: Make the same action reachable by a visible control. Because a phone has no keyboard, and a shortcut stays unknown until someone learns it.
Never: Draw keys as 3D caps with a bottom border or shadow. Because only overlays cast a shadow in Quartz, and the key is flat paper with a 1px control edge.
Should: Use a shortcut of 3 keys or fewer; pick a shorter one or a sequence (G then R).
Should: Hide shortcut hints on phones; Kbd stays inert.
Should: Set aria-hidden on a Kbd inside a control that sets aria-keyshortcuts. Because its spoken keys join the control's name.

4 checks

: Kbd is a kbd element, not focusable, with pointer-events none.
: A shortcut carries a screen-reader-only spoken form ("Command K" on a Mac, "Control K" elsewhere); the caps are aria-hidden.
: Forced colors keep a 1px outline on each cap.
: The platform is read at hydration; before it, differing keys render blank caps with data-placeholder.

8 edge cases

Platform differences: keys="mod+k" renders the symbols on a Mac and the words elsewhere.
Narrow box: Caps wrap between each other; a long key name wraps inside its cap.
Right to left: Caps keep their key order; the group mirrors only its gap.
Inside a tooltip hint: Paper caps on the inverse hint, in text-1; the channels flip, so both themes read.
Without JavaScript: Keys whose forms differ show blank caps; only the client knows the platform.
Unknown key name: keys="mod+foo" shows foo as typed.
Empty Kbd: A 20px blank cap; keys="" draws nothing. Do not render without a key.
Zoom 200%: The cap is at least 20px tall and grows with the text.

3 props

7 tokens