FixNeeds Refinement
Avatar Group Component link

Stacked or overlapping avatars used to show participant lists — conversation members, shared documents, collaboration indicators.

All structural issues resolved
Property renamed to layout with semantic values ✓. Overflow variant added ✓. Inner avatars repointed to canonical Avatar via instance swap ✓. Only C7 (Code Connect) remains — tracked universally across all components.
In Context

How the avatar group appears in a real product screen — conversation list where grouped chats display stacked avatars (DX Team, David's Surprise Party) alongside single-avatar threads.

Avatar Group component shown in the GCash messaging/chat list, where group conversations display 2–3 stacked circular avatars
Live Preview
DMLM
Properties
layout
DS Health
Reusable
Pass
Fits participant lists and collaboration indicators. 4 variants (pair/trio/quad/overflow) cover 2–4 visible avatars plus "+N" overflow for larger groups. Fixed 48×48 container — suitable for most list/row contexts.
Self-contained
Pass
Group carries its own overlap positioning, border overlap treatment, and fixed dimensions. All colors token-bound.
Consistent
Pass
Property renamed from no. of initals → layout with semantic values (pair/trio/quad/overflow). C2 resolved. Inherits the main/avatar/brand/intials typo from Avatar's shared variable collection (tracked under Avatar, not an Avatar Group blocker).
Composable
Pass
All inner avatars are instances of the canonical Avatar component (17143:4488). Changes to Avatar now propagate to Avatar Group automatically. Compositional inheritance restored.
Behavior
State iOS Android Figma Property Notes
2 avatars Yes Yes layout=pair Diagonal overlap — top-left + bottom-right
3 avatars Yes Yes layout=trio Triangle arrangement
4 avatars Yes Yes layout=quad 2×2 grid
Overflow (5+) Yes Yes layout=overflow 3 avatars + "+N" badge in bottom-right slot. Uses the same default/light style as the avatar it replaces.
Pressed / Disabled N/A N/A — Display-only. Tap behavior handled by parent container.
Resolved Issues
  • Property renamed: no. of initals → layout with semantic values (pair/trio/quad/overflow). Fixes typo, removes spaces/dots, replaces pseudo-numeric strings with true enum values. Maps cleanly to SwiftUI EBAvatarGroupLayout.pair/.trio/.quad/.overflow / Compose EBAvatarGroupLayout.Pair etc. C2 Fixed
  • Overflow variant layout=overflow added — bottom-right slot shows "+N" badge instead of a 4th avatar. Handles groups larger than 4. C5 Fixed
  • Inner avatars repointed via instance swap to the canonical Avatar component (17143:4488). Previously referenced a duplicate Avatar at 21:94766 — now all 4 variants inherit from the canonical source. Compositional pattern restored: changes to Avatar will propagate here automatically. C6 Fixed
Open Issues
  • Code Connect mappings not registered. Structural work (count → layout rename, overflow variant, instance swap to canonical Avatar) is complete — registration can proceed. C7 · Code Connect Linkability
Design Recommendations
  • Add size variants. Current 48×48 container is fixed — bigger groups (5+ avatars) benefit from a larger container for readability. Propose groupSize = small | medium | large with appropriate inner avatar sizes. Property
  • Deprecate the duplicate Avatar at 21:94766. Now that Avatar Group points at the canonical 17143:4488, the duplicate should be marked deprecated and removed in a future DS cleanup pass. Family
Layouts
Pair — 2 avatars
DES DEV

Two avatars placed diagonally. Top-left uses dark-initials (brand), bottom-right uses initials-light (default).

DMLM
Properties
Layout
Properties
Variant Pair
Avatar count 2
Container 48 × 48
Colors
Brand bg #005CE5
Brand initials #FFFFFF
Default bg #F6F9FD
Default initials #2340A9
Border (all) #E5EBF4
Layout
Container 48 × 48
Inner avatar 24 × 24
Inner radius 12px (circle)
Inner border 1.5px solid
Overlap offset 16px diagonal
Typography
Initials style Primary/Label/Bold/Small
Font Proxima Soft Bold
Size/lh 10px / 12px
Colors by State

Inner avatars use the same tokens as the main Avatar component. See Avatar / Style tab for the full token reference.

Role Token Value
Brand avatar bg main/avatar/brand/bg #005CE5
Brand avatar border main/avatar/brand/border #E5EBF4
Brand avatar initials main/avatar/brand/intials library typo #FFFFFF
Default avatar bg main/avatar/default/bg #F6F9FD
Default avatar border main/avatar/default/border #E5EBF4
Default avatar initials main/avatar/default/initials #2340A9
Trio — 3 avatars
DES DEV

Three avatars in a triangular arrangement. Two on top (dark + dark), one default at bottom.

DMLMAB
Properties
Layout
Properties
Variant Trio
Avatar count 3
Container 48 × 48
Colors
Brand bg #005CE5
Brand initials #FFFFFF
Default bg #F6F9FD
Default initials #2340A9
Border (all) #E5EBF4
Layout
Container 48 × 48
Inner avatar 24 × 24
Inner radius 12px (circle)
Inner border 1.5px solid
Overlap offset 12px horizontal, 24px vertical
Typography
Initials style Primary/Label/Bold/Small
Font Proxima Soft Bold
Size/lh 10px / 12px
Layout
Role Token
Container size 48 × 48
Inner avatar size 24 × 24
Inner avatar radius 12px
Inner avatar border 1.5px solid
Overlap offset (2 avatars) 16px diagonal
Overlap offset (3 avatars) 12px horizontal, 24px vertical
Overlap offset (4 avatars) 24px grid step
Quad — 4 avatars
DES DEV

Four avatars in a 2×2 grid. Top row: brand + brand. Bottom row: default + default.

DMLMABCD
Properties
Layout
Properties
Variant Quad
Avatar count 4
Container 48 × 48
Colors
Brand bg #005CE5
Brand initials #FFFFFF
Default bg #F6F9FD
Default initials #2340A9
Border (all) #E5EBF4
Layout
Container 48 × 48
Inner avatar 24 × 24
Inner radius 12px (circle)
Inner border 1.5px solid
Overlap offset 24px grid step
Typography
Initials style Primary/Label/Bold/Small
Font Proxima Soft Bold
Size/lh 10px / 12px
Overflow — 3 + "+N" badge
DES DEV

Overflow variant — 3 avatars plus a "+N" badge in the bottom-right position. Use when group has 5 or more members. The "+N" uses the default/light avatar style with overridable text content.

DMLMAB+5
Properties
Layout
Properties
Variant Overflow
Avatar count 3 + "+N"
Badge "+N" (overridable text)
Badge style default/light avatar
Container 48 × 48
Colors
Brand bg #005CE5
Brand initials #FFFFFF
Default bg #F6F9FD
Default initials #2340A9
Border (all) #E5EBF4
Layout
Container 48 × 48
Inner avatar 24 × 24
Inner radius 12px (circle)
Inner border 1.5px solid
Overlap offset 24px grid step · badge in bottom-right
Typography
Initials style Primary/Label/Bold/Small
Font Proxima Soft Bold
Size/lh 10px / 12px
Installation Planned API

iOS — Swift Package Manager

// In Xcode: File → Add Package Dependencies
"https://github.com/AY-Org/eb-ds-ios"

Android — Gradle (Kotlin DSL)

dependencies {
    implementation("com.eastblue.ds:avatar:1.0.0")
}
Property Mapping
Figma PropertySwiftUICompose
layout=pair .ebLayout(.pair) layout = EBAvatarGroupLayout.Pair
layout=trio .ebLayout(.trio) layout = EBAvatarGroupLayout.Trio
layout=quad .ebLayout(.quad) layout = EBAvatarGroupLayout.Quad
layout=overflow .ebLayout(.overflow) layout = EBAvatarGroupLayout.Overflow
SwiftUI
ios/Components/Avatar/EBAvatarGroup.swift
Jetpack Compose
android/components/avatar/EBAvatarGroup.kt
Usage Snippets Planned API
Usage
// Pair / trio / quad — pass avatars, layout auto-detected from count
EBAvatarGroup(avatars: [
    EBAvatar(initials: "DM"),
    EBAvatar(initials: "LM"),
    EBAvatar(initials: "AB")
])

// Overflow — pass full list + max visible count
EBAvatarGroup(avatars: allAvatars, maxVisible: 3)
    .ebLayout(.overflow)
    // renders 3 avatars + "+N" if allAvatars.count > 3
// Pair / trio / quad — pass avatars, layout auto-detected from count
EBAvatarGroup(
    avatars = listOf(
        Avatar(initials = "DM"),
        Avatar(initials = "LM"),
        Avatar(initials = "AB")
    )
)

// Overflow — pass full list + maxVisible
EBAvatarGroup(
    avatars = allAvatars,
    maxVisible = 3,
    layout = EBAvatarGroupLayout.Overflow
)
Accessibility
RequirementiOSAndroid
Accessibility label .accessibilityLabel("3 participants: Dara, Lara, Alex") contentDescription = "3 participants: ..."
Role Decorative if not tappable — use .accessibilityHidden(true) on individual avatars Same — prefer single group-level semantic
Tap target 48 × 48 container meets iOS HIG when whole group is tappable Meets Material 48dp minimum
Usage Guidelines

Do

Use Avatar Group for 2–4 participants in a list item, header, or shared-with indicator.

Don't

Use for counts above 4 without an overflow "+N" badge — users can't infer total count from a cluster alone.

Do

Provide a single group-level accessibility label listing all participants.

Don't

Let each avatar announce separately — creates VoiceOver/TalkBack noise.

Criteria Scorecard
ID Criterion Status Notes
C1 Layer Structure & Naming Ready Semantic names: Avatar, container. Top-level component set uses "Avatar Group" — clean.
C2 Variant & Property Naming Requires Rework Property no. of initals has typo, spaces, and uses string values. Rename to count with integer values.
C3 Token Coverage Ready All colors bound to Avatar's tokens. Inherits the same typo in intials — tracked under Avatar's open issues.
C4 Native Mappability Needs Refinement Maps to stacked avatars via ZStack (iOS) / Box + offset (Compose). Fixed 48×48 and count=2/3/4 don't match a dynamic native list — API should accept an array.
C5 Interaction State Coverage Requires Rework No overflow state for 5+ avatars. Common DS pattern ("+N" badge) is missing.
C6 Asset & Icon Quality Needs Refinement Inner avatars are hardcoded 24px containers, not Avatar component instances. Breaks compositional inheritance — changes to Avatar won't propagate.
C7 Code Connect Linkability Needs Refinement No CLI mappings registered yet.
Variants Inventory (4 total)

layoutNode IDSizeNotes
pair18276:455548 × 482 avatars — diagonal
trio18276:455848 × 483 avatars — triangle
quad18276:456248 × 484 avatars — 2×2 grid
overflow18276:458548 × 483 avatars + "+N" overflow badge
1.0.0 — April 2026Major
Structural closure · node 18276:4554
Property renamed — no. of initals → layout. Values changed from pseudo-numeric strings (2/3/4/5+) to semantic enum values (pair/trio/quad/overflow). Fixes typo, spaces, and dots in one pass. Clean native enum mapping. Fixed
C2 Fixed
Overflow variant added — layout=overflow displays 3 avatars + a "+N" badge in the 4th slot. Handles groups larger than 4. Added
C5 Fixed
Inner avatars repointed to canonical Avatar — Previously referenced a duplicate Avatar component at 21:94766. All 4 variants now use instances of the canonical Avatar at 17143:4488. Compositional inheritance restored. Swapped
C6 Fixed
1.1.0 — April 2026Minor
Structural closure · node 18276:4554
Property renamed — no. of initals → layout. Values changed from pseudo-numeric strings (2/3/4/5+) to semantic enum values (pair/trio/quad/overflow). Fixes typo, spaces, and dots in one pass. Clean native enum mapping. Fixed
C2 Fixed
Overflow variant added — layout=overflow displays 3 avatars + a "+N" badge in the 4th slot. Handles groups larger than 4. Added
C5 Fixed
Inner avatars repointed to canonical Avatar — Previously referenced a duplicate Avatar component at 21:94766. All 4 variants now use instances of the canonical Avatar at 17143:4488. Compositional inheritance restored. Swapped
C6 Fixed
1.0.0 — April 2026Major
Initial Assessment · node 21:94828
Component assessed — 3 variants (2/3/4 avatars) in a fixed 48×48 container. Used for participant lists, collaboration indicators. Documented
Initial
Property name has typo and spaces — no. of initals: missing second "i", contains dot + space. Values are strings instead of integers. Blocks native enum mapping. Fixed in 1.1.0
C2 Fixed
No overflow variant — Component supports only 2/3/4 avatars. Most DS patterns include a "+N" overflow badge for groups larger than the max shown. Fixed in 1.1.0
C5 Fixed
Inner avatars hardcoded, not Avatar instances — The 24px child avatars are duplicated as plain containers inside this component. If the main Avatar changes, this group won't inherit updates. Fixed in 1.1.0
C6 Fixed
Code Connect mappings — No CLI mappings registered yet. Open
C7 Open