# Avatar

> A person: their photo or initials, in a colour that stays theirs everywhere. Beside a name it carries their film role; in a stack it shows who else is here and where.

Source: https://kwark.space/designSystem/components/avatar

## Usage

### What it is
A circle with a person's photo, or their initials on their colour. The colour is chosen from a fixed set by a hash of the person's id (`UserAvatar.tsx`), so Mira is the same colour on her avatar, her cursor in the screenplay and her comment pins, on every device, forever.

### Three uses
| Use | Component | Example |
|---|---|---|
| Alone | `UserAvatar` | The account button, a comment's author |
| With a name and role | `kw-person` (Ready for Kwark) | The project's people list, sharing, a call sheet's crew |
| A stack | `PresenceBar` | Who else is in the project right now |

### The Kwark idea: the role, not the account
On a film, people know each other by what they do. In sharing and the people list, the avatar sits with the person's name and their **film role** in the quiet line (*1st assistant director*, *Gaffer · Camera and Light, read only*), because access in Kwark follows the role (Decision 0042). In presence, the line says *where* they are (*here now, in Scene 12*), and the stack's tooltips name the module (*Aanya Rao, in the schedule*).

### Presence
- A 10px dot at the lower right in `--k-ok` means here now. Away is a ring, and the avatar drops to 55%.
- The presence stack takes no room when nobody else is here.
- It shows up to three faces and a **+N** button that lists everyone with where they are.
- Presence is never a reason for a notification. Kwark is a safe, private place (Decision 0001): people are not watched; nothing records how long anyone spent anywhere.

## Style

### Anatomy

**UserAvatar**
1. 24 · 32 · 40px circles (sm, md, lg); 56px (`--xl`) only on a person's own page. 1px border at 10% of the text colour.
2. A photo with `object-fit: cover`, or initials: the first letters of two words, upper case, Poppins 700, on the person's colour at 20%, letters at 70% of the colour into `--k-text`. One-word names take their first two letters.
3. If the photo fails to load, the initials replace it (`onError`).

**Person** (`kw-person`)
1. The avatar, 10px gap, then the name (Poppins 500 14px) and one line (12px `--k-text-2`): role, then access or where they are.
2. **Here**: a 10px `--k-ok` dot with a 2px `--k-bg` ring at the lower right. **Away**: a 1.5px ring and the avatar at 55%.

**Presence** (`PresenceBar`)
1. 26px marks, each tucked 7px under the one before, a 2px `--k-bg` ring.
2. The peer colour as a solid fill and `--k-peer-ink` initials, 11px 600 (the app draws 10px).
3. **+N** on `--k-surface` in `--k-text-2`; it is a button.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-peer` | #79a9e8 |  |
| `--k-peer-ink` | #14161a |  |
| `--k-series-1` | var(--k-cal-writing) |  |
| `--k-series-2` | var(--k-cal-rehearsal) |  |
| `--k-series-3` | var(--k-cal-recce) |  |
| `--k-series-4` | var(--k-cal-reading) |  |
| `--k-bg` | #f8fafc | #191919 |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-ok` | #2c6e49 | #6cc08a |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-fs-meta` | 12px |  |
| `--k-fs-body` | 14px |  |
| `--k-fs-title` | 16px |  |
| `--k-fs-dense` | 11px |  |

## Code

### React

In the Kwark app: `import UserAvatar from '@/components/ui/UserAvatar'`.

```tsx
<UserAvatar user={{ id: mira.uid, displayName: 'Mira Rao', avatarUrl: mira.photoURL }} size="lg" />
<PresenceBar peers={peers} />   // components/presence/PresenceBar.tsx
```

