Common incorrect uses of <mds-img>. 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-img> with a Raw <img> Element

Using a plain <img> bypasses the built-in error fallback, consumption-aware loading, and accessible-name defaults that <mds-img> provides.

<!-- INCORRECT -->
<img src="/assets/img/copertina.jpg" alt="Copertina" loading="lazy">

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

Do Not Omit alt When the Image Conveys Information

<mds-img> derives a fallback alt from the filename when none is supplied, but a raw filename slug is not a meaningful description. Supply a descriptive alt for every content image.

<!-- INCORRECT -->
<mds-img src="/assets/img/report-annuale-2024.jpg"></mds-img>

<!-- CORRECT -->
<mds-img src="/assets/img/report-annuale-2024.jpg" alt="Report annuale 2024"></mds-img>

Do Not Listen to the Native load or error Events

The inner <img> lives in shadow DOM, and its native load and error events do not bubble, so a listener on the host never receives them. Use the documented mdsImgLoadSuccess and mdsImgLoadError custom events instead.

<!-- INCORRECT -->
<mds-img id="foto" src="/assets/img/foto.jpg" alt="Foto"></mds-img>
<script>
  document.getElementById('foto').addEventListener('load', handler);
  document.getElementById('foto').addEventListener('error', handler);
</script>

<!-- CORRECT -->
<mds-img id="foto" src="/assets/img/foto.jpg" alt="Foto"></mds-img>
<script>
  document.getElementById('foto').addEventListener('mdsImgLoadSuccess', handler);
  document.getElementById('foto').addEventListener('mdsImgLoadError', handler);
</script>

Do Not Use srcset-consumption Without a Meaningful Bucket Tag

Each entry in srcset-consumption must end with low, medium, or high. Entries with any other tag are silently ignored, leaving that consumption level without a source.

<!-- INCORRECT -->
<mds-img
  srcset-consumption="/assets/img/small.jpg 1x, /assets/img/large.jpg 2x"
  alt="Immagine"
></mds-img>

<!-- CORRECT -->
<mds-img
  srcset-consumption="/assets/img/small.jpg low, /assets/img/medium.jpg medium, /assets/img/large.jpg high"
  alt="Immagine"
></mds-img>

Do Not Pierce the Shadow DOM to Style the Inner <img>

Targeting internal selectors with >>>, /deep/, or undocumented class names couples your code to the shadow DOM structure and will break on minor releases. Use --mds-img-* CSS custom properties for color theming, and the documented ::part(media) for geometry/object-fit overrides.

/* INCORRECT */
mds-img >>> img {
  border-radius: 8px;
  object-fit: cover;
}

/* CORRECT */
mds-img::part(media) {
  border-radius: var(--magma-radius-md);
  object-fit: cover;
}

Do Not Set loading="eager" for Every Image

loading defaults to "lazy", which is the correct behavior for most images. Setting "eager" on all images forces the browser to download every image immediately, degrading performance. Reserve "eager" for images that are visible on first paint.

<!-- INCORRECT -->
<mds-img src="/assets/img/thumbnail-1.jpg" alt="Anteprima 1" loading="eager"></mds-img>
<mds-img src="/assets/img/thumbnail-2.jpg" alt="Anteprima 2" loading="eager"></mds-img>
<mds-img src="/assets/img/thumbnail-3.jpg" alt="Anteprima 3" loading="eager"></mds-img>

<!-- CORRECT -->
<mds-img src="/assets/img/hero.jpg" alt="Hero principale" loading="eager"></mds-img>
<mds-img src="/assets/img/thumbnail-1.jpg" alt="Anteprima 1"></mds-img>
<mds-img src="/assets/img/thumbnail-2.jpg" alt="Anteprima 2"></mds-img>