Use mentions for targeted attention inside an existing message, comment, or document; comments for object-attached discussion; threaded discussion for branchable topic conversations; and notification center for cross-object inbox triage.
Use mentions for targeted attention inside an existing message, comment, or document; comments for object-attached discussion; threaded discussion for branchable topic conversations; and notification center for cross-object inbox triage.
Practice the judgment: Imagine this situation: Mention notifications open the object top instead of the exact sentence, comment, thread reply, or action item where the mention appeared. Write the person's goal, choose one of these patterns, and show the state that helps the person continue. Use the decision rules and source trail below to explain your choice.
Review the underlying principle →| Dimension | Mentions | Comments | Threaded discussion | Notification center | Object picker | Typeahead | Activity log | Permission denied state | Review queue |
|---|---|---|---|---|---|---|---|---|---|
| UI or UX | UI + UX - Inline recipient reference with autocomplete, stable recipient identity, notification routing, access checks, and broad-audience safeguards | UI + UX - Object-attached comment composer and comment list with authorship, replies, state, permissions, and moderation | UI + UX - Topic-centered conversation with parent post, reply branches, unread participation state, and thread-level controls | UI + UX - Durable user-opened notification history and action drawer | UI + UX - Existing-entity lookup and selected-object confirmation | UI + UX - Live search-as-you-type result lookup with incremental result preview | UI + UX - Searchable and exportable record of system, user, or administrative events | UI + UX - Authorization and access-boundary state | UI + UX - Actionable queue for triaging many items that need human review |
| UI guidance | Show mention suggestions at the caret with names, handles, avatars, teams, channels, availability or scope hints, permission warnings, and keyboard-highlight state; distinguish exact matches, ambiguous display names, unavailable recipients, and broad-audience mentions. | Render comments as anchored contributions with author identity, timestamp, body, optional attachment or selection context, edited state, reply target, and state labels such as open, resolved, hidden, deleted, or assigned. | Render a threaded discussion around a visible parent topic or parent message, with reply rows that preserve author, timestamp, reply target, branch depth, unread or new state, and thread-scoped actions. | Provide a persistent notification entry point, usually a bell or inbox control, with a count that represents new unseen notifications rather than every unread item forever. | Show enough fields to distinguish same-named objects before selection, and keep the selected object preview visible after the popup closes so the submitted entity can be inspected. | Render a labelled input with a live result panel that shows matching result hits, result count, active result, source labels, and loading or stalled state while the user types. | Render activity logs as evidence-oriented records with event time, actor, action, object, source system, scope, result, and technical context such as IP address or location when available. | Show the blocked object or action, current account, permission level, required role, owner, and request path when revealing that information is allowed. | Render review queue as an actionable worklist with queue scope, counts, filters, sort order, row reason, owner, priority, age or SLA, status, preview context, selection, and row actions. |
| UX guidance | Use mentions when a user needs to call attention to a person, team, channel, role, or group from inside a message, comment, task, document, issue, or thread while keeping the reference embedded in the authored content. | Preserve comment drafts, anchors, authorship, notifications, edit history, deletion outcomes, and resolved or hidden states so conversation context remains trustworthy across reloads, permissions, moderation, and return visits. | Use threaded discussion when users need to follow, contribute to, or resolve a conversation that branches from one topic, question, channel message, or post and must keep replies understandable over time. | Use a notification center when users receive enough asynchronous system or collaboration updates that they need a durable place to review, triage, and act later. | Use an object picker when the user must choose an existing entity whose identity matters beyond the displayed label, such as a record, person, group, account, file, team, project, or workspace. | Use typeahead when users benefit from immediate result feedback while typing and can either open a result hit or continue to a full submitted search. | Use activity log when users need to investigate, audit, verify, or troubleshoot actions across accounts, objects, systems, settings, or security boundaries. | Use permission denied state when the system knows the user is authenticated but their role, group, share, license, policy, or approval status blocks a specific object or action. | Use review queue when a team repeatedly processes a changing set of tickets, comments, pull requests, content items, cases, requests, or records that require human inspection and action. |
| Good UI | A comment composer opens a suggestion list after @, shows people and teams with avatars, handles, access labels, and keyboard focus, then inserts a mention chip for Priya Rao. | A document margin comment shows the selected paragraph, author, timestamp, body text, Reply, Resolve, Assign, and Copy link actions with the composer focused on that selection. | A support topic shows the original question, three top-level replies, one expanded reply branch, an accepted answer badge, unread branch marker, and thread-level Follow and Mute controls. | A bell opens a drawer with Unread and All filters, showing comment mentions, approval requests, export results, and background-job failures in newest-first order. | A Related account field shows two Acme Retail records with account ID, region, status, and owner, then displays a selected-object preview card before saving. | Typing ca opens a panel with live case, calendar, and claim results, a 3 results for ca count, active row styling, and source labels. | An organization audit log table shows timestamp, actor, action, target object, app, IP address, result, and a Details drawer with before and after fields. | A report page says Quarterly revenue report requires Finance viewer access, shows the current account, names the report owner, and offers Request access and Switch account. | A moderation queue has Held, Likely spam, Reported, and Escalated tabs, row evidence, policy reason, reviewer claim state, approve/remove/escalate actions, and bulk-action preview. |
| Bad UI | Mention chips break when copied, pasted, edited, localized, or rendered in plain-text fallbacks. | A Notes textarea sits under a record and calls itself comments even though every user overwrites the same field. | Nested replies are indented until they become unreadable on mobile and the answer is hidden below collapsed context. | Users ignore the center because duplicate low-value messages inflate the badge. | A text field accepts Acme Retail as free text even though the backend needs a record ID. | The input silently becomes Case 104 because the first result was auto-filled while the user was typing ca. | An export button downloads a different date range and timezone than the on-screen filtered log. | A denial page says Something went wrong and shows Retry even though the user lacks a required group. | The most urgent or oldest item is buried by default sort. |
| Good UX | A user mentions @Dana in a private incident note, sees that Dana lacks access, chooses Invite and mention, and the resulting notification opens the exact note. | A reviewer comments on a selected line, adds an action item for Dana, receives a reply, resolves the comment, and can reopen it from the resolved filter. | A user opens a notification to a specific unread reply, sees the parent post and branch context, replies, marks the answer, and mutes future replies after resolution. | Opening the notification drawer clears the new-notification badge while unread items remain available for later triage. | A user searches Acme, compares two same-named records by region and status, selects the active EMEA account, and reviews the selected account ID before saving. | A user types cas, sees matching case records immediately, selects Case 104, and can still edit the query or submit a full search. | An admin filters to failed SSO events, expands one entry, copies the event ID, exports the filtered range, and sees that records older than 180 days require a different archive. | A user opens a restricted report, sees which account is signed in, requests viewer access with a reason, then sees that the request is pending with the owner. | A reviewer claims the oldest SLA-at-risk ticket, opens a preview, assigns it to Billing, returns to the queue with the row removed, and lands on the next oldest item. |
| Bad UX | A mention notification opens the record homepage rather than the exact comment sentence, forcing the recipient to search for why they were pulled in. | A user writes a long comment, loses network connection, and the draft disappears when the page reloads. | A moderator marks an answer but the thread summary still shows unanswered because answer state is stored only on the visible reply card. | Users mark all notifications read and lose the only record of an export job they still need to download. | A user picks the first Acme result because every row looks identical, then links the case to the wrong account. | Slow old results overwrite newer query results and users open the wrong record. | A user marks a notification read and the corresponding activity evidence disappears from the only log. | Every workspace control is disabled after one missing permission, including safe navigation and read-only tasks. | A reviewer marks a pull request reviewed from an old queue row after the author pushed new commits and re-requested review. |
| Best fit | Composed content needs to target people or groups inline. | Feedback must preserve author, timestamp, reply, resolution, assignment, or moderation context. | A topic or parent message can generate multiple reply branches that users need to follow over time. | Users receive multiple asynchronous updates across objects, jobs, collaborators, approvals, or reminders. | Users assign, link, reference, invite, route, or attach an existing entity. | Users search large datasets and benefit from seeing result hits before full submit. | Users need to inspect recorded user, admin, system, security, or integration events. | A signed-in user lacks permission to view, edit, publish, export, delete, approve, share, administer, or configure a resource. | A team or individual repeatedly reviews many independently queued items. |
| Avoid when | The user is selecting a structured owner, assignee, approver, or recipient field outside written content. | The user is simply entering a long answer into a form field. | The surface is a broad feed of independent posts or activity cards. | The product has only occasional current-action feedback that a toast or inline status can handle. | Any arbitrary text is valid. | The task is choosing one constrained field value, which is better handled as autocomplete. | The goal is only to show a readable milestone history for one case or process. | The operation failed for network, server, validation, data, or timeout reasons after permission was granted. | The task is a single request moving through a governed approval route. |
| Required state | Highlighted suggestion, keyboard-selected suggestion, mouse or touch-selected suggestion, and inserted mention token. | Empty comment list and first-comment composer. | Parent topic or parent message with author, timestamp, title or body, category, and reply count. | Closed entry-point state with zero, new-unseen, and unread-but-seen counts. | Empty object lookup field with label, helper text, and current search scope. | Empty state before typing. | Default log state with event records, result count, visible timezone, retention window, and permission scope. | Whole-object access denied state. | Queue loading and count state |
| Accessibility burden | Expose the suggestion list as a labelled popup tied to the editor and announce the number of available mention targets. | Label the comments region with the object or selection being discussed. | Label the thread region with the parent topic or message title. | Announce new notification arrival with status semantics when appropriate, but avoid interrupting users repeatedly for low-priority center items. | Give the lookup field a persistent label and helper text that explains the expected object type. | Use a labelled input and expose the live result panel with combobox, listbox, or region semantics appropriate to the interaction. | Use table or structured list semantics so actor, action, object, timestamp, result, and scope are perceivable together. | Move focus to the permission message when it replaces page content or blocks a workflow. | Use labelled queue name, count, filters, sort, group, row status, selection, preview, and action controls. |
| Common misuse | Treating a mention suggestion list as a generic people picker and ignoring caret position, inline serialization, and notification side effects. | Using one shared Notes field as a comment system and overwriting prior contributors. | Flattening every reply into a chronological stream and losing who replied to whom. | Treating the badge count, unread count, and total notification count as one number. | Treating the picker as a free text field when the system requires an existing object ID. | Auto-filling the first result into the input while users type. | Using vague activity labels that omit actor, action, object, timestamp, or result. | Treating authorization denial as a generic retryable error. | Treating review queue as approval workflow and hiding many-item workload controls. |