Common incorrect uses of <mds-input-otp>. 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 Set autosubmit="false" to Disable Auto-Submit

Stencil reads "false" as false and, since autosubmit is reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where [attr] selectors still match it. Remove the attribute entirely to opt out.

<!-- INCORRECT -->
<mds-input-otp name="otp" autosubmit="false"></mds-input-otp>

<!-- CORRECT -->
<mds-input-otp name="otp"></mds-input-otp>

Do Not Build a Row of Native <input> Elements Instead

Hand-rolling digit cells with native <input type="text" maxlength="1"> elements duplicates focus management, paste handling, and form association that <mds-input-otp> already provides, and breaks Magma theming.

<!-- INCORRECT -->
<div class="otp-row">
  <input type="text" maxlength="1">
  <input type="text" maxlength="1">
  <input type="text" maxlength="1">
  <input type="text" maxlength="1">
  <input type="text" maxlength="1">
  <input type="text" maxlength="1">
</div>

<!-- CORRECT -->
<mds-input-otp name="otp"></mds-input-otp>

Do Not Pierce Shadow DOM to Style Inner Cells

The inner mds-input cells are Shadow DOM internals. Targeting them with descendant selectors or >>> will break silently on any internal refactor.

/* INCORRECT */
mds-input-otp mds-input {
  --mds-input-background: red;
}
mds-input-otp >>> .input {
  border-radius: 0;
}

/* CORRECT - style the host layout only */
mds-input-otp {
  gap: calc(var(--spacing) * 600);
}

Do Not Use autosubmit Without a Parent <form>

autosubmit calls internals.form.requestSubmit(). Outside a <form> there is no owning form, so the call is silently ignored and the expected submission never fires.

<!-- INCORRECT - no owning form, submit never fires -->
<mds-input-otp name="otp" autosubmit></mds-input-otp>

<!-- CORRECT - wrapped in a form that handles the submit -->
<form action="/verify" method="post">
  <mds-input-otp name="otp" autosubmit></mds-input-otp>
</form>

Do Not Listen for the Native input or change Event

Native DOM events may not propagate out of shadow DOM the way you expect. Read the reflected value attribute or use form data on submit instead.

// INCORRECT
document.querySelector('mds-input-otp').addEventListener('input', (e) => {
  console.log(e.target.value); // unreliable from outside shadow DOM
});

// CORRECT - read the reflected prop directly
const otpEl = document.querySelector('mds-input-otp');
document.querySelector('form').addEventListener('submit', (e) => {
  e.preventDefault();
  console.log('Codice OTP:', otpEl.value);
});

Do Not Set length as a Non-Integer or to Zero

length controls how many cells are rendered. A fractional or zero value produces no cells or the wrong number. Always pass a positive integer.

<!-- INCORRECT -->
<mds-input-otp name="otp" length="0"></mds-input-otp>
<mds-input-otp name="otp" length="4.5"></mds-input-otp>

<!-- CORRECT -->
<mds-input-otp name="otp" length="4"></mds-input-otp>