Common incorrect uses of <mds-keyboard>. 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 Slot Raw Text or <kbd> Elements

The default slot expects <mds-keyboard-key> children only. Slotting plain text, <kbd>, or other HTML breaks the separator injection logic and the test-mode key matching.

<!-- INCORRECT -->
<mds-keyboard>
  <kbd>Ctrl</kbd>
  <kbd>S</kbd>
</mds-keyboard>

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

Do Not Add + Separators Manually

The component inserts a styled + between consecutive keys automatically. Adding your own separator duplicates it and breaks the visual rhythm.

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

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

Do Not Set try="false" to Disable Test Mode

try is a boolean attribute: remove it (or leave it unset) to keep the component in display-only mode. A string value is fragile: "false" is read as false on this component, but the attribute stays on the element until the component renders (attribute selectors and scripts reading it see it set). Never write a boolean as a string.

<!-- INCORRECT -->
<mds-keyboard try="false">
  <mds-keyboard-key name="escape"></mds-keyboard-key>
</mds-keyboard>

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

Do Not Set test as a Static Attribute to Signal State

test is a reflected output prop driven by the component’s own verification flow. Setting it as a static HTML attribute paints the pass / fail state without any attempt behind it, and the next attempt overwrites it.

<!-- INCORRECT -->
<mds-keyboard test="pass">
  <mds-keyboard-key name="enter"></mds-keyboard-key>
</mds-keyboard>

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

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

<mds-keyboard-key> is a compound child and communicates with the parent via the Stencil DOM tree. Rendering it standalone loses the compound layout, the + separator, and test-mode driven pressed toggling.

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

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

Do Not Customize Colors with Raw CSS Values Instead of Tokens

Setting --mds-keyboard-background or --mds-keyboard-key-background to a raw hex or rgba() literal bypasses the palette layer and breaks dark mode. Always use a semantic color role, rgb(var(--magma-<role>)) (agents/color.md).

/* INCORRECT */
mds-keyboard {
  --mds-keyboard-background: #1a1a2e;
  --mds-keyboard-key-background: #16213e;
}

/* CORRECT */
mds-keyboard {
  --mds-keyboard-background: rgb(var(--magma-surface-inverse));
  --mds-keyboard-key-background: rgb(var(--magma-surface-inverse-muted));
}