Common incorrect uses of <mds-avatar>. 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 Set variant When initials Is Present

The component derives the background color deterministically from the characters when initials is set, and silently overrides any explicit variant. Setting variant alongside these props is a no-op and misleads readers of the markup.

<!-- INCORRECT -->
<mds-avatar initials="MR" variant="error"></mds-avatar>

<!-- CORRECT -->
<mds-avatar initials="MR"></mds-avatar>

Do Not Use count for Individual Users

count is designed for overflow badges in stacked avatar groups (“+3 more”). Using it to represent a single user’s identity (e.g. an ID number) produces a “+N” label, which is semantically wrong. Use initials for individual users.

<!-- INCORRECT -->
<mds-avatar count="42"></mds-avatar>

<!-- CORRECT - use initials for individual users -->
<mds-avatar initials="GV"></mds-avatar>

Do Not Override Size with Inline width / height Styles

<mds-avatar> keeps a 1:1 aspect ratio internally. Forcing width or height via inline styles or arbitrary CSS bypasses the design token grid and can distort the shape. Use a Magma spacing utility class on the host element instead.

<!-- INCORRECT -->
<mds-avatar src="https://example.com/foto.jpg" style="width: 73px; height: 73px;"></mds-avatar>

<!-- CORRECT -->
<mds-avatar src="https://example.com/foto.jpg" class="w-1600"></mds-avatar>

Do Not Slot <img> to Supply a Profile Photo

<mds-avatar> has no slots - it is a self-contained shadow component. Putting a raw <img> inside it will have no effect; the component will ignore it and show the fallback person glyph. Use the src prop instead.

<!-- INCORRECT -->
<mds-avatar>
  <img src="https://example.com/foto.jpg" alt="Mario Bianchi" />
</mds-avatar>

<!-- CORRECT -->
<mds-avatar src="https://example.com/foto.jpg"></mds-avatar>

Do Not Pierce Shadow DOM to Change Internal Colors

The supported customization surface is the five documented --mds-avatar-* CSS custom properties and, for a deep customisation, the documented parts wrapper, media and icon. Using undocumented part names, >>>, or internal class names to target internals couples your code to the Shadow DOM implementation and breaks on minor releases.

/* INCORRECT */
mds-avatar::part(initials) {
  background-color: hotpink;
}
mds-avatar >>> .initials-text {
  color: white;
}

/* CORRECT */
mds-avatar {
  --mds-avatar-background-color: rgb(var(--magma-accent-emphasis));
  --mds-avatar-color: rgb(var(--magma-accent-on-emphasis));
}

Do Not Use a Raw <img> or <div> as an Avatar

When an avatar-style UI element is needed, reach for <mds-avatar> rather than hand-rolling a circular <img> or <div> with CSS. The component handles lazy loading, load errors, initials fallback, pending state, dark mode, and high-contrast mode automatically.

<!-- INCORRECT -->
<img
  src="https://example.com/foto.jpg"
  alt="Foto di Luca"
  style="border-radius: 50%; width: 48px; height: 48px;"
/>

<!-- CORRECT -->
<mds-avatar src="https://example.com/foto.jpg" class="w-1200"></mds-avatar>