| Prop | Type | Notes |
|---|---|---|
| `user` | `{ id: string; displayName?: string; avatarUrl?: string; email?: string }` | The id chooses the colour; the name gives the initials and the accessible name. |
| `size` | `'sm' \| 'md' \| 'lg'` | 24, 32, 40px |
| `className` | `string` |  |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div style="display:flex;flex-wrap:wrap;gap:12px;align-items:center">
  <span class="kw-avatar kw-avatar--sm" style="--kw-peer:var(--k-series-2)" role="img" aria-label="Aanya Rao">AR</span>
  <span class="kw-avatar" style="--kw-peer:var(--k-series-1)" role="img" aria-label="Mira Rao">MR</span>
  <span class="kw-avatar kw-avatar--lg" style="--kw-peer:var(--k-series-4)" role="img" aria-label="Kabir Shah">KS</span>
  <span class="kw-avatar kw-avatar--xl" style="--kw-peer:var(--k-series-3)" role="img" aria-label="Devika Nair">DN</span>
</div>
<div class="kw-people">
  <span class="kw-person"><span class="kw-avatar-wrap"><span class="kw-avatar kw-avatar--lg" style="--kw-peer:var(--k-series-1)" aria-hidden="true">MR</span><i class="kw-avatar-wrap__here" aria-hidden="true"></i></span><span class="kw-person__text"><span class="kw-person__name">Mira Rao</span><span class="kw-person__role">Writer · here now, in Scene 12</span></span></span>
  <span class="kw-person"><span class="kw-avatar-wrap is-away"><span class="kw-avatar kw-avatar--lg" style="--kw-peer:var(--k-series-2)" aria-hidden="true">AR</span><i class="kw-avatar-wrap__here" aria-hidden="true"></i></span><span class="kw-person__text"><span class="kw-person__name">Aanya Rao</span><span class="kw-person__role">1st assistant director · last here 14:12</span></span></span>
  <span class="kw-person"><span class="kw-avatar kw-avatar--lg" style="--kw-peer:var(--k-series-4)" aria-hidden="true">KS</span><span class="kw-person__text"><span class="kw-person__name">Kabir Shah</span><span class="kw-person__role">Gaffer · Camera and Light, read only</span></span></span>
</div>
<span class="kw-avatar-stack" role="group" aria-label="4 other people in Blank Pages">
  <span class="kw-avatar" style="--kw-peer:var(--k-series-1)" title="Mira Rao, in the screenplay">MR</span>
  <span class="kw-avatar" style="--kw-peer:var(--k-series-2)" title="Aanya Rao, in the schedule">AR</span>
  <span class="kw-avatar" style="--kw-peer:var(--k-series-3)" title="Devika Nair, in Characters">DN</span>
  <button class="kw-avatar kw-avatar--more" type="button" aria-label="1 more person here: show everyone">+1</button>
</span>
```

## Accessibility

### Names
- An avatar alone has the person's name as its accessible name (`alt` on the photo, `role="img"` and `aria-label` on initials). Beside a visible name it is `aria-hidden`.
- A stack is a named group (*4 other people in Blank Pages*); each mark's `title` says who and where, and the **+N** button opens the full list, which is the accessible source.
- Presence state is in words in the list (*here now*, *last here 14:12*), never only in the dot.

### Contrast and focus
- Initials meet 4.5:1 on their wash in light and dark; the solid presence marks use `--k-peer-ink`.
- The **+N** button shows a 2px `--k-focus` ring above its neighbours.

## For agents

### Rules

- **Must** derive the avatar colour from a stable id, so a person keeps one colour on avatar, cursor and pins.
- **Always** give an avatar the person's name as its accessible name, or hide it when the name is beside it.
- **Always** show the film role in the line beside a person in sharing and people lists (Decision 0042).
- **Must** make "+N" a button that lists everyone with where they are.
- **Never** use presence to notify, track time or rank people; Kwark is a safe, private place (Decision 0001).

### AI readiness test

**Task:** Show who can open the Day 7 call sheet and who is looking at it now.

**Give the agent:** This page, Sharing and roles pattern, Decision 0042.

**Constraint:** Some crew have no photo; one has a one-word name.

**A reliable answer:**
- Person rows with avatar, name and film role
- Initials from two words or the first two letters
- Colour from the user id
- Here dot plus "here now" in words
- A presence stack of 3 and a +N button
