Common incorrect uses of <mds-tooltip>. 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 a Bare ID String as target

The value of target is passed directly to querySelector, so a CSS selector is required: a bare id (hint-trigger) looks for an element named <hint-trigger>, finds nothing, and the tooltip never attaches.

<!-- INCORRECT -->
<span id="hint-trigger">Aiuto</span>
<mds-tooltip target="hint-trigger">Testo di aiuto</mds-tooltip>

<!-- CORRECT -->
<span id="hint-trigger">Aiuto</span>
<mds-tooltip target="#hint-trigger">Testo di aiuto</mds-tooltip>

Do Not Slot HTML Elements or Components

The default slot is text-only. Nesting HTML elements or Magma components breaks the inner layout and may produce unexpected rendering because the slot is wrapped in <mds-text>.

<!-- INCORRECT -->
<mds-tooltip target="#voce">
  <mds-icon name="mi/baseline/warning"></mds-icon>
  <strong>Attenzione:</strong> campo obbligatorio
</mds-tooltip>

<!-- CORRECT -->
<mds-tooltip target="#voce">Attenzione: campo obbligatorio</mds-tooltip>

Do Not Wrap the Trigger Inside the Tooltip

<mds-tooltip> uses a detached trigger model - the tooltip is placed as a sibling in the DOM and linked via target, not wrapped around its trigger. Nesting the trigger breaks the floating position logic.

<!-- INCORRECT -->
<mds-tooltip target="#btn">
  <mds-button id="btn" label="Elimina"></mds-button>
  Elimina il record selezionato
</mds-tooltip>

<!-- CORRECT -->
<mds-button id="btn" label="Elimina" variant="error" tone="text"></mds-button>
<mds-tooltip target="#btn">Elimina il record selezionato</mds-tooltip>

Do Not Set visible="false" to Hide the Tooltip

visible is a boolean attribute; setting it to the string "false" leaves the attribute on the element. The tooltip itself reads it as hidden, but every presence check ([visible], hasAttribute('visible')) still reads it as visible. Remove the attribute (or set the property to false) to hide it.

<!-- INCORRECT -->
<mds-tooltip target="#campo" visible="false">Testo nascosto</mds-tooltip>

<!-- CORRECT -->
<mds-tooltip target="#campo">Testo nascosto</mds-tooltip>

// CORRECT (programmatic)
document.querySelector('mds-tooltip').visible = false;

Do Not Pierce the Shadow DOM to Style Internal Parts

The only supported customization surface is the set of --mds-tooltip-* CSS custom properties and the documented text shadow part. Targeting undocumented internal selectors couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-tooltip >>> .text {
  font-style: italic;
}
mds-tooltip::part(arrow) {
  fill: red;
}

/* CORRECT */
mds-tooltip {
  --mds-tooltip-background: rgb(var(--magma-accent-surface));
  --mds-tooltip-delay: 0.5s;
}
mds-tooltip::part(text) {
  font-style: italic;
}

Do Not Repeat the Name of the Trigger as Its Description

A tooltip describes its trigger by default. When its text is the name of the trigger, as on an icon-only button, an aria-label with the same text makes a screen reader read it twice, as the name and as the description. Make the tooltip the name instead.

<!-- INCORRECT -->
<mds-button id="tokens-btn" icon="mi/baseline/palette" aria-label="Tokens"></mds-button>
<mds-tooltip target="#tokens-btn">Tokens</mds-tooltip>

<!-- CORRECT -->
<mds-button id="tokens-btn" icon="mi/baseline/palette"></mds-button>
<mds-tooltip target="#tokens-btn" relation="label">Tokens</mds-tooltip>

Do Not Replace <mds-tooltip> with a Native title Attribute

The native title tooltip is not styleable and not announced consistently by screen readers on touch devices. Use <mds-tooltip> for all contextual hints.

<!-- INCORRECT -->
<mds-button label="Elimina" title="Elimina il record selezionato"></mds-button>

<!-- CORRECT -->
<mds-button id="elimina-btn" label="Elimina" variant="error" tone="text"></mds-button>
<mds-tooltip target="#elimina-btn">Elimina il record selezionato</mds-tooltip>