| 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 | Render mentions as inline tokens or highlighted text that preserve a stable recipient identity, display name, avatar or team marker, recipient type, and selected state without breaking surrounding editable text. | 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. | Render a labelled lookup field with search text, scoped result list, active result, selected object chip or preview, object type, stable ID or equivalent key, secondary metadata, clear action, no-result state, loading state, and validation text. | 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. | Use comments when users need to discuss, question, annotate, review, or leave follow-up notes on a specific object, selection, file line, record, document, or task without changing the primary content directly. | 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 support queue shows New triage, SLA at risk, owner, customer, status, priority, age, preview text, assignment, and next actions without opening every ticket. |
| Bad UI | The editor highlights every @word as a mention even when it is plain text and has no recipient identity. | A Notes textarea sits under a record and calls itself comments even though every user overwrites the same field. | All replies are rendered as identical flat messages with no indication of which parent or branch they answer. | A red badge says 42 forever because opening the drawer, reading items, and viewing related work never update the count. | 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. | A page titled Activity shows vague entries such as Changed settings with no actor, target, timestamp, or source. | A denial page says Something went wrong and shows Retry even though the user lacks a required group. | A review queue shows a flat list of titles with no reason, age, owner, status, priority, or action controls. |
| 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 user mentions someone in a private channel, the person is not notified, and the sender receives no warning or recovery path. | A user writes a long comment, loses network connection, and the draft disappears when the page reloads. | A user clicks New reply and lands at the top of a long topic with no highlight, branch context, or last-read position. | A payment failure that blocks the current checkout is only stored in the notification center and never appears in the task. | A user types a person name and presses Save, but no actual user account was selected. | Users cannot finish typing because focus jumps into the first result on every keystroke. | A user marks a notification read and the corresponding activity evidence disappears from the only log. | The app returns a blank screen for a restricted file, so the user cannot tell whether the file is gone, private, or opened with the wrong account. | Two reviewers open the same unclaimed item, both act, and the second decision overwrites the first with no stale-row warning. |
| Best fit | Composed content needs to target people or groups inline. | Users need object-attached discussion without changing the primary object content directly. | 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 feedback is a simple object-attached comment with no navigable topic discussion. | 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 user is not signed in and the next step is authentication rather than authorization. | The task is a single request moving through a governed approval route. |
| Required state | Empty composer, @ trigger, loading suggestions, no results, and filtered suggestions. | 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. | Give the entry-point control an accessible name that includes new or unread count without relying only on a red dot. | 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. | Use a heading that identifies the access boundary and a text description that does not rely on lock icons or red color alone. | Use labelled queue name, count, filters, sort, group, row status, selection, preview, and action controls. |
| Common misuse | Parsing @words after submit without requiring the sender to choose a real recipient. | 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. | Calling a known-value autocomplete field typeahead even though no result set is searched. | Calling a social feed or notification drawer an activity log without event evidence. | Treating authorization denial as a generic retryable error. | Using an ordinary table with no review reason, urgency, ownership, or decision actions. |