Removed from guidelines

Comments enable a discussion on an entity such as a page, blog post, issue or pull request. Depending on the context, discussions can be between any combination of authors, contributors and readers.

When and how to use this pattern

Use comments to enable a discussion on an entity. Comments can vary in their purpose. They can be geared toward:

  • Driving toward an action or decision
  • Soliciting feedback
  • A freeform social discussion

The Comments pattern consists of an activity stream of posted comments, combined with a form textarea to allow the current user to submit a comment (if they have the required permissions).

Each comment in the stream includes:

  • An avatar (commenter profile picture)
  • Actor (commenter). If the comment is by the author of the entity, the commenter's name may be followed by an author lozenge: AUTHOR
  • Comment
  • Actions
  • Date (which serves as a permalink to the comment)

A specific comment can be highlighted, for example when the comment permalink has been followed.


Comment stream and comment entry field

Nested comments



A linear, single-threaded discussion displayed in chronological order. Most suitable when:

  • Discussion is very focused on the content of the entity and tangential discussions between participants are not encouraged
  • A clear action or decision is desired, or to elicit information from participants. The end of the discussion usually represents the resolution.


A multi-threaded discussion where participants are able to reply to each other. Comments are shown in chronological order except when they are replies, in which case they are shown nested beneath the comment they are in reply to. Best used for:

  • Broad discussions where tangential discussions are encouraged between participants
  • Freeform discussions where a strong focus isn't required, such as social discussions


Inline comments don't appear in a list at the end of the entity as per Flat and Nested comments above, but are shown in the context of the content the comment refers to. For example, a comment about a particular line of code in a pull request, straight after the code being discussed.