Karol Lewandowski d8e83b57ea
UI Guidelines (#1308)
* Add UI Guidelines to  SDK docs

* Add UI Guidelines to  SDK docs

* Fixing build errors

* optimize PNGs

* add UI guidelines landing page placeholder

* IJ SDK Docs <-> UI guidelines crosslinks updated

* split_button.md: remove reference to removed setting

* use <ui-path>

* use MD instead of <note>

* use %gh-ic% links

* drop_down.md: fix <control>

* code samples: fix most obvious issues

* remove obsolete `_defaults.md`

* ijs.tree: UI cleanup

* Delete "under construction" pages

* Fix headers

* Add link-summary

* Remove invalid links

* Delete unused files

* Remove ''@2x' from image file names

* Use Markdown syntax for some images and tables

* Rename non-unique files to unique

* Remove alpha in images where content is unreadable

* align quotation marks

* Controls: cleanup/fixes, add code links, edit

* tooltip.md: fix HTML

* misc fixes

* typography.md: fix table contents

* typography.md: fix table header

* UI guidelines landing page + TOC fixes

* remove unused icons_list.md

* Normalize image paths

* validation_errors.md: Fix broken tab

* "correct"/"incorrect" labels styling

* Resize images to 50%

* button.topic: fixes

* grammar, spelling, minor edits

* remove '&nbsp;'

* fix 99px

* cleanup

* UI_kit.md: minor

* Fix "MRK058: Large image in paragraph rendered as a block element by default."

* button.topic: Add img[alt]

* mnemonics.md: Update "Contact Us" link to the IJSDK YouTrack

* split_button.md: Use ui-path

* UI landing: add feedback snippet

* Improve code snippets formatting and naming

* Fix code samples

* Fix code samples

* Add Kotlin variants for code samples

* Add icons_list.md

* crosslinks

* Change external link to https://intellij-icons.jetbrains.design/

* icons list -> https://intellij-icons.jetbrains.design

* Hide info about reducing split button to simple action button (now it is available through the registry only)

* reformat

* icons_style.md: Images in new line

---------

Co-authored-by: marianna.kononenko <marianna.kononenko@jetbrains.com>
Co-authored-by: Yann Cébron <yann.cebron@jetbrains.com>
2024-05-16 13:51:56 +02:00

98 lines
3.3 KiB
Markdown

<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# Context Help
<link-summary>Choosing a proper component for context help.</link-summary>
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/).
There are three ways to show context help:
* in a [help tooltip](tooltip.md)
* as [inline help text](inline_help_text.md)
* in an [empty state](empty_state.md)
This article explains when to use the first two. For when to use the empty state, see the [](empty_state.md) topic.
## Inline text or a tooltip
Use **inline help text** in settings dialogs:
* 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.
![](09_use_inline_help_text.png){width=600}
Use a **help tooltip** if:
* A dialog is often used. The more often a person uses an interface, the more likely they are to remember what each option does.
![](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.*
* There is no space for an inline text.
![](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}
## 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.
<format color="Red" style="bold">Incorrect</format>
![](06_explain_how_ui_works.png){width=418}
Do not explain common actions and entities. Show a regular tooltip with an action name and shortcut in this case.
| <format color="Red" style="bold">Incorrect</format> | <format color="Green" style="bold">Correct</format> |
|-----------------------------------------------------|-----------------------------------------------------|
| ![](07_explain_obvious_incorrect.png){width=300} | ![](07_explain_obvious_correct.png){width=145} |
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.
<format color="Red" style="bold">Incorrect</format>
![](08_explain_all_options.png){width=317}
## How to use
See [Inline help text](inline_help_text.md) and [Tooltip](tooltip.md).