Common incorrect uses of <mds-tab-bar>. 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 Place HTML Elements or Text Directly in the Bar’s Default Slot

<mds-tab-bar> only coordinates <mds-tab-bar-item> children; arbitrary HTML or text in its slot breaks the mutual-exclusion logic and the change event.

<!-- INCORRECT -->
<mds-tab-bar>
  <button>Home</button>
  <a href="/cerca">Cerca</a>
</mds-tab-bar>

<!-- CORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home" selected></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/search" label="Cerca"></mds-tab-bar-item>
</mds-tab-bar>

Do Not Use the Deprecated Default Slot for an Item’s Text

Setting an item’s text via the default slot is deprecated. Slotted text is read into label, and nested HTML is stripped with a console warning - use the label prop for the text and the icon prop for the glyph.

<!-- INCORRECT -->
<mds-tab-bar-item icon="mi/baseline/inbox">Messaggi</mds-tab-bar-item>
<mds-tab-bar-item>
  <span class="bold">Messaggi</span>
  <small>(3)</small>
</mds-tab-bar-item>

<!-- CORRECT -->
<mds-tab-bar-item icon="mi/baseline/inbox" label="Messaggi"></mds-tab-bar-item>

Do Not Slot <mds-icon> to Add an Icon

The item’s icon prop renders the glyph through the shared icon service and positions it correctly above the label. Slotting <mds-icon> puts it in the deprecated default slot, where it is misaligned or stripped.

<!-- INCORRECT -->
<mds-tab-bar-item>
  <mds-icon name="mi/baseline/home"></mds-icon>
  Home
</mds-tab-bar-item>

<!-- CORRECT -->
<mds-tab-bar-item icon="mi/baseline/home" label="Home"></mds-tab-bar-item>

Do Not Set selected="false" to Deselect an Item

selected is a boolean attribute. The item happens to style selected="false" as unselected, but the attribute stays on the element and contradicts the state for attribute selectors and checks. Remove the attribute entirely to deselect an item, or let the parent coordinate selection automatically.

<!-- INCORRECT -->
<mds-tab-bar-item icon="mi/baseline/home" label="Home" selected="false"></mds-tab-bar-item>

<!-- CORRECT -->
<mds-tab-bar-item icon="mi/baseline/home" label="Home"></mds-tab-bar-item>

Do Not Listen for the Item’s Internal Event on the Bar’s Children

mdsTabBarItemSelect is the item-level event <mds-tab-bar> coordinates on: its detail is the item’s id, which the bar overwrites with its own mds-tab-bar-item-<index> values. To react to selection changes from outside, listen for mdsTabBarChange on the parent instead, whose detail.index is the position of the selected item.

<!-- INCORRECT -->
<script>
  document.querySelector('mds-tab-bar-item').addEventListener('mdsTabBarItemSelect', handler);
</script>

<!-- CORRECT -->
<script>
  document.querySelector('mds-tab-bar').addEventListener('mdsTabBarChange', (e) => {
    handler(e.detail.index);
  });
</script>

Do Not Style Items by Piercing Shadow DOM

The only supported customization surface is the four --mds-tab-bar-item-* CSS custom properties. Targeting internal nodes via ::part(), >>>, or undocumented class names couples your code to the Shadow DOM implementation and will break on minor releases.

/* INCORRECT */
mds-tab-bar-item >>> mds-icon {
  fill: hotpink;
}

/* CORRECT */
mds-tab-bar mds-tab-bar-item {
  --mds-tab-bar-item-color-selected: rgb(var(--magma-accent-fg));
}