Correct and idiomatic ways to use the <mds-avatar-stack> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Basic Avatar Stack

The canonical form. Slot one <mds-avatar-stack-item> per person directly inside the stack. Each item wraps an internal avatar; no extra wrapper elements are needed.

<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-item initials="er" tone="weak"></mds-avatar-stack-item>
</mds-avatar-stack>

Avatar Stack with Profile Images

Use src on each item when real user photos are available. If the image fails to load, the avatar shows the generic person glyph; while src is set, initials is not displayed.

<mds-avatar-stack>
  <mds-avatar-stack-item
    src="/avatars/mario-rossi.jpg"
    initials="mr"
    tone="weak"
  ></mds-avatar-stack-item>
  <mds-avatar-stack-item
    src="/avatars/anna-conti.jpg"
    initials="ac"
    tone="weak"
  ></mds-avatar-stack-item>
  <mds-avatar-stack-item
    src="/avatars/elena-ricci.jpg"
    initials="er"
    tone="weak"
  ></mds-avatar-stack-item>
</mds-avatar-stack>

Sizing the Stack

Use the size prop on the parent to scale the whole stack at once. Do not set individual sizes on the items - the parent drives dimensions, overlap, and border for all children.

<!-- Small - compact lists, comment threads -->
<mds-avatar-stack size="sm">
  <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>

<!-- Medium (default) -->
<mds-avatar-stack size="md">
  <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>

<!-- Large - hero areas, team pages -->
<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>

Overflow Counter via total

When the represented group is larger than the number of visible avatars, set total to the real headcount. The component automatically appends a trailing “+N” badge for the hidden members.

<!-- 5 visible avatars out of a team of 12: shows "+7" badge -->
<mds-avatar-stack total="12">
  <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-item initials="mt" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="jb" tone="weak"></mds-avatar-stack-item>
</mds-avatar-stack>

Per-Item Variant Colors

Each <mds-avatar-stack-item> accepts its own variant, which colors the avatar when it has no initials: initials derive their own color and override it. tone accepts strong or weak (default).

<mds-avatar-stack>
  <mds-avatar-stack-item variant="primary" tone="strong"></mds-avatar-stack-item>
  <mds-avatar-stack-item variant="success" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item variant="warning" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item variant="info" tone="weak"></mds-avatar-stack-item>
</mds-avatar-stack>

Size and Overflow Combined

Combine size and total to produce a large, labelled stack for team-overview sections.

<mds-avatar-stack size="lg" total="25">
  <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-item initials="mt" tone="weak"></mds-avatar-stack-item>
</mds-avatar-stack>

Styling Customization

Style the stack only through its documented --mds-avatar-stack-* CSS custom properties. Set them on the host or a parent selector; use semantic color roles via rgb(var(--magma-<role>)) so dark mode keeps working.

/* Custom ring color and overlap for a card-hero section */
.team-hero mds-avatar-stack {
  --mds-avatar-stack-background: rgb(var(--magma-accent-emphasis));
  --mds-avatar-stack-count-background-color: rgb(var(--magma-wash-soft));
  --mds-avatar-stack-count-color: rgb(var(--magma-text-default));
  --mds-avatar-stack-lg-offset: 2.5;
}