Common incorrect uses of <mds-mention>. 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 Slot Content Into the Component

<mds-mention> has no default slot and no named slots. Any child nodes placed inside the tag are silently ignored. Pass all content through the label and icon props.

<!-- INCORRECT -->
<mds-mention>
  <mds-icon name="mi/baseline/person"></mds-icon>
  mario.rossi
</mds-mention>

<!-- CORRECT -->
<mds-mention label="mario.rossi" icon="mi/baseline/person"></mds-mention>

Do Not Use a Raw <span> Chip Instead of the Component

Wrapping text in a styled <span> misses the remove affordance, icon handling, size ramp, and dark-mode token cascade. Use <mds-mention> whenever the UI needs an @-mention token.

<!-- INCORRECT -->
<span class="pill">@mario.rossi</span>

<!-- CORRECT -->
<mds-mention label="mario.rossi"></mds-mention>

Do Not Override Size with Inline CSS

The size prop drives icon dimensions, padding, and typography together as a coordinated unit. Setting font-size, width, or height inline breaks that coordination and can misalign the icon and label.

<!-- INCORRECT -->
<mds-mention label="anna.verdi" style="font-size: 20px; height: 40px;"></mds-mention>

<!-- CORRECT -->
<mds-mention label="anna.verdi" size="lg"></mds-mention>

Do Not Customize Style by Piercing the Shadow DOM

The only supported customization surface is --mds-mention-icon-size. Targeting internal elements via >>>, /deep/, or undocumented ::part() names couples your code to implementation details and will break on minor releases.

/* INCORRECT */
mds-mention >>> mds-icon {
  width: 32px;
}

/* CORRECT */
mds-mention {
  --mds-mention-icon-size: calc(var(--spacing) * 700);
}

Do Not Listen for click on the Remove Button Directly

The remove button lives inside the shadow DOM and stops its own click from propagating: a click listener on the host never sees the remove action (it fires only for clicks on the rest of the pill), and reaching into the shadow root ties your code to an internal class name. Listen for mdsMentionDelete instead - it is the contract, and it names the mention that was dismissed.

<!-- INCORRECT -->
<mds-mention id="m1" label="marco.bianchi" deletable></mds-mention>
<script>
  document.querySelector('#m1').addEventListener('click', removeMention);
</script>

<!-- CORRECT -->
<mds-mention id="m1" label="marco.bianchi" deletable></mds-mention>
<script>
  document.querySelector('#m1').addEventListener('mdsMentionDelete', removeMention);
</script>