Common incorrect uses of <mds-push-notification>. 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 Arbitrary HTML in the Default Slot

The default slot is designed for mds-push-notification-item children only. Placing raw HTML or other components breaks the animation lifecycle, event wiring, and the intro/outro sequencing the container manages.

<!-- INCORRECT -->
<mds-push-notification>
  <div class="my-notification">
    <strong>Avviso</strong>
    <p>Il documento e' pronto.</p>
  </div>
</mds-push-notification>

<!-- CORRECT -->
<mds-push-notification>
  <mds-push-notification-item
    subject="Avviso"
    message="Il documento e' pronto."
  ></mds-push-notification-item>
</mds-push-notification>

Do Not Set visible="false" to Hide the Panel

visible is a boolean prop: a false boolean is written by removing the attribute, the convention for every Magma boolean (agents/conventions.md). Stencil does parse "false" as false, but the attribute stays in the markup until the component hydrates and its reflection removes it, so a [visible] selector or any code reading the attribute sees it set in the meantime. Remove the attribute entirely - or call hide() - to close the panel.

<!-- INCORRECT -->
<mds-push-notification visible="false"></mds-push-notification>

<!-- CORRECT: remove the attribute -->
<mds-push-notification></mds-push-notification>

// CORRECT: via imperative method
document.querySelector('mds-push-notification').hide();

Do Not Listen to the Native close Event Instead of mdsPushNotificationHide

The component emits mdsPushNotificationHide when the panel hides. Listening for a native close event will never fire because the component does not dispatch it, and native DOM events from inside the shadow root do not reliably bubble to the light DOM.

// INCORRECT
panel.addEventListener('close', () => updateUI());

// CORRECT
panel.addEventListener('mdsPushNotificationHide', () => updateUI());

Do Not Use behavior="manual" and Then Forget to Call show() / hide()

With behavior="manual" the container never auto-shows when items are added; you must explicitly call show() or set visible. Leaving it on manual without wiring visibility logic means notifications are silently queued but never displayed.

<!-- INCORRECT: items never appear because manual mode needs explicit show() -->
<mds-push-notification behavior="manual" id="notif-panel">
  <mds-push-notification-item
    subject="Nuovo messaggio"
    message="Messaggio ricevuto."
  ></mds-push-notification-item>
</mds-push-notification>

<!-- CORRECT: call show() after adding items -->
<mds-push-notification behavior="manual" id="notif-panel">
  <mds-push-notification-item
    subject="Nuovo messaggio"
    message="Messaggio ricevuto."
  ></mds-push-notification-item>
</mds-push-notification>

<script>
  document.querySelector('#notif-panel').show();
</script>

Do Not Pierce Shadow DOM to Style Item Internals

The only supported customization surface for the container is the --mds-push-notification-* CSS custom properties plus the documented ::part(notifications) part. Use per-item CSS custom properties (prefixed --mds-push-notification-item-*) for item-level styling. Do not reach into shadow parts that are not documented.

/* INCORRECT */
mds-push-notification >>> .notifications {
  background: white;
}
mds-push-notification::part(content) {
  padding: 2rem;
}

/* CORRECT */
mds-push-notification {
  --mds-push-notification-background: rgb(var(--magma-surface-overlay) / 0.9);
  --mds-push-notification-items-gap: calc(var(--spacing) * 300);
}
mds-push-notification::part(notifications) {
  /* documented part - safe to target */
  padding-block: calc(var(--spacing) * 200);
}

Do Not Slot Actions in the Wrong Slot

Action buttons belong in the action slot of mds-push-notification-item, not in the default slot of mds-push-notification. Placing a button in the parent’s default slot treats it like a notification item, breaks the animation sequence, and the button will be styled and animated as if it were a notification. A clear-all button is not needed either: the container renders its own.

<!-- INCORRECT: button lands in the parent's default slot -->
<mds-push-notification>
  <mds-button variant="dark">Cancella tutto</mds-button>
  <mds-push-notification-item subject="Avviso" message="Nuovo messaggio."></mds-push-notification-item>
</mds-push-notification>

<!-- CORRECT: action belongs on the item's action slot -->
<mds-push-notification>
  <mds-push-notification-item subject="Avviso" message="Nuovo messaggio.">
    <mds-button slot="action" variant="primary" tone="weak" size="sm">Apri</mds-button>
  </mds-push-notification-item>
</mds-push-notification>

Do Not Apply an Unsupported tone Value to Item

mds-push-notification-item accepts tone="strong" or tone="weak" only (ToneMinimalVariantType). Using tone="outline" (a tone of mds-button and mds-badge) silently falls back to the default weak look and the intended visual emphasis is lost. variant and tone paint only the item’s icon or avatar, so pair them with icon.

<!-- INCORRECT: outline and text are not supported tones for this component -->
<mds-push-notification-item
  icon="mi/baseline/error"
  variant="error"
  tone="outline"
  subject="Errore"
  message="Operazione fallita."
></mds-push-notification-item>

<!-- CORRECT -->
<mds-push-notification-item
  icon="mi/baseline/error"
  variant="error"
  tone="strong"
  subject="Errore"
  message="Operazione fallita."
></mds-push-notification-item>