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

<mds-list-item> is a compound child; it must be a direct default-slot child of <mds-list>. Using it standalone removes the list context that assistive technology relies on.

<!-- INCORRECT -->
<div>
  <mds-list-item>Primo elemento</mds-list-item>
  <mds-list-item>Secondo elemento</mds-list-item>
</div>

<!-- CORRECT -->
<mds-list>
  <mds-list-item>Primo elemento</mds-list-item>
  <mds-list-item>Secondo elemento</mds-list-item>
</mds-list>

Do Not Put HTML Elements in the Default Slot

The default slot is meant for plain text only; nested elements are not stripped, they render inline and can break layout. Use the typography and variant props to control text style instead.

<!-- INCORRECT -->
<mds-list>
  <mds-list-item>
    <strong>Titolo voce</strong>
    <small> - descrizione aggiuntiva</small>
  </mds-list-item>
</mds-list>

<!-- CORRECT -->
<mds-list>
  <mds-list-item typography="detail">Titolo voce - descrizione aggiuntiva</mds-list-item>
</mds-list>

Do Not Slot <mds-icon> to Add a Leading Icon

The icon prop renders the glyph through the shared icon service and positions it correctly. Slotting <mds-icon> puts it in the text-only default slot, where it is misaligned and the default bullet still renders.

<!-- INCORRECT -->
<mds-list>
  <mds-list-item>
    <mds-icon name="mi/baseline/check"></mds-icon>
    Servizio attivo
  </mds-list-item>
</mds-list>

<!-- CORRECT -->
<mds-list>
  <mds-list-item icon="mi/baseline/check">Servizio attivo</mds-list-item>
</mds-list>

Do Not Use a typography Value Outside the Accepted Set

<mds-list-item> accepts only TypographyInfoType | TypographyReadType: caption, detail, label, option, paragraph, tip. Heading values like h1-h6 or action are outside the type and are not checked at runtime: the inner text renders the heading style next to a bullet aligned for body text.

<!-- INCORRECT -->
<mds-list>
  <mds-list-item typography="h3">Titolo sezione</mds-list-item>
  <mds-list-item typography="action">Azione</mds-list-item>
</mds-list>

<!-- CORRECT -->
<mds-list>
  <mds-list-item typography="detail">Voce elenco</mds-list-item>
  <mds-list-item typography="paragraph">Descrizione estesa della voce</mds-list-item>
</mds-list>

Do Not Pierce Shadow DOM to Style the Icon or Text

The supported customization surface is --mds-list-item-icon-margin for layout and ::part(icon) / ::part(text) for the two documented shadow parts. Targeting internals via >>> or undocumented class names couples code to the implementation.

/* INCORRECT */
mds-list-item >>> .icon {
  fill: red;
}

/* CORRECT */
mds-list-item::part(icon) {
  fill: rgb(var(--magma-danger-fg));
}

Do Not Replace <mds-list> + <mds-list-item> with a Raw <ul> + <li>

When a Magma list is needed, use the component pair - not raw HTML. Raw elements bypass the design-system theming, token integration, and high-contrast support.

<!-- INCORRECT -->
<ul>
  <li>Documento ricevuto</li>
  <li>In attesa di approvazione</li>
</ul>

<!-- CORRECT -->
<mds-list>
  <mds-list-item>Documento ricevuto</mds-list-item>
  <mds-list-item>In attesa di approvazione</mds-list-item>
</mds-list>