Designing comments and mentions in Figma

Quick answer

A comment thread is a composer, a list of messages, and a resolved state. An @mention is a person picked from a list, then shown as a chip in the text. Design those as components. Do not draw a new comment style on every screen. Notify the mentioned person from the inbox. The thread itself stays on the thing being discussed.

This is product comments. Figma’s own comment tool is a different surface. You are specifying the comments in the product you are designing.

Who this is for

• Product designers adding feedback on a record, a file, or a page inside an app.
• Design-system teams who need one thread component.
• Engineers who need edit windows, permissions, and what “resolved” hides.

If people only need to react with one click, use a reaction or a rating. Do not make them write a thread.

Where the thread sits

Placement	Use when
Side panel	The thing being discussed is a canvas, a doc, or a wide page
Under the record	The page is the record, and the thread is part of reading it
On a selection	Comments pin to a block, and the list can get long

Pick one placement per product. A pin plus a duplicate thread at the bottom makes two sources of truth. Pins need an anchor the engineering team can store. If you cannot say what the pin sticks to when the layout changes, use a single thread on the record instead.

Anatomy

Composer. Text area, mention trigger, and a submit button that is disabled while the field is empty. Placeholder: “Write a comment”, or “Reply” inside a thread. Do not use the placeholder as the only label.

Message. Avatar, name, time, body. Edited messages say they were edited. The time in the file can be relative; the handoff should include a full timestamp.

Reply. Nested one level under the message it answers. Deeper nesting is hard to scan and hard to resolve. One level is enough.

Resolved. The thread collapses to one line: who resolved it, and a way to reopen. Resolved is not deleted. People look for the decision later.

Deleted. “Comment removed” if other people could see it before. Silent disappearance looks like a bug.

Mentions

Type @ and show a short list of people who can see this thread. Reuse the combobox pattern: keyboard, selected row, empty query.

• Only list people with access. Mentioning someone who cannot open the page creates a notification they cannot use.
• A mention in the text is a chip or a clear name style, not a color that disappears in dark mode.
• One mention creates one inbox item. Do not also toast for the same mention unless the person is looking at another page and you have decided the toast is the only alert. Prefer the inbox.

If the list is long, the mention menu searches. Do not dump the whole company into a scroll area with no field.

Permissions

Write these on the frame:

• Who can comment, who can only read, and who can resolve.
• Whether the author can edit, and for how long. If you do not limit the edit window, say that edits are always allowed.
• Whether resolve is author-only, or anyone who can comment.

A reader who cannot comment still needs to see the thread. Hide the composer and say why in one line if it is not obvious from the rest of the page: “View only”.

Empty

The first comment is an empty thread, not an error. “No comments yet” plus the composer is enough. Do not put an illustration here unless this empty state is the main content of the page. A quiet line beats a drawing under every card.

What to hand off

• Placement, and the anchor if comments pin to blocks.
• Required fields. Body is required. A comment that is only a mention still needs the mention rules.
• Edit, delete, and resolve permissions.
• That mentions notify, and which inbox type they use.
• Order: oldest first or newest first. Pick one for the product.

Common mistakes

• A different composer on mobile and desktop that submit different fields.
• Mentions of people without access.
• Resolve that deletes the thread.
• Nesting replies more than one level because a sample thread looked clever.

FAQ

Thread or a flat list?

Thread when a record has several topics. A flat list when there is one conversation, such as approval notes. Do not thread a list of three notes.

Can comments include files?

Yes, if the product already has upload. Show the file as an attachment on the message, with the same limits as upload elsewhere. Do not invent a second uploader.

Do public visitors get this?

Only if the page is public and you have a moderation path. Internal comments and public comments should not share one unmoderated list.

Next

When a page has nothing on it yet, the empty state does the talking. Continue with empty states. The full shelf is on Patterns.