## When to use

When users need to talk to each other about a specific object — a design, a task, a row, a paragraph. Comments anchor to the object; mentions notify a person; reactions condense agreement without a reply. The three nest: a comment thread carries mentions inside its text and reactions on each message.

## Comment thread

A vertical stack of comments anchored to a parent object. Each row carries author avatar + name + timestamp + body + reactions strip + reply action. Threaded replies indent one level — deeper nesting collapses to "X replies" by default.

Discussion 3 comments · 2 participants
Avery Chen 2 hours ago Should the OKLCH ramp here use the chrome or the data scale? @Kim what's the convention? 2 1 Kim Granlund 1 hour ago Chrome — the data scale is reserved for visualization series. Spec at .claude/docs/specs/component-token-contract.md. 3 Jordan Lee 12 minutes ago Filed a follow-up — adding a lint rule so this doesn't happen again. #linter

## Comment composer

The input field below a thread. Multiline, with attach + mention + emoji affordances inline, and Send / Cancel actions. Submits on Cmd/Ctrl+Enter; Enter inserts a newline.

Cmd + Enter to send

## @-mention picker

Popover that opens after the user types `@`. Shows team members + recently-mentioned at top, fuzzy-filtered by query. Each row carries avatar + name + handle + role tag. Arrow keys navigate; Enter inserts; Esc closes without inserting.

Mention Kim Granlund @kim · Owner Avery Chen @avery · Designer Jordan Lee @jordan · Engineer @team Notify everyone in this workspace

## Reactions bar

The strip of reaction tags under a comment or message. Each tag shows emoji + count; the user's own reaction is highlighted. A trailing "+" opens the picker. Click a count to toggle the user's own reaction; long-press shows who reacted.

👍 4 🎉 2 👀 1 🚀 1

## Reactions picker

The emoji-grid popover that opens from the "+" button. Recent + frequent emojis at top; full categorical grid below; search input above. Arrow + Enter for keyboard; click for pointer.

Frequently used Smileys

## Composition rules

- Comments anchor to an object — every thread has a parent (a doc paragraph, a row, a design selection). The thread surface usually opens beside the object, not in a global modal. Threadless "general comments" are a separate pattern (chat thread, 11a).
- Mentions notify; reactions don't — typing `@name` always pings that user; emoji reactions never do. The semantic gap matters: mentions are an action ("read this"), reactions are an acknowledgment ("seen / agreed").
- Cmd/Ctrl+Enter to send, Enter for newline — comments are multi-line by default. The opposite (Enter to send, Shift+Enter for newline) is correct for chat input (11b) but wrong here.
- Reactions are typed by emoji, not by sentiment — don't normalize "👍" and "🚀" into a `like_count`. Each emoji is its own bucket; counts are per-emoji.
- Resolve, don't delete — threads should be resolvable (collapsed, marked done) but not destructively deleted by default. Audit trail matters.
- Sharing dialogs live in the RBAC domain — the "Share this with…" surface is concept 36e, not a sub-concept of comments. Don't re-author it under collaboration.

## See also

- field-ui · textarea-ui — composer input.
- menu-ui — mention picker surface.
- tag-ui — reaction chips.
- avatar-ui — author identity.
- permissions-sharing — the sharing-dialog surface (concept 36e).
- agent-tool-call — sibling thread-shape (model output, not user comments).