Correct and idiomatic ways to use the <mds-keyboard-key> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Single Key Inside <mds-keyboard>

Always nest <mds-keyboard-key> inside <mds-keyboard>. The parent inserts the + separators and wires up key-combination testing; the key is meaningless outside this context.

<mds-keyboard>
  <mds-keyboard-key name="control"></mds-keyboard-key>
</mds-keyboard>

Multi-Key Shortcut Combination

List every key in the combination as a direct child. The parent inserts + separators automatically - do not add them manually.

<mds-keyboard>
  <mds-keyboard-key name="control"></mds-keyboard-key>
  <mds-keyboard-key name="s"></mds-keyboard-key>
</mds-keyboard>

<mds-keyboard>
  <mds-keyboard-key name="command"></mds-keyboard-key>
  <mds-keyboard-key name="shift"></mds-keyboard-key>
  <mds-keyboard-key name="z"></mds-keyboard-key>
</mds-keyboard>

Icon-Resolved Keys

Keys such as arrows, enter, tab, space, command, shift, backspace, and others resolve to an icon automatically. No extra configuration is needed - name alone is sufficient.

<mds-keyboard>
  <mds-keyboard-key name="arrowup"></mds-keyboard-key>
  <mds-keyboard-key name="enter"></mds-keyboard-key>
</mds-keyboard>

<mds-keyboard>
  <mds-keyboard-key name="tab"></mds-keyboard-key>
  <mds-keyboard-key name="space"></mds-keyboard-key>
</mds-keyboard>

Keyboard-Side Disambiguation

For keys that exist on both sides of a physical keyboard, use the directional variant (shiftleft, shiftright, controlleft, etc.). The component appends an l / r indicator to disambiguate.

<mds-keyboard>
  <mds-keyboard-key name="shiftleft"></mds-keyboard-key>
  <mds-keyboard-key name="controlleft"></mds-keyboard-key>
  <mds-keyboard-key name="a"></mds-keyboard-key>
</mds-keyboard>

Interactive Combination Test via try

Add try to <mds-keyboard> to let users verify they can type the shortcut. The parent drives pressed on child keys as the user types - do not set pressed yourself in this mode.

<mds-keyboard try>
  <mds-keyboard-key name="control"></mds-keyboard-key>
  <mds-keyboard-key name="z"></mds-keyboard-key>
</mds-keyboard>

Styling Customization via CSS Custom Properties

Adjust the keycap appearance through the documented --mds-keyboard-key-* CSS custom properties. Set them on the host element or a parent selector.

/* Increase padding for a larger keycap feel */
.keycap-large mds-keyboard-key {
  --mds-keyboard-key-padding: calc(var(--spacing) * 300);
}

/* Slow down the press animation */
.keycap-slow mds-keyboard-key {
  --mds-keyboard-key-transition-duration: 600ms;
}

/* Deepen the bottom shadow for more three-dimensional depth */
.keycap-deep mds-keyboard-key {
  --mds-keyboard-key-illumination-dark-size: calc(var(--spacing) * 400);
  --mds-keyboard-key-illumination-light-size: calc(var(--spacing) * 100);
}