Common incorrect uses of <mds-toast>. 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 Put HTML in the Default Slot

The default slot accepts plain text only; nested elements are rendered inside the caption text and break the layout. Use the icon slot for an icon and the action slot for buttons.

<!-- INCORRECT -->
<mds-toast visible variant="error">
  <strong>Errore:</strong> salvataggio fallito
  <mds-button>Riprova</mds-button>
</mds-toast>

<!-- CORRECT -->
<mds-toast visible variant="error">
  <mds-icon slot="icon" name="mi/baseline/error-outline"></mds-icon>
  Salvataggio fallito
  <mds-button slot="action" size="sm" variant="error" tone="weak">Riprova</mds-button>
</mds-toast>

Do Not Set duration="0" to Mean “Use the Default”

Setting duration="0" explicitly disables auto-dismiss and keeps the toast on screen until the user closes it. To use the 5000 ms default, omit the attribute entirely.

<!-- INCORRECT - disables auto-dismiss unintentionally -->
<mds-toast visible variant="success" duration="0">
  Documento salvato
</mds-toast>

<!-- CORRECT - default 5000 ms applies -->
<mds-toast visible variant="success">
  Documento salvato
</mds-toast>

Do Not Use visible="false" to Hide the Toast

Setting a boolean attribute to the string "false" leaves the attribute on the element. The toast itself reads it as hidden, but every presence check ([visible], hasAttribute('visible'), as in the cleanup code below) still reads it as visible. Remove the attribute entirely (or set the prop to undefined) to hide the toast.

<!-- INCORRECT - presence checks still read the toast as visible -->
<mds-toast visible="false" variant="info">
  Sincronizzazione in corso
</mds-toast>

<!-- CORRECT - attribute absent means hidden -->
<mds-toast variant="info">
  Sincronizzazione in corso
</mds-toast>

Do Not React to visible Becoming false to Clean Up

When the timer fires it sets visible to false, but the outro animation is still running. Listening to that attribute change too early removes the element mid-animation. Wait for mdsToastClose, which fires after the animation completes.

// INCORRECT - element may still be animating
const toast = document.querySelector('mds-toast');
const observer = new MutationObserver(() => {
  if (!toast.hasAttribute('visible')) {
    toast.remove();
  }
});
observer.observe(toast, { attributes: true });

// CORRECT - fires after the outro animation
toast.addEventListener('mdsToastClose', () => {
  toast.remove();
});

Do Not Use a Variant Without Checking Its Acceptance

<mds-toast> accepts variant values from ThemeVariantType but ships CSS overrides only for light, dark, error, warning, info, and success. Using variant="primary" or variant="ai" is valid by type but produces no themed color overrides - the toast falls back to its base inverse colors, the same as dark. Stick to the six variants above.

<!-- INCORRECT - no color override; looks identical to variant="dark" -->
<mds-toast visible variant="primary">
  Azione confermata
</mds-toast>

<!-- CORRECT - uses a variant with full CSS support -->
<mds-toast visible variant="success">
  Azione confermata
</mds-toast>

Do Not Use tone="outline" or tone="text"

<mds-toast> uses ToneMinimalVariantType, which accepts only strong and weak. Passing tone="outline" or tone="text" silently falls back to the default and produces no visual difference.

<!-- INCORRECT - value not in ToneMinimalVariantType -->
<mds-toast visible variant="info" tone="outline">
  Aggiornamento disponibile
</mds-toast>

<!-- CORRECT -->
<mds-toast visible variant="info" tone="weak">
  Aggiornamento disponibile
</mds-toast>

Do Not Customize via Undocumented Shadow Parts or Internal Selectors

The supported surface is --mds-toast-* CSS custom properties. There are no documented ::part() targets for <mds-toast>; targeting internal class names with ::part(), >>>, or attribute-selector hacks couples your code to the shadow DOM implementation and will break on minor releases.

/* INCORRECT */
mds-toast >>> .dialog {
  border-radius: 0;
}

/* CORRECT - use the documented custom properties */
mds-toast {
  --mds-toast-background: rgb(var(--magma-surface-inverse));
  --mds-toast-color: rgb(var(--magma-on-inverse));
  --mds-toast-width: 360px;
}