Common incorrect uses of <mds-tab>. 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 Size Individual Tab Items

Setting size on a <mds-tab-item> directly is overridden by the parent at render time. Use the size prop on <mds-tab> to size all tabs uniformly.

<!-- INCORRECT -->
<mds-tab>
  <mds-tab-item label="Elenco" size="sm" selected></mds-tab-item>
  <mds-tab-item label="Griglia" size="sm"></mds-tab-item>
</mds-tab>

<!-- CORRECT -->
<mds-tab size="sm">
  <mds-tab-item label="Elenco" selected></mds-tab-item>
  <mds-tab-item label="Griglia"></mds-tab-item>
</mds-tab>

Do Not Mix Tab Items and Content Panels Out of Order

Panels in slot="content" are wired to <mds-tab-item> elements by document order. A missing panel leaves its tab with no content, a wrong ordering shows the wrong panel when a tab is selected.

<!-- INCORRECT: only two content panels for three tab items -->
<mds-tab>
  <mds-tab-item label="A" selected></mds-tab-item>
  <mds-tab-item label="B"></mds-tab-item>
  <mds-tab-item label="C"></mds-tab-item>

  <div slot="content"><mds-text>Pannello A.</mds-text></div>
  <div slot="content"><mds-text>Pannello B.</mds-text></div>
</mds-tab>

<!-- CORRECT: one content panel per tab item, same order -->
<mds-tab>
  <mds-tab-item label="A" selected></mds-tab-item>
  <mds-tab-item label="B"></mds-tab-item>
  <mds-tab-item label="C"></mds-tab-item>

  <div slot="content"><mds-text>Pannello A.</mds-text></div>
  <div slot="content"><mds-text>Pannello B.</mds-text></div>
  <div slot="content"><mds-text>Pannello C.</mds-text></div>
</mds-tab>

Do Not Mix Link Items and Panel Tabs in One Strip

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, and assistive technology announces the strip wrong. Keep the link out of the strip, as an <mds-button> next to it.

<!-- INCORRECT -->
<mds-tab>
  <mds-tab-item label="Dettagli" selected></mds-tab-item>
  <mds-tab-item label="Allegati"></mds-tab-item>
  <mds-tab-item label="Portale" href="https://portale.example.com"></mds-tab-item>

  <div slot="content"><mds-text>Dettagli.</mds-text></div>
  <div slot="content"><mds-text>Allegati.</mds-text></div>
  <div slot="content"></div>
</mds-tab>

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

  <div slot="content"><mds-text>Dettagli.</mds-text></div>
  <div slot="content"><mds-text>Allegati.</mds-text></div>
</mds-tab>
<mds-button label="Portale" href="https://portale.example.com" target="blank" tone="text"></mds-button>

Do Not Put Tab Items Outside <mds-tab>

<mds-tab-item> communicates with its parent through internal Stencil events. Used outside <mds-tab> it renders as an inert button with no selection, panel, or keyboard management.

<!-- INCORRECT -->
<div class="my-tab-wrapper">
  <mds-tab-item label="Scheda uno" selected></mds-tab-item>
  <mds-tab-item label="Scheda due"></mds-tab-item>
</div>
<div>...</div>

<!-- CORRECT -->
<mds-tab>
  <mds-tab-item label="Scheda uno" selected></mds-tab-item>
  <mds-tab-item label="Scheda due"></mds-tab-item>
  <div slot="content">...</div>
  <div slot="content">...</div>
</mds-tab>

Do Not Listen to the mdsTabItemSelect Event from Outside

mdsTabItemSelect is the item-level event that <mds-tab-item> fires to its parent <mds-tab>: its detail carries the item element (target) and value, not the position of the tab. To react to the active tab of the group listen to mdsTabChange on <mds-tab>, whose detail has the tab index (id) and value.

<!-- INCORRECT -->
<mds-tab id="schede">
  <mds-tab-item label="Prima" selected></mds-tab-item>
  <mds-tab-item label="Seconda"></mds-tab-item>
</mds-tab>

<script>
  document.querySelector('#schede').addEventListener('mdsTabItemSelect', handler);
</script>

<!-- CORRECT -->
<mds-tab id="schede">
  <mds-tab-item label="Prima" selected></mds-tab-item>
  <mds-tab-item label="Seconda"></mds-tab-item>
</mds-tab>

<script>
  document.querySelector('#schede').addEventListener('mdsTabChange', handler);
</script>

Do Not Use scrollbar="false" or overflow="false" to Turn Off Boolean Props

Stencil reads "false" as false and, since both props are reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where [attr] selectors still match it. Remove the attribute entirely to turn a prop off.

<!-- INCORRECT -->
<mds-tab scrollbar="false" overflow="false">
  <mds-tab-item label="Prima" selected></mds-tab-item>
</mds-tab>

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

Do Not Place Raw HTML Instead of <mds-tab-item> in the Default Slot

The default slot expects <mds-tab-item> elements only. Placing a raw <button> or <a> there bypasses the ARIA tablist structure, selection management, and keyboard handling that <mds-tab> provides.

<!-- INCORRECT -->
<mds-tab>
  <button class="tab">Documenti</button>
  <button class="tab">Messaggi</button>
  <div slot="content">...</div>
  <div slot="content">...</div>
</mds-tab>

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

Do Not Customize via Undocumented Shadow Parts or Internal Selectors

The supported customization surface is the --mds-tab-* CSS custom properties and the documented shadow parts (tabs, contents, slider). Targeting other internals via >>>, /deep/, or undocumented class names couples your code to the shadow DOM implementation and will break on minor releases.

/* INCORRECT */
mds-tab >>> .tabs-wrapper {
  background: red;
}
mds-tab::part(tabs-wrapper) {
  padding: 0;
}

/* CORRECT */
mds-tab {
  --mds-tab-tabs-background: rgb(var(--magma-accent-surface));
  --mds-tab-tabs-padding: calc(var(--spacing) * 400);
  --mds-tab-tabs-radius: var(--magma-radius-xl);
}
mds-tab::part(tabs) {
  outline: 2px solid rgb(var(--magma-accent-border));
}