hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-28 01:07:49 +08:00
Code Issues Packages Projects Releases Wiki Activity
intellij-sdk-code-samples/topics/ui/principles/context_help.md
marianna.kononenko 8358a45c8b UX-2323 Update existing UI Guidelines: Context help
2025-02-04 14:38:14 +01:00

5.1 KiB
Raw Blame History

Context Help

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 or the application behavior. A full description of the functionality should be provided in product web help.

Context help can be shown as an inline help text, in a help tooltip, and in an empty state.

Inline help text

Context help in an inline text

Use an inline help text 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.

Tooltip

Context help in a tooltip

Use a tooltip:

  • 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.

Empty state

Empty state of a tool window

Fill in empty states 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.

When to use

Below you will find rules for tooltips and inline texts.

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.

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.

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.

Correct Don't explain every option Incorrect Every option has its tooltip
## How to use

See Inline help text, Tooltip, and .