Common incorrect uses of <mds-help>. 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 Put HTML Elements in the Default Slot

The default slot is text-only; the content is rendered inside mds-tooltip, which expects a plain string. Nested elements or components may be stripped or break the tooltip layout.

<!-- INCORRECT -->
<mds-help>
  <strong>Attenzione:</strong> il limite massimo e' <em>100 caratteri</em>.
</mds-help>

<!-- CORRECT -->
<mds-help>Attenzione: il limite massimo e' 100 caratteri.</mds-help>

Do Not Pierce Shadow DOM to Style the Icon

The only supported customization surface is --mds-help-* CSS custom properties and the documented ::part(icon) shadow part. Targeting internal elements via >>> or undocumented selectors couples your code to the shadow DOM implementation.

/* INCORRECT */
mds-help >>> mds-icon {
  fill: red;
}

/* CORRECT */
mds-help::part(icon) {
  fill: rgb(var(--magma-warning-text-default));
}

Do Not Use <mds-help> as a Generic Tooltip Anchor

<mds-help> always renders its own help icon and wraps mds-tooltip internally. It is not a generic popover wrapper. If you need a tooltip on an arbitrary element, use mds-tooltip directly with a target selector.

<!-- INCORRECT: slotting a custom trigger to replace the icon -->
<mds-help>
  <mds-button slot="default" label="Dettagli"></mds-button>
  Testo di spiegazione.
</mds-help>

<!-- CORRECT: use mds-tooltip with a target for a custom trigger -->
<mds-button id="info-btn" label="Dettagli"></mds-button>
<mds-tooltip target="#info-btn">Testo di spiegazione.</mds-tooltip>

Do Not Override Width with Inline Styles Instead of CSS Custom Properties

Setting style="width: ..." on the host bypasses the component’s layout contract. Use the documented --mds-help-tooltip-* CSS custom properties to size the tooltip, and leave the host dimensions alone.

<!-- INCORRECT -->
<mds-help style="width: 400px;">Descrizione del campo.</mds-help>

<!-- CORRECT -->
<style>
  mds-help.sezione-avanzata {
    --mds-help-tooltip-max-width: 400px;
  }
</style>
<mds-help class="sezione-avanzata">Descrizione del campo.</mds-help>