# Avatar

Level: molecule.

## Purpose and use

Identify a person or account next to their name, using an icon, image or flag.
Use a full image component for content imagery and a separate button for actions.

## Anatomy, behavior, and accessibility

- A circle or square contains media or the shared avatar icon. Optional top
  count, bottom icon badge and status dot overlay the image independently.
- Image and flag modes fall back to the icon when their source string is empty.
  Size values are string tokens, not arbitrary pixel numbers.
- A nonempty media alternative supplies the root `img` role and accessible name;
  the image also receives that alternative. The icon and overlays are hidden
  from assistive technology. Put essential status/count information in nearby text.
- The component is presentational: it has no selection, click, loading or disabled
  API. Use meaningful image/flag alternatives when they add identity information.

## Open Questions

A failed image request does not trigger the empty-source icon fallback. Broken
media handling and duplicate announcement of root/image alternatives need review
if those scenarios are required.

## Local component contract

This is the active owned contract for `component.avatar`. The API below
is verified against the current local implementation, focused test and story.
The Source commit `0112cba0779a2d2a4b6c7a17243201694344d70a` remains
migration provenance, not the runtime owner.

### Classes and selectors

- `WblAvatarComponent` — `wbl-avatar` (src/app/design-system/patterns/avatar/avatar.component.ts).

### Inputs

- `WblAvatarComponent.size = input<WblAvatarSize>('16')`
- `WblAvatarComponent.shape = input<WblAvatarShape>('circle')`
- `WblAvatarComponent.content = input<WblAvatarContent>('icon')`
- `WblAvatarComponent.imageSrc = input('')`
- `WblAvatarComponent.imageAlt = input('')`
- `WblAvatarComponent.flagSrc = input('')`
- `WblAvatarComponent.flagAlt = input('')`
- `WblAvatarComponent.iconName = input<WblIconName>('avatar')`
- `WblAvatarComponent.topBadge = input(false)`
- `WblAvatarComponent.topBadgeLabel = input<string | number>('1')`
- `WblAvatarComponent.bottomBadge = input(false)`
- `WblAvatarComponent.bottomBadgeIconName = input<WblIconName>('cross-M')`
- `WblAvatarComponent.statusBadge = input(false)`

### Public types and allowed values

```ts
type WblAvatarSize = '16' | '20' | '32' | '40' | '48';
type WblAvatarShape = 'circle' | 'square';
type WblAvatarContent = 'icon' | 'image' | 'flag';
```

Icon-name inputs use `WblIconName` from the [shared icon contract](../atoms/icon.md);
choose a key present in the owned icon pack, not an arbitrary external icon name.

### Models

- None.

### Outputs

- None.

### Slots and projection markers

- The exact template has no Angular content-projection slot.

### Local evidence

- Code: `src/app/design-system/patterns/avatar/avatar.component.ts`.
- Focused test: `src/app/design-system/patterns/avatar/avatar.component.spec.ts`.
- Public export: `export * from './patterns/avatar/avatar.component';` in `src/app/design-system/index.ts`.
- Storybook: `storybook/stories/avatar.stories.ts` (`Design System/Patterns/wbl-avatar`).

## Figma status

This runtime contract does not infer a Figma owner. Assembly evidence, when
verified, is maintained separately through the inventory-linked sidecar.

## Provenance

The archived source-document copy is historical evidence only. The active
resolver is local code/test/export and the exact Storybook story above.