Common incorrect uses of <mds-keyboard-key>. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in agents/anti-patterns.md - they apply here too but are not repeated.

Do Not Use <mds-keyboard-key> Outside <mds-keyboard>

The key is a compound child component and must be a direct slot child of <mds-keyboard>. Used standalone it renders visually but has no separator wiring, no test capability, and violates the compound component contract.

<!-- INCORRECT -->
<mds-keyboard-key name="control"></mds-keyboard-key>
<span>+</span>
<mds-keyboard-key name="c"></mds-keyboard-key>

<!-- CORRECT -->
<mds-keyboard>
  <mds-keyboard-key name="control"></mds-keyboard-key>
  <mds-keyboard-key name="c"></mds-keyboard-key>
</mds-keyboard>

Do Not Add + Separators Manually

The parent <mds-keyboard> inserts + separators between child keys automatically. Adding them manually results in duplicate or misaligned separators.

<!-- INCORRECT -->
<mds-keyboard>
  <mds-keyboard-key name="command"></mds-keyboard-key>
  <span>+</span>
  <mds-keyboard-key name="v"></mds-keyboard-key>
</mds-keyboard>

<!-- CORRECT -->
<mds-keyboard>
  <mds-keyboard-key name="command"></mds-keyboard-key>
  <mds-keyboard-key name="v"></mds-keyboard-key>
</mds-keyboard>

Do Not Set pressed Manually When try Is Active

When <mds-keyboard try> is enabled, the parent owns pressed and sets it as the user types. Setting it manually conflicts with the parent state machine and produces incorrect visual feedback.

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

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

Do Not Use a Generic name String Outside the Key Dictionary

name is a KeyboardKeyName union type. Passing an arbitrary string (e.g. "ctrl", "cmd", "esc") that is not in the dictionary causes a runtime lookup failure because the component reads keyboardKeysData[name] without a guard.

<!-- INCORRECT -->
<mds-keyboard>
  <mds-keyboard-key name="ctrl"></mds-keyboard-key>
  <mds-keyboard-key name="cmd"></mds-keyboard-key>
  <mds-keyboard-key name="esc"></mds-keyboard-key>
</mds-keyboard>

<!-- CORRECT -->
<mds-keyboard>
  <mds-keyboard-key name="control"></mds-keyboard-key>
  <mds-keyboard-key name="command"></mds-keyboard-key>
  <mds-keyboard-key name="escape"></mds-keyboard-key>
</mds-keyboard>

Do Not Slot Content Inside <mds-keyboard-key>

<mds-keyboard-key> exposes no default or named slot. Any slotted content is ignored; the glyph is derived entirely from the name prop.

<!-- INCORRECT -->
<mds-keyboard>
  <mds-keyboard-key name="control">Ctrl</mds-keyboard-key>
</mds-keyboard>

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

Customize via CSS Custom Properties, Not Shadow-Piercing Selectors

The supported customization surface is the documented --mds-keyboard-key-* CSS custom properties. Piercing shadow DOM via ::part() on undocumented internals, >>>, or class hacks couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-keyboard-key >>> .physical-key {
  background-color: blue;
}

/* CORRECT */
mds-keyboard-key {
  --mds-keyboard-key-padding: calc(var(--spacing) * 300);
  --mds-keyboard-key-transition-duration: 400ms;
}