diff --git a/images/ui/balloon/notification_balloon.png b/images/ui/balloon/notification_balloon.png new file mode 100644 index 00000000000..2d893cc5b31 Binary files /dev/null and b/images/ui/balloon/notification_balloon.png differ diff --git a/images/ui/balloon/notification_balloon_body_only_correct.png b/images/ui/balloon/notification_balloon_body_only_correct.png new file mode 100644 index 00000000000..b60cab6c7b5 Binary files /dev/null and b/images/ui/balloon/notification_balloon_body_only_correct.png differ diff --git a/images/ui/balloon/notification_balloon_body_only_correct_dark.png b/images/ui/balloon/notification_balloon_body_only_correct_dark.png new file mode 100644 index 00000000000..6694ce63a2a Binary files /dev/null and b/images/ui/balloon/notification_balloon_body_only_correct_dark.png differ diff --git a/images/ui/balloon/notification_balloon_body_only_incorrect.png b/images/ui/balloon/notification_balloon_body_only_incorrect.png new file mode 100644 index 00000000000..9a4b1aeabad Binary files /dev/null and b/images/ui/balloon/notification_balloon_body_only_incorrect.png differ diff --git a/images/ui/balloon/notification_balloon_body_only_incorrect_dark.png b/images/ui/balloon/notification_balloon_body_only_incorrect_dark.png new file mode 100644 index 00000000000..2ee67103249 Binary files /dev/null and b/images/ui/balloon/notification_balloon_body_only_incorrect_dark.png differ diff --git a/images/ui/balloon/notification_balloon_body_two_lines.png b/images/ui/balloon/notification_balloon_body_two_lines.png new file mode 100644 index 00000000000..4cdf6f6e419 Binary files /dev/null and b/images/ui/balloon/notification_balloon_body_two_lines.png differ diff --git a/images/ui/balloon/notification_balloon_body_two_lines_dark.png b/images/ui/balloon/notification_balloon_body_two_lines_dark.png new file mode 100644 index 00000000000..d535ffa8414 Binary files /dev/null and b/images/ui/balloon/notification_balloon_body_two_lines_dark.png differ diff --git a/images/ui/balloon/notification_balloon_dark.png b/images/ui/balloon/notification_balloon_dark.png new file mode 100644 index 00000000000..c83040286f9 Binary files /dev/null and b/images/ui/balloon/notification_balloon_dark.png differ diff --git a/images/ui/balloon/notification_balloon_error_actions.png b/images/ui/balloon/notification_balloon_error_actions.png new file mode 100644 index 00000000000..a77e7794c30 Binary files /dev/null and b/images/ui/balloon/notification_balloon_error_actions.png differ diff --git a/images/ui/balloon/notification_balloon_error_actions_dark.png b/images/ui/balloon/notification_balloon_error_actions_dark.png new file mode 100644 index 00000000000..6712df9906b Binary files /dev/null and b/images/ui/balloon/notification_balloon_error_actions_dark.png differ diff --git a/images/ui/balloon/notification_balloon_error_actions_text_correct.png b/images/ui/balloon/notification_balloon_error_actions_text_correct.png new file mode 100644 index 00000000000..14eb60f389b Binary files /dev/null and b/images/ui/balloon/notification_balloon_error_actions_text_correct.png differ diff --git a/images/ui/balloon/notification_balloon_error_actions_text_correct_dark.png b/images/ui/balloon/notification_balloon_error_actions_text_correct_dark.png new file mode 100644 index 00000000000..d5285c6007f Binary files /dev/null and b/images/ui/balloon/notification_balloon_error_actions_text_correct_dark.png differ diff --git a/images/ui/balloon/notification_balloon_error_actions_text_incorrect.png b/images/ui/balloon/notification_balloon_error_actions_text_incorrect.png new file mode 100644 index 00000000000..ce8fa50d243 Binary files /dev/null and b/images/ui/balloon/notification_balloon_error_actions_text_incorrect.png differ diff --git a/images/ui/balloon/notification_balloon_error_actions_text_incorrect_dark.png b/images/ui/balloon/notification_balloon_error_actions_text_incorrect_dark.png new file mode 100644 index 00000000000..cf2f4a15d0c Binary files /dev/null and b/images/ui/balloon/notification_balloon_error_actions_text_incorrect_dark.png differ diff --git a/images/ui/balloon/notification_balloon_more_actions.png b/images/ui/balloon/notification_balloon_more_actions.png new file mode 100644 index 00000000000..9705fbe5e21 Binary files /dev/null and b/images/ui/balloon/notification_balloon_more_actions.png differ diff --git a/images/ui/balloon/notification_balloon_more_actions_dark.png b/images/ui/balloon/notification_balloon_more_actions_dark.png new file mode 100644 index 00000000000..4ef5f870042 Binary files /dev/null and b/images/ui/balloon/notification_balloon_more_actions_dark.png differ diff --git a/images/ui/balloon/notification_balloon_plugin_icon.png b/images/ui/balloon/notification_balloon_plugin_icon.png new file mode 100644 index 00000000000..d8cb085b277 Binary files /dev/null and b/images/ui/balloon/notification_balloon_plugin_icon.png differ diff --git a/images/ui/balloon/notification_balloon_plugin_icon_dark.png b/images/ui/balloon/notification_balloon_plugin_icon_dark.png new file mode 100644 index 00000000000..299112f5fb1 Binary files /dev/null and b/images/ui/balloon/notification_balloon_plugin_icon_dark.png differ diff --git a/images/ui/balloon/notification_balloon_severity_error.png b/images/ui/balloon/notification_balloon_severity_error.png new file mode 100644 index 00000000000..33ad80a1018 Binary files /dev/null and b/images/ui/balloon/notification_balloon_severity_error.png differ diff --git a/images/ui/balloon/notification_balloon_severity_error_dark.png b/images/ui/balloon/notification_balloon_severity_error_dark.png new file mode 100644 index 00000000000..6712df9906b Binary files /dev/null and b/images/ui/balloon/notification_balloon_severity_error_dark.png differ diff --git a/images/ui/balloon/notification_balloon_severity_info.png b/images/ui/balloon/notification_balloon_severity_info.png new file mode 100644 index 00000000000..257e7ccec2e Binary files /dev/null and b/images/ui/balloon/notification_balloon_severity_info.png differ diff --git a/images/ui/balloon/notification_balloon_severity_info_dark.png b/images/ui/balloon/notification_balloon_severity_info_dark.png new file mode 100644 index 00000000000..9ebe2376a69 Binary files /dev/null and b/images/ui/balloon/notification_balloon_severity_info_dark.png differ diff --git a/images/ui/balloon/notification_balloon_severity_warning.png b/images/ui/balloon/notification_balloon_severity_warning.png new file mode 100644 index 00000000000..d6ac71ce819 Binary files /dev/null and b/images/ui/balloon/notification_balloon_severity_warning.png differ diff --git a/images/ui/balloon/notification_balloon_severity_warning_dark.png b/images/ui/balloon/notification_balloon_severity_warning_dark.png new file mode 100644 index 00000000000..f22d271808f Binary files /dev/null and b/images/ui/balloon/notification_balloon_severity_warning_dark.png differ diff --git a/images/ui/balloon/notification_balloon_suggestion_configuration.png b/images/ui/balloon/notification_balloon_suggestion_configuration.png new file mode 100644 index 00000000000..4f5fa5d1093 Binary files /dev/null and b/images/ui/balloon/notification_balloon_suggestion_configuration.png differ diff --git a/images/ui/balloon/notification_balloon_suggestion_configuration_dark.png b/images/ui/balloon/notification_balloon_suggestion_configuration_dark.png new file mode 100644 index 00000000000..b9281ba963f Binary files /dev/null and b/images/ui/balloon/notification_balloon_suggestion_configuration_dark.png differ diff --git a/images/ui/balloon/notification_balloon_suggestion_request_input-1.png b/images/ui/balloon/notification_balloon_suggestion_request_input-1.png new file mode 100644 index 00000000000..ec738904438 Binary files /dev/null and b/images/ui/balloon/notification_balloon_suggestion_request_input-1.png differ diff --git a/images/ui/balloon/notification_balloon_suggestion_request_input.png b/images/ui/balloon/notification_balloon_suggestion_request_input.png new file mode 100644 index 00000000000..c7ee8b486d8 Binary files /dev/null and b/images/ui/balloon/notification_balloon_suggestion_request_input.png differ diff --git a/images/ui/balloon/notification_balloon_suggestion_request_input_dark-1.png b/images/ui/balloon/notification_balloon_suggestion_request_input_dark-1.png new file mode 100644 index 00000000000..98b604d4528 Binary files /dev/null and b/images/ui/balloon/notification_balloon_suggestion_request_input_dark-1.png differ diff --git a/images/ui/balloon/notification_balloon_suggestion_request_input_dark.png b/images/ui/balloon/notification_balloon_suggestion_request_input_dark.png new file mode 100644 index 00000000000..8501461aaea Binary files /dev/null and b/images/ui/balloon/notification_balloon_suggestion_request_input_dark.png differ diff --git a/images/ui/balloon/notification_balloon_timeline_automatic_configuration.png b/images/ui/balloon/notification_balloon_timeline_automatic_configuration.png new file mode 100644 index 00000000000..b60cab6c7b5 Binary files /dev/null and b/images/ui/balloon/notification_balloon_timeline_automatic_configuration.png differ diff --git a/images/ui/balloon/notification_balloon_timeline_automatic_configuration_dark.png b/images/ui/balloon/notification_balloon_timeline_automatic_configuration_dark.png new file mode 100644 index 00000000000..6694ce63a2a Binary files /dev/null and b/images/ui/balloon/notification_balloon_timeline_automatic_configuration_dark.png differ diff --git a/images/ui/balloon/notification_balloon_timeline_long_process.png b/images/ui/balloon/notification_balloon_timeline_long_process.png new file mode 100644 index 00000000000..5b2dad1f86b Binary files /dev/null and b/images/ui/balloon/notification_balloon_timeline_long_process.png differ diff --git a/images/ui/balloon/notification_balloon_timeline_long_process_dark.png b/images/ui/balloon/notification_balloon_timeline_long_process_dark.png new file mode 100644 index 00000000000..1895b6f7bb9 Binary files /dev/null and b/images/ui/balloon/notification_balloon_timeline_long_process_dark.png differ diff --git a/images/ui/balloon/notification_balloon_timeline_no_context_action.png b/images/ui/balloon/notification_balloon_timeline_no_context_action.png new file mode 100644 index 00000000000..e1d9e63aea7 Binary files /dev/null and b/images/ui/balloon/notification_balloon_timeline_no_context_action.png differ diff --git a/images/ui/balloon/notification_balloon_timeline_no_context_action_dark.png b/images/ui/balloon/notification_balloon_timeline_no_context_action_dark.png new file mode 100644 index 00000000000..39fdb719fdb Binary files /dev/null and b/images/ui/balloon/notification_balloon_timeline_no_context_action_dark.png differ diff --git a/images/ui/balloon/notification_balloon_title_only.png b/images/ui/balloon/notification_balloon_title_only.png new file mode 100644 index 00000000000..459335221a6 Binary files /dev/null and b/images/ui/balloon/notification_balloon_title_only.png differ diff --git a/images/ui/balloon/notification_balloon_title_only_dark.png b/images/ui/balloon/notification_balloon_title_only_dark.png new file mode 100644 index 00000000000..24c0127f8df Binary files /dev/null and b/images/ui/balloon/notification_balloon_title_only_dark.png differ diff --git a/images/ui/balloon/notification_balloon_toolwindow.png b/images/ui/balloon/notification_balloon_toolwindow.png new file mode 100644 index 00000000000..cdabb807529 Binary files /dev/null and b/images/ui/balloon/notification_balloon_toolwindow.png differ diff --git a/images/ui/balloon/notification_balloon_toolwindow_dark.png b/images/ui/balloon/notification_balloon_toolwindow_dark.png new file mode 100644 index 00000000000..06fb49d9f43 Binary files /dev/null and b/images/ui/balloon/notification_balloon_toolwindow_dark.png differ diff --git a/topics/ui/controls/balloon.md b/topics/ui/controls/balloon.md index 73224e3a0d8..464c2029166 100644 --- a/topics/ui/controls/balloon.md +++ b/topics/ui/controls/balloon.md @@ -1,8 +1,8 @@ -# Balloon +# Notification Balloon -UI guidelines on using balloons. +UI guidelines on using notification balloons. @@ -12,131 +12,178 @@ -Balloon notifications inform users of the events or system states related to a project or IDE. +Notification balloons inform users of the events or system states related to a project or IDE. -![](01_balloon_example.png){width=389} +![A notification balloon for a found database connection with an action to connect to it](notification_balloon.png){width=706} + +## Suggestion and timeline notifications + +There are two types of notification balloons: +* **Suggestion** notifications show the recommended action as a noticeable button. Use to suggest an automatic configuration for a project or an IDE, or to ask for user input. +* **Timeline** notifications show useful actions as links. Use for showing results of long processes, automatic configuration, or actions without context. + +These types appear in different sections of the Notifications tool window: + +![The Notifications toolwindow with suggestion and timeline notifications in different sections](notification_balloon_toolwindow.png){width=706} ## When to use -Use a balloon notification if: +### Show result of a potentially long process + +Use a timeline notification. + +![Two notifications with results of long processes: project build and git push](notification_balloon_timeline_long_process.png){width=706} + +### Show result of an action without context + +Use a timeline notification when an action was called from a context that is already closed, like a dialog or a popup. + +![Two notifications with results of actions that are not tied to a particular dialog: the UI language was changed and project folders excluded from Windows Defender](notification_balloon_timeline_no_context_action.png){width=706} + +### Show result of an automatic configuration -* There is no need to point to a particular context or location in the interface. -* User action is recommended but not required immediately. +Use a timeline notification when the project or IDE settings were automatically configured, and the user might need to check the changes. + +![A notification about automatic project configuration: the workspace is restored after a branch is checked out](notification_balloon_timeline_automatic_configuration.png){width=706} + +### Suggest an action to configure a project or an IDE + +Use a suggestion notification to promote an action for project or IDE configuration when not taking this action might lead to less optimal functioning or errors. + +![Two examples of a suggestion notification for project or IDE configuration: Windows Defender affecting the IDE with a suggestion to explude a project from it, and a suggestion for switching the UI to an available language](notification_balloon_suggestion_configuration.png){width=706} + +### Request user input + +Use a suggestion notification to ask the user for an additional input or action that is not connected to their own workflows. + +![Two suggestion notifications for requiring user input: a request to fill a survey and a notice about a discount for PhpStorm](notification_balloon_suggestion_request_input.png){width=706} -In other cases, choose another [notification type](notification_types.md). ## How to use +### Sticky or timed + +**Sticky** notifications stay on screen until the user clicks any of its actions or closes it. By default, use this behavior for [suggestion notifications](#suggestion-and-timeline-notifications). + +**Timed** notifications stay on screen for 10 seconds and then hide. By default, use this behavior for [timeline notifications](#suggestion-and-timeline-notifications). + +Change the default behavior if it makes sense in a particular use case. + + ### Message severity #### Error -Use to inform of a critical event or state that might disrupt the user's experience. +Use to inform of a critical event or state that might disrupt the user experience. -![](02_error.png){width=389} +![An error notification about a plugin being suspended because it requires another plugin that is missing](notification_balloon_severity_error.png){width=706} #### Warning -Use in case of an event or state that might slow the user's work down or require an action to fix the IDE settings. +Use in case an event or state might slow down the user's work or require an action to fix the project or IDE settings. -![](03_warning.png){width=389} +![A warning notification about IDE shortcuts conflicting with macOS shortcuts](notification_balloon_severity_warning.png){width=706} #### Information -Use to suggest optimizations for the IDE settings and notify about the results of a process that is not tied to any tool window. - -![](04_information.png){width=389} - -#### Information about a certain plugin +Use in all other cases. -Use to show a plugin-related suggestion. +![An information notification requesting to fill a survey about a plugin](notification_balloon_severity_info.png){width=706} -Add the plugin’s icon to indicate that the notification relates to a particular plugin. Use a 16×16 SVG icon. +
-![](05_information_plugin.png){width=389} +When possible, use a plugin or functionality icon instead of the Info icon. This helps identifing the source of the notification quicker. -### Sticky or Timed +![Two notifications with dedicated icons instead of the generic info icon: database connection found with the database icon and suggested plugins found with the generic plugin icon](notification_balloon_plugin_icon.png){width=706} -By default, choose a **sticky** balloon. Sticky notifications stay on screen until the user clicks a link in the message or closes the notification manually. -This behaviour is preferable as it guarantees the user will not miss the notification. -Use a **timed** notification when the message is informational, and missing it will not affect the user’s workflow. -Timed notifications stay on screen for 10 seconds and then disappear. -They can be viewed later in the Event Log. +### Text -### Title +#### Writing -Briefly describe the event and the context in which it occurred, e.g., a particular plugin or library, VCS, a run/debug configuration, etc. +[Write short and clear](writing_short.md) as notifications have limited space and may appear for a short time. -[Write short and clear](writing_short.md) as the title should fit in one line. +Use sentence case for both the title and the body. -Use sentence case and follow the [punctuation rules](punctuation.md). +Follow the [punctuation rules](punctuation.md). -If the message fits well in one sentence and does not require a separate title, choose either a title or a body: +#### Title +Describe the event and the context in which it occurred. The context could be the name of a plugin, library, or functionality. -* Use title-only message when it’s short and fits in one line: +#### Body +Provide the details on the event or system state to help users decide what to do next. Consider answering these questions: +* What was the cause of this state? +* What are the consequences? +* What is affected: files, libraries, versions, plugins, etc.? -![](03_warning.png){width=389} +#### Using only title or body -* Use only body text when the message fits in two lines and the title would duplicate its meaning, fully or partially: +Use only the title when it is short and fits in one line. -Incorrect +![A notification with the title only about the number of files updated after git pull](notification_balloon_title_only.png){width=706} -![](06_only_text_incorrect.png){width=389} +Use only the body text when it fits in two lines and the title would duplicate its meaning. Correct +![A notification with the body only about the workspace being restored after branch checkout](notification_balloon_body_only_correct.png){width=706} -![](06_only_text_correct.png){width=389} - -### Body +Incorrect +![The same notification as above but with duplicating information in the title](notification_balloon_body_only_incorrect.png){width=706} -Provide the details on the event or system state to help users decide what to do next: +#### Long messages are collapsed -* What is the cause or trigger? -* What are the consequences? -* What exactly is affected? Files, libraries, versions, plugins, etc. +Only the first two lines of the body text are visible by default, the rest is shown when expanded. Place the most important information in the beginning of the body text so it is visible by default. -Note that only the first line of the body text is visible by default. The rest of the message is only visible when expanded with an arrow icon. -Make the beginning of the text most informative. +![A notification about Windows Defender slowing down the IDE in the collapsed and expanded states. The notification body is long and takes 9 lines](notification_balloon_body_two_lines.png){width=706} -![](07_expandable.png){width=777} ### Actions Add actions to help users take the next steps: fix a problem, view relevant information, configure settings, etc. -If the notification is informational and there is a possibility it might appear too often, add the "Don’t ask again" action: -![](04_information.png){width=389} +#### Number of actions -The Preferable number of actions is two, as it is easier for the user to choose. +The preferable number of actions is two, as it is easier for the user to choose. If more than two actions are useful, place the most likely to be used first, and hide the others under the More dropdown: -If a set of more than 2 actions is useful for the user, place the primary action first, and hide the others under the "More actions" dropdown: +![The Windows Defender notification with the primary action "Exclude folders" on the left and 3 more actions under the "More" dropdown link](notification_balloon_more_actions.png){width=706} -![](08_dropdown.png){width=389} +#### Actions in error and warning notifications If the notification reports an error or warning, always provide an action to help users fix the problem: -![](02_error.png){width=389} +![An error notification about the plugin being suspended because it requires another plugin to work with actions "Manage plugins" and "Disable the suspended plugin"](notification_balloon_error_actions.png){width=706} -If no actions are available, provide more details in the body text, e.g., how to fix the error or what is the warning/error cause: +If no actions are available, provide more details in the body text: how to fix or what was the cause. + +Correct +![A notification about a plugin being incompatible with the current IDE version with a suggestion to update the plugin](notification_balloon_error_actions_text_correct.png){width=706} Incorrect +![The name notification but without the suggestion to update the plugin](notification_balloon_error_actions_text_incorrect.png){width=706} -![](09_error_incorrect.png){width=389} -Correct +#### The "Don't show again" action + +If the notification is informational, and there is a possibility it might appear too often, add the Don’t show again action: + +![A notification about a database connection found with the "Don't show again link"](notification_balloon.png){width=706} + + +#### Capitalization + +Use sentence capitalization for all actions in notification balloons. + -![](09_error_correct.png){width=389} -### Naming a notification group +## Naming a notification group -Each balloon notification belongs to a group. Groups can be seen in Settings | Appearance & Behavior | Notifications. +Each notification balloon belongs to a group. Groups can be seen in Settings | Appearance & Behavior | Notifications. To name a notification group, follow these rules: * Name the group with an ending to the phrase "Notifications in this group notify the user about…". Examples: _Automatic indent detection_, _Content root duplicates_. * If a name about a particular process or event cannot be given, use the name of a subsystem or plugin. Examples: _HTTP Client_, _Power Save Mode_. * When a group contains notifications about errors or problems, do not use a verb. Example: _Debugger errors_, not _Debugger errors ~~found~~_. -* Do **not** use words "notification" or "group". They are implied from the settings context. +* Do not use words "notification" or "group". They are implied from the settings context.