Common incorrect uses of <mds-push-notification-item>. 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 Use the Item Outside Its Parent

<mds-push-notification-item> is a compound child that must live inside <mds-push-notification>. The parent drives entry / exit animation, stacking, and auto-hide when the last item closes.

<!-- INCORRECT -->
<mds-push-notification-item
  icon="mi/baseline/email"
  subject="Nuovo messaggio"
  message="Hai ricevuto un nuovo messaggio"
></mds-push-notification-item>

<!-- CORRECT -->
<mds-push-notification>
  <mds-push-notification-item
    icon="mi/baseline/email"
    subject="Nuovo messaggio"
    message="Hai ricevuto un nuovo messaggio"
  ></mds-push-notification-item>
</mds-push-notification>

Do Not Put Content in the Default Slot

<mds-push-notification-item> has no default slot. All text content goes through the message and subject props; interactive content goes into the named action or badge slots.

<!-- INCORRECT -->
<mds-push-notification-item>
  Hai un nuovo messaggio
</mds-push-notification-item>

<!-- CORRECT -->
<mds-push-notification-item
  message="Hai un nuovo messaggio"
  subject="Posta in arrivo"
></mds-push-notification-item>

Do Not Slot Arbitrary Content Into action Without mds-button

The action slot is designed for <mds-button> elements at size="sm". Slotting raw <button> or large components breaks layout alignment and loses Magma theming and keyboard semantics.

<!-- INCORRECT -->
<mds-push-notification-item subject="Richiesta" message="Approva la richiesta di accesso">
  <button slot="action" class="btn">Approva</button>
</mds-push-notification-item>

<!-- CORRECT -->
<mds-push-notification-item subject="Richiesta" message="Approva la richiesta di accesso">
  <mds-button slot="action" variant="success" tone="weak" size="sm" label="Approva"></mds-button>
</mds-push-notification-item>

Do Not Mix icon and src With preview="image"

When icon is set, the component always renders an <mds-avatar> for the icon. If src is also set and preview is not "avatar", an <mds-img> picture is rendered as well - producing two media areas side by side, which is almost never the intended layout. Pick one visual mode per notification.

<!-- INCORRECT - both an icon avatar and an image preview render simultaneously -->
<mds-push-notification-item
  icon="mi/baseline/photo"
  src="./cover.jpg"
  preview="image"
  subject="Nuova foto"
  message="La copertina e' stata aggiornata"
></mds-push-notification-item>

<!-- CORRECT - icon only, no image -->
<mds-push-notification-item
  icon="mi/baseline/photo"
  subject="Nuova foto"
  message="La copertina e' stata aggiornata"
></mds-push-notification-item>

<!-- CORRECT - image preview only, no icon -->
<mds-push-notification-item
  src="./cover.jpg"
  subject="Nuova foto"
  message="La copertina e' stata aggiornata"
></mds-push-notification-item>

Do Not Listen for the Native close DOM Event

The component emits mdsPushNotificationItemClose, not a native close. Listening for close never fires, and the click of the dismiss button does not leave the component (its handler calls stopPropagation()).

// INCORRECT
element.addEventListener('close', handler);

// CORRECT
element.addEventListener('mdsPushNotificationItemClose', handler);

Customize via Documented Vars, Not Internal Selectors

The supported customization surface is --mds-push-notification-item-* CSS custom properties and documented shadow parts (actions, avatar, content, picture). Targeting shadow-DOM internals via ::part() on undocumented parts or via >>> will break on minor releases.

/* INCORRECT */
mds-push-notification-item::part(header) {
  font-weight: bold;
}
mds-push-notification-item >>> .message {
  color: red;
}

/* CORRECT */
mds-push-notification-item {
  --mds-push-notification-item-message-line-clamp: 3;
  --mds-push-notification-item-shadow: var(--shadow-md-sharp);
}
mds-push-notification-item::part(content) {
  gap: calc(var(--spacing) * 200);
}