Notifications/Design guide

This page compiles the design guidelines that must be followed when defining new notifications in order to create a consistent experience.

The notification system is extensible by nature. Different extensions will add new types of notifications and users will benefit from those notifications to be consistent with the rest.

The recommendations of this guide are based on the development of the cross-wiki notification system. An initial revision of the notifications to conform to the present guidelines was illustrated in this ticket.

Text copy[edit]

Notification text should be succinct. Brief (to make notifications easy to scan) but also clear and informative (to make it useful).

Styling of elements[edit]

Text style should be consistently applied.

Bold is used to emphasise content. Bold is used for page titles. By quickly looking at the notification icon (e.g., reverted edit) and the bolded text (e.g., page for which the edit was reverted) should provide a good summary of what the notification was about.
Grey text is used for extracts of content. A lighter grey text will be used when including an excerpt of the notification content (more on this below).

Surface content[edit]

Notifications can surface information excepts to provide more context (the reason for a reverted edit, a piece of a conversation, etc.)

Notifications should include parts of the content when it is the key piece of information or adds relevant context. This makes it easy to find a given notification when going back to the notification list in order to organise your work.

Content will be presented in lighter grey and truncated to avoid it to get in the way of quickly scanning notifications.

Make the copy short by relying on actions[edit]

Notifications on top omit the actor name since it is not essential for those events (they are about content). Notifications at the bottom explicitly mention the actor since they represent a more direct connection between users (a user thanking or mentioning another).

The main message to communicate can rely on the actions for additional context.

If the agent username is not a core part of the notification message, it should be omitted from the text. The user action will act as a signature.

Omit usual namespaces[edit]

The notification text may include references to content in different namespaces.

For those namespaces which are clear implicitly, we can skip them. For example, users are referred by name (“Ludmilla”) without namespace (“user:Ludmilla”).

Abbreviate bundled items copy[edit]

Items inside a bundle share a context, thus the text can be abbreviated omitting the redundant parts. For example, there is no need to indicate the topic of each reply if all of them are replying to the same topic.

When notifications are presented as part of a bundle, avoid repeating information that is already captured in the bundle.

Bundled notifications are closely related (e.g., about the same content), emphasising what makes each item different facilitates their understanding.

Secondary actions[edit]

Actions provide additional context, and allow users to access related content.

Keep the agent as the first action[edit]

For those notifications where the agent is a relevant piece of content, they should provide an action linking to it.

The agent action should be presented first. That will bring consistency for such a common action and makes it act as a signature.

Avoid empty verbs[edit]

Actions provide context and link related information. Their label should represent such information directly.

When possible avoid “View/see”: “Ludmilla” (the user name in the example) is preferred to “View Ludmilla user page” (but “View changes” may still be preferred to just “changes").

Icons[edit]

Discussion-related icons use a common icon system (regardless of being based on wikitext or Flow). The differences are based on the content created (topics as green single bubble; replies as blue double bubble), and the use of modificators to indicate the connection to the user (mention, user talk page) or the editing of existing content (pencil).

Icons should be recognisable, simple and present consistent semantic relationships (look similar for similar notifications but different to unrelated ones).

Keep icons simple[edit]

Notifications can be displayed in many different contexts. By default icons are 30x30px, but they can be displayed at smaller sizes than that. The simpler the icons the easier it will be to scan the list of notifications looking for them.

Icon colors[edit]

Color is used to help differentiate icons so they are more recognisable at a glance. This is useful in a context such as the notification panel where we want to optimise for quick information scan. In addition, we try to follow a consistent use of color:

Blue is for updates. There is new activity for an element that already existed (e.g., new reply on an existing discussion topic).
Green is for new information and positive feedback. The creation of a new main information element (e.g., new topic created) and for positive feedback (e.g.,thanks) use green.
Grey is for neutral or destructive events. Events such as reverts and deletions are shown in grey. Grey is used instead of red (used for this purpose in other contexts) to make the messaging more constructive: encourage a positive interaction to a revert as oppose to encourage overreacting.

This guidelines are not expected to be applied strictly since there may be many hard to classify cases, but they help to increase the diversity among the same notification family.

Define a family of icons for similar events[edit]

Communication-related notifications use a speech bubble as the main shape with different modificators depending on the specific event. For example, a reply is represented by a pair of speech bubbles, but if the user was mentioned the speech bubble includes the "@" sign.