Commenting and Annotation System Spec Template

Both. Show new comments to other users immediately via WebSocket updates, but design the core experience for async use. Most comment threads involve someone leaving feedback and another person responding hours later. Real-time delivery ensures comments are visible instantly, but the notification and resolution model should assume async workflows.

Tie each comment to the version it was created on. When viewing a historical version, show the comments from that version. When viewing the current version, show both current comments and "legacy" comments from previous versions (visually distinguished). This preserves review context across revisions. Never silently delete comments when a new version is published.

Design tools use coordinate-based anchoring: a pin at (x, y) on a specific artboard. Document editors use text-range anchoring: a start and end position within the document text. Both need mutation handling, but the strategies differ. Coordinate anchors need to track element transforms (move, resize, reorder). Text anchors need to track insertions and deletions around the selection. Consider using unique IDs on content blocks as stable anchors rather than absolute positions.

For internal team tools, require authentication. For client-facing review tools (design review, content approval), guest commenting via share links significantly lowers friction. Require a display name but not an account. Badge guest comments clearly so team members can distinguish internal from external feedback. Rate-limit guest comments to prevent abuse.

Three strategies: thread resolution (move completed discussions out of the active view), comment filtering (show only unresolved, only mine, only mentions), and summarization (show a collapsed "12 comments, 3 unresolved" indicator instead of rendering all threads). Give users control over their view density. ---