Common incorrect uses of <mds-accordion-item>. 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 mds-accordion-item Outside mds-accordion

The item relies on the parent to assign its id, manage sibling state, and emit coordinated change events. Placed standalone it still toggles, but nothing coordinates it, no mdsAccordionChange is emitted, and its events carry an empty id.

<!-- INCORRECT -->
<mds-accordion-item label="Sezione autonoma">
  <mds-text>Contenuto senza accordeon genitore.</mds-text>
</mds-accordion-item>

<!-- CORRECT -->
<mds-accordion>
  <mds-accordion-item label="Sezione autonoma">
    <mds-text>Contenuto all'interno del genitore corretto.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Do Not Wrap mds-accordion-item in Extra Elements

Items are direct children of mds-accordion by contract (see agents/conventions.md). The parent still finds wrapped items, since it queries every descendant, but the borders of an open item depend on its position among its siblings (:first-child / :last-child), which a wrapper changes.

<!-- INCORRECT -->
<mds-accordion>
  <div class="group">
    <mds-accordion-item label="FAQ 1">
      <mds-text>Risposta alla prima domanda.</mds-text>
    </mds-accordion-item>
  </div>
</mds-accordion>

<!-- CORRECT -->
<mds-accordion>
  <mds-accordion-item label="FAQ 1">
    <mds-text>Risposta alla prima domanda.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Do Not Set label via the Default Slot

label is a required prop that renders the header button text, which is also the button’s accessible name; the default slot holds only the collapsible body content. Putting header text in the slot places it inside the body region and leaves the required label prop empty, breaking both layout and accessibility.

<!-- INCORRECT -->
<mds-accordion>
  <mds-accordion-item>
    Dettagli dell'ordine
  </mds-accordion-item>
</mds-accordion>

<!-- CORRECT -->
<mds-accordion>
  <mds-accordion-item label="Dettagli dell'ordine">
    <mds-text>Numero ordine: 12345, data: 01/06/2026.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Do Not Override Open/Close State by Piercing the Shadow DOM

selected is reflected as a host attribute and is writable via JavaScript. Targeting the internal .content div or .icon element via >>> or undocumented class names to show/hide content manually bypasses the coordinated state machine and breaks sibling sync. The documented content part styles the panel body; it does not open it. Setting selected from JavaScript emits no event and does not close the siblings: in single mode, unset the open item yourself.

/* INCORRECT */
mds-accordion-item >>> .content {
  grid-template-rows: 1fr;
}

/* CORRECT - toggle via the reflected property */
const item = document.querySelector('mds-accordion-item#item-0');
item.selected = true;

Do Not Listen for Native click or change Events Instead of the Documented mds* Events

A native click bubbles up from anywhere inside the item, body content included, and carries no state; there is no native change event on this component. The documented events mdsAccordionItemChange, mdsAccordionItemSelect, and mdsAccordionItemUnselect are the designed surface.

<!-- INCORRECT -->
<mds-accordion id="faq">
  <mds-accordion-item label="Domanda 1">
    <mds-text>Risposta 1.</mds-text>
  </mds-accordion-item>
</mds-accordion>

<script>
  document.querySelector('#faq mds-accordion-item').addEventListener('click', () => {
    console.log('clicked - also fires for clicks inside the body');
  });
</script>

<!-- CORRECT -->
<script>
  document.querySelector('#faq mds-accordion-item').addEventListener('mdsAccordionItemChange', (e) => {
    console.log('stato:', e.detail.selected);
  });
</script>

Do Not Use <details>/<summary> Inside the Slot as a Second Disclosure Layer

The item already is a styled disclosure widget. Nesting a native <details> inside the slot creates redundant expand/collapse semantics, duplicates keyboard interactions, and produces conflicting visual states.

<!-- INCORRECT -->
<mds-accordion>
  <mds-accordion-item label="Configurazione">
    <details>
      <summary>Mostra dettagli</summary>
      <p>Parametri avanzati di configurazione.</p>
    </details>
  </mds-accordion-item>
</mds-accordion>

<!-- CORRECT - put content directly in the slot -->
<mds-accordion>
  <mds-accordion-item label="Configurazione">
    <mds-text typography="h6">Parametri avanzati</mds-text>
    <mds-text>Descrizione dei parametri di configurazione avanzata.</mds-text>
  </mds-accordion-item>
</mds-accordion>