Common incorrect uses of <mds-avatar-stack-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 Outside mds-avatar-stack

<mds-avatar-stack-item> is a compound child and relies on its parent for sizing, overlap and the overflow counter. Used standalone, it falls back to the medium size, with no stack container and no size / total control.

<!-- INCORRECT -->
<mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>

<!-- CORRECT -->
<mds-avatar-stack>
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
</mds-avatar-stack>

Do Not Set size on the Item

The child has no size prop; setting it as an attribute has no effect. Control the scale of every item in the stack with the size prop on the parent.

<!-- INCORRECT -->
<mds-avatar-stack>
  <mds-avatar-stack-item initials="mr" size="lg"></mds-avatar-stack-item>
</mds-avatar-stack>

<!-- CORRECT -->
<mds-avatar-stack size="lg">
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
</mds-avatar-stack>

Do Not Duplicate count When Using total

When total is set on the parent it auto-appends the overflow item. Adding a manual count item on top produces a double overflow indicator.

<!-- INCORRECT -->
<mds-avatar-stack total="12">
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac"></mds-avatar-stack-item>
  <mds-avatar-stack-item count="10"></mds-avatar-stack-item>
</mds-avatar-stack>

<!-- CORRECT - let the parent compute and render the overflow badge -->
<mds-avatar-stack total="12">
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac"></mds-avatar-stack-item>
</mds-avatar-stack>

Do Not Wrap Items in a Div

The parent counts only its direct mds-avatar-stack-item children to compute the overflow. Wrapping items in a <div> or any other element breaks that count, and the parent’s size (applied with ::slotted) no longer reaches the items.

<!-- INCORRECT -->
<mds-avatar-stack total="5">
  <div>
    <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
    <mds-avatar-stack-item initials="ac"></mds-avatar-stack-item>
  </div>
</mds-avatar-stack>

<!-- CORRECT - items must be direct slot children -->
<mds-avatar-stack total="5">
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac"></mds-avatar-stack-item>
</mds-avatar-stack>

Do Not Use tone and variant as the Only Differentiator

tone and variant style the placeholder background but are overridden by initials and ignored when src is present. Relying on color alone to identify users is not accessible. Always provide initials or src.

<!-- INCORRECT - color-only identity, no label for screen readers -->
<mds-avatar-stack>
  <mds-avatar-stack-item variant="blue"></mds-avatar-stack-item>
  <mds-avatar-stack-item variant="green"></mds-avatar-stack-item>
</mds-avatar-stack>

<!-- CORRECT - initials provide a visible and screen-reader-friendly label -->
<mds-avatar-stack>
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac"></mds-avatar-stack-item>
</mds-avatar-stack>

Do Not Use an Invalid tone Value

tone on this component accepts only weak (default) and strong - the ToneMinimalVariantType set. Values like outline or text, valid on other components, match no style here: the avatar renders as with strong, not with the weak default.

<!-- INCORRECT (tone="outline" is not in ToneMinimalVariantType) -->
<mds-avatar-stack>
  <mds-avatar-stack-item initials="mr" tone="outline"></mds-avatar-stack-item>
</mds-avatar-stack>

<!-- CORRECT -->
<mds-avatar-stack>
  <mds-avatar-stack-item initials="mr" tone="strong"></mds-avatar-stack-item>
</mds-avatar-stack>