display.dev/product/PRD-031

@-mentions & tagging in commentsIn review

Owner
Sarah Chen, PMdrafted with Claude Code (agent)
Version
v3updated Jul 16, 2026
Target release
Sep 15, 2026GA · after org-internal beta
Reviewers
Priya Sharma, David Parksecurity: Michael Torres
5 changes vs v2

1Problem

Teams review shared artifacts in comment threads, but there is no way to pull a specific teammate into a thread. Today the workaround is copying the artifact link into Slack with "can you look at the pricing table?" — which splits the discussion across two tools and loses the anchor to the exact element being discussed.

Evidence · internal dogfood, Jun 2026
Of 214 comment threads opened on shared artifacts in June, 41% waited more than 24 hours for a reply from the person who could actually answer — and in 29 of those threads someone typed a teammate's name in plain text, expecting it to notify them. It didn't.

People already believe mentions exist. We are shipping the behavior they assume is there: type @Priya in a comment, Priya gets notified, the thread keeps its anchor to the element under discussion.

2Goals & non-goals

✓Goals

  • Pull the right person into a thread in one action, without leaving the artifact.
  • Mentioned person is notified in-app within 60 seconds.
  • Zero notification spam: batching, dedupe, and mute are respected from day one.
  • Mentions survive comment edits and thread resolution.

✕Non-goals

  • A full notification inbox or activity feed (separate track, H2).
  • Presence, typing indicators, or read receipts.
  • Mentioning Slack/Teams users who have no display.dev account.
  • Cross-org mentions — moved to out of scope in v3, see §7.new in v3

3User stories

  1. As a reviewer, I type @ in a comment and pick a teammate, so the right person sees my question without me leaving the doc.
  2. As the mentioned person, I get one notification that deep-links to the exact thread and element, so I can answer in context in under a minute.
  3. As an artifact owner, I can see which open threads are waiting on whom, so review doesn't stall silently.
  4. As someone who muted a thread, I stay muted even when mentioned again in it — my attention is mine to allocate.

4Functional requirements

✓ agreed in review  ·  ⧗ still open

FR-1 Typing @ in a comment opens a typeahead of members of the artifact's org, filtered as you type. Keyboard-first: arrows + enter, escape dismisses. ✓ agreed
FR-2 Typeahead ranks by relevance to this artifact: people already in the thread, then recent commenters, then org alphabetical. ✓ agreed
FR-3 A confirmed mention renders as a pill — @David Park — stable through comment edits; deleting any character of the pill removes the whole mention. ✓ agreed
FR-4 Each mentioned user is notified per the rules in §5. Notification deep-links to the thread and scrolls the anchored element into view. ✓ agreed
FR-5 Editing a comment re-notifies only newly added mentions. Removing a mention never sends anything.added in v2 ✓ agreed
FR-6 Mentioning someone who lacks access to the artifact prompts the mentioner to grant view access (or auto-grants for org-visible artifacts — pending OQ-3). ⧗ open
FR-7 Mentions work in resolved threads; the thread stays resolved and the notification carries its resolved state.added in v2 ✓ agreed
FR-8 Users may mention collaborators from partner orgs on artifacts shared across org boundaries.removed in v3 cut
FR-9 Agents with an identity in the org (e.g. @claude-code) appear in the typeahead and can be mentioned; whether a mention triggers agent action is pending OQ-4. ⧗ open

5Notification behavior

Whole section added in v2 after Priya's review comment. The principle: one mention, at most one email. In-app is immediate, email is a fallback for people who aren't looking.

Channel matrix per event
EventIn-appEmail
Mentioned in a new comment immediate batched ≤ 10 min
Newly mentioned via comment edit immediate batched ≤ 10 min
Mentioned in a thread you muted none none
Reply lands in a thread where you were mentioned earlier immediate daily digest only
Guest with link-only access is mentionednew in v3 none none — pill renders, no delivery

Dedupe rule: if the mention is seen in-app before the email batch window closes, the email is dropped. Muting a thread wins over everything — being mentioned again does not un-mute it (US-4).

6Out of scope

— Group mentions (@design, @everyone) — revisit after we have org groups.
— Mention analytics ("who gets mentioned most") — no user has asked; skip.
— Cross-org mentions. Security review SEC-2214 (Jul 15) flagged directory enumeration: the typeahead would let any collaborator list another org's member directory. Needs a scoped-visibility model first — deferred to the external-collaboration track.new in v3

7Open questions

  1. OQ-1 Should mentions work in resolved threads, or should mentioning reopen the thread? ✓ Resolved Jul 9 (v2): mentions allowed, thread stays resolved → FR-7.
  2. OQ-2 Do cross-org mentions ship at launch? ✓ Resolved Jul 16 (v3): no — scoped out per SEC-2214, see §6.new in v3
  3. OQ-3 Mentioning someone without access: prompt the mentioner to grant access (Priya's position — explicit is safer) or auto-grant on org-visible artifacts (David — fewer dead-end mentions)? decision: Sarah · due Jul 23, blocks FR-6
  4. OQ-4 When an agent is mentioned (@claude-code fix the y-axis), does the mention itself trigger the agent, or only notify its owner? Leaning: notify-only at GA, triggering is its own PRD. decision: Sarah + David · due Jul 30, blocks FR-9

8Milestones

  1. Jul 2✓PRD v1 drafted, review opened
  2. Jul 15✓Security review complete (SEC-2214)
  3. Aug 6·Typeahead + mention pill behind flag
  4. Aug 20·Notification pipeline (batching, dedupe, digest)
  5. Aug 27·Org-internal beta — dogfood on our own review threads
  6. Sep 15·GA — target release