diff --git a/images/ui/context_help/context_help_alternatives.png b/images/ui/context_help/context_help_alternatives.png new file mode 100644 index 000000000..4d90e997b Binary files /dev/null and b/images/ui/context_help/context_help_alternatives.png differ diff --git a/images/ui/context_help/context_help_alternatives_dark.png b/images/ui/context_help/context_help_alternatives_dark.png new file mode 100644 index 000000000..a4fd1fc26 Binary files /dev/null and b/images/ui/context_help/context_help_alternatives_dark.png differ diff --git a/images/ui/context_help/context_help_explain.png b/images/ui/context_help/context_help_explain.png new file mode 100644 index 000000000..cb24c63cf Binary files /dev/null and b/images/ui/context_help/context_help_explain.png differ diff --git a/images/ui/context_help/context_help_explain_dark.png b/images/ui/context_help/context_help_explain_dark.png new file mode 100644 index 000000000..4b207e638 Binary files /dev/null and b/images/ui/context_help/context_help_explain_dark.png differ diff --git a/images/ui/context_help/context_help_explain_simple_correct.png b/images/ui/context_help/context_help_explain_simple_correct.png new file mode 100644 index 000000000..2d55fe1b1 Binary files /dev/null and b/images/ui/context_help/context_help_explain_simple_correct.png differ diff --git a/images/ui/context_help/context_help_explain_simple_correct_dark.png b/images/ui/context_help/context_help_explain_simple_correct_dark.png new file mode 100644 index 000000000..2870c8ebb Binary files /dev/null and b/images/ui/context_help/context_help_explain_simple_correct_dark.png differ diff --git a/images/ui/context_help/context_help_explain_simple_incorrect.png b/images/ui/context_help/context_help_explain_simple_incorrect.png new file mode 100644 index 000000000..4e8477c30 Binary files /dev/null and b/images/ui/context_help/context_help_explain_simple_incorrect.png differ diff --git a/images/ui/context_help/context_help_explain_simple_incorrect_dark.png b/images/ui/context_help/context_help_explain_simple_incorrect_dark.png new file mode 100644 index 000000000..8e84e95fa Binary files /dev/null and b/images/ui/context_help/context_help_explain_simple_incorrect_dark.png differ diff --git a/images/ui/context_help/context_help_explain_too_many_correct.png b/images/ui/context_help/context_help_explain_too_many_correct.png new file mode 100644 index 000000000..6fc163e97 Binary files /dev/null and b/images/ui/context_help/context_help_explain_too_many_correct.png differ diff --git a/images/ui/context_help/context_help_explain_too_many_correct_dark.png b/images/ui/context_help/context_help_explain_too_many_correct_dark.png new file mode 100644 index 000000000..67cb64d01 Binary files /dev/null and b/images/ui/context_help/context_help_explain_too_many_correct_dark.png differ diff --git a/images/ui/context_help/context_help_explain_too_many_incorrect.png b/images/ui/context_help/context_help_explain_too_many_incorrect.png new file mode 100644 index 000000000..8ae014cf4 Binary files /dev/null and b/images/ui/context_help/context_help_explain_too_many_incorrect.png differ diff --git a/images/ui/context_help/context_help_explain_too_many_incorrect_dark.png b/images/ui/context_help/context_help_explain_too_many_incorrect_dark.png new file mode 100644 index 000000000..3868ebc96 Binary files /dev/null and b/images/ui/context_help/context_help_explain_too_many_incorrect_dark.png differ diff --git a/images/ui/context_help/context_help_explain_ui_correct.png b/images/ui/context_help/context_help_explain_ui_correct.png new file mode 100644 index 000000000..abd2461d4 Binary files /dev/null and b/images/ui/context_help/context_help_explain_ui_correct.png differ diff --git a/images/ui/context_help/context_help_explain_ui_correct_dark.png b/images/ui/context_help/context_help_explain_ui_correct_dark.png new file mode 100644 index 000000000..be4c90c0a Binary files /dev/null and b/images/ui/context_help/context_help_explain_ui_correct_dark.png differ diff --git a/images/ui/context_help/context_help_explain_ui_incorrect.png b/images/ui/context_help/context_help_explain_ui_incorrect.png new file mode 100644 index 000000000..72d7257d9 Binary files /dev/null and b/images/ui/context_help/context_help_explain_ui_incorrect.png differ diff --git a/images/ui/context_help/context_help_explain_ui_incorrect_dark.png b/images/ui/context_help/context_help_explain_ui_incorrect_dark.png new file mode 100644 index 000000000..ffff5f42d Binary files /dev/null and b/images/ui/context_help/context_help_explain_ui_incorrect_dark.png differ diff --git a/images/ui/context_help/context_help_inline_text.png b/images/ui/context_help/context_help_inline_text.png new file mode 100644 index 000000000..fc474753f Binary files /dev/null and b/images/ui/context_help/context_help_inline_text.png differ diff --git a/images/ui/context_help/context_help_inline_text_dark.png b/images/ui/context_help/context_help_inline_text_dark.png new file mode 100644 index 000000000..ae79c84ae Binary files /dev/null and b/images/ui/context_help/context_help_inline_text_dark.png differ diff --git a/images/ui/context_help/context_help_input_format.png b/images/ui/context_help/context_help_input_format.png new file mode 100644 index 000000000..3f5a7b5c9 Binary files /dev/null and b/images/ui/context_help/context_help_input_format.png differ diff --git a/images/ui/context_help/context_help_input_format_dark.png b/images/ui/context_help/context_help_input_format_dark.png new file mode 100644 index 000000000..21e2ccb6b Binary files /dev/null and b/images/ui/context_help/context_help_input_format_dark.png differ diff --git a/images/ui/context_help/context_help_input_warning.png b/images/ui/context_help/context_help_input_warning.png new file mode 100644 index 000000000..d45f43fe5 Binary files /dev/null and b/images/ui/context_help/context_help_input_warning.png differ diff --git a/images/ui/context_help/context_help_input_warning_dark.png b/images/ui/context_help/context_help_input_warning_dark.png new file mode 100644 index 000000000..4efdfc8c4 Binary files /dev/null and b/images/ui/context_help/context_help_input_warning_dark.png differ diff --git a/images/ui/context_help/context_help_limitation.png b/images/ui/context_help/context_help_limitation.png new file mode 100644 index 000000000..ced9e4f45 Binary files /dev/null and b/images/ui/context_help/context_help_limitation.png differ diff --git a/images/ui/context_help/context_help_limitation_dark.png b/images/ui/context_help/context_help_limitation_dark.png new file mode 100644 index 000000000..09db7bb93 Binary files /dev/null and b/images/ui/context_help/context_help_limitation_dark.png differ diff --git a/images/ui/context_help/context_help_navigation.png b/images/ui/context_help/context_help_navigation.png new file mode 100644 index 000000000..cfd611232 Binary files /dev/null and b/images/ui/context_help/context_help_navigation.png differ diff --git a/images/ui/context_help/context_help_navigation_dark.png b/images/ui/context_help/context_help_navigation_dark.png new file mode 100644 index 000000000..5b97e2cb4 Binary files /dev/null and b/images/ui/context_help/context_help_navigation_dark.png differ diff --git a/images/ui/context_help/context_help_terms.png b/images/ui/context_help/context_help_terms.png new file mode 100644 index 000000000..da5ee8d44 Binary files /dev/null and b/images/ui/context_help/context_help_terms.png differ diff --git a/images/ui/context_help/context_help_terms_dark.png b/images/ui/context_help/context_help_terms_dark.png new file mode 100644 index 000000000..f72fb977a Binary files /dev/null and b/images/ui/context_help/context_help_terms_dark.png differ diff --git a/images/ui/context_help/context_help_tooltip.png b/images/ui/context_help/context_help_tooltip.png new file mode 100644 index 000000000..aabba3f24 Binary files /dev/null and b/images/ui/context_help/context_help_tooltip.png differ diff --git a/images/ui/context_help/context_help_tooltip_dark.png b/images/ui/context_help/context_help_tooltip_dark.png new file mode 100644 index 000000000..56e24a13a Binary files /dev/null and b/images/ui/context_help/context_help_tooltip_dark.png differ diff --git a/images/ui/context_help/database tool window.png b/images/ui/context_help/database tool window.png new file mode 100644 index 000000000..98973d297 Binary files /dev/null and b/images/ui/context_help/database tool window.png differ diff --git a/images/ui/context_help/database tool window_dark.png b/images/ui/context_help/database tool window_dark.png new file mode 100644 index 000000000..44d5122f1 Binary files /dev/null and b/images/ui/context_help/database tool window_dark.png differ diff --git a/images/ui/empty_state/empty_state_structure.png b/images/ui/empty_state/empty_state_structure.png new file mode 100644 index 000000000..ab03829e8 Binary files /dev/null and b/images/ui/empty_state/empty_state_structure.png differ diff --git a/images/ui/empty_state/empty_state_structure_dark.png b/images/ui/empty_state/empty_state_structure_dark.png new file mode 100644 index 000000000..aa6f9eec3 Binary files /dev/null and b/images/ui/empty_state/empty_state_structure_dark.png differ diff --git a/topics/ui/principles/context_help.md b/topics/ui/principles/context_help.md index 113c1a2b3..50bcbd59c 100644 --- a/topics/ui/principles/context_help.md +++ b/topics/ui/principles/context_help.md @@ -4,101 +4,143 @@ Choosing a proper component for context help. -Use context help to briefly explain how a functionality works if it is not clear from the UI and the application behavior. Provide a full description of the functionality in [product web help](https://www.jetbrains.com/help/idea/). +Use context help to briefly explain how a functionality works if it is not clear from the UI or the application behavior. A full description of the functionality should be provided in [product web help](https://www.jetbrains.com/help/idea/). -There are three ways to show context help: +Context help can be shown as an [inline help text](inline_help_text.md), in a [help tooltip](tooltip.md), and in an [empty state](empty_state.md). -* in a [help tooltip](tooltip.md) -* as [inline help text](inline_help_text.md) -* in an [empty state](empty_state.md) +## Inline help text -This article explains when to use the first two. For when to use the empty state, see the [](empty_state.md) topic. +Context help in an inline text -## Inline text or a tooltip +Use an [inline help text](inline_help_text.md) in settings dialogs that are not constrained by space and are not frequently used. Since settings are rarely changed, users may forget their purpose, so displaying the information immediately makes sense. -Use **inline help text** in settings dialogs: +## Tooltip -* Settings are rarely changed. Users may forget what a setting does when they use it the next time, so it makes sense to provide additional information straight away. -* Settings dialogs are usually not constrained in space. In most cases, it is possible to fit in a help text. +Context help in a tooltip -![](09_use_inline_help_text.png){width=600} +Use a [tooltip](tooltip.md): +- If the space is not enough for showing the inline help text. +- In frequently used dialogs, tool windows, or popups. The more often a person uses an interface, the more likely they are to remember what each option does. +- For icons or other controls that do not have a label. -Use a **help tooltip** if: +## Empty state -* A dialog is often used. The more often a person uses an interface, the more likely they are to remember what each option does. +Empty state of a tool window - ![](10_use_help_tooltip.png){width=573 style=block} - *A refactoring dialog is used more often than a settings dialog. A help tooltip is less distracting than an inline help text.* +Fill in [empty states](empty_state.md) of tool windows, tables, trees, and other containers with: +- a reason why the data is missing +- an action that can fix it +- a link to a corresponding article in the web help. -* There is no space for an inline text. +## When to use - ![](11_no_space_in_settings.png){width=734} - -* The control that needs explanation is an icon or does not have a label. - - ![](03_action_help_tooltip.png){width=305} - -## When to use context help - -Explain complex behavior that a short action or a setting name cannot convey clearly. - -![](04_question_icon_tooltip.png){width=543} - -![](02_text_size.png){width=380} - -Explain IDE-specific entities. - -![](01_IDE_specific.png){width=300} - -Provide input format requirements and examples. - -![](02_formatting_example.png){width=478} - -Suggest alternative ways. - -![](03_alternative_ways.png){width=418} - -Warn about possible problems. - -![](04_possible_problems.png){width=361} - -Explain limitations. - -![](05_limitations.png){width=432} - -Provide quick navigation to related settings. - -![](04_link_internal.png){width=345} +Below you will find rules for [tooltips](tooltip.md) and [inline texts](inline_help_text.md). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Explain a setting + +

Explain complex behavior that a short action or a setting name cannot convey clearly.

+
+ Input format requirements + +

Provide input format requirements and examples.

+
+ Suggest alternative ways + +

Suggest alternative ways.

+
+ Warn about possible issues + +

Warn about possible issues.

+
+ Explain limitations + +

Explain limitations.

+
+ Provide quick navigation to related settings + +

Provide quick navigation to related settings.

+
+ Explain IDE-specific entities + +

Explain IDE-specific entities.

+
## When not to use Do not use context help to explain how the user interface works. If you need to explain that, consider redesigning the UI. -Incorrect - -![](06_explain_how_ui_works.png){width=418} + + + + + +
+ Correct + Don't explain how UI elements should work + + Incorrect + Incorrect UI requires additional explanation +
Do not explain common actions and entities. Show a regular tooltip with an action name and shortcut in this case. - - +
- - - - - - + +
IncorrectCorrect
+ Correct + Don't explain common actions + + Incorrect + Common actions are explained in the tooltip +
Do not explain each option. Too many help icons or too much inline text make a dialog cluttered and harder to navigate visually. If all options need to be explained, consider rewriting the labels to make them clearer. -Incorrect - -![](08_explain_all_options.png){width=317} - + + + + + +
+ Correct + Don't explain every option + + Incorrect + Every option has its tooltip +
## How to use -See [Inline help text](inline_help_text.md) and [Tooltip](tooltip.md). +See [Inline help text](inline_help_text.md), [Tooltip](tooltip.md), and [](empty_state.md).