Common incorrect uses of <mds-avatar-stack>. 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 Place <mds-avatar-stack-item> Inside a Wrapper Element

The parent counts only its direct mds-avatar-stack-item children. An intermediate wrapper breaks that count, so the overflow counter is wrong, and the parent’s size (applied with ::slotted) does not reach the wrapped items.

<!-- INCORRECT -->
<mds-avatar-stack total="10">
  <div class="group">
    <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 -->
<mds-avatar-stack total="10">
  <mds-avatar-stack-item initials="mr" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac" tone="weak"></mds-avatar-stack-item>
</mds-avatar-stack>

Do Not Slot a Raw <mds-avatar> Directly

<mds-avatar-stack-item> is the correct child for this compound component - it handles sizing, border, overlap offset, and count badge rendering. Slotting a bare <mds-avatar> skips all of that wiring.

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

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

Do Not Set total Lower Than or Equal to the Child Count

When total does not exceed the number of slotted items, no overflow badge is rendered. Setting total lower than the child count is also misleading about group size and produces no visible effect.

<!-- INCORRECT - total equals child count, badge never appears -->
<mds-avatar-stack total="3">
  <mds-avatar-stack-item initials="mr" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="er" tone="weak"></mds-avatar-stack-item>
</mds-avatar-stack>

<!-- CORRECT - total exceeds slotted count by the hidden members -->
<mds-avatar-stack total="10">
  <mds-avatar-stack-item initials="mr" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="er" tone="weak"></mds-avatar-stack-item>
</mds-avatar-stack>

Do Not Add count Manually When total Is Set

count on <mds-avatar-stack-item> is reserved for the auto-generated overflow badge; the parent computes and appends it when total is provided. Adding a count item by hand alongside total results in a duplicate badge.

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

<!-- CORRECT - let the parent handle the badge -->
<mds-avatar-stack total="10">
  <mds-avatar-stack-item initials="mr" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac" tone="weak"></mds-avatar-stack-item>
</mds-avatar-stack>

Do Not Size Individual Items - Size the Parent

<mds-avatar-stack-item> exposes no size prop; dimensions are driven by the parent’s size. Overriding size with inline CSS on individual items breaks the uniform overlap geometry the component calculates.

<!-- INCORRECT -->
<mds-avatar-stack>
  <mds-avatar-stack-item initials="mr" style="width: 48px; height: 48px;"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac" style="width: 48px; height: 48px;"></mds-avatar-stack-item>
</mds-avatar-stack>

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

Customize via Documented Vars, Not Internal Selectors

The supported customization surface is the --mds-avatar-stack-* CSS custom properties on the parent. Targeting shadow internals via >>> or undocumented ::part() names couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-avatar-stack >>> .avatar {
  border-color: blue;
}

/* CORRECT */
mds-avatar-stack {
  --mds-avatar-stack-background: rgb(var(--magma-accent-emphasis));
  --mds-avatar-stack-count-background-color: rgb(var(--magma-wash-soft));
}