Common incorrect uses of <mds-card-media>. 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-card-media> Outside <mds-card>

<mds-card-media> is a compound child designed to live inside <mds-card>. Using it standalone produces unstyled output and breaks the card layout algorithm, which derives its responsive grid from the presence of its region children.

<!-- INCORRECT -->
<mds-card-media>
  <mds-img src="/img/foto.jpg" alt="Foto"></mds-img>
</mds-card-media>

<!-- CORRECT -->
<mds-card>
  <mds-card-media>
    <mds-img src="/img/foto.jpg" alt="Foto"></mds-img>
  </mds-card-media>
</mds-card>

Do Not Set slot="media" Manually

<mds-card-media> self-assigns into the card’s media region via its internal Host slot="media". Adding slot="media" on the element is redundant and signals a misunderstanding of the component’s self-slotting contract.

<!-- INCORRECT -->
<mds-card>
  <mds-card-media slot="media">
    <mds-img src="/img/copertina.jpg" alt="Copertina"></mds-img>
  </mds-card-media>
</mds-card>

<!-- CORRECT -->
<mds-card>
  <mds-card-media>
    <mds-img src="/img/copertina.jpg" alt="Copertina"></mds-img>
  </mds-card-media>
</mds-card>

Do Not Put the Overlay Text in the Default Slot

Text or controls that should appear in front of the media must go in the content named slot. Content placed in the default slot is stacked below the media asset (the host is a grid), not overlaid on it.

<!-- INCORRECT -->
<mds-card>
  <mds-card-media>
    <mds-img src="/img/foto.jpg" alt="Foto"></mds-img>
    <mds-text>Didascalia</mds-text>
  </mds-card-media>
</mds-card>

<!-- CORRECT -->
<mds-card>
  <mds-card-media>
    <mds-img src="/img/foto.jpg" alt="Foto"></mds-img>
    <mds-text slot="content">Didascalia</mds-text>
  </mds-card-media>
</mds-card>

Do Not Place <mds-card-media> Inside a Wrapper Element

mds-card reads its direct children to compute the layout grid and has no default slot. Wrapping <mds-card-media> in a <div> or any other element without a slot hides it from that detection pass and leaves it out of every region: it is not rendered at all.

<!-- INCORRECT -->
<mds-card>
  <div class="media-wrapper">
    <mds-card-media>
      <mds-img src="/img/foto.jpg" alt="Foto"></mds-img>
    </mds-card-media>
  </div>
</mds-card>

<!-- CORRECT -->
<mds-card>
  <mds-card-media>
    <mds-img src="/img/foto.jpg" alt="Foto"></mds-img>
  </mds-card-media>
</mds-card>

Do Not Use a Raw <img> Instead of <mds-img>

Placing a raw <img> in the default slot works visually but bypasses the lazy loading, error state, consumption-preference handling, and accessible-name fallback that mds-img provides.

<!-- INCORRECT -->
<mds-card>
  <mds-card-media>
    <img src="/img/prodotto.jpg" alt="Prodotto">
  </mds-card-media>
</mds-card>

<!-- CORRECT -->
<mds-card>
  <mds-card-media>
    <mds-img src="/img/prodotto.jpg" alt="Prodotto"></mds-img>
  </mds-card-media>
</mds-card>

Do Not Pierce Shadow DOM to Style the Overlay Container

The content div inside the shadow root is exposed as the content shadow part. Use ::part(content) for style overrides, not >>>, /deep/, or internal class selectors - the latter couple your code to the implementation and break on minor releases.

/* INCORRECT */
mds-card-media >>> .content {
  align-items: flex-start;
}

/* CORRECT */
mds-card-media::part(content) {
  align-items: flex-start;
}