Common incorrect uses of <mds-list> and <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 Replace <mds-list> with a Native <ul> or <ol>

Using a raw list element bypasses the design-system layout, typography defaults, and FOUC handling built into the component pair.

<!-- INCORRECT -->
<ul>
  <li>Primo elemento</li>
  <li>Secondo elemento</li>
</ul>

<!-- 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 of <mds-list-item>

The default slot of <mds-list-item> accepts a plain text string only; placing HTML elements or other components there is explicitly discouraged in the component’s API and can break layout and compound-component communication.

<!-- INCORRECT -->
<mds-list>
  <mds-list-item>
    <strong>Allegato 1</strong> - Contratto firmato
  </mds-list-item>
</mds-list>

<!-- CORRECT -->
<mds-list>
  <mds-list-item>Allegato 1 - Contratto firmato</mds-list-item>
</mds-list>

Do Not Use <mds-list-item> Outside <mds-list>

<mds-list-item> is a compound child designed to work exclusively inside <mds-list>. Using it standalone or wrapping it in a plain <div> breaks the accessible list context.

<!-- INCORRECT -->
<div class="my-list">
  <mds-list-item>Voce autonoma</mds-list-item>
</div>

<!-- CORRECT -->
<mds-list>
  <mds-list-item>Voce autonoma</mds-list-item>
</mds-list>

Do Not Slot <mds-icon> to Override the Bullet

The icon prop on <mds-list-item> is the supported way to change the leading glyph. Slotting <mds-icon> into the default slot puts it inline in a text-only slot, misaligned, while the default bullet still renders.

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

<!-- CORRECT -->
<mds-list>
  <mds-list-item icon="mi/baseline/check">Voce completata</mds-list-item>
</mds-list>

Do Not Add Non-Item Children Directly to <mds-list>

The default slot of <mds-list> is documented to receive <mds-list-item> elements. Mixing in headings, paragraphs, or other components breaks the expected structure and removes the semantic list context.

<!-- INCORRECT -->
<mds-list>
  <mds-text typography="h6">Documenti richiesti</mds-text>
  <mds-list-item>Documento d'identita'</mds-list-item>
  <mds-list-item>Codice fiscale</mds-list-item>
</mds-list>

<!-- CORRECT -->
<mds-text typography="h6">Documenti richiesti</mds-text>
<mds-list>
  <mds-list-item>Documento d'identita'</mds-list-item>
  <mds-list-item>Codice fiscale</mds-list-item>
</mds-list>

Do Not Apply an Invalid typography Value to <mds-list-item>

mds-list-item.typography accepts TypographyInfoType | TypographyReadType - the allowed values are caption, detail, label, option, paragraph, and tip. Heading values such as 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 non valido</mds-list-item>
</mds-list>

<!-- CORRECT -->
<mds-list>
  <mds-list-item typography="paragraph">Testo valido</mds-list-item>
</mds-list>