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
Notification text should be succinct. Brief (to make notifications easy to scan) but also clear and informative (to make it useful).

Styling of elements
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
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
[[File:Notification-guide-actor-omitted.png|thumb|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.
 * 400x400px]]
 * 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
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
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
Actions provide additional context, and allow users to access related content.

Keep the agent as the first action
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
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
Icons should be recognisable, simple and present consistent semantic relationships (look similar for similar notifications but different to unrelated ones).

Keep icons simple
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
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: 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.
 * 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.

Define a family of icons for similar events
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.