Avatar Group — GCash DS Assessment

KeepNeeds Refinement

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

Keep — all structural issues resolved

All four DS Health traits pass and nothing is open. layout has semantic values, an overflow variant covers groups larger than four, and the inner avatars are instances of the canonical Avatar.

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.

Live Preview

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.

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

Component Playground

Layout

Typography

Colors

Installation Planned API

iOS — Swift Package Manager

.package(url: "https://github.com/AY-Org/eb-ds-ios", from: "1.0.0")

Android — Gradle (Kotlin DSL)

implementation("com.eastblue.ds:avatar:1.0.0")

Import

import EastBlueDS
import com.eastblue.ds.avatar.*

Property Mapping

Figma Property	SwiftUI	Compose
layout — pair, overflow, quad, trio	`.ebLayout(.pair / .overflow / .quad / .trio)`	`layout = EBAvatarGroupLayout.Pair / Overflow / Quad / Trio`

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
)

Requirement	iOS	Android
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 people in a list item, header or shared-with indicator.

Don't

Don’t use it for one person — use Avatar.

Do

Use the overflow layout, with a “+N” badge, when there are more than four people.

Don't

Don’t squeeze more than four avatars into the group.

Do

Give the group one accessibility label that lists everyone.

Don't

Don’t let each avatar announce separately — it creates VoiceOver and 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	Ready	Property is `layout` with semantic values — `pair`, `trio`, `quad`, `overflow`. Clean native enum mapping.
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 `layout=pair/trio/quad` don't match a dynamic native list — API should accept an array.
C5	Interaction State Coverage	Ready	`layout=overflow` shows three avatars and a "+N" badge in the fourth slot, covering groups larger than four.
C6	Asset & Icon Quality	Ready	Inner avatars are instances of the canonical Avatar, so changes to Avatar carry through.

Variants Inventory (4 total)

1 layout setting × 4 values (pair, overflow, quad, trio) = 4 variants.

layout	Node ID	Size	Notes
pair	18276:4555	48 × 48	2 avatars — diagonal
trio	18276:4558	48 × 48	3 avatars — triangle
quad	18276:4562	48 × 48	4 avatars — 2×2 grid
overflow	18276:4585	48 × 48	3 avatars + "+N" overflow badge

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

Component Playground

Layout

VStack

Typography

Colors

Do

Don't

Do

Don't

Do

Don't