Common incorrect uses of <mds-input-switch>. 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 Boolean Props to the String “false”

checked, disabled, explicit, and indeterminate are boolean attributes. Stencil reads "false" as false and, since all four are 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 turn it off.

<!-- INCORRECT -->
<mds-input-switch checked="false" disabled="false">Notifiche</mds-input-switch>

<!-- CORRECT -->
<mds-input-switch>Notifiche</mds-input-switch>

Do Not Use a Native <input> Instead of <mds-input-switch>

Replacing the component with a raw <input type="checkbox"> or <input type="radio"> bypasses the design system’s theming, accessibility defaults, label layout, and form integration.

<!-- INCORRECT -->
<label>
  <input type="checkbox" name="notifiche" value="1"> Notifiche via e-mail
</label>

<!-- CORRECT -->
<mds-input-switch name="notifiche" value="1">Notifiche via e-mail</mds-input-switch>

Do Not Use explicit or size with type="checkbox" or type="radio"

explicit surfaces a glyph inside the switch knob and size scales the knob - both are only honored when type="switch". They are silently ignored on other types.

<!-- INCORRECT -->
<mds-input-switch type="checkbox" name="opt" value="1" explicit size="lg">Opzione</mds-input-switch>

<!-- CORRECT -->
<mds-input-switch type="checkbox" name="opt" value="1">Opzione</mds-input-switch>

<!-- correct use of explicit and size: only with type="switch" -->
<mds-input-switch type="switch" name="opt" value="1" explicit size="lg">Opzione</mds-input-switch>

Do Not Listen for Native change Instead of mdsInputSwitchChange

The component stops and prevents the native change event internally. Listen for the documented mdsInputSwitchChange event, which carries { name, checked, value } in event.detail.

<!-- INCORRECT -->
<mds-input-switch id="toggle" name="tema" value="scuro">Tema scuro</mds-input-switch>
<script>
  document.querySelector('#toggle').addEventListener('change', handler);
</script>

<!-- CORRECT -->
<mds-input-switch id="toggle" name="tema" value="scuro">Tema scuro</mds-input-switch>
<script>
  document.querySelector('#toggle').addEventListener('mdsInputSwitchChange', (e) => {
    console.log(e.detail.checked);
  });
</script>

Do Not Use indeterminate on type="switch" or type="radio"

The indeterminate glyph (indeterminate-check-box) is part of the checkbox icon variant only. Setting indeterminate on a switch has no visual effect, on a radio it blanks the radio glyph, and on both it misleads consumers about the control state.

<!-- INCORRECT -->
<mds-input-switch type="switch" name="opt" value="1" indeterminate>Tutti i permessi</mds-input-switch>

<!-- CORRECT -->
<mds-input-switch type="checkbox" name="tutti" value="all" indeterminate>Seleziona tutto</mds-input-switch>

Do Not Omit name in a Radio Group

Without a shared name, the radios do not form a group: as with native radios, each nameless radio is a group of its own, so several can be checked at once, and none of them is submitted with the form.

<!-- INCORRECT -->
<mds-input-switch type="radio" value="a" checked>Opzione A</mds-input-switch>
<mds-input-switch type="radio" value="b">Opzione B</mds-input-switch>

<!-- CORRECT -->
<mds-input-switch type="radio" name="scelta" value="a" checked>Opzione A</mds-input-switch>
<mds-input-switch type="radio" name="scelta" value="b">Opzione B</mds-input-switch>

Do Not Customize with Undocumented CSS Parts or Internal Selectors

The only supported customization surface is the documented --mds-input-switch-* CSS custom properties. Targeting shadow internals via ::part() on undocumented parts or via >>> will break on minor releases.

/* INCORRECT */
mds-input-switch >>> .switch {
  border-radius: 4px;
}
mds-input-switch::part(toggle) {
  box-shadow: none;
}

/* CORRECT */
mds-input-switch {
  --mds-input-switch-box-color-enabled-checked: rgb(var(--magma-success-emphasis));
  --mds-input-switch-duration: 150ms;
}