Kbd | Glaze design system

Keys

When to use it

Use: A hint names the keys for an action: send, a new line, the command menu.
Use: A shortcuts list or a help panel.
Use: A search field shows the key that focuses it (Input mode="search" does this for you).
Not for: A value, an ID or a path: use mono text or <code>, not a key cap.
Not for: Something the person clicks. Use Button.

6 rules

Must: Write a shortcut as keys="mod+k", never as ⌘ or Ctrl by hand. Because keys shows ⌘ where the platform has a Command key and Ctrl elsewhere, and gives a screen reader the spoken names, where a hand-written ⌘ shows everyone else the wrong key.
Never: Use Kbd for an ID, a path or a value; it is for keys only. Because a key cap tells the person to press something, so a run ID in one reads as a shortcut.
Never: Set a font, a size or a fill on Kbd. Because its mono is already 0.8 of a caption so it never looks bigger than the text beside it, and a fill turns it into a badge.
Should: Put aria-keyshortcuts on the control the shortcut triggers, beside the visible Kbd. Because the hint is text near the button, and aria-keyshortcuts tells a screen reader the button itself answers to the keys.
Should: Sit a Kbd inside a caption or a body line, not on its own above a control.
Should: Show at most three keys in a shortcut; a longer chord belongs in a help page, not a hint.

3 checks

: With keys, the caps are aria-hidden and a hidden span reads the spoken names: "Command K", "Control K".
: The caps are text-2 on paper, 5.5:1, with a 1px ink 15% line.
: Kbd is not focusable and takes no pointer events, so a press passes to the row or button under it.

5 edge cases

Before hydration: A key that differs by platform is a blank cap of the minimum width, so a Command-key platform never flashes Ctrl.
keys="": Renders nothing, not an empty cap.
Long key name: Wraps inside the cap, which grows taller, instead of spilling out.
Touch phone: Hide shortcut hints where the pointer is coarse; there is no keyboard to press them on.
Dark theme: The cap turns near-black with the line at ink 15%.

4 props

7 tokens