<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>
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-okmeans 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.
Anatomy
UserAvatar
- 24 · 32 · 40px circles (sm, md, lg); 56px (
--xl) only on a person’s own page. 1px border at 10% of the text colour. - 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. - If the photo fails to load, the initials replace it (
onError).
Person (kw-person)
- The avatar, 10px gap, then the name (Poppins 500 14px) and one line (12px
--k-text-2): role, then access or where they are. - Here: a 10px
--k-okdot with a 2px--k-bgring at the lower right. Away: a 1.5px ring and the avatar at 55%.
Presence (PresenceBar)
- 26px marks, each tucked 7px under the one before, a 2px
--k-bgring. - The peer colour as a solid fill and
--k-peer-inkinitials, 11px 600 (the app draws 10px). - +N on
--k-surfacein--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 |
React
In the Kwark app: import UserAvatar from '@/components/ui/UserAvatar'.
<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.
<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>
Names
- An avatar alone has the person’s name as its accessible name (
alton the photo,role="img"andaria-labelon initials). Beside a visible name it isaria-hidden. - A stack is a named group (4 other people in Blank Pages); each mark’s
titlesays 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-focusring above its neighbours.
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