She stops the playhead on a frame nobody remembers filming.
Mira<div class="kw-presence-layer kw-card" style="width:100%;height:120px">
<p style="margin:0;font-family:var(--k-font-screenplay)">She stops the playhead on a frame<span class="kw-caret-peer" data-name="Arjun" style="--kw-peer:var(--k-cal-recce)"></span> nobody remembers <span class="kw-select-peer">filming</span>.</p>
<span class="kw-cursor" style="left:62%;top:58px"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 1.5 14 8l-5.2 1.3L6.4 14z" fill="currentColor"/></svg><span class="kw-cursor__name">Mira</span></span>
</div>
<div class="kw-presence-bar"><span class="kw-avatar-stack"><span class="kw-avatar">M</span><span class="kw-avatar" style="--kw-peer:var(--k-cal-recce)">A</span></span>2 others here</div>
When to use
On shared surfaces where people work at the same time: the screenplay page, the outline board, the stripboard. Positions are measured as a fraction of the page, so a cursor lands on the same word for everybody whatever their window size.
When not to
- Never in private spaces (private research, Dailies).
- Never to show who is “idle”. Kwark has no idle curtain (Decision 0012).
Anatomy in use
- Pointer: an arrow in the person’s colour, with their name in a tag; it moves with a 90ms ease so movement reads as a hand.
- Caret: a 2px line with the name above.
- Selection: a 28% wash of their colour.
- Bar: avatars with a ring in each person’s colour, and 2 others here.
- Against the right or bottom edge the name flips inside, so no arrow belongs to nobody.
Writing
Name tags use first names. The bar counts others, not you.
Mira tag beside her pointer, flipped inside at the page edge.
A pointer that blocks clicks, or “Arjun is idle”.
Anatomy
Layer fills its positioned parent with pointer-events: none, z-index 40. Name tag 11px 600 on the peer colour with --k-peer-ink.
Tokens
| Token | Light | Dark |
|---|---|---|
--k-peer |
#79a9e8 | |
--k-peer-ink |
#14161a | |
--k-bg |
#f8fafc | #191919 |
--k-cal-recce |
#4d6a7a | #83aac0 |
React
In the Kwark app: import { PresenceCursors } from '@/components/presence/PresenceCursors'.
<div ref={usePointerSurface('script')} style={{ position: 'relative' }}>
<PresenceCursors surface="script" />
</div>
<PresenceBar people={peers} max={5} />
| Prop | Type | Notes |
|---|---|---|
surface |
string |
a fraction of this element lands on the same word for everybody |
people |
Peer[] |
PresenceBar |
max |
number |
avatars before “+n” |
HTML and CSS
Works anywhere with kwark.css.
<div class="kw-presence-layer kw-card" style="width:100%;height:120px">
<p style="margin:0;font-family:var(--k-font-screenplay)">She stops the playhead on a frame<span class="kw-caret-peer" data-name="Arjun" style="--kw-peer:var(--k-cal-recce)"></span> nobody remembers <span class="kw-select-peer">filming</span>.</p>
<span class="kw-cursor" style="left:62%;top:58px"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 1.5 14 8l-5.2 1.3L6.4 14z" fill="currentColor"/></svg><span class="kw-cursor__name">Mira</span></span>
</div>
<div class="kw-presence-bar"><span class="kw-avatar-stack"><span class="kw-avatar">M</span><span class="kw-avatar" style="--kw-peer:var(--k-cal-recce)">A</span></span>2 others here</div>
- Cursors are decorative to assistive tech; the bar announces arrivals politely (“Arjun joined”).
- Under reduced motion pointers jump instead of easing.
- Peer colours keep
--k-peer-inktext at 4.5:1.
Rules
- Never let presence layers take pointer events.
- Must measure positions against the page, not the window.
- Never show presence in private spaces or label anyone idle.
AI readiness test
Task. Show collaborators on the stripboard.
Give the agent. Presence cursor, Stripboard strip, Collaboration pattern.
Constraint. Two people may drag strips at once.
A reliable answer
- Pointers over the board, no pointer events
- A dragged strip shows who holds it
- Positions relative to the board
- Bar counts others