Common incorrect uses of <mds-tab-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 <mds-tab-item> Outside <mds-tab>

The item communicates with its parent through Stencil’s internal listener (mdsTabItemSelect); used standalone it has no tab-switching behavior and no aria context.

<!-- INCORRECT -->
<mds-tab-item label="Dettagli" selected></mds-tab-item>

<!-- CORRECT -->
<mds-tab>
  <mds-tab-item label="Dettagli" selected></mds-tab-item>
  <div slot="content"><p>Contenuto dei dettagli.</p></div>
</mds-tab>

Do Not Wrap <mds-tab-item> in a Div or Other Element

The parent finds the items anywhere inside it, but it lays out and styles only its direct slot children (::slotted(mds-tab-item)): a wrapper takes their place in the tab strip, so the items lose the strip layout and their stacking above the slider indicator.

<!-- INCORRECT -->
<mds-tab>
  <div class="tab-group">
    <mds-tab-item label="Uno" selected></mds-tab-item>
    <mds-tab-item label="Due"></mds-tab-item>
  </div>
  <div slot="content">...</div>
  <div slot="content">...</div>
</mds-tab>

<!-- CORRECT -->
<mds-tab>
  <mds-tab-item label="Uno" selected></mds-tab-item>
  <mds-tab-item label="Due"></mds-tab-item>
  <div slot="content">...</div>
  <div slot="content">...</div>
</mds-tab>

Do Not Set selected="false" to Deselect

selected is a boolean attribute; selected="false" leaves a selected attribute on the element that contradicts the state, so attribute selectors and checks still read the item as selected. Remove the attribute entirely to deselect.

<!-- INCORRECT -->
<mds-tab-item label="Archivio" selected="false"></mds-tab-item>

<!-- CORRECT -->
<mds-tab-item label="Archivio"></mds-tab-item>

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

<mds-tab-item> has no documented default slot for content; it is a button-like leaf element. Use the icon prop to add a glyph.

<!-- INCORRECT -->
<mds-tab-item>
  <mds-icon name="mi/baseline/settings"></mds-icon>
  Impostazioni
</mds-tab-item>

<!-- CORRECT -->
<mds-tab-item label="Impostazioni" icon="mi/baseline/settings"></mds-tab-item>

Do Not Override size on Individual Items When a Parent Size Is Set

The parent pushes its size down to every child item on load and whenever size changes. Setting size on individual items is overwritten and creates confusion about the source of truth.

<!-- INCORRECT -->
<mds-tab size="sm">
  <mds-tab-item label="Uno" size="lg" selected></mds-tab-item>
  <mds-tab-item label="Due" size="sm"></mds-tab-item>
  <div slot="content">...</div>
  <div slot="content">...</div>
</mds-tab>

<!-- CORRECT -->
<mds-tab size="sm">
  <mds-tab-item label="Uno" selected></mds-tab-item>
  <mds-tab-item label="Due"></mds-tab-item>
  <div slot="content">...</div>
  <div slot="content">...</div>
</mds-tab>

Do Not Pierce the Shadow DOM to Style the Inner Button

The only supported customization surface is the --mds-tab-item-* CSS custom properties and the documented button shadow part. Targeting internals via ::part(button) >>> .button or undocumented selectors couples your code to the implementation.

/* INCORRECT */
mds-tab-item::part(button) >>> .text {
  font-weight: 900;
}

/* CORRECT */
mds-tab-item {
  --mds-tab-item-selected-background: rgb(var(--magma-accent-surface));
}
mds-tab-item::part(button) {
  border-radius: var(--magma-radius-lg);
}

Do Not Mix Content Panels and Tab Items Without a 1-to-1 Pairing

The parent resolves each content panel by index, matching it to the mds-tab-item at the same position. A mismatch breaks it: with fewer slot="content" elements than tab items a tab shows no panel, with more the component throws while wiring them and no panel gets hidden. No panel at all is fine: the strip then only reports the selection, or navigates when the items have href.

<!-- INCORRECT - two items, one content panel -->
<mds-tab>
  <mds-tab-item label="Uno" selected></mds-tab-item>
  <mds-tab-item label="Due"></mds-tab-item>
  <div slot="content"><p>Contenuto unico.</p></div>
</mds-tab>

<!-- CORRECT - one content panel per tab item -->
<mds-tab>
  <mds-tab-item label="Uno" selected></mds-tab-item>
  <mds-tab-item label="Due"></mds-tab-item>
  <div slot="content"><p>Contenuto del tab Uno.</p></div>
  <div slot="content"><p>Contenuto del tab Due.</p></div>
</mds-tab>

Do Not Mix a Link Item with Panel Tabs

A strip is either a tablist of tabs, each controlling a panel, or a navigation of links (href on every item): a link inside a tablist is not a child the role allows. Keep the link out of the strip, as an <mds-button> next to it (see mds-tab).

<!-- INCORRECT -->
<mds-tab>
  <mds-tab-item label="Locale" selected></mds-tab-item>
  <mds-tab-item label="Portale" href="https://portale.example.com"></mds-tab-item>
  <div slot="content"><p>Vista locale.</p></div>
  <div slot="content"></div>
</mds-tab>

<!-- CORRECT -->
<mds-tab>
  <mds-tab-item label="Locale" selected></mds-tab-item>
  <div slot="content"><p>Vista locale.</p></div>
</mds-tab>
<mds-button label="Portale" href="https://portale.example.com" target="blank" tone="text"></mds-button>