Common incorrect uses of <mds-accordion>. 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 Place Non-Item Children Directly in the Accordion Slot

The default slot of <mds-accordion> is designed exclusively for <mds-accordion-item> elements. Placing raw HTML or other components there bypasses the parent’s selection coordination and breaks the compound component communication.

<!-- INCORRECT -->
<mds-accordion>
  <div>
    <h3>Sezione uno</h3>
    <p>Contenuto della sezione.</p>
  </div>
</mds-accordion>

<!-- CORRECT -->
<mds-accordion>
  <mds-accordion-item label="Sezione uno">
    <mds-text>Contenuto della sezione.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Do Not Use mds-accordion-item Outside mds-accordion

<mds-accordion-item> is a compound child and relies on the parent to assign its id and manage selection state. Used standalone it has no coordinator and its mdsAccordionItemSelect / mdsAccordionItemUnselect events go unanswered.

<!-- INCORRECT -->
<mds-accordion-item label="Domanda frequente">
  <mds-text>Risposta alla domanda.</mds-text>
</mds-accordion-item>

<!-- CORRECT -->
<mds-accordion>
  <mds-accordion-item label="Domanda frequente">
    <mds-text>Risposta alla domanda.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Do Not Listen to Native click or toggle Instead of mdsAccordionChange

A native click bubbles up from anywhere inside the accordion, panel content included, and carries no selection state; there is no native toggle event on this component. Listen for mdsAccordionChange, whose detail.selected holds the open index/indices.

<!-- INCORRECT -->
<mds-accordion id="my-accordion">
  <mds-accordion-item label="Sezione A">
    <mds-text>Contenuto A.</mds-text>
  </mds-accordion-item>
</mds-accordion>
<script>
  document.getElementById('my-accordion').addEventListener('click', (e) => {
    // fires on any click, panel content included, and says nothing about the selection
    console.log('clicked');
  });
</script>

<!-- CORRECT -->
<mds-accordion id="my-accordion">
  <mds-accordion-item label="Sezione A">
    <mds-text>Contenuto A.</mds-text>
  </mds-accordion-item>
</mds-accordion>
<script>
  document.getElementById('my-accordion').addEventListener('mdsAccordionChange', (e) => {
    console.log('Selezione corrente:', e.detail.selected);
  });
</script>

Do Not Mix mds-accordion-item and mds-accordion-timer-item

mds-accordion-timer and its child mds-accordion-timer-item are a separate compound pair. Slotting timer items into a plain accordion (or vice versa) breaks internal event wiring because each parent only listens for its own child’s events.

<!-- INCORRECT -->
<mds-accordion>
  <mds-accordion-timer-item description="Avanzamento automatico">
    <mds-text>Contenuto con timer.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion>

<!-- CORRECT - use mds-accordion-timer with mds-accordion-timer-item -->
<mds-accordion-timer>
  <mds-accordion-timer-item description="Avanzamento automatico">
    <mds-text>Contenuto con timer.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

Do Not Pierce Shadow DOM to Style Internals

The only supported customization surface is the --mds-accordion-* CSS custom properties and the documented ::part() names on mds-accordion-item (content, icon, label). Targeting undocumented internals via >>> or deep class selectors couples code to the Shadow DOM implementation and breaks on minor releases.

/* INCORRECT */
mds-accordion >>> .action {
  font-weight: bold;
}
mds-accordion-item::part(spinner) {
  display: none;
}

/* CORRECT */
mds-accordion {
  --mds-accordion-color: rgb(var(--magma-text-default));
  --mds-accordion-border-color: rgb(var(--magma-accent-border));
}
mds-accordion-item::part(label) {
  font-style: italic;
}