Common incorrect uses of <mds-details>. 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 the Title Text in the Default Slot

The default slot is the collapsible body. Text placed there is hidden until the user expands the block, so it cannot serve as the visible header. Use the title slot for the header label.

<!-- INCORRECT -->
<mds-details>
  Requisiti di accesso
</mds-details>

<!-- CORRECT -->
<mds-details>
  <mds-text typography="h6" slot="title">Requisiti di accesso</mds-text>
</mds-details>

Do Not Replace <mds-details> with a Raw <details> Element

The native <details> lacks Magma theming, the leading icon slot, the action slot, smooth CSS grid transitions, preference support (reduced-motion, high-contrast), and the mdsDetailsChange event contract. Always use <mds-details> inside a Magma application.

<!-- INCORRECT -->
<details>
  <summary>Modulistica richiesta</summary>
  <p>Scarica il modulo A3 prima di procedere.</p>
</details>

<!-- CORRECT -->
<mds-details>
  <mds-text typography="h6" slot="title">Modulistica richiesta</mds-text>
  <mds-text typography="detail">Scarica il modulo A3 prima di procedere.</mds-text>
</mds-details>

Do Not Set opened="false" to Collapse the Component

opened is a boolean attribute. The component reads the string "false" as false and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (mds-details[opened]) see the block as open. Remove the attribute entirely to collapse it, or set the property to undefined / false in JavaScript.

<!-- INCORRECT -->
<mds-details opened="false">
  <mds-text typography="h6" slot="title">Note operative</mds-text>
</mds-details>

<!-- CORRECT -->
<mds-details>
  <mds-text typography="h6" slot="title">Note operative</mds-text>
</mds-details>

Do Not Inline an <mds-icon> in the title Slot to Fake a Leading Glyph

The icon slot is the dedicated region for the leading glyph; it also participates in the toggle click area. Putting mds-icon inside the title slot bypasses this layout: the icon area stays hidden and the glyph sits in the title text.

<!-- INCORRECT -->
<mds-details>
  <span slot="title">
    <mds-icon name="mi/baseline/info"></mds-icon>
    Informazioni sul servizio
  </span>
</mds-details>

<!-- CORRECT -->
<mds-details>
  <mds-icon slot="icon" name="mi/baseline/info"></mds-icon>
  <mds-text typography="h6" slot="title">Informazioni sul servizio</mds-text>
</mds-details>

Do Not Listen for Native click to Detect Toggle

Clicking the header triggers mdsDetailsChange with the new state. Listening for raw click on the host or its shadow parts is fragile - it fires on every sub-element click, may not bubble out of shadow DOM as expected, and gives you no reliable open/closed state.

<!-- INCORRECT -->
<mds-details id="det">
  <mds-text typography="h6" slot="title">Dettaglio</mds-text>
</mds-details>

<script>
  // Do not do this - fires on any click, no open/closed state
  document.getElementById('det').addEventListener('click', () => {
    console.log('click rilevato');
  });
</script>

<!-- CORRECT -->
<script>
  document.getElementById('det').addEventListener('mdsDetailsChange', (e) => {
    console.log('Aperto:', e.detail); // true | false
  });
</script>

Do Not Pierce the Shadow DOM to Style Internals

The only supported customization surface is the three documented --mds-details-* CSS custom properties and the three documented shadow parts (header, title, content). Targeting undocumented class names or using >>> couples your code to the internal implementation and will break on minor releases.

/* INCORRECT */
mds-details >>> .helper-icon {
  fill: red;
}
mds-details >>> .header {
  background: yellow;
}

/* CORRECT */
mds-details {
  --mds-details-helper-icon-color: rgb(var(--magma-danger-fg));
  --mds-details-duration: 200ms;
}
mds-details::part(header) {
  background: rgb(var(--magma-surface-muted));
}