How Do You Design Comments and Mentions in a SaaS App?

How Do You Design Comments and Mentions in a SaaS App?

Design the mention first and the comment thread second. The mention is what makes comments useful, because it turns a note into an assignment someone will actually see. Get the picker, the notification and the permission behaviour right and the rest of the feature is ordinary form design.

We design product interfaces for B2B software teams, and comments are one of the most requested features and one of the most consistently underspecified. Teams scope it as an input box and a list. Then the questions arrive.

Here is the set of decisions that actually make it work, in the order we would answer them.

Why Are Comments Harder Than They Look?

Because a comment is four features wearing one coat. There is text entry with a picker inside it. There is a notification system. There is a permissions question about who can see what. And there is a resolution model that decides when a thread stops being active.

Teams that scope only the first one ship something that works in a demo and falls apart in a real account with thirty people and a hundred threads.

The good news is that each of the four is a known problem with a known shape. The cost is in deciding them deliberately rather than discovering them in a bug report.

What Should the Mention Picker Actually Do?

Open on the trigger character, filter as you type, and be operable entirely from the keyboard. This is the combobox pattern, and it is worth building to the standard rather than improvising.

The W3C ARIA Authoring Practices Guide describes a combobox as an input widget with an associated popup, and specifies what the input needs: role combobox, aria-controls referencing the popup, aria-expanded set to false when hidden and true when visible, aria-autocomplete set to list or both, aria-activedescendant pointing at the focused option, and an accessible name from aria-labelledby or aria-label. The popup itself takes role listbox, with options marked aria-selected.

The keyboard behaviour is specified too. Down Arrow moves into the popup, Up Arrow focuses the last item, Escape dismisses it, Enter accepts the focused suggestion, and printable characters continue typing in the input.

Build this once, properly, and reuse it. A hand-rolled picker in a comment box is the single most common place we find keyboard traps, which is the failure we described in focus management in product UI.

Who Should Appear in the Picker?

Only people who can already see the thing being commented on. This is a permissions rule, not a convenience, and getting it wrong leaks information.

Two failure modes are common. Showing everyone in the organisation, so a user mentions someone who then receives a notification about a record they cannot open. And showing only people already in the thread, which makes the feature useless for bringing someone in.

The right default is everyone with access to the parent object, sorted by recent collaborators first. If you allow mentioning someone without access, you need an explicit grant step, and the person mentioning must see what they are about to share.

What Happens When Someone Is Mentioned?

They get one notification, on the channel they chose, containing enough context to decide whether to act without opening the app. That last part is what separates a useful mention from noise.

Include the commenter, the object, and the comment text itself. A notification saying someone mentioned you in a comment forces a context switch to learn something that would have fitted in the notification.

Batch aggressively. Five mentions in a thread over two minutes is one notification, not five. The rules for this are the same ones we set out in designing notifications people do not turn off.

Should Comments Be Threaded?

One level of nesting, at most. Flat threads become hard to follow past about fifteen comments. Unlimited nesting becomes impossible to render on a phone and impossible to summarise.

The pattern that works for product software is a top-level comment with replies underneath it, and no replies to replies. It maps to how people actually discuss a specific thing.

If your users need deeper discussion, they need a different tool, and the honest answer is to link out to it rather than to rebuild a forum inside a settings panel.

How Do You Handle Resolving and Deleting?

Resolve should hide by default and be reversible. Delete should be rare, restricted, and logged.

The distinction matters because they get conflated. Resolving says this conversation is finished. Deleting says this was never said. Teams need the first constantly and the second almost never.

Give the author a short window to delete their own comment, give administrators the ability to remove content, and record removals in the audit trail. That covers the real cases, which are a typo and a compliance request. This is the same reasoning as in designing an audit log customers will use.

How Should Editing Work?

Allow it, show that it happened, and do not re-notify. An edited marker with a timestamp is enough. Re-notifying everyone because somebody fixed a spelling mistake is how a good feature earns a mute.

The exception is adding a mention during an edit. A person newly mentioned has genuinely not been told, and should be. Notify only the newly mentioned people, not the whole thread.

Keep the original text retrievable for administrators if your customers are in regulated industries. They will ask.

What Does This Need for Screen Reader Users?

New comments arriving need to be announced without stealing focus. WCAG Success Criterion 4.1.3 Status Messages, at Level AA, requires that status messages can be programmatically determined through role or properties so assistive technologies can announce them without receiving focus.

In practice that means a live region. The criterion is commonly met with role status for state updates, role alert for warnings and errors, or an aria-live region with an appropriate politeness level.

Use the polite level for incoming comments. A new comment is information, not an emergency, and interrupting someone mid-sentence to announce it is worse than being slightly late.

What About Real-Time Presence?

Add it last, if at all. Showing who is typing and who is viewing is genuinely nice and is a large amount of infrastructure for a feature most B2B workflows do not need.

Asynchronous is the normal mode for product comments. Two people are rarely in the same record at the same moment, and when they are, they are usually also in a call.

If you do build it, make presence a display detail rather than something the comment system depends on. A presence service failing should not stop someone leaving a comment.

What Would We Ship First?

A flat thread with one level of replies, an accessible mention picker scoped to people with access, one batched notification per mention with the text included, resolve rather than delete, and a polite live region. No presence, no reactions, no rich text beyond links.

That is a week or two of work rather than a quarter, and it covers what people actually do with comments. The features we left out can be added on evidence rather than on assumption.

If you are adding collaboration to a product and want a second pair of eyes on the interaction design, we are happy to walk through it with you. Find us at phoenix.studio.