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

Single Key Display

The simplest use: one <mds-keyboard-key> child inside <mds-keyboard>. The name attribute selects a key from the built-in key dictionary; the component renders the physical-looking keycap with the key’s alias (e.g. F1, Ctrl).

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

Multi-Key Shortcut Combination

Slot two or more <mds-keyboard-key> elements. The component automatically inserts a + separator between consecutive keys, so you never need to add it manually.

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

Specifying Key Side (Left / Right Modifier)

Use the side-specific name values (controlleft, controlright, shiftleft, shiftright, commandleft, commandright, etc.) when the shortcut must be typed with a specific hand. The keycap renders a small positional indicator.

<!-- Only the left Shift key is accepted during a test -->
<mds-keyboard try>
  <mds-keyboard-key name="shiftleft"></mds-keyboard-key>
  <mds-keyboard-key name="d"></mds-keyboard-key>
</mds-keyboard>

Interactive Verification Mode (try)

Add the try attribute to let the user confirm the shortcut by typing it. A trigger button appears; clicking it puts the component into capture mode. The keys must be pressed in the order they are slotted: at the first key release the component reflects the outcome (pass / fail) on the test attribute and shows a localized tooltip.

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

Shortcut Reference Table

Embed <mds-keyboard> inside a <mds-table> to build a keyboard-shortcut reference sheet. Each row pairs the visual shortcut with its description.

<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Combinazione"></mds-table-header-cell>
    <mds-table-header-cell label="Azione"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row>
      <mds-table-cell>
        <mds-keyboard>
          <mds-keyboard-key name="control"></mds-keyboard-key>
          <mds-keyboard-key name="c"></mds-keyboard-key>
        </mds-keyboard>
      </mds-table-cell>
      <mds-table-cell><mds-text>Copia</mds-text></mds-table-cell>
    </mds-table-row>
    <mds-table-row>
      <mds-table-cell>
        <mds-keyboard>
          <mds-keyboard-key name="control"></mds-keyboard-key>
          <mds-keyboard-key name="v"></mds-keyboard-key>
        </mds-keyboard>
      </mds-table-cell>
      <mds-table-cell><mds-text>Incolla</mds-text></mds-table-cell>
    </mds-table-row>
    <mds-table-row>
      <mds-table-cell>
        <mds-keyboard>
          <mds-keyboard-key name="control"></mds-keyboard-key>
          <mds-keyboard-key name="z"></mds-keyboard-key>
        </mds-keyboard>
      </mds-table-cell>
      <mds-table-cell><mds-text>Annulla</mds-text></mds-table-cell>
    </mds-table-row>
  </mds-table-body>
</mds-table>

Reading the test Outcome Attribute

When try is set the test attribute is reflected onto the host as "pass" or "fail" after each attempt. Use it as a CSS attribute selector, or observe the attribute from JavaScript to drive follow-on UI (the component emits no event).

<mds-keyboard id="shortcut-ctrl-s" try>
  <mds-keyboard-key name="control"></mds-keyboard-key>
  <mds-keyboard-key name="s"></mds-keyboard-key>
</mds-keyboard>

const keyboard = document.querySelector('#shortcut-ctrl-s');
new MutationObserver(() => {
  if (keyboard.getAttribute('test') === 'pass') {
    console.log('Combinazione corretta!');
  }
}).observe(keyboard, { attributes: true, attributeFilter: ['test'] });

Styling Customization

Adjust colors and lighting only through the documented --mds-keyboard-* CSS custom properties. Use the semantic color roles via rgb(var(--magma-<role>)) (agents/color.md) so dark mode continues to work.

.custom-keyboard mds-keyboard {
  --mds-keyboard-background: rgb(var(--magma-surface-inverse));
  --mds-keyboard-color: rgb(var(--magma-on-inverse));
  --mds-keyboard-key-background: rgb(var(--magma-surface-inverse-muted));
  --mds-keyboard-padding: calc(var(--spacing) * 300);
}