Comments

Problem Context

• Users need to discuss or annotate a specific document selection, file line, design frame, issue, ticket, record, image, task, or content item.
• The comment may be public, internal, private, permission-limited, assigned as an action item, resolved, reopened, edited, hidden, redacted, or deleted.
• Comment activity may generate notifications, appear in feeds, affect review queues, or need moderation, but the canonical comment remains attached to its object or selection.
• Users need to understand who said what, when it changed, who can act on it, and whether the conversation still needs attention.

Selection Rules

• Choose comments when the core object needs attached discussion, review feedback, annotation, or follow-up notes that remain separate from the object's primary editable content.
• Use textarea when the only need is a multi-line answer field and there is no authorship, reply, timestamp, resolution, moderation, or notification lifecycle.
• Use feed when the primary experience is consuming a stream of updates from many objects rather than reading discussion anchored to one object.
• Use activity log when entries must represent system events, provenance, or compliance history rather than authored conversational content.
• Use notification center when comment activity must be triaged across objects with unread, retention, and preference behavior.
• Use review queue when many comments need moderation, assignment, bulk triage, or repeated human decisions.
• Keep comment anchors visible or recoverable when the referenced selection, line, object, or attachment changes.
• Separate destructive moderation from everyday reply and resolve actions with permission checks, warnings, and history where appropriate.

Required States

• Empty comment list and first-comment composer.
• Draft comment, saving comment, saved comment, failed save, retry, and discarded draft states.
• Open comment with author, timestamp, body, anchor, and item actions.
• Reply state, reply saved state, and focused return to the affected comment.
• Resolved, reopened, assigned, done, edited, deleted, hidden, reported, and redacted states.
• Permission-limited state where some users can read and reply but cannot edit, delete, hide, or resolve.
• Anchor missing, outdated selection, collapsed conversation, filtered resolved comments, and direct-linked comment states.
• Notification-deep-linked state that scrolls and focuses the exact comment or reply.

Interaction Contract

• Submitting a comment creates a durable item with stable ID, author, timestamp, body, anchor, visibility scope, and notification behavior.
• Reply, resolve, reopen, assign, hide, edit, delete, report, and copy-link actions operate on the named comment or conversation, not on the whole object by accident.
• Draft text survives navigation warnings, reload recovery, temporary offline state, validation errors, and permission checks until the user sends or discards it.
• Edits show an edited indicator and, when product policy requires it, expose edit history or moderation reason to eligible users.
• Deletion and redaction clearly communicate reversibility, timeline impact, and who can still see metadata or history.
• Resolved or hidden comments remain discoverable through filters, history, or moderation views when the product promises recoverability.
• Notification links, copied links, and search results open the exact object and comment context, with focus or highlight on the target comment.

Implementation Checklist

• Define comment anchor type, author model, visibility scope, permission rules, draft lifecycle, notification triggers, and moderation states before building the composer.
• Design the composer with clear placeholder text, submit and cancel behavior, attachment or formatting affordances, validation, and failure recovery.
• Render comment items with stable identity, author, timestamp, body, edited state, anchor summary, and item-scoped action menu.
• Support reply, resolve, reopen, assign, hide, edit, delete, report, copy link, and filter behavior only when the product rules require them.
• Preserve comment drafts and comment-list position across reload, route return, failed save, offline retry, object update, and permission changes.
• Add direct-link behavior that scrolls and focuses the referenced comment, including when it is collapsed, resolved, hidden, or attached to changed content.
• Test keyboard access, screen reader labels, touch access to non-hover actions, long comments, deleted users, edited history, moderation, deleted anchors, and mobile wrapping.

Common Generated-UI Mistakes

• Using one shared Notes field as a comment system and overwriting prior contributors.
• Treating a comment as a feed item and losing its object or selection anchor.
• Hiding edit, delete, resolve, or moderation actions behind hover-only controls.
• Deleting or hiding comments without warning, permission checks, reason text, or timeline evidence.
• Sending notifications that do not deep-link to the exact comment or reply.
• Letting resolved or hidden comments disappear with no filter, history, or reopen path.
• Making comments the only audit record for decisions that require durable activity-log evidence.
• Allowing replies or assignments to fail silently when the target user lacks access.

Critique Questions

• What exact object, selection, line, frame, record, or task does this comment belong to?
• Can users tell who wrote each comment, when it changed, and whether it still needs action?
• Which actions are available to author, owner, moderator, assignee, guest, and read-only users?
• What happens to comments when the anchor is edited, deleted, moved, hidden, or permission-limited?
• Can a notification, copied link, or search result take users back to the exact comment context?
• Is deletion reversible, and if not, does the interface warn and leave the right timeline evidence?