Mentions

Problem Context

• Users are composing messages, comments, documents, tasks, issues, pull requests, notes, tickets, or thread replies and need to draw attention to specific people or groups.
• Mentionable targets may include individuals, teams, channels, roles, user groups, on-call rotations, bots, or workspace-wide audiences with different notification and permission rules.
• Mentions can create notifications, action items, task ownership, inbox filters, search handles, or audit events, but they remain embedded in authored content.
• The recipient may lack access, have notifications paused, share a display name with another person, belong to a broad audience, or receive the mention through a team preference.

Selection Rules

• Choose mentions when the interaction begins in prose or rich text and the user needs an inline reference that targets a recipient or audience.
• Use object picker when the user is selecting owners, reviewers, approvers, assignees, or recipients as a structured field rather than writing a message.
• Use comments when the product needs anchored conversation state; mentions can live inside comments but should not carry reply, resolve, edit, or delete behavior by themselves.
• Use threaded discussion when the core task is following a branchable topic conversation; mentions inside replies should notify without changing the thread hierarchy.
• Use notification center for the retained inbox where mention events are read, filtered, muted, or opened after delivery.
• Use typeahead or combobox for the suggestion-list interaction, but add mention-specific recipient identity, access, and notification semantics.
• Warn before broad mentions that reach a channel, team, workspace, or chat, especially when audience size, quiet hours, or admin rules make the effect large.
• Do not send a mention silently when the target cannot see the object, private channel, document, issue, or thread; show invite, request access, remove, or send-without-notify choices according to product policy.

Required States

• Empty composer, @ trigger, loading suggestions, no results, and filtered suggestions.
• Highlighted suggestion, keyboard-selected suggestion, mouse or touch-selected suggestion, and inserted mention token.
• Individual, team, channel, user group, role, bot, and broad-audience mention states where the product supports them.
• Ambiguous display name, duplicate handle, unavailable recipient, deleted user, deactivated account, and external guest states.
• Recipient lacks access, sender lacks permission to mention, admin-restricted broad mention, guest-restricted broad mention, and invite-before-mention states.
• Notification sent, notification suppressed by preferences or paused status, thread-limited mention, failed notification, and retry or remove states.
• Mention edited, mention removed, pasted mention text, copied mention, escaped plain @ text, and serialized mention ID states.
• Direct-linked mention state where the recipient opens the exact message, comment, reply, task, or document location.

Interaction Contract

• Typing @ opens a suggestion list scoped to the current workspace, channel, object, permission boundary, and caret location.
• Selecting a suggestion inserts an inline token bound to a stable target ID, not just the visible display name.
• Arrow keys move through suggestions, Enter or Tab commits the highlighted target, Escape closes suggestions without deleting typed text, and Backspace removes or edits the mention predictably.
• Submitting content validates access, broad-audience policy, duplicate recipients, quiet-hour or paused-notification behavior, and notification preferences before delivery.
• If a recipient cannot see the content, the sender gets a clear warning and an allowed recovery path such as invite, request access, remove mention, or send without notifying.
• Mention notifications deep-link to the exact sentence, comment, task, reply, or document location and highlight the mention or its containing item on arrival.
• Editing a mention updates the target identity, display text, notification rules, and audit or activity evidence according to product policy.

Implementation Checklist

• Define mentionable target types, stable IDs, display labels, handles, avatars, membership, visibility, notification policy, broad-audience rules, and serialization format before building the editor.
• Implement caret-aware suggestion positioning, keyboard navigation, loading and empty states, duplicate-name disambiguation, screen-reader labels, touch-safe rows, and mobile viewport behavior.
• Validate access and notification outcomes at submit time, including private spaces, guest users, deactivated users, muted threads, paused notifications, broad mentions, and admin restrictions.
• Design warning and recovery flows for broad mentions, unavailable recipients, missing access, duplicate mentions, failed notification delivery, and mention edits.
• Ensure copied, pasted, edited, deleted, and rendered mentions preserve or intentionally drop target identity with visible feedback.
• Test notification deep links, inbox filtering, search, action-item creation, assignment side effects, audit evidence, localization of display names, and ambiguous names.

Common Generated-UI Mistakes

• Parsing @words after submit without requiring the sender to choose a real recipient.
• Treating a mention suggestion list as a generic people picker and ignoring caret position, inline serialization, and notification side effects.
• Allowing broad mentions with no audience size, policy, quiet-hours, or confirmation warning.
• Mentioning people who cannot access the object and giving neither sender nor recipient a recoverable path.
• Using mentions as the only assignment mechanism without creating task ownership, due state, or completion behavior.
• Letting ambiguous display names, renamed users, deactivated users, or external guests collapse into the same visible token.
• Sending notification links to the top of a page rather than the exact mention context.
• Failing to distinguish person mentions, team mentions, channel mentions, bots, roles, and plain @ text.

Critique Questions

• What stable target ID is bound to each visible mention token?
• Can the sender tell whether they are mentioning a person, team, channel, role, bot, or broad audience?
• What happens when several people match the same display name or handle?
• Can every mentioned recipient see the underlying object or conversation?
• Does the interface warn before broad mentions and respect admin, guest, quiet-hours, and notification-preference rules?
• Where does the recipient land when they open the mention notification?
• Does a mention also create assignment, task, or audit state, and is that state visible outside the prose?