The attachment of discussion and annotation to a specific piece of content, balancing collaborative input with the integrity of the primary experience.
Variants
- Flat: Simple comment lists without nesting
- Threaded: Nested replies supporting conversation depth
Resolution states
Persistent: Comments remain visible until manually resolved
- Supports ongoing discussions and reference
- Useful for documentation and knowledge capture
- Maintains historical context
Ephemeral: Comments fade over time
- Reduces interface clutter for transient feedback
- Suitable for iterative design and development workflows
- Focuses attention on current issues
States
Empty state
- No comments exist yet
- Clear invitation to start discussions
- Might show commenting capabilities subtly
Active commenting
- Comment threads in progress
- Clear visual indicators for commented elements
- Easy navigation between comment locations
Resolved discussions
- Completed or archived comment threads
- Optional visibility controls for resolved items
- Historical context preservation
Draft states
- Unsaved comment composition
- Auto-save and recovery capabilities
- Clear indication of draft vs published status
Examples
Commenting can be integrated into any interface or content type, including:
Text documents
A comment marks its passage without changing the text, and overlapping comments keep separate threads. Later the actor can turn a commented passage into a quote. The words stay where they are, the thread moves to the quote, and other documents can refer to the quote by its identity. This is incremental formalisation applied to one passage: the passage gains structure when it starts to matter, not when the first comment is written. The demo cannot yet turn a quote back into a plain comment.
Domain entities
…
Consequences
- discussion is anchored where it applies and stays out of the content itself, so the primary reading survives an active review
- comments acquire a lifecycle of their own — open, answered, resolved — and something has to say when a thread is finished, or the layer only ever grows
- the thread beside the content is a second place where decisions get made, and whatever was settled there is invisible to anyone reading only the content
- some commented passages start being referred to, not only discussed, and a highlight with a thread is too weak an object for that; the passage needs an identity of its own, without leaving its place in the text or losing its thread
Resources & references
- Ink & Switch / Universal Comments
- Google Docs / Comments
- Notion / Comments, mentions & reactions
- Figma / Comments
Appears in
Making sense at scale
- Marking items while reading, step 3 — Share selected marks with others
Working on the same thing
- Contributing in place, step 2 — Attach the discussion to its place
Related patterns
Precedes
- Status feedback — comments acquire a lifecycle of their own — open, answered, resolved — and something has to say when a thread is finished, or the layer only ever grows
- Incremental formalisation — some commented passages start being referred to, not only discussed, and a highlight with a thread is too weak an object for that; the passage needs an identity of its own, without leaving its place in the text or losing its thread
Complements
- Change review — review talk anchors to the delta rather than to the document at large
- Collaboration — provides broader collaborative context
- Activity log — tracks commenting activity over time
- Notification — alerts users to comment activity
Tangential to
- Conversation — provides dialogue interaction principles
Related to
- Deep linking — Comments get unique URLs
Preceded by
- Annotation — once the marks are visible to others the layer stops being a private reading aid: other people read the actor's attention, and a mark becomes something that can be answered rather than only added to