Common incorrect uses of <mds-note>. 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 Remove the Note Directly - Listen for mdsNoteDelete

The component emits mdsNoteDelete when the close button is activated; it never removes itself. Removing the element without listening to the event means deletable notes can never be dismissed, while bypassing the event skips any cleanup logic the host application needs to run.

<!-- INCORRECT: close button present but nothing removes the note -->
<mds-note variant="yellow" deletable>
  <mds-text typography="detail">Questa nota non sparira' mai.</mds-text>
</mds-note>

<!-- CORRECT: listen for the event and remove programmatically -->
<mds-note id="nota-avviso" variant="yellow" deletable>
  <mds-text typography="detail">Chiudi per rimuovere questa nota.</mds-text>
</mds-note>
<script>
  document.getElementById('nota-avviso').addEventListener('mdsNoteDelete', (e) => {
    e.target.remove();
  });
</script>

Do Not Use variant Values from the Status or Brand Ladders

<mds-note> uses ThemeLabelVariantType - the twelve decorative label colors (yellow, blue, green, red, orange, sky, violet, lime, aqua, orchid, purple, amaranth). Status values (info, success, warning, error) and brand values (primary, secondary) are not part of this type and silently fall back to the yellow base, breaking the intended color. A label color never communicates state: a status message is an mds-banner.

<!-- INCORRECT: status variant not accepted by mds-note -->
<mds-note variant="warning">
  <mds-text typography="detail">Operazione in corso.</mds-text>
</mds-note>

<!-- CORRECT: a state is a banner with a status variant -->
<mds-banner variant="warning">
  <mds-text typography="detail">Operazione in corso.</mds-text>
</mds-banner>

Do Not Put the Title in the Default Slot

The component provides a dedicated named title slot for the note heading. Placing a heading element in the default slot renders it inside the body content area, without the fixed position of the title slot, which is always rendered before the body whatever the source order.

<!-- INCORRECT: heading mixed into default body slot -->
<mds-note variant="blue">
  <mds-text typography="h5">Nota importante</mds-text>
  <mds-text typography="detail">Dettagli dell'annotazione qui.</mds-text>
</mds-note>

<!-- CORRECT: heading goes in the title slot -->
<mds-note variant="blue">
  <mds-text typography="h5" slot="title">Nota importante</mds-text>
  <mds-text typography="detail">Dettagli dell'annotazione qui.</mds-text>
</mds-note>

Do Not Set deletable="false" to Disable the Close Button

deletable is a boolean attribute, and a false boolean is an absent attribute (agents/conventions.md). The runtime parses the string "false" as false and hides the button, but the prop is not reflected, so the attribute stays on the element and [deletable] selectors or any code that reads the markup see a deletable note. Remove the attribute entirely to hide it.

<!-- INCORRECT: the attribute still says the note is deletable -->
<mds-note variant="green" deletable="false">
  <mds-text typography="detail">Questa nota dovrebbe essere fissa.</mds-text>
</mds-note>

<!-- CORRECT: omit the attribute -->
<mds-note variant="green">
  <mds-text typography="detail">Questa nota e' fissa.</mds-text>
</mds-note>

Do Not Style the Note with Arbitrary CSS or Tailwind Utilities

The only supported customization surface is the documented --mds-note-* CSS custom properties. Applying Tailwind background utilities or raw color values couples the note’s appearance to the utility layer and breaks dark mode and high-contrast handling.

/* INCORRECT */
mds-note {
  background-color: #fffacd;
  color: #3a3000;
}

/* CORRECT */
mds-note {
  --mds-note-background: rgb(var(--label-yellow-09));
  --mds-note-color: rgb(var(--label-yellow-02));
}