Icons` class (e.g., [`GithubIcons`](%gh-ic%/plugins/github/gen/org/jetbrains/plugins/github/GithubIcons.java)).
-If custom icons are required, please refer to the detailed [design guide](https://jetbrains.design/intellij/principles/icons/).
+If custom icons are required, please refer to detailed [design guide](icons_style.md).
To generate SVG icons suited for the IntelliJ-based IDEs, also consider third-party web tool [IntelliJ Icon Generator](https://bjansen.github.io/intellij-icon-generator/).
## Organizing Icons
@@ -300,9 +301,9 @@ prescribed colors within their icons:
| Light | `#6C707E` ▆ |
| Dark | `#CED0D6` ▆ |
-> Various online resources, like the IntelliJ Platform UI Guidelines
-> [here](https://jetbrains.design/intellij/components/tool_window/#07) and
-> [here](https://jetbrains.design/intellij/principles/icons/#grid-and-size),
+> Various online resources, like the UI Guidelines
+> [here](tool_window.md) and
+> [here](icons_style.md#grid-and-size),
> will be updated soon and currently don't include information about the New UI.
>
{style="note"}
diff --git a/topics/reference_guide/inspection_options.md b/topics/reference_guide/inspection_options.md
index 360310fea..3217b42e4 100644
--- a/topics/reference_guide/inspection_options.md
+++ b/topics/reference_guide/inspection_options.md
@@ -18,7 +18,7 @@ Currently, there are two ways of providing the inspection options:
{style="note"}
Declarative API allows to:
-* delegate component rendering to the platform and make all the inspection options UI consistent and compliant with the [IntelliJ Platform UI Guideline](https://jetbrains.design/intellij/)
+* delegate component rendering to the platform and make all the inspection options UI consistent and compliant with the [](ui_guidelines_welcome.md)
* optimize checking whether the inspection contains any options
* manipulate options in places other than inspection panels (e.g., in quick fixes)
* render options in contexts other than IntelliJ Platform-based IDEs
diff --git a/topics/reference_guide/themes_metadata.md b/topics/reference_guide/themes_metadata.md
index 1168c324d..a85b1afe4 100644
--- a/topics/reference_guide/themes_metadata.md
+++ b/topics/reference_guide/themes_metadata.md
@@ -1,6 +1,6 @@
-# Exposing Theme Metadata
+
-
+# Exposing Theme Metadata
Exposing plugin's UI components' customization keys allowing theme developers to change your components look.
@@ -94,7 +94,7 @@ All keys must follow this Naming Pattern:
| **`Focused`** | The current focused component. | `Button.focusedBorderColor` |
| **`Selected`** | A selected tab or any other control that has equally meaningful selected and inactive states. | `ToolWindow.HeaderTab.selectedBackground` |
| **`Hover`**
**`Pressed`**
| An action as indicated in states. | `Link.hoverForeground`
`Link.pressedForeground`
|
-| **`Error`**
**`Warning`**
**`Success`**
| Validation states. [See example](https://jetbrains.design/intellij/principles/validation_errors/) in the guide article. | `ValidationTooltip.errorBackground`
`ValidationTooltip.warningBorderColor`
|
+| **`Error`**
**`Warning`**
**`Success`**
| Validation states. [See example](validation_errors.md) in UI Guidelines. | `ValidationTooltip.errorBackground`
`ValidationTooltip.warningBorderColor`
|
| **`Disabled`** | Unavailable components. | `Label.disabledForeground` |
#### Part
diff --git a/topics/tutorials/code_inspections.md b/topics/tutorials/code_inspections.md
index 3b9b0a72d..78eae6602 100644
--- a/topics/tutorials/code_inspections.md
+++ b/topics/tutorials/code_inspections.md
@@ -8,7 +8,7 @@
**Product Help:** [Code Inspection](https://www.jetbrains.com/idea/webhelp/code-inspection.html), [Creating Custom Inspections](https://www.jetbrains.com/idea/help/creating-custom-inspections.html)
-**Platform UI Guidelines:** [Inspections](https://jetbrains.design/intellij/text/inspections/)
+**UI Guidelines:** [](inspections.md)
@@ -16,7 +16,7 @@ The IntelliJ Platform provides tools designed for static code analysis called _c
Custom code inspections can be implemented as IntelliJ Platform plugins.
An example of the plugin approach is the [comparing_string_references_inspection](%gh-sdk-samples-master%/comparing_string_references_inspection) code sample.
-See the [Inspections](https://jetbrains.design/intellij/text/inspections/) topic in the IntelliJ Platform UI Guidelines on naming, writing description, and message texts for inspections.
+See the [Inspections](inspections.md) topic in UI Guidelines on naming, writing description, and message texts for inspections.
## Creating an Inspection Plugin
@@ -112,7 +112,7 @@ The change to the PSI tree is accomplished by the usual approach to modification
The inspection description is an HTML file.
The description is displayed in the upper right panel of the Inspections settings dialog when an inspection is selected from the list.
-See the [Inspections](https://jetbrains.design/intellij/text/inspections/) topic in the IntelliJ Platform UI Guidelines on important guidelines for writing the description.
+See the [Inspections](inspections.md) topic in UI Guidelines on important guidelines for writing the description.
Implicit in using [`LocalInspectionTool`](%gh-ic%/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java) in the class hierarchy of the inspection implementation means following some conventions.
diff --git a/topics/tutorials/code_intentions.md b/topics/tutorials/code_intentions.md
index a65da68a7..d514bc144 100644
--- a/topics/tutorials/code_intentions.md
+++ b/topics/tutorials/code_intentions.md
@@ -8,7 +8,7 @@
**Product Help:** [Intention Actions](https://www.jetbrains.com/help/idea/intention-actions.html)
-**Platform UI Guidelines:** [Inspections](https://jetbrains.design/intellij/text/inspections/)
+**UI Guidelines:** [](inspections.md)
@@ -20,7 +20,7 @@ In addition, the sample plugin contains a JUnit-based test.
The IntelliJ Platform analyzes your code and helps handle situations that may result in errors.
When a possible problem is suspected, the IDE suggests an appropriate intention action, denoted with special icons.
-See [Inspections](https://jetbrains.design/intellij/text/inspections/) topic in the IntelliJ Platform UI Guidelines on naming, writing description, and message texts for inspections/intentions.
+See [Inspections](inspections.md) topic in UI Guidelines on naming, writing description, and message texts for inspections/intentions.
You can view a list of all available intention actions as well as enable/disable them using the [Intentions List](https://www.jetbrains.com/help/idea/intention-actions.html#intention-settings) in Settings | Editor | Intentions.
diff --git a/topics/ui/components/tool_window.md b/topics/ui/components/tool_window.md
new file mode 100644
index 000000000..fe5b1e95a
--- /dev/null
+++ b/topics/ui/components/tool_window.md
@@ -0,0 +1,55 @@
+
+
+# Tool Window
+
+UI guidelines on using tool windows.
+
+A tool window is a pane inside the main IDE window. For information about tool windows, see [IntelliJ IDEA Web Help](https://www.jetbrains.com/help/idea/tool-windows.html). For information about implementing tool windows, see [](tool_windows.md).
+
+{width=960}
+
+## When to use
+
+Use the tool window to show a large amount of information that the user needs while working side-by-side with the editor or other tool windows. For example, viewing the project structure, running and debugging an application, and viewing git log.
+
+If the amount of information is small, show it in the editor, main toolbar, status bar or popup. For example, show version control changes on the editor gutter, breadcrumbs in the main toolbar, current branch and file details in the status bar, quick doc in a popup.
+
+If the user does not need the information from the main window to complete an operation, show the content in the popup or dialog window. For example, Search Everywhere popup, Settings dialog.
+
+## Tool window structure
+
+{width=483}
+
+## How to use
+
+Give the tool window a name:
+
+* The name should be [short and descriptive](writing_short.md), preferably not longer than two words.
+* Use title-case capitalization.
+
+Show the tool window name in the tool window button and header. If there are tabs in the tool window header, add a colon after the tool window name. Otherwise, do not add it.
+
+{width=308}
+
+Add an icon for the tool window. The icon is 13px x 13px, grey and monochromatic. See how to create icons in the [icons guidelines](icons_style.md).
+
+**Exception:** Problems and Event Log icons change color and show the current status.
+
+Select the tool window orientation depending on the content. Vertical tool windows work better for trees, for example, Project, Structure, or Maven tool windows. Horizontal tool windows work better for tables, wide content or master-detail panels, for example, Git Log, Terminal, or Problems.
+
+Do **not** show the tool window button if the tool window is not relevant to the current project configuration. For example, do not show the Maven tool window for a project without Maven configuration files.
+
+If a tool window has no content yet, show its button by default only if the window contains basic functionality that is likely to be used for all projects, for example, Version Control or Problems. Otherwise, do not show the tool window button by default.
+
+Add a toolbar for [frequently used actions and filters](toolbar.md#what-items-to-add-on-toolbar). Use a horizontal toolbar for vertical tool windows and a vertical toolbar for horizontal tool windows. For more details, see the [toolbar guidelines](toolbar.md).
+
+Put tool window viewing mode settings under the gear icon in the header. If there is no toolbar, put other options under the gear icon as well. For example, see the gear icon in the Project tool window.
+
+Add tabs if all the information does not fit in one tab or refers to similar instances, like run sessions, history for files, find results. The tabs for entities should be closable.
+
+{width=308 style=block}
+*Separate tabs are added for each file history.*
+
+{width=448 style=block}
+*Separate tabs are added for different search queries.*
+
diff --git a/topics/ui/controls/balloon.md b/topics/ui/controls/balloon.md
new file mode 100644
index 000000000..73224e3a0
--- /dev/null
+++ b/topics/ui/controls/balloon.md
@@ -0,0 +1,142 @@
+
+
+# Balloon
+
+UI guidelines on using balloons.
+
+
+
+**Implementation:** [`Notifications`](%gh-ic%/platform/ide-core/src/com/intellij/notification/Notifications.java)
+
+**Related:** [](notifications.md#balloons)
+
+
+
+Balloon notifications inform users of the events or system states related to a project or IDE.
+
+{width=389}
+
+## When to use
+
+Use a balloon notification if:
+
+* There is no need to point to a particular context or location in the interface.
+* User action is recommended but not required immediately.
+
+In other cases, choose another [notification type](notification_types.md).
+
+## How to use
+
+### Message severity
+
+#### Error
+
+Use to inform of a critical event or state that might disrupt the user's experience.
+
+{width=389}
+
+#### 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.
+
+{width=389}
+
+#### 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.
+
+{width=389}
+
+#### Information about a certain plugin
+
+Use to show a plugin-related suggestion.
+
+Add the plugin’s icon to indicate that the notification relates to a particular plugin. Use a 16×16 SVG icon.
+
+{width=389}
+
+### Sticky or Timed
+
+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.
+
+### Title
+
+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 the title should fit in one line.
+
+Use sentence case and 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:
+
+* Use title-only message when it’s short and fits in one line:
+
+{width=389}
+
+* Use only body text when the message fits in two lines and the title would duplicate its meaning, fully or partially:
+
+Incorrect
+
+{width=389}
+
+Correct
+
+{width=389}
+
+### Body
+
+Provide the details on the event or system state to help users decide what to do next:
+
+* What is the cause or trigger?
+* What are the consequences?
+* What exactly is affected? Files, libraries, versions, plugins, etc.
+
+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.
+
+{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:
+
+{width=389}
+
+The Preferable number of actions is two, as it is easier for the user to choose.
+
+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:
+
+{width=389}
+
+If the notification reports an error or warning, always provide an action to help users fix the problem:
+
+{width=389}
+
+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:
+
+Incorrect
+
+{width=389}
+
+Correct
+
+{width=389}
+
+### Naming a notification group
+
+Each balloon notification 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.
+
diff --git a/topics/ui/controls/banner.md b/topics/ui/controls/banner.md
new file mode 100644
index 000000000..89ecdfecf
--- /dev/null
+++ b/topics/ui/controls/banner.md
@@ -0,0 +1,83 @@
+
+
+# Banner
+
+UI guidelines on using banners.
+
+
+
+**Implementation:** [`EditorNotifications.Provider`](%gh-ic%/platform/platform-api/src/com/intellij/ui/EditorNotifications.java)
+
+**Related:** [](notifications.md#editor-banner)
+
+
+
+A banner notification informs the user about the state of a specific context in the project. For example, when there is a missing or broken configuration for some file.
+
+{width=796}
+
+## When to use
+
+Use a banner if user actions should attract attention in a file tab, tool window, or dialog, but are not required immediately.
+
+{width=600 style=block}
+*Reconnecting to the database is required to make edits.*
+
+{width=500 style=block}
+*The component needs to be installed in order to run the available virtual devices.*
+
+Do **not** use a banner if there is no particular UI component it can be tied to. Use a [balloon notification](balloon.md) in the main window instead.
+
+For all other cases, choose another notification type.
+
+### Types of banners
+
+#### Information
+
+Use when actions can improve the user’s workflow, but are considered optional and can be safely ignored.
+
+{width=733 style=block}
+*The new tool window UI is suggested to improve the workflow for version control.*
+
+#### Warning
+
+Use to suggest actions that can impact the user’s workflow.
+
+{width=698 style=block}
+*Generated files should be edited directly.*
+
+#### Error
+
+Use to suggest actions that are required to unblock the user’s workflow.
+
+{width=796 style=block}
+*Syntax highlighting and other inspections are broken until a JDK is defined for the project.*
+
+## How to use
+
+{width=504}
+
+### Message
+
+* The message should be [short and descriptive](writing_short.md) (two sentences at most) and follow the [Punctuation](punctuation.md) guide.
+* Use sentence case capitalization.
+
+### Actions
+
+* The action name should be [short and descriptive](writing_short.md), preferably not longer than two–three words.
+* Use sentence case capitalization.
+* Limit the number of actions to two to make the call to action clear in the specific context.
+* Use the built-in 'Hide' action instead of creating a separate one.
+
+### Icon (optional)
+
+* 16x16 icons can be used to complement the message, e.g., a gift icon to advertise functionality.
+
+### Placement
+
+* Place the banner at the top of the related UI component.
+* It can float or be adjacent to the content, depending on the amount of the available space and whether or not the content’s vertical shifting needs to be minimized.
+
+{width=509}
+
+*The banner floats on top of the preview surface to reduce shifting during code editing.*
diff --git a/topics/ui/controls/built_in_button.md b/topics/ui/controls/built_in_button.md
new file mode 100644
index 000000000..f6df90d96
--- /dev/null
+++ b/topics/ui/controls/built_in_button.md
@@ -0,0 +1,121 @@
+
+
+# Built-In Button
+
+UI guidelines on using built-in buttons.
+
+A built-in button is an icon placed inside an input control.
+
+{width=250}
+
+## How to use
+
+Place the built-in button inside the input control. Do **not** place the built-in button on the right of a control:
+
+{width=250}
+
+To place a button inside a text field, use [`ExtendableTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/fields/ExtendableTextField.java) and
+its `addExtension()` method.
+
+The shortcut for a built-in button is Shift+Enter.
+
+## Types
+
+### Browse
+
+A browse button opens a dialog with the disk, a tree view or a table of values.
+Use a control with the browse icon for a file/folder path selected from the disk.
+
+{width=250}
+
+An input field with browse button: [`TextFieldWithBrowseButton`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/TextFieldWithBrowseButton.java)
+
+A combo box with browse button:
+
+
+
+```kotlin
+val browseExtension = ExtendableTextComponent.Extension.create(
+ AllIcons.General.OpenDisk,
+ AllIcons.General.OpenDiskHover,
+ "Open file",
+ { System.out.println("Browse file clicked") }
+)
+val extComboBox = ComboBox(STRING_VALUES)
+extComboBox.setEditable(true)
+extComboBox.setEditor(object : BasicComboBoxEditor() {
+ override fun createEditorComponent(): JTextField {
+ val ecbEditor = ExtendableTextField()
+ ecbEditor.addExtension(browseExtension)
+ ecbEditor.setBorder(null)
+ return ecbEditor
+ }
+})
+```
+
+
+
+
+```java
+ExtendableTextComponent.Extension browseExtension =
+ ExtendableTextComponent.Extension.create(
+ AllIcons.General.OpenDisk,
+ AllIcons.General.OpenDiskHover,
+ "Open file",
+ () -> System.out.println("Browse file clicked")
+ );
+ComboBox extComboBox = new ComboBox<>(STRING_VALUES);
+extComboBox.setEditable(true);
+extComboBox.setEditor(new BasicComboBoxEditor() {
+ @Override
+ protected JTextField createEditorComponent() {
+ ExtendableTextField ecbEditor = new ExtendableTextField();
+ ecbEditor.addExtension(browseExtension);
+ ecbEditor.setBorder(null);
+ return ecbEditor;
+ }
+});
+```
+
+
+
+
+Do **not** place the button on the right of the control.
+
+{width=250}
+
+### Expand field
+
+If the input text can be long and place is constrained, use a built-in button to expand the control ([`ExtendableTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/fields/ExtendableTextField.java)):
+
+{width=332}
+
+{width=582}
+
+Do **not** use the Show Viewer button instead.
+
+{width=357}
+
+### List values
+
+Use a control with the table icon to select from the list of classes, methods or environment variables:
+
+{width=250}
+
+Use a combo box instead of the Variables button. This icon works as a combo box.
+
+{width=514}
+
+### Add value
+
+The Plus button works the same way as the Browse button.
+The only difference is that the selected value is added, instead of overwriting the existing one.
+Place the plus icon inside the control.
+{width=250}
+
+### Copy, Info
+
+| {width="57"} | {width="57"} |
+|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| Do not use the Copy button, the content can be selected and copied using the Cmd/Ctrl+C shortcut or the context menu. | Do not use the info button to open an external link. Use context help instead. |
+{style=none}
diff --git a/topics/ui/controls/button.topic b/topics/ui/controls/button.topic
new file mode 100644
index 000000000..a5a173e0d
--- /dev/null
+++ b/topics/ui/controls/button.topic
@@ -0,0 +1,574 @@
+
+
+
+
+
+ UI guidelines on using buttons.
+
+
+
+ Implementation:
+ JButton
+
+
+
+ 
+
+ Use a button to invoke an immediate action.
+ Use a link instead if:
+
+
+ The action takes the user to another page of the same dialog or an external source like
+ documentation:
+ 
+
+ The Manage scope link takes to another page of the Settings dialog.
+
+
+ Exception: Next and Previous buttons in wizard navigation.
+
+
+
+
+ The command is a secondary action that is not related to the primary purpose of the window,
+ and the space is constrained.
+
+
+
+ |
+
+ Incorrect
+
+ |
+
+
+ Correct
+
+ |
+
+
+
+ 
+ |
+
+ 
+ |
+
+
+
+
+
+ Use toolbar buttons instead if there are several buttons related to a table or list:
+
+
+ |
+
+ Incorrect
+
+ |
+
+
+ Correct
+
+ |
+
+
+
+ 
+ |
+  |
+
+
+
+ Use a split button instead if:
+
+ There are several related actions (more than 2), but the space is limited and/or packed.
+ The action is not common and is dangerous, for example, can destroy user data and cannot be easily
+ undone.
+
+
+ Use a built-in button instead if it's related to an input field, combo box,
+ search field.
+
+
+
+
+
+ The label displays the action the button performs.
+ Write the label as an imperative verb, e.g. Save, Print, Cancel. Use title capitalization.
+
+ Exceptions
+ : standard buttons like OK, Back/Forward, Previous/Next, Yes/No, Agree, Options, Settings, Details.
+
+ The button should answer the question in the title, so the user can skip the description. Prefer specific
+ labels over
+ generic ones:
+
+
+ |
+
+ Incorrect
+
+ |
+
+
+ Correct
+
+ |
+
+
+ 
+ Unclear what happens on the click. |
+ 
+ The label indicates what happens on the click. |
+
+
+
+ Exception: the Cancel button if it is clear what action is being canceled.
+ For example, use the
+ Cancel
+ button, not the
+ Don’t Create
+ button.
+
+ The label should be short, not more than 5 words. If it’s not obvious what element the button is related
+ to, add more
+ words to make it clear. Prefer clear labels to short:
+
+
+ |
+
+ Acceptable
+
+ |
+
+
+ Better
+
+ |
+
+
+
+ 
+ |
+
+ 
+ |
+
+
+
+
+ Add an ellipsis if additional actions such as adding more info or confirming the action are required:
+ 
+
+ Do
+ not
+ add ellipsis if another window is opened, but no more input from the user is required. For example,
+ About, Details.
+
+ Do not
+ use the word
+ Now
+ in the label because buttons always trigger an immediate action:
+
+
+
+
+ |
+
+ Incorrect
+
+ |
+
+
+ Better
+
+ |
+
+
+  |
+
+ 
+ |
+
+
+ Use the
+ Close
+ label only if nothing can be changed in the dialog and there is no confirmation button, for example, in
+ the
+ Help | My Productivity
+ dialog.
+ In all other cases, use the
+ Cancel
+ button.
+
+ Do
+ not
+ add an icon to the button. The main purpose of an icon is to quickly find a familiar action in a packed
+ toolbar or menu. Usually, no more than 3 buttons are placed nearby, their labels can be scanned quickly,
+ and icons are not required.
+
+
+
+
+
+ On hovering over a button, show a tooltip with the shortcut and the action name if it can be clarified.
+ For more details,
+ see Context help.
+
+
+
+ 
+
+ If the action is clear, show the shortcut only.
+
+ |
+
+ 
+
+ If the action can be clarified, show the action name and the shortcut.
+
+ |
+
+
+
+
+
+
+
+
+
+
+ |
+
+
+ macOS
+
+ |
+
+ 
+
+ Windows
+
+ |
+
+
+ The default button confirms the main purpose of a dialog. It is triggered by pressing
+ Enter
+ or
+ Ctrl+Enter
+ on Windows/Linux and
+ Enter
+ or
+ Cmd+Enter
+ on macOS.
+ Exception: If the focus is on an element that uses the
+ Enter
+ key (e.g., a text area), the default button is triggered only by
+ Ctrl+Enter
+ on Windows/Linux and
+ Cmd+Enter
+ on macOS.
+ The default button should always be present in a dialog. Only one button in a dialog can be the default
+ one.
+ If the action is dangerous, e.g., can lead to data loss, provide an easy way to undo the command.
+ If it's not possible to undo the action, make a secondary button the default one:
+ 
+
+
+
+
+
+ 
+ All buttons can get focus, even on macOS if the
+ Full Keyboard Access
+ option is disabled in Preferences > Keyboard >
+ Shortcuts.
+ A focused button behavior varies on macOS/Linux and Windows.
+
+
+ macOS
+
+
+
+ A focused button is invoked by pressing
+ Space
+ . Focused and default buttons are
+ independent
+ ,
+ so when
+ the focus moves from one button to another, the default button does not change.
+
+
+
+
+ Make the second most popular button in the dialog focused.
+ For example, the
+ New Window
+ button in the
+ Open Project
+ dialog:
+ 
+
+
+
+ It’s recommended to have one default and one focused button, so that most of the actions can be
+ triggered using
+ the keyboard.
+
+ Incorrect
+
+ 
+
+ The
+ This Window
+ button is the default and the focused one, while it’s
+ better to place the focus on the
+ New Window
+ button, so that the user can
+ access both options using the keyboard.
+
+
+
+
+
+ Windows/Linux
+
+
+ The focused button is triggered by pressing
+ Enter
+ or
+ Space
+ . If non-default
+ button gets focus, the default button is invoked using
+ Ctrl+Enter
+ .
+ 
+ On pressing the
+ Tab
+ key, the
+ New Window
+ button gets the focus and is triggered with
+ Enter
+ or
+ Space
+ .
+ The original
+ This Window
+ button is triggered with
+ Ctrl+Enter
+ .
+
+ If the focus moves to a control that’s not a button, the original default button is triggered by
+ Enter
+ .
+
+
+
+
+
+
+ 
+ Disable a button if:
+
+ It’s an
+ Apply
+ button and no changes have been made in this dialog.
+
+ The control to which the button is related is disabled.
+ Not all required fields in the dialog are filled.
+
+
+ Other common buttons are described below. They can be regular or default buttons.
+
+
+
+
+ The
+ Cancel
+ button reverts the app to the state before the dialog was invoked, and works equivalent to the
+
+ Esc
+
+ key on Win and Linux, and
+ Esc
+ or
+ Cmd+Period
+ on macOS.
+ If a confirmation button is present in a dialog, e.g.,
+ OK
+ or
+ Save
+ , it’s recommended to have a button that cancels the
+ dialog, e.g.,
+ Cancel
+ ,
+ Continue Editing
+ , etc.
+
+
+
+ Use the Apply button in dialogs with many settings that affect how data is displayed. The Apply button
+ allows you to
+ save and preview the effect of the selected options, and continue changing the settings, for example,
+ change a scheme in
+ Settings.
+
+
+ The help button appears in the bottom-left corner of a dialog and shows help in a tooltip on hover, or
+ opens a help
+ dialog when clicking it. For more details, see Context help.
+
+ 
+
+
+
+ The button width accommodates the length of the label plus standard indents 14px, but not less than the
+ 72px.
+ 
+ The button height is fixed, so the label is always a single line.
+ To lay out the button that depends on other control, e.g., input field, follow the rules
+ for dependent controls. Otherwise, follow
+ the rules for independent controls.
+
+
+
+
+
diff --git a/topics/ui/controls/checkbox.md b/topics/ui/controls/checkbox.md
new file mode 100644
index 000000000..f97bbf1cd
--- /dev/null
+++ b/topics/ui/controls/checkbox.md
@@ -0,0 +1,192 @@
+
+
+# Checkbox
+
+UI guidelines on using checkboxes.
+
+
+
+**Implementation:** [`JCheckBox`](https://docs.oracle.com/javase/tutorial/uiswing/components/button.html), [`JBCheckBox`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBCheckBox.java)
+
+
+
+{width=166}
+
+## When to use
+
+Use checkboxes for yes/no choices or for selecting several items in a group.
+
+Do **not** use checkboxes if:
+
+* Only one option in a group can be selected. Use a [radio button group](radio_button.md) instead.
+* The behavior in the "off" state is unclear from the checkbox label. Use two radio buttons instead and label them accordingly.
+ {width=365}
+* With the checkbox, it is unclear how the setting works if it’s unchecked. With radio buttons, both states are labeled clearly.*
+
+## How to use
+
+### Label
+
+A label accompanies each checkbox and is placed next to it.
+
+{width=161}
+
+If a label is long, split it into two lines. Use HTML formatting for that.
+
+{width=331}
+
+
+
+
+```kotlin
+checkBox(
+ """Insert selected suggestion by pressing space, dot,
+ or other context-dependent keys""")
+```
+
+
+
+
+```java
+new JCheckBox(
+ "Insert selected suggestion by pressing space, dot,
" +
+ "or other context-dependent keys");
+```
+
+
+
+
+Avoid labels that take more than two lines. See recommendations on writing concise labels below.
+
+If a checkbox appears in a table, place the label into the column header and do not repeat it on every row.
+
+{width=347}
+
+**Implementation**: Checkboxes are rendered in tables with [`BooleanTableCellRenderer`](%gh-ic%/platform/core-ui/src/ui/BooleanTableCellRenderer.java)
+and edited with `DefaultCellEditor(JCheckBox)` implementation.
+For any column that should be rendered as a checkbox, set both a renderer and editor for consistency.
+The type of data in the correspondent column of the `Table` model should either be `Boolean` or `String` containing `true` or `false`.
+
+```java
+TableColumn column = table.getColumnModel().getColumn(COLUMN_INDEX);
+column.setCellEditor(JBTable.createBooleanEditor());
+column.setCellRenderer(new BooleanTableCellRender());
+```
+
+### Writing guidelines
+
+Use sentence-style capitalization.
+
+Do not use ending punctuation.
+
+Use the imperative form of verbs.
+
+{width=350}
+
+Do not use negation in labels as it complicates understanding.
+**Exception**: "Do not show again" checkbox.
+
+{width=224}
+
+Make labels short and intelligible — see [Writing short and clear](writing_short.md).
+
+### Three-state checkbox
+
+In a group of options, use the parent checkbox to show the status of its children.
+
+{width=542}
+
+*The parent checkbox in checked, indeterminate and unchecked states*
+**Implementation**: The three-state checkbox is represented by the [`ThreeStateCheckBox`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/ThreeStateCheckBox.java)
+class which represents its state with the `ThreeStateCheckBox.State` enum containing `SELECTED, NOT_SELECTED, DONT_CARE` states.
+
+When the user clicks an indeterminate checkbox for the first time, the whole group becomes checked. The second click unchecks the whole group.
+
+An indeterminate checkbox can also show the download status. An example with a remote repository:
+
+{width=358}
+
+*Repositories "tools-base" and "contrib" are being loaded. When loading is finished, the indeterminate checkbox will be replaced with the checked checkbox if there are commits, or an unchecked checkbox if there are no commits.*
+
+**Implementation**: In a table, the three-state checkbox is represented by [`ThreeStateCheckBoxRenderer`](%gh-ic%/platform/lang-impl/src/com/intellij/profile/codeInspection/ui/table/ThreeStateCheckBoxRenderer.java)
+that provides both `TableCellRenderer` and `TableEditor`.
+It accepts `Boolean` type in the column being supplied by the `TableModel` and becomes `DONT_CARE` when the value in the cell is null.
+Otherwise, it becomes `SELECTED` for `Boolean.TRUE`, and `NOT_SELECTED` for `Boolean.FALSE`.
+
+## Placement
+
+If a checkbox depends on another control, e.g., an input field, follow the rules for [dependent controls](layout.md#dependent-controls). Otherwise, follow the rules for [independent controls](layout.md#independent-controls).
+
+
diff --git a/topics/ui/controls/combo_box.md b/topics/ui/controls/combo_box.md
new file mode 100644
index 000000000..c7f13b446
--- /dev/null
+++ b/topics/ui/controls/combo_box.md
@@ -0,0 +1,102 @@
+
+
+# Combo Box
+
+UI guidelines on using combo boxes.
+
+
+
+**Implementation**: [`ComboBox`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/ComboBox.java)
+
+
+
+A combo box combines a [drop-down list](drop_down.md) and an [input field](input_field.md), allowing the user to select a value from the list or enter a custom value.
+
+{width=328}
+
+Use [`ComboBox`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/ComboBox.java) instead of `javax.swing.JComboBox`.
+To make combo box editable invoke:
+
+```java
+comboBox.setEditable(true);
+```
+
+## When to use
+
+Use a combo box if:
+
+* The user needs to select a value or enter a custom value.
+
+ {width=165}
+
+* The possible choices are objects or states.
+
+
+* The user may need to return to previous values. For example, save previously entered paths, so the user can quickly
+ select them later:
+
+ {width=413}
+
+### When not to use
+
+If the number of options is finite, and there’s no need to enter custom values. In this case, use a [drop-down list](drop_down.md) or [radio buttons](radio_button.md).
+
+If it’s not possible to list the most likely choices. In this case, use an [input field](input_field.md) instead.
+
+{width=152}
+
+If the list is big, and the user knows what value they need and won’t review the list. In this case, use an input field with completion.
+
+{width=509}
+
+## How to use
+
+For the [label](drop_down.md#label) and the [default value](drop_down.md#default-value) apply the same rules as for the
+[drop-down list](drop_down.md).
+
+If there are no values in the list initially, replace the combo box with an input field.
+This way, users won't waste their time clicking the empty combo box to find out that there are no options available.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="221"} | {width="216"} |
+
+Replace the input field with a combo box after a value has been entered and confirmed.
+
+### Menu
+
+#### Control
+
+Open the combo box menu by clicking the arrow button on the right or pressing the Down arrow key when the combo box is focused.
+The menu opens down by default. If there is not enough space, the menu opens up.
+
+When the menu opens, select the element that was shown in the closed combo box. If a custom value is entered, then do not select a value in the list.
+
+Move the selection in the menu and update the value in the combo box by pressing the Up and Down arrow keys.
+On mouse hover, move the selection to an item the cursor is pointing to and update the value by clicking the mouse button or pressing Enter.
+
+The menu remains opened until the user clicks the item in the list, presses Enter or Esc, clicks outside the menu,
+or switches to another app.
+
+#### Menu items
+
+The menu list contains predefined or the most likely options. Follow the rules for [drop-down menu items](drop_down.md#menu-items).
+
+If the user needs to return to previous inputs, add such values to the end of the list when clicking the confirmation button in the dialog.
+
+{width=413}
+
+Use [built-in buttons](built_in_button.md) to add values or expand the combo box, e.g., the browse button:
+
+{width=384}
+
+## Validation
+
+If the user enters an invalid value, highlight the combo box with red and show an error message in a tooltip. For
+more details, see [Validation errors](validation_errors.md).
+
+{width=235}
+
+## Sizes and placement
+
+Follow the [drop-down guidelines](drop_down.md#sizes-and-placement).
diff --git a/topics/ui/controls/description_text.md b/topics/ui/controls/description_text.md
new file mode 100644
index 000000000..ed65acc5b
--- /dev/null
+++ b/topics/ui/controls/description_text.md
@@ -0,0 +1,80 @@
+
+
+# Description Text
+
+UI guidelines on descriptions texts.
+
+Description text provides explanatory information about a set of settings or a single item in a list or tree.
+
+{width=715}
+
+## When to Use
+
+Use description text to:
+
+* Show details about items in a list or tree:
+
+{width=665}
+
+* Describe a group of settings:
+
+{width=1012}
+
+## How to Use
+
+### Text
+
+Follow general rules in [Writing short and clear](writing_short.md) and [Punctuation](punctuation.md).
+
+Use the default text style for plain text. Increase line height by 3px from the default value.
+
+Use [H4 bold](typography.md) (Default bold) for headings or to highlight important words:
+
+{width=320}
+
+Use the editor font to highlight code snippets:
+
+{width=283}
+
+Use bullets for lists:
+
+{width=283}
+
+Limit the width of the line to 70–80 symbols, as it is not convenient to read very long lines:
+
+Incorrect
+
+{width=878}
+
+Correct
+
+{width=878}
+
+If the text does not fit, add a scrollbar:
+
+{width=333}
+
+### Appearance
+
+Do not add borders around the description text. Use the panel color for the background.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="302"} | {width="302"} |
+
+For [links](link.md), use the default link color: `Link.activeForeground`. Underline links on hover:
+
+{width=283}
+
+### Insets
+
+Separate the text from the surroundings with insets.
+
+Use a 12px horizontal inset if the description text’s area has other elements:
+
+{width=586}
+
+Increase inset up to 20px if the description text is the only element:
+
+{width=571}
+
diff --git a/topics/ui/controls/drop_down.md b/topics/ui/controls/drop_down.md
new file mode 100644
index 000000000..887c25e56
--- /dev/null
+++ b/topics/ui/controls/drop_down.md
@@ -0,0 +1,206 @@
+
+
+# Drop-Down List
+
+UI guidelines on using drop-down lists.
+
+
+
+**Implementation:** [`ComboBox`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/ComboBox.java)
+
+
+
+A drop-down list is a type of button that appears in dialogs. It shows a list of choices on clicking it and allows selecting one option.
+
+{width=134}
+
+## When to use
+
+Use a drop-down list if:
+
+A single option should be selected.
+
+The possible choices are objects or states.
+
+{width=182}
+
+The number of choices is more than 4.
+
+The screen space is limited, so there is not enough room for radio buttons.
+
+The default value is recommended for the most users. A drop-down is a good way to hide unpopular alternatives.
+
+{width=228}
+
+*"Subpixels" is the best choice for most users.*
+
+If there are other drop-downs in the same window and these options are not more important than others. A list of radio buttons is more noticeable than the drop-down.
+
+If a layout combines various UI elements for one setting, use a drop-down even if there are 4 options or fewer:
+
+{width=523}
+
+### When not to use
+
+If multiple selections are possible, use checkboxes.
+
+If there is a list of actions, use a menu or a split button:
+
+{width=136}
+
+If there are 4 options or fewer, use radio buttons.
+
+{width=255}
+
+If users may need to enter a value not currently in the list, use a combo box.
+
+{width=165}
+
+If a drop-down appears on a toolbar, use [toolbar drop-down](toolbar_drop_down.md) instead.
+
+{width=209}
+
+## How to use
+
+### Label
+
+Follow the rules for the [input field](input_field.md#label).
+
+{width=490}
+
+### Default value
+
+Select the most likely or the safest value by default.
+
+{width=298 style=block}
+*The safest value is "Ask", the behavior will not be unexpected to the user.*
+
+Do **not** use an empty value as the default value. If no values are added to a drop-down yet, replace it with a button to add values.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="221"} | {width="190"} |
+
+## Menu {id="menu_1"}
+
+### Control
+
+A drop-down menu opens on clicking the drop-down button anywhere or pressing the Down key when the drop-down is
+focused.
+The menu opens down by default. If there is not enough space, the menu opens up.
+
+When the menu opens, the default option (displayed when the menu is closed) is selected.
+
+Move the selection in the menu by pressing Up and Down arrows when an item is hovered. On hovering the cursor over the item just move selection and do not update the value.
+
+
+
+The menu remains opened until the user selects an item, clicks outside the menu, presses the Esc key or
+switches to another app.
+
+Allow single-click activation using mouse: click on a drop-down, the drop-down opens, select an item by hovering, close the drop-down with the new item selected by releasing the mouse button.
+
+### Menu items
+
+Use sentence-style capitalization for each menu item.
+
+{width=251}
+
+Avoid repeating words in drop-down list items. Move repeating words to the label or after the drop-down.
+
+{width=274}
+
+Sort items in one of the following orders:
+
+* Logical order, for example, in a spatial relationship:
+
+ {width=172}
+
+* Alphabetical or numeric order if the options are equivalent to make it easier to find items:
+
+ {width=267}
+
+* Place the most common options first. If there are more than 10 options, separate the most popular options with a line:
+
+ {width=254}
+
+Group related options, add a separator and group header if possible:
+
+{width=216}
+
+If there are actions related to the drop-down, put them under the gear icon on the right:
+
+{width=336}
+
+Enclose meta-options in pointy brackets and place meta-options at the beginning or at the end if they are secondary.
+
+{width=263}
+
+*<Choose per test> is a meta-options because it’s not a real runner.*
+
+Do **not** assign special meanings to numeric or string values, use meta-options instead. It can be unclear that either 0 or an empty string are used to disable an option.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="262"} | {width="262"} |
+
+ In the incorrect example an empty string is used to set <Same
+ as language level>, which is unclear.
+ Replace the <None> option with a checkbox if it does not make the layout more complex:
+
+Incorrect
+
+{width=288}
+
+Correct
+
+{width=277}
+
+Preview list items with images if they are associated with well-known icons. Use formatting for a list of fonts. It will help users make a choice.
+
+{width=609}
+
+Use **bold** font to show default values, blue font for values changed from the default,
+and grey font to add a hint.
+
+{width=188 style=block}
+*Default and Darcula are bundled schemes, Default is blue because it’s customized.*
+
+{width=529}
+
+Submenus are not supported for the drop-down list. Use a tree view instead:
+
+{width=169}
+
+## Sizes and placement
+
+### Width
+
+A drop-down width is fixed and does not change depending on the selected value.
+
+{width=133}
+
+A drop-down width should be enough to fit the longest option plus 20px, but not less than 72px.
+
+{width=157}
+
+### Menu
+
+The width of a drop-down menu can either equal the drop-down control width, or be wider to fit longer items.
+
+{width=100}
+
+Choose a list length that eliminates unnecessary vertical scrolling. The minimum height of the list with scrolling is 200px. Expand the list to 600px if space is not constrained and the list does not hide meaningful information under it, e.g., the information that can be important to make a choice.
+
+{width=225}
+
+[//]: # (TODO: For sizes inside the menu list see [Menu list](menu_list.md).)
+
+### Placement
+
+Follow the rules for the [input field](#placement).
+
+
diff --git a/topics/ui/controls/got_it_tooltip.md b/topics/ui/controls/got_it_tooltip.md
new file mode 100644
index 000000000..1e24a5860
--- /dev/null
+++ b/topics/ui/controls/got_it_tooltip.md
@@ -0,0 +1,266 @@
+
+
+# Got It Tooltip
+
+UI guidelines on using "Got it" tooltips.
+
+
+
+**Implementation:** [`GotItTooltip`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/GotItTooltip.kt)
+
+**Related:** [](notifications.md#gotIt)
+
+
+
+A Got It tooltip informs users about a new or changed feature and gives basic information about it.
+
+{width=335}
+
+## When to use
+
+Point to small UI controls that can be missed among other information in the screen.
+
+{width=509 style=block}
+*After method or parameter names are edited, the Inplace Refactoring icon appears.*
+
+{width=375 style=block}
+*After the "Code With Me" plugin is installed, a drop-down menu appears on the toolbar.*
+
+Explain behavior that is not clear from the UI.
+
+{width=333 style=block}
+*When extracting a method, users can change only the method name in the blue box. The tooltip explains where to change the order of parameters in the parentheses and other properties of a method.*
+
+Suggest keyboard interactions.
+
+{width=244 style=block}
+*The inlay with options after the blue box is a new control. The tooltip explains how to use it with the keyboard.*
+
+Explain how to revert to the old UI in case of significant UI changes.
+
+{width=552 style=block}
+*The tooltip explains how to revert to a new experimental UI. Only users who switched to the new UI can see it.*
+
+Do **not** use the tooltip if there is no space to attach it. Instead, use a [banner](banner.md) in a dialog or a notification in the main window.
+
+{width=709}
+
+{width=397}
+
+## How to use
+
+{width=527}
+
+Always add the body text.
+
+Add a header if the body text is 2 lines and more. A short header can quickly explain what this tooltip is about.
+
+{width=342}
+
+Implementation:
+
+
+
+
+```kotlin
+GotItTooltip(TOOLTIP_ID, GET_IT_TEXT, parentDisposable)
+ .withHeader("The reader mode is on")
+```
+
+
+
+
+```java
+new GotItTooltip(TOOLTIP_ID, GET_IT_TEXT, parentDisposable)
+ .withHeader("The reader mode is on");
+```
+
+
+
+
+Add a shortcut if the tooltip describes a single action that has a shortcut.
+
+{width=248}
+
+Implementation:
+
+
+
+
+```kotlin
+GotItTooltip(
+ TOOLTIP_ID,
+ { "You can rename usages ${shortcut("My.Action")}" },
+ parentDisposable
+)
+```
+
+
+
+
+```java
+new GotItTooltip(
+ TOOLTIP_ID,
+ gotItTextBuilder -> {
+ String shortcut = gotItTextBuilder.shortcut("My.Action");
+ return "You can rename usages " + shortcut;
+ },
+ parentDisposable
+);
+```
+
+
+
+
+### Link
+
+Add a local link if users might want to revert changes in a feature or configure it.
+
+{width=389}
+
+
+
+
+```kotlin
+GotItTooltip(TOOLTIP_ID, TOOLTIP_TEXT, parentDisposable)
+ .withLink("Disable for all files", this::actionMethodReference)
+```
+
+
+
+
+```java
+new GotItTooltip(TOOLTIP_ID, TOOLTIP_TEXT, parentDisposable)
+ .withLink("Disable for all files", this::actionMethodReference);
+```
+
+
+
+
+Add an external link if there is a help source that can further explain the functionality.
+
+{width=340}
+
+
+
+
+```kotlin
+GotItTooltip(TOOLTIP_ID, GOT_IT_TEXT, parentDisposable)
+ .withBrowserLink("How to use", new URL("https://example.com"))
+```
+
+
+
+
+```java
+new GotItTooltip(TOOLTIP_ID, GOT_IT_TEXT, parentDisposable)
+ .withBrowserLink("How to use", new URL("https://example.com"));
+```
+
+
+
+
+Do **not** add more than one link.
+
+### Text length and formatting
+
+Show no more than 5 lines of body text. If the text does not fit, leave only the essential information and add a link to a help article.
+
+Use sentence case both for the header and body text, and follow the [punctuation rules](punctuation.md).
+
+Make the help text [short and descriptive](writing_short.md).
+
+Avoid using style formatting. It makes the tooltip harder to read.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="341"} | {width="341"} |
+
+### Location
+
+Do **not** cover the information the user is currently working with.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="509"} | {width="509"} |
+
+**Implementation:** See four predefined point providers in the [`GotItTooltip`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/GotItTooltip.kt) class.
+
+
+
+
+```kotlin
+GotItTooltip(TOOLTIP_ID, GOT_IT_TEXT, parentDisposable)
+ .show(gutterComponent, GotItTooltip.TOP_MIDDLE)
+```
+
+
+
+
+```java
+new GotItTooltip(TOOLTIP_ID, GOT_IT_TEXT, parentDisposable)
+ .show(gutterComponent, GotItTooltip.TOP_MIDDLE);
+```
+
+
+
+
+### Timeout
+
+Consider adding a timeout if:
+
+* The text is no longer than 10 words.
+* The tooltip appears at the place at which the user is currently looking.
+* There is no link in the tooltip.
+
+{width=244}
+
+*The Got It tooltip has a timeout because the text is short, the user has just started the Rename refactoring, and is very likely looking at this place.*
+
+Note that adding a timeout automatically hides the Got It button.
+
+**Implementation:** Default timeout duration is 5 seconds. A custom duration can be set:
+
+
+
+
+```kotlin
+GotItTooltip(TOOLTIP_ID, GOT_IT_TEXT, parentDisposable)
+ .withTimeout(3000)
+```
+
+
+
+
+```java
+new GotItTooltip(TOOLTIP_ID, GOT_IT_TEXT, parentDisposable)
+ .withTimeout(3000);
+```
+
+
+
+
+### Versioning
+
+If a tooltip appears automatically after the IDE starts, tie it to the IDE version. Due to the technical limitations, tooltip counters might be reset when the IDE version is updated, and the users might see the same tooltips again.
+
+If a tooltip is triggered by an action or plugin installation, do not tie them to the current IDE version. In this case, users might miss a tooltip if they are using this functionality or plugin for the first time in the next IDE version.
+
+## Built-in behavior
+
+By default, a tooltip is shown only once per user.
+
+The tooltip disappears when:
+
+* Esc is pressed
+* User clicks any place outside the tooltip
+
+The default timeout duration is 5 seconds.
+
+If several tooltips appear on application start, they are shown one by one.
+
+Text width is 280px by default. The tooltip width adjusts automatically to make the right margin 16px.
+
+{width=681}
+
+{width=625}
diff --git a/topics/ui/controls/group_header.md b/topics/ui/controls/group_header.md
new file mode 100644
index 000000000..210449927
--- /dev/null
+++ b/topics/ui/controls/group_header.md
@@ -0,0 +1,44 @@
+
+
+# Group Header
+
+UI guidelines on using group headers.
+
+
+
+**Implementation:** [`TitledSeparator`](%gh-ic%/platform/platform-api/src/com/intellij/ui/TitledSeparator.java)
+
+
+
+A group header clearly labels a group of UI controls.
+
+{width=455}
+
+## When to use
+
+Follow the rules in [Groups of controls](groups_of_controls.md).
+
+Do **not** use group headers when each group contains 3 controls and less. Separate with [vertical insets](layout.md#organize-with-insets) instead.
+
+Incorrect
+
+{width=569 style=block}
+*Each group has less than 3 controls. Group headers only add noise in this case because control labels are enough to understand their purpose.*
+
+Correct
+
+{width=569}
+
+## How to use
+
+Use title capitalization for the label.
+
+Make the label short, preferably no more than 4 words. Avoid generic words, such as "General" or "Options". See [Writing short and clear](writing_short.md).
+
+If a group contains rarely used or advanced settings, use a **collapsible group header** and collapse it by default.
+
+{width=455}
+
+
+
+
diff --git a/topics/ui/controls/icon_button.md b/topics/ui/controls/icon_button.md
new file mode 100644
index 000000000..41d1aceb7
--- /dev/null
+++ b/topics/ui/controls/icon_button.md
@@ -0,0 +1,82 @@
+
+
+# Icon Button
+
+UI guidelines on using icon buttons.
+
+
+
+**Implementation:** [`ActionButton`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/actionSystem/impl/ActionButton.java)
+
+
+
+A toolbar icon button is an icon that appears on a toolbar.
+
+{width=156}
+
+## Types
+
+There are three types of toolbar icon buttons:
+
+An action button triggers an action immediately on clicking it, e.g., the Open button.
+
+A toggle button switches the state on clicking it, e.g., a button to show and hide warnings in the output tree.
+
+{width=143}
+
+A drop-down button has an arrow icon in the bottom right corner and opens a menu with actions or checkboxes.
+
+[//]: # (TODO: Use [menu list](menu_list.md) guidelines for drop-down buttons.)
+
+{width=284}
+
+## When to use
+
+Follow the rules for [toolbar](toolbar.md#what-items-to-add-on-toolbar).
+
+## How to use
+
+Provide a recognizable icon. Use an [existing icon](https://intellij-icons.jetbrains.design) or create a new one using [icon guidelines](icons_style.md).
+
+Provide a short and descriptive name for a toolbar icon button. Show a tooltip with the button name on mouse hover.
+Include a shortcut if there is one. See [Context help](context_help.md) for details.
+
+{width=163}
+
+Highlight a toolbar icon button on mouse hover. Highlight a toolbar icon button with a brighter color on clicking it.
+
+* Toggle buttons remain highlighted when they are in the switched on mode. Toggled on buttons do not change color on hover.
+
+* Drop-down buttons remain highlighted while the menu is opened.
+
+{width=183}
+
+If an action is not available in this context, disable the corresponding button and gray out the icon.
+For toolbar drop-down buttons, disable the arrow icon as well.
+Do **not** highlight a disabled icon on mouse hover.
+
+## Sizes and placement
+
+Icons size is 16x16px, icon selection is 22x22px.
+
+For guidelines on the space between toolbar icon buttons see [Toolbar](toolbar.md).
+
+
diff --git a/topics/ui/controls/inline_help_text.md b/topics/ui/controls/inline_help_text.md
new file mode 100644
index 000000000..c8191a839
--- /dev/null
+++ b/topics/ui/controls/inline_help_text.md
@@ -0,0 +1,223 @@
+
+
+# Inline Help Text
+
+UI guidelines on using inline help texts.
+
+Inline help text provides useful information about a setting.
+
+{width=304}
+
+## When to use
+
+Follow the rules for [context help](context_help.md).
+
+## How to use
+
+### Text length and formatting
+
+Show no more than 5 lines of help text not to clutter the screen. Note that the text width is limited to 70 characters.
+
+{width=380}
+
+Show more than 5 lines only when a text cannot be shortened for legal purposes.
+
+{width=396}
+
+Implementation
+
+```kotlin
+panel {
+ row {
+ checkBox("Send usage statistics when using EAP versions")
+ .comment("""
+ Help JetBrains improve its products by sending anonymous
+ data about features and plugins used, hardware and software
+ configuration, statistics on types of files, number of files
+ per project, etc.
+
+ Please note that this will not include personal data or
+ any sensitive information, such as source code, file names,
+ etc. The data sent complies with the
+
+ JetBrains Privacy Policy
+ """.trimIndent()
+ )
+ }
+}
+```
+
+Provide a link to the corresponding help article or to a place in the IDE where the related settings can be found.
+Place the link at the end of the text where possible so that it does not disrupt reading.
+
+{width=366 style=block}
+*External link*
+
+{width=345 style=block}
+*Local link*
+
+Text style formatting:
+
+* Avoid text highlighting. Usually, the help text is short and no bold or italics are needed.
+
+ {width=364}
+
+* Use formatting for code, console commands, or parameters. Use HTML tags. Enclosing text in `` tags is not needed.
+
+ {width=213}
+
+Avoid using brackets.
+
+{width=362}
+
+### Writing guidelines
+
+Make help text [short and descriptive](writing_short.md).
+
+Do not repeat the setting name in the help text.
+
+{width=481}
+
+## Placement
+
+### Labeled input, button, checkbox, or radio button
+
+Labeled inputs are fields, combo boxes, or text areas.
+
+Place the help text to the right of a labeled input, checkbox, or radio button if all the following applies:
+
+* The space to the right is empty.
+* The help text has 1–5 words, not counting articles and prepositions.
+* The control label has 1–5 words.
+
+{width=433}
+
+```kotlin
+panel {
+ row("Plugin update policy:") {
+ comboBox(listOf("Default", "Non default"))
+ comment("Ignore by Maven 3+")
+ }
+ row("Thread count:") {
+ textField()
+ comment("-T option")
+ }
+}
+```
+
+{width=438}
+
+```kotlin
+panel {
+ row {
+ checkBox("Build project automatically")
+ comment("Works while not running / debugging")
+ }
+ row {
+ checkBox("Compile independent modules in parallel")
+ comment("May require larger heap size")
+ }
+}
+```
+
+{width=309}
+
+Otherwise, place the help text under the UI control.
+
+{width=484}
+
+```kotlin
+panel {
+ row("Default directory:") {
+ textFieldWithBrowseButton()
+ .comment(
+ "Preselected in \"Open ...\" and \"New | Project\" dialogs"
+ )
+ }
+}
+```
+
+If there is no space under the UI control, use the [help tooltip](tooltip.md#question-mark-icon-for-help-tooltips) with the question mark icon for labeled inputs, checkboxes, and radio buttons.
+For buttons, use the help tooltip without the icon.
+
+### List, tree or table
+
+If the help text applies to a whole list, tree, or table, place it below the control.
+
+{width=531}
+
+```kotlin
+
+import javax.swing.JTable
+
+panel {
+ row {
+ cell(createTable()) // Actual table creation
+ .align(Align.FILL)
+ .comment("""
+ <Project> is content roots of all modules,
+ all immediate descendants
of the projects base
+ directory, and .idea directory contents
+ """.trimIndent()
+ )
+ }.resizableRow()
+}
+```
+
+If it applies to a single list, tree or table item:
+
+* If the help text has 1–10 words, place it to the right of the item.
+*
+
+{width=422}
+
+* If the text is longer than 10 words:
+
+For a list or tree in the master part, place the text into the detail part.
+
+{width=673}
+
+If the case with the master-detail layout above does not apply, use the [help tooltip](tooltip.md#question-mark-icon-for-help-tooltips) with the question mark icon.
+
+{width=390}
+
+### Group of controls
+
+If the help text applies to several UI controls, place it at the bottom of the group.
+
+{width=430}
+
+Implementation
+
+Use [`Panel.group()`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/dsl/builder/Panel.kt) as the border for panels that need title and possibly the gray line on the right of the title:
+
+```kotlin
+panel {
+ group("Build and Run") {
+ row("Build and run with:") {
+ comboBox(listOf("IntelliJ IDEA", "Gradle"))
+ }
+ row("Run tests with:") {
+ comboBox(listOf("IntelliJ IDEA", "Gradle"))
+ }
+ row {
+ comment("""
+ By default IntelliJ IDEA uses Gradle to build the project
+ and run the tasks.
+ In a pure Java/Kotlin project, building and running
+ by means of IDE might be faster, thanks to optimizations.
+ Note, that the IDE doesn't support all Gradle plugins and
+ the project might not be built correctly with some of them.
+ """.trimIndent()
+ )
+ }
+ }
+ group("Gradle") {
+ row("Use Gradle from:") {
+ comboBox(gradleModel)
+ }
+ }
+}
+```
+
+You can find more examples by invoking the Tools | Internal Actions | UI | Kotlin UI DSL | UI DSL Showcase action (available in [internal mode](enabling_internal.md)) and clicking the View source links on specific pages.
diff --git a/topics/ui/controls/input_field.md b/topics/ui/controls/input_field.md
new file mode 100644
index 000000000..7bf32f22f
--- /dev/null
+++ b/topics/ui/controls/input_field.md
@@ -0,0 +1,179 @@
+
+
+# Input Field
+
+UI guidelines on using input fields.
+
+
+
+**Implementation:** [`JBTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBTextField.java)
+
+
+
+An input field allows users to enter or edit a text line using the keyboard.
+
+{width=170}
+
+## When to use
+
+Use an input field if it’s not possible to enumerate the most likely values. Otherwise, use a [combo box](combo_box.md) or a [drop-down list](drop_down.md).
+
+If input has to be in a specific format, use one of the following controls:
+
+* If the previous user input must be preserved, use a [combo box](combo_box.md).
+* Use a [text area](text_area.md) for long (commit message) or multi-line (code snippet) input. If place is constrained, use an [expandable input field](#input-field-types).
+* Use a slider if a precise value is not required, or if it’s possible to provide feedback on the effect of setting changes. If place is constrained, use an input field.
+* Use a [search field](search_field.md) to input a search query.
+* Use calendar to set a date.
+* Use color box to choose a color.
+
+## How to use
+
+### Label
+
+A label accompanies each input field and indicates the information type.
+
+Labels should be [short and descriptive](writing_short.md).
+
+Write the label either as a noun and end it with a colon:
+
+{width=153}
+
+Or as a phrase with no ending punctuation:
+
+{width=247}
+
+Do **not** use labels to tell users what to do:
+
+{width=186}
+
+Use sentence-style capitalization.
+
+If there are several input fields on a form, it’s recommended to make labels approximately the same length to avoid gaps between labels and fields. For example:
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="385"} | {width="224"} |
+
+If an input field is disabled, disable the label too:
+
+{width=153}
+
+Make the label text selectable. The user may want to search for this option on the Internet or to send a question to support.
+
+Place the label on the left or above the input field. For more details, see the [Layout](layout.md) topic.
+
+### Placeholder
+
+Placeholder is grey text placed inside an input field. Follow these rules:
+
+* Use sentence-style capitalization.
+* Do **not** use ending punctuation or ellipsis.
+* Hide the placeholder when the user starts typing, not when the input field gets the focus.
+
+To show placeholder text, use `JBTextField.getEmptyText().setText(...)`.
+
+Use the placeholder to indicate that an input field is optional.
+
+{width=397}
+
+Use the placeholder to show the default value:
+
+{width=247}
+
+If the user overwrites the value, it can be restored by removing the new value from the input field or by clicking the "Reset to default" link on the right:
+
+{width=361}
+
+Do **not** use the placeholder to show examples. The user can get the impression that the field is already filled. Provide examples or explanation under the input field (see [Context help](context_help.md)):
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="150"} | {width="150"} |
+
+Do **not** use the placeholder as the field label. After the field has been filled, it is difficult to understand its purpose.
+
+{width=100}
+
+### Prefilled value
+
+Pre-fill the field if it has the default or a frequently used value. Use the default text color for pre-filled values:
+
+{width=152}
+
+Do **not** prefill with "Unnamed". It takes time to read it and does not help the user to fill the form.
+
+{width=535}
+
+### Field focus
+
+When an input field gets the focus, place the caret at the end of the text:
+
+{width=321}
+
+If users are more likely to re-enter the entire value, select the whole text when the field gets the focus:
+
+{width=274}
+
+### Input field types
+
+If the input text can be long and place is constrained, use an expandable input field [`ExpandableTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/fields/ExpandableTextField.java).
+For more details, see [built-in buttons](built_in_button.md#expand-field).
+
+{width=332}
+
+If input data is secured, replace it with dots via [`JBPasswordField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBPasswordField.java).
+
+{width=271}
+
+If there are many predefined values (for example, code snippets, commit author), add completion to the input field [`TextFieldWithCompletion`](%gh-ic%/platform/platform-impl/src/com/intellij/util/textCompletion/TextFieldWithCompletion.java).
+
+{width=509}
+
+An input field with completion looks the same way as a regular input field. When an empty input field gets the focus, show a tooltip after a delay to indicate that code completion is supported.
+
+{width=291}
+
+Show the completion popup when the user starts typing or presses Ctrl+Space.
+
+Use [built-in buttons](built_in_button.md) to help the user enter data. For example, to browse the disk.
+
+### Validation
+
+If the user enters an invalid value, highlight the field with red and show an error message in a tooltip. For more details, see [Validation errors](validation_errors.md).
+
+{width=239}
+
+## Sizes and placement
+
+Sizes are the same for all themes:
+
+{width=65}
+
+### Field width
+
+Choose the width appropriate for the most common values, but not less than 65px. The field width helps the user understand what value is expected and to make sure that they fill the field correctly.
+
+| Correct | {width=104} |
+|-----------------------------------------------------|----------------------------------------|
+| Incorrect | {width=240} |
+| Correct | {width=387} |
+| Incorrect | {width=331} |
+
+{style=none}
+
+If the input value is longer than the field width, show the beginning of the value when the field becomes inactive:
+
+{width=243}
+
+### Placement
+
+If the input field depends on another control, for example, a checkbox, follow the rules for (layout.md#dependent-controls). Otherwise, follow the rules for [independent controls](layout.md#independent-controls).
+
+
diff --git a/topics/ui/controls/link.md b/topics/ui/controls/link.md
new file mode 100644
index 000000000..63639098d
--- /dev/null
+++ b/topics/ui/controls/link.md
@@ -0,0 +1,136 @@
+
+
+# Link
+
+UI guidelines on using links.
+
+
+
+**Implementation:** [`ActionLink`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/ActionLink.kt), [`DropDownLink`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/DropDownLink.kt)
+
+
+
+{width=120}
+
+## When to use
+
+Use a regular link for navigation between pages of the same window.
+
+{width=494}
+
+*This option is in the Settings dialog. "Configure servers" opens another page of the same dialog.*
+
+{width=411}
+
+*Do not use a button to navigate to another page of the same window.*
+
+Use an external link for navigation to web resources. See below for the [external link icon](#external-link-icon).
+
+{width=248}
+
+Use a regular or [drop-down link](#drop-down-link) for secondary actions in packed or small UI areas.
+
+{width=367}
+
+*The "Reset" action is a link for two reasons: (1) The action appears only when the default value in the field is changed and reverting to a default is considered a rare scenario. (2) A lightweight link fits better than a button in this busy layout.*
+
+{width=550}
+
+*The "Modify options" drop-down link fits into the top right corner of a busy layout.*
+
+Do not use links for primary actions or when a UI is not constrained.
+Use a [button](button.topic) or a [drop down list](drop_down.md) instead.
+These controls can be selected from the keyboard and are bigger and easier to click.
+
+{width=451}
+
+## How to use
+
+### Writing guidelines
+
+Use sentence capitalization.
+
+Add an ellipsis to a button-link if it opens another UI area where input is possible. See examples for the [Button](button.topic).
+
+Do not use words like "navigate" or "click here". A link already implies navigation or clicking.
+
+{width=398}
+
+When possible, replace "Learn more" and other generic phrases with more informative ones.
+
+{width=316}
+
+### Link as a part of text
+
+A link can be a part of a checkbox or radio button label or of any stand-alone text, like the text in an [empty state](empty_state.md) or in [context help](context_help.md).
+
+{width=403}
+
+Make a link the minimum phrase that is enough to understand what will happen without reading the whole text.
+
+{width=489}
+
+### Link in a tree or table
+
+Use a link as a secondary action for some items of a tree or table.
+
+{width=387}
+
+If an action is needed for all items of a tree or table:
+
+* Add an [icon button](icon_button.md) to a toolbar.
+* For a list of choices, add a separate table column of drop-down cells (see [Table](table.md#editing-values)).
+* If a link in every tree or table line has meaningful formatting, leave it:
+ {width=342}
+ *Links in the "Push Commits" window have the format that helps understand the relation between them: "[remote repository] : [branch]". Moving these links elsewhere would break this meaning.*
+
+### External link icon
+
+Always add the arrow icon for an external link. The icon shows that the user will switch to a browser and lose the current context.
+
+{width=248}
+
+
+
+```kotlin
+val externalLink = ActionLink("External link") {
+ BrowserUtil.browse("https://www.jetbrains.com")
+}.apply {
+ setExternalLinkIcon()
+}
+```
+
+
+
+
+```java
+ActionLink externalLink = new ActionLink(
+ "External link",
+ event -> BrowserUtil.browse("https://www.jetbrains.com")
+);
+externalLink.setExternalLinkIcon();
+```
+
+
+
+
+An exception is a help topic link in [empty states](empty_state.md).
+The help icon already hints that this is an external help resource, so the arrow icon is unnecessary.
+
+{width=164}
+
+### Drop-down link
+
+Drop-down links show a context menu or a popup.
+Use [`DropDownLink`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/DropDownLink.kt) to implement a drop-down link.
+
+{width=445}
+
+## Placement
+
+Lay out button-links as buttons and dropdown-links as combo boxes. See [Layout](layout.md).
+
+## Built-in behavior
+
+A focused link is activated from the keyboard with Space.
+
diff --git a/topics/ui/controls/loader.md b/topics/ui/controls/loader.md
new file mode 100644
index 000000000..1d59465fc
--- /dev/null
+++ b/topics/ui/controls/loader.md
@@ -0,0 +1,94 @@
+
+
+# Loader
+
+UI guidelines on using loaders.
+
+
+
+**Implementation:** [`AnimatedIcon.Default`](%gh-ic%/platform/ide-core/src/com/intellij/ui/AnimatedIcon.java)
+
+
+
+A loader informs users about performing a lengthy operation.
+
+{width=330}
+
+## When to use
+
+Follow the rules for [progress indicators](progress_indicators.md).
+
+## How to use
+
+The loader form and sizes are the same in all themes. Use the default 16x16 loader in all cases.
+
+
+
+```kotlin
+JLabel(
+ "Loading...",
+ AnimatedIcon.Default(),
+ SwingConstants.LEFT
+)
+```
+
+
+
+
+```java
+new JLabel(
+ "Loading...",
+ new AnimatedIcon.Default(),
+ SwingConstants.LEFT
+);
+```
+
+
+
+
+
+
+A loader may have a label if the process is long and the loader is shown in an empty area. In this case, use a [progress text](progress_text.md) as the label:
+
+{width=597}
+
+Remove the loader as soon as the process completes.
+
+## Placement
+
+
+
+
+ | Inside a field |
+  |
+
+
+
+ |
+
+ ExpandableTextField textField = new ExpandableTextField();
+ textField.addExtension(
+ Extension.create(new AnimatedIcon.Default(), null, null)
+ );
+
+ |
+
+
+
+ | In a corner |
+ 
+ |
+
+
+
+ | Next to an item |
+  |
+
+
+
+ | Before a progress text |
+ 
+ |
+
+
+
diff --git a/topics/ui/controls/notification_types.md b/topics/ui/controls/notification_types.md
new file mode 100644
index 000000000..e3ccf7a3d
--- /dev/null
+++ b/topics/ui/controls/notification_types.md
@@ -0,0 +1,100 @@
+
+
+# Notifications
+
+UI guidelines on using notifications.
+
+Notifications inform users about the status of user or system initiated operations. They can have different actions depending on the message.
+
+There are four types of notifications:
+
+- Alert
+- [Banner](banner.md)
+- [Balloon](balloon.md)
+- Tool window balloon
+
+## What notification to use
+
+Consider two factors when deciding which notification type to use.
+
+**User action**
+
+ Are the users required to address the notification before they can proceed with current tasks?
+ - Required immediately
+ - Required, but not immediately
+ - Not required
+
+**Context of trigger**
+
+ What initiated the notification? Does the initiation point to a particular context or location?
+ - File tab
+ - Tool windows
+ - Other
+
+Use the following table to determine which notification to use based on the two factors:
+
+
+ | User action |
+ Context |
+ Type |
+ Examples |
+
+ | Required immediately
+ |
+ All
+ |
+ Alerts
+ |
+
+ Confirm Restart
+ Opening projects in new window
+ When trying to rename a method, but a conflict is found
+ Need a dependency before using a feature
+ 
+ |
+
+
+ | Required, but not immediately |
+
+ File tabs
+ Tool windows
+ |
+ Banners |
+
+ Configuring SDK for your project
+ Requiring a Gradle sync for tools to work properly
+ 
+ |
+
+
+ | Not required |
+ Tool windows |
+ Tool Window balloons |
+
+ Status of task completion
+ When Find Usages is invoked on a method, use a tool window balloon to show the feedback since the results will be found in the Find tool window
+ 
+ |
+
+
+ |
+ All but file tabs or tool windows |
+ Sticky balloons |
+
+ IDE and Plugin Updates
+ 
+ |
+
+
+ |
+ |
+ Timed balloons |
+
+ Module imported
+ Framework detection
+ 
+ |
+
+
+
+**Exception**: If the action is highly recommended, consider using Banners across all files for visibility instead of Sticky balloon.
diff --git a/topics/ui/controls/progress_bar.md b/topics/ui/controls/progress_bar.md
new file mode 100644
index 000000000..aec207351
--- /dev/null
+++ b/topics/ui/controls/progress_bar.md
@@ -0,0 +1,132 @@
+
+
+# Progress Bar
+
+UI guidelines on using progress bars.
+
+
+
+**Implementation:** [`JProgressBar`](https://docs.oracle.com/javase/tutorial/uiswing/components/progress.html)
+
+
+
+A progress bar informs users about the progress of a lengthy operation.
+
+{width=308}
+
+## When to use
+
+Follow the rules for [progress indicators](progress_indicators.md).
+
+## How to use
+
+### Types
+
+Use **determinate** progress bar, if the process duration is known:
+
+{width=308}
+
+Otherwise, use **indeterminate** progress bar:
+
+{width=308}
+
+If an indeterminate process reaches a point where its duration can be determined, switch to a determinate progress bar. For example:
+
+{width=308}
+
+{width=308}
+
+### Process name and details
+
+A progress bar can have a process name and process details. For wording, follow the rules for [progress text](progress_text.md).
+
+#### Process name
+
+Place a process name above the progress bar:
+
+{width=308}
+
+If the vertical space is limited, place the process name with a colon on the left:
+
+{width=308}
+
+If there are several processes in a group, add a bold header. The header is a noun.
+
+{width=308}
+
+Do **not** show a process name for inline processes:
+
+{width=605}
+
+#### Process details
+
+Place process details under the progress bar in one line:
+
+{width=308}
+
+The length of the comment is limited by the progress bar:
+
+{width=308}
+
+If space is limited, show percentage completed:
+
+{width=342}
+
+#### In dialog
+
+Use a process name as a dialog header, capitalize the title and remove ellipsis. Process details appear above the progress bar:
+
+{width=544}
+
+#### In status bar
+
+Place a process name under the progress bar in the Status bar:
+
+{width=238}
+
+### Process status
+
+If a process consists of substeps that can fail but do not terminate the process, then use green and red colors to show the intermediate status.
+For example, show the status of the running tests:
+
+{width=390}
+
+Do **not** color progress bar to show the final result of the task, use [notifications](notification_types.md).
+In case of success, show notification for the user-initiated tasks, in case of failure — for all tasks.
+
+### Process control
+
+Provide the Cancel button in the progress dialog if the process can be interrupted (see [Loading Project dialog](#in-dialog)).
+Use the Stop button if interrupting does not return the environment to its previous state.
+
+Use the Stop icon if there are several processes running at the same time in one dialog or there is not enough space for the button (e.g., [Status bar](#in-status-bar)):
+
+{width=700}
+
+Always place the Stop icon on the right next to the progress bar. On hover over the Stop icon, show the "Stop" or "Cancel" comment under the progress bar instead of process details:
+
+{width=332}
+
+If the process takes a long time and can prevent the user from performing tasks, provide an option to pause a process using the Pause button or the Pause icon.
+Replace process details with the "Pause" comment on hover over the Pause icon:
+
+{width=331}
+
+It is **not** recommended providing an option to pause the process. It is preferable that the process runs in the background and does not interfere with a user.
+
+If a user pauses the process, show "Paused" under the progress bar.
+Replace the Pause icon with Resume, show "Resume" under the progress bar and when hovered over the Resume button:
+
+{width=330}
+
+Hide the progress bar as soon as the process completes.
+
+## Sizes and placement
+
+The progress form and sizes are the same in all themes.
+
+{width=586}
+
+
+
+
diff --git a/topics/ui/controls/progress_indicators.md b/topics/ui/controls/progress_indicators.md
new file mode 100644
index 000000000..ea13c0754
--- /dev/null
+++ b/topics/ui/controls/progress_indicators.md
@@ -0,0 +1,112 @@
+
+
+# Progress Indicators
+
+UI guidelines on using progress indicators.
+
+Progress indicators inform users about an ongoing operation. There are three types of indicators:
+
+* [Loader](loader.md)
+* [Progress text](progress_text.md)
+* [Progress bar](progress_bar.md)
+
+## Which indicator to use
+
+If an operation lasts for less than a second in most cases, do not show any progress indicator. Progress indicators for a short operation are distracting.
+
+If the user has to wait until a process completes to continue working with the app, show a progress bar in a modal dialog.
+
+{width=440}
+
+If the progress is non-modal, select progress indicator based on where it appears.
+
+* [Input field, combo box, drop-down](#input-field-combo-box-drop-down)
+
+* [Search field](#search-field)
+
+* [Tree, list, tool window](#tree-list-tool-window)
+
+* [Breadcrumb and dialog label](#breadcrumb-and-dialog-label)
+
+* [Settings dialog](#settings-dialog)
+
+* [Empty state](#empty-state)
+
+* [Main window](#main-window)
+
+### Input field, combo box, drop-down
+
+Place the loader inside an input field on the right to show that the field content is being loaded or checked.
+
+{width=201}
+
+### Search field
+
+Place the loader on the right to show that search is being performed.
+
+{width=262}
+
+### Tree, list, tool window
+
+If each tree node loads independently, and it’s important to know the current state of each node, show the loader instead of the node icon:
+
+{width=372}
+
+If nodes do not have icons, or icons can’t be replaced for some reason, show progress text after the node’s label:
+
+{width=400}
+
+If the loader applies to the whole content, place it in the top right corner:
+
+{width=400}
+
+If processes start simultaneously and have the same execution time, place the loader in the top right corner of the area.
+For example, in the Push dialog, repositories are loaded at the same time.
+Loaders in each line will blink at the same time and will look distracting.
+
+{width=400}
+
+If the top right corner of the area is taken with content and there is no space for the loader, show the progress bar at the top of the tool window.
+For example, the VCS Log tool window has a progress bar at the top when the content is loading or during searching.
+
+{width=605}
+
+### Breadcrumb and dialog label
+
+Place the loader after breadcrumbs or a dialog label to show that the page is being loaded:
+
+{width=274}
+
+### Settings dialog
+
+If some settings or configurations take a significant time to load, it’s preferable to reserve space for a progress bar.
+For example, show a progress bar while installing a plugin:
+
+{width=251}
+
+### Empty state
+
+If the state is empty, show progress text. For example, in search dialogs, and the details panel in settings or tool windows:
+
+{width=708}
+
+Show one more progress indicator, e.g., a loader like on the example above, if loading continues when some data is already displayed.
+
+If a process takes longer than 4 seconds, provide [process details](progress_text.md#details), e.g., the time left or passed, work units
+like the current step, to indicate that the process is being performed and is not hanging:
+
+{width=576}
+
+If it’s not possible to provide progress details, show the loader to indicate that a long process is not frozen:
+
+{width=576}
+
+### Main window
+
+If a process is long and can run in the background, show the progress bar in the main window in the status bar:
+
+{width=238}
+
+Or in a non-modal dialog:
+
+{width=700}
diff --git a/topics/ui/controls/progress_text.md b/topics/ui/controls/progress_text.md
new file mode 100644
index 000000000..d5aed48ab
--- /dev/null
+++ b/topics/ui/controls/progress_text.md
@@ -0,0 +1,102 @@
+
+
+# Progress Text
+
+UI guidelines on writing progress texts.
+
+{width=632}
+
+## When to use
+
+Follow the rules for [progress indicators](progress_indicators.md).
+
+## How to use
+
+### Process name
+
+Use the progressive form of the verb which describes the process, for example:
+
+{width=288}
+
+Add an ellipsis at the end to show that an action is in progress.
+
+Use sentence case for process names.
+
+A process name remains unchanged while the process runs.
+
+Do not animate the ellipsis, as it attracts too much attention.
+The progressive verb form, the text position and the style are enough to understand that this is an action in progress.
+
+### Details
+
+Use sentence case for details.
+
+Do not provide details that are meaningless for the user, for example, "Please wait":
+
+Incorrect
+
+{width=288}
+
+Add time units if the remaining time can be predicted.
+
+Round up the first time unit to one of the following numeric anchors: 1, 2, 3, 5, 10, 15, 20 and 30.
+For example, if there are 7 minutes and 50 seconds remaining, the progress text should read "About 10 minutes left".
+If less than 5 seconds are left, it should say "About 5 seconds left".
+
+{width=288}
+
+Use work units if the remaining time cannot be predicted, as they help the user understand why the process takes so long.
+
+Work units: the current step, the currently processed file, the number of processed files/tde amount of information, the percentage of work completed, and so on:
+
+{width=288}
+
+The time passed if the user controls the process, for example, needs to stop it after a certain time:
+
+{width=288}
+
+Update the timer every second.
+
+### Cancellation action
+
+If the process can be cancelled, add a [link](link.md) for the cancel action for an empty state:
+
+{width=475}
+
+Use title case for the cancel action.
+
+Replace progress text with the loaded data or an [empty state](empty_state.md) when the process has finished.
+Show another progress indicator, e.g., a loader as in the example below, if loading continues after some data has been displayed.
+
+{width=708}
+
+### Trees
+
+Do not show details or a link to cancel the operation for progress in trees and lists. Only show the process name since space is limited here.
+
+## Sizes and placement
+
+### Empty state
+
+Center-align the first line of the progress text if it is no longer than 200px.
+If it is longer than 200px, center-align characters from the first 200px and put the rest of the characters to the right.
+
+Left-align subsequent lines with the first line.
+
+The minimum text width is 40 characters.
+If an area is too narrow to fit the minimum text width, show text using the whole width, including margins.
+If no space is left, hide the text under area borders.
+
+Wrap text when the area’s width changes.
+
+Fields and vertical spaces:
+
+{width=757}
+
+### Tree
+
+{width=261}
+
+## Style
+
+Font color is the same as for [Empty state](empty_state.md) text.
diff --git a/topics/ui/controls/radio_button.md b/topics/ui/controls/radio_button.md
new file mode 100644
index 000000000..69b8fc0a3
--- /dev/null
+++ b/topics/ui/controls/radio_button.md
@@ -0,0 +1,109 @@
+
+
+# Radio Button
+
+UI guidelines on using radio buttons.
+
+
+
+**Implementation:** [`JBRadioButton`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBRadioButton.java)
+
+
+
+{width=213}
+
+## When to use
+
+Use a radio button group to choose one option from 2 to 4 mutually exclusive options.
+
+Do **not** use radio buttons if:
+
+* Several options in a group can be selected. Use a group of [checkboxes](checkbox.md) instead.
+* There are only 2 opposite yes/no options. Use a checkbox instead.
+
+{width=427}
+
+* There are 5 and more options that can be charted on an axis, e.g., time delay. Use a slider instead.
+
+* There are 5 and more options. Use a [drop-down list](drop_down.md):
+
+ | Incorrect | Correct |
+ |-----------------------------------------------------|-----------------------------------------------------|
+ | {width="189"} | {width="351"} |
+
+Consider using a [drop-down list](drop_down.md) if:
+
+* The screen space is limited.
+* The option might be used less often than other options on the screen.
+* There are other drop-down lists in the same group of UI components. A radio button group is more noticeable than a drop-down list, so it will look like a more important setting.
+* There is a combination of several UI components for one setting:
+ {width=575}
+ *The automatic updates setting consists of a checkbox, three lengthy-labeled options in a dropdown and a button.*
+
+## How to use
+
+### Label
+
+A label accompanies each checkbox and is placed next to it.
+
+{width=197}
+
+If a label is long, split it into two lines. Avoid labels that take more than two lines. See recommendations on writing concise labels below.
+
+{width=195}
+
+To implement this, use HTML formatting:
+
+
+
+```kotlin
+radioButton(
+ "Show options before adding
to version control")
+```
+
+
+
+
+```java
+new JRadioButton(
+ "Show options before adding
to version control");
+```
+
+
+
+
+### Writing guidelines
+
+Use sentence-style capitalization.
+
+Do not use ending punctuation.
+
+Use the imperative form of verbs.
+
+Do not use negation in labels as it complicates understanding.
+
+Incorrect
+
+{width=264}
+
+Correct
+
+{width=139}
+
+Make labels short and intelligible — see [Writing short and clear text](writing_short.md).
+
+### Group label
+
+{width=267}
+
+Always start a radio button group with a group label. It explains what the options are for.
+
+Use a checkbox or another radio button as a group label if the radio button group needs to be turned on or off.
+
+Use a colon at the end of a group label.
+
+## Sizes and placement
+
+If a radio button group depends on another control, e.g., a checkbox, follow the rules for [dependent colors](layout.md#dependent-controls).
+Otherwise, follow the rules for [independent colors](layout.md).
+
diff --git a/topics/ui/controls/scrollbar.md b/topics/ui/controls/scrollbar.md
new file mode 100644
index 000000000..b980403df
--- /dev/null
+++ b/topics/ui/controls/scrollbar.md
@@ -0,0 +1,116 @@
+
+
+# Scrollbar
+
+UI guidelines on using scrollbars.
+
+
+
+**Implementation:** [`JBScrollBar`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBScrollBar.java)
+
+
+
+The scrollbar allows users to browse content that’s larger than the visible area, such as text or images, by scrolling it horizontally or vertically.
+
+{width=370}
+
+## Parts of a scrollbar
+
+A scroll bar consists of a track, a thumb, and a status icon if there is a known status for displayed content.
+
+{width=157}
+
+### Track
+
+A track represents the overall length or width of the document.
+
+The track can contain optional markers for quicker navigation between the important parts of the document, for example:
+
+* The occurrences of a search string.
+
+* Breakpoints and the current execution lines.
+
+* A place where an inspection failed.
+
+* Files with errors laid out in a tree.
+
+* Changed parts of a file.
+
+A marker can fit the track width or be placed to the left of the track. Use the latter when you expect the marked region to be tall.
+
+Hovering over the track can also show a lens with a preview of the content at the corresponding position in the document.
+This can be useful in large documents when it is not desirable to change the viewpoint:
+
+{width=622}
+
+### Thumb
+
+A thumb represents the visible portion of the content. For example, a small thumb indicates that there’s lots of content available for scrolling.
+
+### Status icon (optional)
+
+A status icon shows the overall status of inspections performed on the content and allows you to avoid scrolling over the entire view.
+If at least one inspection has failed, the overall status should be the status of that inspection.
+
+{width=492}
+
+## How to use
+
+Respect the OS settings when showing the scrollbar.
+For example, on macOS you can hide the scrollbar until you scroll the content.
+Always show the scrollbar when it is important to understand which part of the content is currently shown.
+For example, the scrollbar in the Editor helps users understand the location of the current code fragment and the overall size of the currently opened file.
+
+Show the track on hover to make the clickable area clearer. Consider not showing the track on hover if it might have more than 5–10 stripes at a time.
+
+Increase the thumb contrast against the background on hover and when scrolling to make it more prominent.
+
+Clicking the track above/below the thumb scrolls one page up/down the viewpoint.
+This allows you to hide the up/down icons on the scrollbar to lessen the visual noise and to scroll with mouse-clicks.
+Track markers serve as a mini-map of the document.
+If they are present, clicking them takes you to the position that this marker is pointing to without having to scroll down the page.
+Change the cursor to "Hand" when hovering such scrollbars.
+
+When showing a text, wrap it instead of showing the horizontal scrollbar when possible. With both scrollbars, it is harder to manipulate the content.
+
+Incorrect
+
+{width=500}
+
+Correct
+
+{width=500}
+
+A horizontal scroll bar can be added for code snippets or for formatted input. Use the context menu to enable soft-wrapping.
+
+Correct
+
+{width=370}
+
+Show only 1 scrollbar per table which scrolls the entire table:
+
+Incorrect
+
+{width=562}
+
+Correct
+
+{width=562}
+
+## Placement
+
+Reserve the space for a vertical scrollbar if there is a column on the right side, otherwise the scrollbar always overlaps content.
+
+Incorrect
+
+{width=350}
+
+Correct
+
+{width=350}
+
+## Style
+
+| Windows/Linux | macOS |
+|--------------------------------|--------------------------------|
+| {width="96"} | {width="96"} |
diff --git a/topics/ui/controls/search_field.md b/topics/ui/controls/search_field.md
new file mode 100644
index 000000000..e8d9094df
--- /dev/null
+++ b/topics/ui/controls/search_field.md
@@ -0,0 +1,295 @@
+
+
+# Search Field
+
+UI guidelines on using search fields.
+
+
+
+**Implementation:** [`SearchTextField`](%gh-ic%/platform/platform-api/src/com/intellij/ui/SearchTextField.java)
+
+
+
+A search field is an input field that helps users locate objects, actions or text in an application.
+
+{width=400}
+
+This article focuses on the search field.
+
+[//]: # (TODO: See another article for [search results](search_results.md).)
+
+## When to use
+
+Use the search field when specific objects are difficult to find at a glance, for example:
+
+* There are many objects, for example, in the VCS Log table or in the Editor with a large file opened.
+* Objects aren't in a single location, for example controls are located on different setting pages.
+
+## How to use
+
+### Label and Placeholder
+
+Do **not** add a label to the search field. The magnifying glass icon is self-explanatory.
+
+Incorrect
+
+{width=360}
+
+Correct
+
+{width=360}
+
+Mark the replace field with a label or a placeholder when shown together with the search field to distinguish between them:
+
+{width=865}
+
+Provide hints and scope as placeholder text.
+For example, the placeholder for plugins' search depends on the settings page tab to make it clear that search depends on the tab:
+
+{width=581}
+
+### Icons
+
+#### Search Options
+
+Use icon buttons inside the search field to save space and not to overload the UI and to be able to use them in already packed UI such as the Speed Search popup in trees or lists:
+
+{width=400}
+
+Available option icons:
+
+| {width=16} | Match case |
+|--------------------------------|--------------|
+| {width=16} | Regex |
+| {width=16} | Words |
+| {width=16} | In selection |
+{style=none}
+
+Change the state of options icons on hover so that it is clear that they are clickable:
+
+{width=400}
+
+Make icon buttons easily accessible with Tab navigation.
+Option icons should be placed on the right of the search field in the tabbing order.
+Show a border around the focused option.
+
+{width=400}
+
+Icon buttons should change color when enabled so that it is clear which options are currently enabled:
+
+{width=400}
+
+#### Clear a Search String
+
+Show the clear button only when filtering on-screen content.
+When the button is clicked, clear the search field and restore the content to its default state.
+Do **not** show the clear button if the search field is empty.
+
+{width=581}
+
+Do **not** show the clear button when the initial data state is empty or doesn't differ from the result.
+For example, the close icon is not really useful in the editor search field since matches are highlighted and not filtered:
+
+Incorrect
+
+{width=419}
+
+When search can be configured with options, show the clear button on the left of the option buttons.
+This way, option buttons won't jump when the clear button appears.
+The separator between the options and the clear button makes it harder to mis-click the potentially dangerous clear icon.
+
+{width=400}
+
+#### Multiline Search Strings
+
+Searching for multiline matches can be achieved with a separate New Line action button:
+
+{width=342}
+
+Put the New line action button on the left of the option buttons:
+
+{width=300}
+
+Move the New Line action button below the option buttons when the search field becomes a multi-line one:
+
+{width=300}
+
+Add a vertical separator when the scrollbar appears:
+
+{width=300}
+
+The default shortcut for the New Line action:
+
+
+
+ | macOS |
+ ⇧⌘⏎ |
+
+
+ | Windows/Linux |
+ Ctrl + Shift + Enter |
+
+
+
+### Completion
+
+Provide completion for complex searches with filtering by attributes:
+
+{width=354}
+
+Do **not** use filter attributes as separate controls on the toolbar.
+Not all of them are needed every time while they take a lot of space and overload the interface.
+Use completion instead:
+
+Incorrect
+
+{width=550}
+
+Correct
+
+{width=550}
+
+The following syntax is used for attributes:
+
+* Binary attributes are marked with a number sign (#), for example, _#by-jetbrains_ to show plugins which are developed by JetBrains.
+
+* Values for open attributes are provided after a colon, for example, _status: disabled_ to show all disabled plugins.
+
+Provide aliases to the main attributes where possible, this way it would be easier for users to find the required filter.
+For example, the User attribute in the VCS Log search field can have the Author alias.
+
+Show a popup with search attributes when the field gets focus, and after each space character except the space character following an attribute's name.
+This will make it clear that filtering by attributes is available.
+
+Filter out the completion suggestions as the user types:
+
+{width=354}
+
+Show a popup with values right after the user has entered an attribute.
+
+{width=354}
+
+### Search History
+
+Use the magnifying glass icon with an arrow when search history is available:
+
+{width=250}
+
+And without an arrow when it's not:
+
+{width=250}
+
+Show search history in a popup when clicking on the magnifying glass icon:
+
+{width=256}
+
+Show context help in the history popup when it is empty:
+
+{width=256}
+
+The keyboard shortcut for the History action is Alt + Down on all systems.
+
+Add a search string to history:
+
+* On Enter for searches that are executed.
+* When the search field loses focus for searches that are executed on any keystroke.
+
+## Sizes and placement
+
+### Placement
+
+Put the search field on top of the on-screen content that is being searched, and align them vertically.
+For example, the search field in Settings dialog is aligned with the filtered settings tree:
+
+Correct
+
+{width=256}
+
+The search field is not aligned with the content on the Keymap settings page, which makes it harder to relate the content and the search string:
+
+Incorrect
+
+{width=491}
+
+Correct
+
+{width=491}
+
+Fit the search field to the popup windows and to a toolbar if it has top borders. This way the overall form looks less complex.
+
+Incorrect
+
+{width=475}
+
+Correct
+
+{width=475}
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="235"} | {width="235"} |
+
+Show the search field on demand when search is supplementary to other functionality or if space is limited.
+For example, space in the Project view is limited and too loaded to always show the _Speed Search_ bar:
+
+{width=360}
+
+When searching through content that is not displayed on the screen, put the search field on top of the active frame as a popup.
+This makes it more prominent and gives space for search results.
+For example, Search Everywhere is shown on top of the main IDE frame:
+
+{width=686}
+
+### Sizes
+
+For a search field shown without a toolbar (i.e. _Speed Search_ in trees), the search width could be adjusted on typing to accommodate input:
+
+{width=160}
+
+For a search field that is not fitted to a toolbar, set the minimum width to 200:
+
+{width=425}
+
+For a search which is fitted to the toolbar, expand the field to the toolbar width.
+
+Center-align icons and the search string with the one-line search field vertically. Adjust the right and left paddings to the higher search fields:
+
+{width=297}
+
+{width=296}
+
+Save the position of the search and option icons when the search field becomes a multi-line one:
+
+{width=250}
+
+### Spaces
+
+Between the floating search field and on-screen content:
+
+{width=265}
+
+Between history and the search field:
+
+{width=269}
+
+Between search string and completion popup:
+
+{width=266}
+
+Completion popup:
+
+{width=95}
+
+## Style
+
+### Colors and Fonts
+
+For a general search field, use the same colors as for an input field.
+
+For a search field that is fitted to the toolbar, use a narrower focus border on macOS. The border width is 2px in that case:
+{width=475}
+
+Use the same font for the search string as used for showing the results.
+
+Use the Context help font color for the attributes' names as they are secondary to their values.
+
diff --git a/topics/ui/controls/split_button.md b/topics/ui/controls/split_button.md
new file mode 100644
index 000000000..ca930aef8
--- /dev/null
+++ b/topics/ui/controls/split_button.md
@@ -0,0 +1,206 @@
+
+
+# Split Button
+
+UI guidelines on using split buttons.
+
+
+
+**Implementation:** [`JBOptionButton`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBOptionButton.kt)
+
+
+
+The Split button is a button that has two parts — the main action on the left and a control button which shows a dropdown with less common actions on the right.
+
+{width=218}
+
+## When to use
+
+Use the split button:
+
+When more than 2 related actions are possible but the space is limited and/or packed:
+For example, it is useful for the Commit actions group in the Commit dialog:
+
+{width=218}
+
+The Split button is not useful in the Replace popup, since not all actions are related.
+For example, Open in Find Window
+is not related to the main action. Such actions are hard to find in the drop-down menu:
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="152"} | {width="327"} |
+
+In the Adjust Code Style dialog, only 1 related action is possible, and it does not save a lot of space:
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="152"} | {width="234"} |
+
+To hide actions which are dangerous and uncommon. Dangerous means an action can destroy users’ data and cannot be easily undone.
+It is less possible to accidentally click an action hidden in a menu.
+It is recommended to hide even a single related uncommon dangerous action.
+For example, Force Push can override remote commits from other authors and should not be easily available:
+
+{width=111}
+
+If an action is dangerous but common, do not hide it under the split button, use simple buttons.
+
+[//]: # (TODO: An action should follow the principles for dangerous actions behavior.)
+
+
+Do **not** use the Split Button in other cases, use simple [Buttons](button.topic) instead.
+
+## How to use
+
+### Main action
+
+
+
+ | Click |
+ Invoke the main action |
+
+
+
+### Control button
+
+
+
+ | Click |
+
+
+ - Show a dropdown menu with secondary actions
+ - Hide the menu on clicking outside the menu, or on the second click on the right part of the button
+
+ |
+
+
+ | Hover |
+
+
+ - Show a tooltip:
+
+ -
+ The tooltip must not overlap the dropdown menu. Do not show a tooltip under the menu, show it on the opposite side of the button:
+
+ Correct
+ 
+
+ Incorrect
+ 
+
+
+ |
+
+
+
+### Dropdown menu
+
+Place actions related to the main button’s action in the dropdown menu.
+
+{width=218}
+
+Do **not** duplicate the main action in the dropdown menu, otherwise it is confusing how to trigger the main action — with the button or from the menu.
+
+[//]: # (### Reduce split button to simple action buttons)
+
+[//]: # ()
+
+[//]: # (The Split button can be reduced to simple action buttons which are laid out automatically next to each other. This is controlled by the following option in settings:)
+
+[//]: # (Settings | Appearance & Behavior | Appearance | Merge buttons in dialogs)
+
+[//]: # ()
+
+[//]: # (For example, the Commit button reduced to its components (the option is disabled) looks like the following:
)
+
+[//]: # ()
+
+[//]: # ({width=500})
+
+## Keyboard navigation & shortcuts
+
+Trigger the **main** action when the [default](button.topic#default) button shortcut is pressed if the split button is the default one.
+
+Open the dropdown menu with the first menu item selected on Alt+Shift+Enter.
+
+Do **not** show the dropdown menu when the button gains focus.
+
+### Focus on the button
+
+
+
+ | Enter and Ctrl+Enter |
+ - Invoke the default button action
|
+
+
+ | Space |
+ |
+
+
+ | Arrow Down |
+ - Show the dropdown menu with secondary actions and move focus to the first item in the menu
|
+
+
+ | Tab and Shift + Tab |
+ - Move focus to the control next to the split button and hide the drop-down menu
|
+
+
+
+### Focus in the drop-down menu
+
+
+
+ | Enter and Space |
+ Invoke the selected action |
+
+
+ | Arrow Down and Arrow Up |
+
+
+ - Navigate through the elements
+ - Pressing Up on the top element moves the focus to the bottom element
+ - Pressing Down on the bottom element moves the focus to the top element
+
+ |
+
+
+ | Esc |
+ Close the popup and move the focus to the split button |
+
+
+
+## Sizes and placement
+
+Follow the rules for the [simple button](button.topic#sizes-and-placement).
+
+### Button
+
+The width of the split button equals to the width of the main button (follow the rules of the [simple button](button.topic)) plus the width of the drop-down button.
+
+| Windows | Mac | Darcula |
+|--------------------------------------|--------------------------------|------------------------------------|
+| {width="92"} | {width="90"} | {width="94"} |
+
+A different width for the split button makes it easier to understand that this button is different from other buttons in the dialog.
+
+### Drop-down menu
+
+Follow the rules for menus with regard to sizes, colors, fonts and spacing.
+
+Menu item height and spacing between the menu and the button:
+
+{width=232}
+
+## Style
+
+Increase line height in the dropdown menu to lessen the chance of choosing the wrong menu item by mistake.
+
+Leave 2px around the separator inactive to lessen the chance of choosing the wrong menu item by mistake:
+
+{width=218}
+
+Align the dropdown with the button left border:
+
+{width=219}
+
diff --git a/topics/ui/controls/split_icon_button.md b/topics/ui/controls/split_icon_button.md
new file mode 100644
index 000000000..9d8ce1e14
--- /dev/null
+++ b/topics/ui/controls/split_icon_button.md
@@ -0,0 +1,59 @@
+
+
+# Split Icon Button
+
+UI guidelines on using split icon buttons.
+
+
+
+**Implementation:** [`SplitButtonAction`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/actionSystem/SplitButtonAction.java)
+
+
+
+A split icon button appears on a horizontal toolbar and consists of two parts: the main icon and a triangle icon for the action list.
+
+{width=278}
+
+## When to use
+
+The split icon button helps reduce the number of icons on the toolbar and minimize visual noise.
+
+Use the split icon button for a group of similar actions if there are already many icons on the toolbar and:
+
+* The user invokes one action more often than others,
+
+* Or if the user invokes one action several times, then switches to another action and invokes it several times but does not switch between actions too often.
+
+{width=325}
+
+*Profiler actions are grouped into a split button*
+
+If the user invokes actions with the same frequency or often switches from one action to another, use separate icons for each action.
+
+To decide whether to add the whole group of actions on the toolbar, follow the rules for the [toolbar](toolbar.md#what-items-to-add-on-toolbar).
+
+Use the split icon button on horizontal toolbars only, as it’s too wide for vertical toolbars.
+
+## How to use
+
+Make sure that all actions in the popup menu have icons. When an action is launched, its icon will be used as the main icon.
+
+{width=325}
+
+*The user clicks Profile Allocations, the action starts, and its icon is shown as the main icon.*
+
+## Built-in behavior
+
+On hover, the main icon and the triangle icon are highlighted separately, and the line between two parts is added.
+The tooltip for the main icon action is shown on hovering over it.
+
+{width=192}
+
+The main icon invokes its action on click. The triangle icon opens the action menu on click:
+
+{width=325}
+
+If some actions are unavailable, the corresponding menu items are disabled. The action menu should always open, even if all the items in it are disabled.
+
+{width=325}
+
diff --git a/topics/ui/controls/table.md b/topics/ui/controls/table.md
new file mode 100644
index 000000000..e6e9b74e3
--- /dev/null
+++ b/topics/ui/controls/table.md
@@ -0,0 +1,404 @@
+
+
+# Table
+
+UI guidelines on using tables.
+
+
+
+**Implementation:** [`JBTable`](%gh-ic%/platform/platform-api/src/com/intellij/ui/table/JBTable.java)
+
+
+
+{width=448}
+
+## When to use
+
+Use tables so that users can review, enter or edit uniform sets of data or options. For example:
+
+* Git | Show Git Log
+* Settings | Appearance & Behavior | Path Variables
+* Settings | Appearance & Behavior | File Colors
+
+Use tables:
+
+* To compare data in a set, for example, in the File Colors table, it is convenient to compare file colors with one another and make sure that they are distinguishable:
+
+* {width=350}
+
+* To search by all parameters in a data set, for example, in the File History table, it is possible to quickly filter the table by the date, author or commit message.
+
+{width=488}
+
+Do **not** use tables:
+
+* For hierarchical structures. Use Tree View instead.
+
+* When there are more than 4 options per entry. Use the Master-Detail layout instead.
+
+* When at least one of the options requires a multi-line control, for example, the Text Area in Settings | Editor | Copyright | Copyright Profiles. Use Master-Detail layout instead:
+
+ {width=709}
+
+## How to use
+
+### Label
+
+A label is optional for tables.
+
+Add a label if the table content is not obvious from the dialog title or the table header. For example, in the table that lets you configure filters for import and completion per-scope:
+
+{width=448}
+
+Avoid a label if it duplicates the dialog title or the table header. For example, there is no need for a label in the JavaScript | Libraries table since the Settings page title and the table context make it clear what is in the table:
+
+{width=424}
+
+Add a label if the control above can be mistaken for a table header:
+
+{width=350}
+
+Do **not** add a label to explain the table behavior. Use context help instead:
+
+Incorrect
+
+{width=448}
+
+Correct
+
+{width=448}
+
+Follow the rules for the [Input field](input_field.md):
+
+* The label should be short and descriptive.
+* A label must be a noun phrase punctuated with a colon.
+* Use sentence-style capitalization.
+* If a table is disabled, disable the label.
+* Make label text selectable.
+
+Always put the label on top of the table.
+
+Do **not** use a Group separator instead of a Table label. A horizontal line is redundant here:
+
+Incorrect
+
+{width=448}
+
+Correct
+
+{width=448}
+
+### Header
+
+A table header is the row at the top of the table that helps identify the columns below each of the headers. Follow these rules:
+
+Add a header to a table if table data is non-descriptive or ambiguous.
+For example, in the Environment Variables table a header is required, since that content of each column is not clear:
+
+Correct
+
+{width=350}
+
+Incorrect
+
+{width=350}
+
+Do **not** use a header if all columns in a table have self-descriptive content, for example, names, dates, color previews, etc. For example, a header in File History is redundant:
+
+Correct
+
+{width=488}
+
+Incorrect
+
+{width=488}
+
+Labels in a header should be short and descriptive. Try to avoid headers which are too long for the content in the rows below. [How to write texts](writing_short.md).
+
+Use nouns and noun phrases.
+
+Use title-case capitalization.
+
+Freeze a headers when scrolling the table. A header provides useful context and should not be hidden.
+
+Align header with the content in the column below:
+
+{width=350}
+
+### Placeholder
+
+A table placeholder is shown when there is no data yet. Always put meaningful text here, do **not** write "Nothing to show".
+
+{width=226}
+
+It is better to add a reason why a table is empty, and an action link to fill it:
+
+{width=226}
+
+See more on empty tables [here](empty_state.md).
+
+### Toolbar
+
+Add a toolbar to provide actions which help manipulate data in the table (add, remove, import, etc.):
+
+{width=370}
+
+Use the [`ToolbarDecorator`](%gh-ic%/platform/platform-api/src/com/intellij/ui/ToolbarDecorator.java) class to implement such a toolbar. See more on toolbars [here](toolbar.md).
+
+### Zebra striping and inner borders
+
+Zebra striping is alternate highlighting of lines or rows in data tables or forms.
+
+Use stripes if you want to help users distinguish between different data sets. For example, the current branch is highlighted differently from other branches:
+
+{width=488}
+
+Do **not** use stripes In a simple data set as guides to track content between columns. Alternating backgrounds create two distinct layers of focus while the type of data in different rows is the same.
+
+Incorrect
+
+{width=448}
+
+Default line height, [proper column width](table.md#sizes-and-placement) and highlighting rows on mouse hover should provide enough guidance to track content.
+For example, look at the same table without stripes, with bigger line height and adjusted column width:
+
+Correct
+
+{width=448}
+
+Bigger distance between groups of related information can also help in tracking content. Line height between groups should be increased by 4px for each group level.
+
+For example, look at the File History table grouped by commit, author, and date:
+
+{width=488}
+
+Do **not** add borders between rows or columns, they add unnecessary noise to the table:
+
+Incorrect
+
+{width=493}
+
+Correct
+
+{width=493}
+
+### Interaction
+
+Highlight the hovered row to assist in tracking content across columns:
+
+{width=448}
+
+Change the background to active selection color for the selected row when the table is focused:
+
+{width=448}
+
+and to inactive selection when the focus is on another element:
+
+{width=448}
+
+Do **not** leave the active selection color in the table when the focus switches to some other element.
+It is otherwise confusing which element is currently active.
+
+Columns in tables should be resizable to allow users to set a comfortable column width.
+Change the mouse cursor to "Horizontal Resize" when hovering the rectangular area between columns.
+This area is defined by table height and by 2px padding around the columns’ divider.
+This makes it clear that columns can be resized even in a table without a header:
+
+{width=448}
+
+Double click when the "Horizontal Resize" cursor is activated, should auto resize the column to fit the content.
+
+If column sorting is available, display the sorting state in the column header.
+If the user clicks on a column that is already sorted, reverse the sorting order and rotate the sorting icon:
+
+{width=350}
+
+Add sorting to a table if the default sorting by one column may be insufficient to scan the data set.
+For example, in the table above, it is useful to be able to sort both by path and encoding to quickly find all paths with a specific encoding,
+or to find a specific path in the sorted list.
+
+If columns can be reordered, change the cursor to "Hand" when hovering the table header, and allow changing their order by dragging the table header.
+
+In tables without a header show the drag icon on top of the column when hovering it:
+
+{width=488}
+
+Change the cursor to "Hand" on the icon hover:
+
+{width=488}
+
+Allow dragging a column when the cursor is placed anyplace over this column.
+This makes it clear that columns can be dragged even if there is no table header.
+
+In disabled table greyed-out text, disable controls and any interaction:
+
+{width=448}
+
+### Editing values
+
+If data in a cell is editable or configurable:
+
+Allow in-place editing of content for text data. It should be possible to activate editing on mouse click:
+
+{width=448}
+
+The line with the edited cell should be selected.
+The edited cell should have borders, and their color should be the same as the color for [Input field](input_field.md) borders.
+
+Allow in-place editing for paths and add the Browse button to the cell:
+
+{width=448}
+
+Show a separate dialog for non-text data, for example, a color chooser for colors.
+
+Do **not** show a separate dialog for editing simple data rows without a compound preview (an example of a compound preview can be found in Settings | Editor | Language Injections).
+For example, there is no need for a separate dialog in the Settings | Appearance & Behavior | Path Variables table, as all editing could be done in place.
+
+If it’s possible to enumerate less than 15 most likely or valid variants, show a combobox-like configurable with a down-arrow icon and a popup on click:
+
+{width=115}
+
+Show the combo icon only on hover or when the corresponding line is selected. A lot of arrows in one column form their own information layers and attract too much attention.
+
+If there are more than 15 variants, show a completion popup.
+
+Do **not** use a full-size combobox inside tables. It looks inconsistent and has too many details for a table; a simple dropdown icon with the variants popup is enough.
+
+Incorrect
+
+{width=115}
+
+## Sizes and placement
+
+### Sizes
+
+Choose a column width appropriate for the most common values, but no less than **65px**. Too wide columns make it hard to read data.
+
+Correct
+
+{width=350}
+
+Incorrect
+
+{width=592}
+
+The minimum table width is **350px**. If a table is too narrow after you have adjusted column widths, add space to the rightmost column.
+
+Add space to the rightmost column if you need to align it with other tables in the same window.
+
+If content doesn't fit a cell's width, cut the text by the right border:
+
+{width=370}
+
+Do **not** put ellipsis at the end of a cropped line, as it can be confused with the content.
+Also, ellipsis can form a separate redundant column when content in the majority of cells in one column doesn't fit its width.
+
+Do **not** add a fade-away gradient for cropped text, as it adds too many shades to a table text, and they attract too much attention.
+
+### Placement
+
+Do **not** put vertical elements (for example, diagrams) in the middle of a table, as they prevent users from scanning data easily:
+
+Incorrect
+
+{width=488}
+
+Place them closer to the sides instead:
+
+Correct
+
+{width=488}
+
+Right-align numbers when it is useful to compare them by their length. Left-align all the other content.
+
+{width=350}
+
+For aligning in a dialog with other controls, see [Layout](layout.md).
+
+
+
+## Style
+
+| IntelliJ | {width=350} |
+|----------|------------------------------------|
+| Darcula | {width=350} |
+
+{style=none}
diff --git a/topics/ui/controls/tabs.md b/topics/ui/controls/tabs.md
new file mode 100644
index 000000000..fc15ad981
--- /dev/null
+++ b/topics/ui/controls/tabs.md
@@ -0,0 +1,72 @@
+
+
+# Tabs
+
+UI guidelines on using tabs.
+
+
+
+**Implementation:** [`JBTabbedPane`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBTabbedPane.java)
+
+
+
+Tabs organize content in dialogs by grouping similar UI controls.
+
+{width=322}
+
+In code editors, tabs are created with another component — [`JBEditorTabs`](%gh-ic%/platform/platform-api/src/com/intellij/ui/tabs/impl/JBEditorTabs.java). It supports extended functionality like icons, closeable, and draggable tabs. Do **not** use this component in dialogs.
+
+In tool windows, tabs are generated automatically. See also [Tool window](tool_window.md).
+
+## When to use
+
+Follow the rules in [Groups of controls](groups_of_controls.md).
+
+## How to use
+
+Use title capitalization for tab labels.
+
+Make the label short, preferably no more than 3 words.
+Avoid generic words, such as "General" or "Advanced".
+See [Writing short and clear](writing_short.md).
+
+{width=284}
+
+Place the most frequently used content in the first tab.
+Tabs that do not fit allotted screen space automatically hide under the dropdown component.
+(It is better to add no more than 8 tabs, but this number is not limited.)
+
+{width=533}
+
+Always place tabs on top. It is possible to place them at other sides of the content — bottom, left, or right — but such a placement is extremely rare and might confuse users.
+
+Do not remove or disable a tab when its function is unavailable. Explain why a tab’s content is unavailable in the body of the tab.
+
+## Placement
+
+Make sure the border of the tab reaches the edges of the area tabs occupy.
+
+Incorrect
+
+{width=595}
+
+Correct
+
+{width=595}
+
+Do **not** surround the tab content area with a visible border.
+
+Incorrect
+
+{width=595}
+
+Avoid placing independent content groups under the tabs' area.
+
+Incorrect
+
+{width=595}
+
+When there are other UI controls above tabs, separate them with a vertical indent.
+
+{width=595}
+
diff --git a/topics/ui/controls/text_area.md b/topics/ui/controls/text_area.md
new file mode 100644
index 000000000..877429d35
--- /dev/null
+++ b/topics/ui/controls/text_area.md
@@ -0,0 +1,109 @@
+
+
+# Text Area
+
+UI guidelines on using text areas.
+
+
+
+**Implementation:** [`JBTextArea`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/JBTextArea.java)
+
+
+
+A text area allows users to enter or edit multi-line text.
+
+{width=300}
+
+## When to use
+
+Use a text area if input is unconstrained and long, or if the newline character is a valid value. Example: commit message or code snippets.
+
+Do **not** use a text area if:
+
+* Input consists of several words. Use an [input field](input_field.md) instead.
+* There is not enough space for a text area, or if input is normally short but can occasionally be long or multi-line. Use an [expandable input field](input_field.md#input-field-types) instead.
+* Values are added one by one. Use a [table](table.md) instead.
+* Text is read-only. Use a [description text](description_text.md) instead.
+
+## How to use
+
+### Label
+
+Follow the rules for the [input field](input_field.md).
+
+A label is required for all empty text areas.
+If a text area is prefilled, and it’s clear from the context what data it contains, a label can be omitted.
+For example, the following text area is used to preview file and code templates:
+
+{width=584}
+
+*If a new file template is added and the text area is empty, the label is required.*
+
+Do **not** put units on the right of the text area.
+
+Do **not** use a [group header](group_header.md) instead of the text area label. The horizontal
+line is redundant here. Use [context help](context_help.md) to explain the field behavior.
+
+Incorrect
+
+{width=598}
+
+Correct
+
+{width=598}
+
+### Placeholder, prefilled values and field focus
+
+Follow the rules for the input field: [placeholder](input_field.md#placeholder), [prefilled value](input_field.md#prefilled-value), [field focus](input_field.md#field-focus).
+
+### History {id="history_1"}
+
+If the previous user input should be saved, use ⌥↑ and ⌥↓ on macOS and Alt+Up/Down
+on Windows and Linux to navigate through the history.
+If history is available, add a note at the bottom of the input field:
+
+{width=400}
+
+Save the current value, so that the user can return to it while navigating through the history.
+
+### Validation
+
+If the user types an invalid value, highlight the text area with red and show an error message in a tooltip. For more details, see [Validation errors](validation_errors.md).
+
+{width=306}
+
+## Size and placement
+
+Recommended sizes:
+
+{width=492}
+
+This is the default size, it can be changed if the dialog is resized.
+
+**Height**. The minimum text area height is 3 lines ~55px, so the user understands that it’s multi-line. The maximum height is not limited and should be appropriate for the most common values.
+
+**Width**. The minimum text area width is 270px. It’s inconvenient to use a narrower field due to frequent line breaks. The maximum width is 80 symbols ~600px, otherwise, it’s hard to read the text.
+
+Size the text area to display an integral number of lines of text:
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+|  |  |
+
+Do **not** resize a text area on input. It will change the position of other controls and they can become hardly discoverable.
+
+If the text is long and does not fit the text area, add [scrollbar](scrollbar.md).
+
+For placement, follow the rules for the [input field](input_field.md).
+
+## Style
+
+Use the same colors as for the [input field](input_field.md).
+
+Do **not** highlight a text area on selection, only if a validation error occurs.
+
+### History
+
+Background: dialog default theme color
+
+Font: Windows, IntelliJ — default, macOS 2px smaller than default
diff --git a/topics/ui/controls/toggle_button.md b/topics/ui/controls/toggle_button.md
new file mode 100644
index 000000000..5b3d78d64
--- /dev/null
+++ b/topics/ui/controls/toggle_button.md
@@ -0,0 +1,78 @@
+
+
+# Toggle Button
+
+UI guidelines on using toggle buttons.
+
+
+
+**Implementation:** see [](#control)
+
+
+
+The toggle button is used to switch between On and Off states.
+
+{width=53}
+
+## When to use
+
+Use the toggle button to switch the state of an item in search results:
+
+{width=676}
+
+Do not use the toggle button for items in dialogs and menus. Instead, use a checkbox in dialogs and a checkmark in menus:
+
+{width=400}
+
+## How to use
+
+### Label
+
+The toggle button in search results should duplicate the option from the settings or the menu.
+Label and capitalization should be the same as on the option label:
+
+{width=228 style=block}
+*Setting in the preferences*
+
+{width=676 style=block}
+*The same setting in search results*
+
+Do not make a setting available only from search results.
+
+[//]: # (TODO: See [discoverability](discoverability.md) for details.)
+
+If the setting is in a tree or menu, use the toggle button label to specify where the setting is located:
+
+{width=387 style=block}
+*Setting in a tree*
+
+{width=676 style=block}
+*The same setting in search results; separate tree levels with a colon*
+
+{width=497 style=block}
+*Setting in the main menu*
+
+{width=676 style=block}
+*The same setting in search results; separate the first menu level with a vertical bar, and separate others with a colon*
+
+Refer to [checkbox](checkbox.md) for writing checkbox labels and menu labels.
+
+[//]: # (TODO: and [menu](menu_list.md))
+
+Do not add the word "On" or "Off" to the item name, since the state description is already in the toggle button.
+
+### Control
+
+A toggle button is implemented with the [`OnOffButton`](%gh-ic%/platform/platform-api/src/com/intellij/ui/components/OnOffButton.java) class.
+But generally, you shouldn't use the class directly.
+The IDE automatically places the buttons in the search feed if you follow one of the patterns described below:
+
+1. If this is a system or editor or another kind of settings, register the corresponding [`BooleanOptionDescription`](%gh-ic%/platform/platform-api/src/com/intellij/ide/ui/search/BooleanOptionDescription.java) for the option. The options can be bound (but not limited) to:
+
+ - A [`SearchTopHitProvider`](%gh-ic%/platform/platform-api/src/com/intellij/ide/SearchTopHitProvider.java) instance which is registered in plugin.xml with the `` tag. For example, see the [`SystemOptionsTopHitProvider`](%gh-ic%/platform/platform-impl/src/com/intellij/ide/ui/SystemOptionsTopHitProvider.java) class that represents matching of Reopen last project on startup checkbox
+ to `BooleanOptionDescription`.
+
+ - [`EditorOptionDescription`](%gh-ic%/platform/platform-impl/src/com/intellij/ide/ui/EditorOptionDescription.java) bound to [`EditorSettingsExternalizable`](%gh-ic%/platform/ide-core-impl/src/com/intellij/openapi/editor/ex/EditorSettingsExternalizable.java), which under the hood works with the editor.xml.
+2. Implement your own action that's inherited from [`ToggleAction`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/actionSystem/ToggleAction.java) and registered in plugin.xml.
+
+The toggle button changes state when it is clicked with the mouse or when Enter is pressed on the item line.
diff --git a/topics/ui/controls/toolbar.md b/topics/ui/controls/toolbar.md
new file mode 100644
index 000000000..f89b5e166
--- /dev/null
+++ b/topics/ui/controls/toolbar.md
@@ -0,0 +1,150 @@
+
+
+# Toolbar
+
+UI guidelines on using toolbars.
+
+A toolbar provides quick access to frequently used actions and filters. It appears in dialogs, pop-ups, tool windows, lists, trees, and tables.
+
+{width=428}
+
+## Toolbar items
+
+The following controls can appear on a toolbar:
+
+* [Icon button](icon_button.md): action, toggle, or drop-down
+
+* [Split icon button](split_icon_button.md)
+
+* [Toolbar drop-down list](toolbar_drop_down.md)
+
+* [Search field](search_field.md)
+
+* [Button](button.topic)
+
+* Separator
+
+* Label
+
+* Chevron
+
+{width=704}
+
+## What items to add on toolbar
+
+Put only the most frequently used commands on the toolbar. Rely on usage statistics if it’s available.
+
+If an action is new, and it seems useful, add it to the corresponding toolbar.
+Remove it after several releases if it’s not popular, which means it’s used by less than ~5% of users who use this toolbar.
+
+Do **not** put unpopular or well-known commands, like Copy and Paste on the toolbar. Use the main menu or the context menu for such commands.
+
+It’s **not** recommended to add more items than the default toolbar length. Otherwise, the items will be hidden and it will be hard to discover them.
+
+{width=283}
+
+Left align items on a horizontal toolbar and top align on a vertical toolbar.
+
+Group related toolbar icon buttons and separate groups with lines. If there are several unrelated icons, do **not** add separators after each icon.
+
+{width=242}
+
+Label a group of icons if it helps to make the icons clearer and if it’s needed to promote the icons. The icons group becomes more visible with the label.
+
+Arrange items inside groups by the frequency of use, from left to right from top to bottom. Rely on statistics.
+
+It is recommended to arrange groups in the following order unless it contradicts the usage statistics. If it does, arrange groups by the frequency of use.
+
+{width=260}
+
+The less frequently used commands can be right aligned.
+
+{width=491}
+
+Do **not** put two toolbars next to each other. One toolbar should be enough for the most popular actions.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="58"} | {width="30"} |
+
+Make every toolbar action available from the main menu or the context menu.
+Toolbars are customizable and can be hidden, so commands should be available from other places as well.
+
+If the default component size changes and there is not enough space for items on a toolbar, hide them under the chevron.
+
+{width=30}
+
+## Visibility and customization
+
+Provide the ability to hide the toolbar in the main window via the toolbar context menu.
+
+{width=428}
+
+Provide commands for invoking the toolbar. Use the main menu for the main window toolbars. Use the pane view settings for toolbars in tool windows.
+
+{width=597}
+
+Provide the ability to customize toolbars in the main window.
+To do this, add the toolbar to the list on the Settings | Appearance & Behavior | Menus and Toolbars page and open
+it using the Customize Toolbar... action from the toolbar context menu.
+
+{width=404}
+
+## Sizes and placement
+
+The toolbar can be vertical or horizontal.
+
+{width=498}
+
+By default, place the toolbar at the top of the area.
+
+{width=220}
+
+### Exceptions
+
+Place the toolbar on the left in horizontal tool windows if horizontal space is not limited.
+A horizontal toolbar will be too wide and will occupy lots of space:
+
+{width=220}
+
+Place the toolbar on the right if it’s not the first toolbar in the pane, and it’s rarely used.
+
+{width=386}
+
+Place the toolbar at the bottom on macOS, and on the right on Windows and Linux in [tables](table.md).
+
+{width=432 style=block}
+*macOS*
+
+{width=431 style=block}
+*Windows*
+
+The toolbar width is limited by the width of the element it belongs to. For example, by the width of the tool window or the list part in a master-detail layout.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="283"} | {width=283} |
+
+Toolbar sizes are the same for all themes:
+
+{width=539}
+
+{width=418}
+
+The toolbar items sizes change together with the application font size proportionally.
+
+{width=604}
+
+## Style
+
+{width=477}
+
+Separate the toolbar from the content with a line from all four sides if it appears in a tool window or a table:
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="220"} | {width="220"} |
+
+Do **not** separate a toolbar with lines if it appears above the list:
+
+{width=404}
diff --git a/topics/ui/controls/toolbar_drop_down.md b/topics/ui/controls/toolbar_drop_down.md
new file mode 100644
index 000000000..3e0fcb641
--- /dev/null
+++ b/topics/ui/controls/toolbar_drop_down.md
@@ -0,0 +1,121 @@
+
+
+# Toolbar Drop-Down List
+
+UI guidelines on using toolbar drop-down lists.
+
+
+
+**Implementation:** [`ComboBoxButton`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/actionSystem/ex/ComboBoxAction.java)
+
+
+
+A toolbar drop-down list is a type of button that appears on a horizontal toolbar and shows a list of choices on clicking it.
+
+{width=205}
+
+## When to use
+
+Use toolbar drop-down if a single option should be selected.
+
+If the choices are objects or states.
+
+To select values that are controlled by the toolbar button on the right.
+
+{width=209}
+
+To filter values or change the appearance in the control below:
+
+{width=244}
+
+Use a [toolbar drop-down button](icon_button.md) instead of a drop-down list in the following cases:
+
+* If there is a list of actions:
+
+{width=136}
+
+* The options are secondary and the user won’t change them in most cases.
+
+* Multi-selection is required, for example, to group by several attributes.
+
+Do **not** use toolbar drop-down in dialogs, use the [drop-down list](drop_down.md) instead.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="302"} | {width="302"} |
+
+## How to use
+
+Do **not** add a label to the toolbar drop-down.
+
+For the default value, follow the rules for the [drop-down list](drop_down.md#default-value).
+
+Add separators between the toolbar drop-down and icons:
+
+{width=313}
+
+If a drop-down is controlled by buttons, add a border, as separators will break the connection between the controlling icons and the drop-down:
+
+{width=209}
+
+The toolbar drop-down does not get the focus. Highlight it on hover the same way as toolbar icons.
+
+{width=209}
+
+### Menu
+
+#### Control
+
+Open the drop-down menu when clicking anywhere on a drop-down list.
+Open the menu down by default. If there is not enough space, open the menu up.
+
+Select the first option when the menu opens.
+
+Move the selection in the menu on pressing the Up and Down arrows or on hovering the cursor over the item.
+
+Filter items in the list on typing:
+
+{width=209}
+
+Close the menu if the user selects an item, clicks outside the menu, presses the Esc key or switches to another app.
+
+Allow single-click activation using mouse: click on a drop-down, the drop-down opens, select an item by hovering,
+close the drop-down with the new item selected by releasing the mouse button.
+
+#### Menu items
+
+Follow the rules for the [drop-down list](drop_down.md#menu-items).
+
+If it’s necessary to configure options in a toolbar drop-down list, add customization actions at the top or at the bottom of the list
+and separate them with a line.
+Use title case capitalization for actions.
+
+{width=201}
+
+A toolbar drop-down list can have submenus.
+
+### Submenu
+
+A submenu is a menu item that shows a list of nested items. A submenu includes a triangular indicator that distinguishes it from other menu items.
+
+Use item submenus to group related options and to show hierarchy:
+
+{width=272}
+
+Show the submenu list on hovering over an item.
+
+If the selection moves with the Up and Down arrow keys, show the submenu list on pressing the Right arrow or the Enter key.
+
+Avoid submenus inside submenus. Submenus hide choices too deep and are difficult to navigate.
+
+## Sizes and placement
+
+Toolbar drop-down sizes are the same for all themes.
+
+{width=181}
+
+The width changes depending on the selected value to save space if the value is short.
+
+{width=169}
+
+For menu sizes see [Drop-down menu](drop_down.md#menu_1).
diff --git a/topics/ui/controls/tooltip.md b/topics/ui/controls/tooltip.md
new file mode 100644
index 000000000..5d08891cd
--- /dev/null
+++ b/topics/ui/controls/tooltip.md
@@ -0,0 +1,322 @@
+
+
+# Tooltip
+
+UI guidelines on using tooltips.
+
+
+
+**Implementation:** [`HelpTooltip`](%gh-ic%/platform/platform-api/src/com/intellij/ide/HelpTooltip.java)
+
+
+
+A tooltip shows an action name or provides useful information about an action or a setting.
+
+{width=174}
+
+## When to use
+
+There are three types of tooltips:
+
+
+
+
+ Action
+ Shows an action name or label for icons and unlabeled controls, and a shortcut if available.
+ |
+
+ 
+ |
+
+
+
+ Action help
+ Shows help text for icons and unlabeled controls in addition to an action name or label.
+ |
+
+ 
+ |
+
+
+
+ Help
+ Shows help text for all other controls.
+ |
+
+ 
+ |
+
+
+
+
+All icons and unlabeled controls should have an **Action** or an **Action help** tooltip.
+
+Use **Action help** and **Help** tooltips according to the [Context help](context_help.md) rules.
+
+## How to use
+
+### Required and optional information
+
+Always show the required information in a tooltip:
+
+
+ | Tooltip |
+ Required info |
+ Optional |
+
+
+ Action
+ 
+ |
+
+ Action name
+ |
+
+ Shortcut
+ |
+
+
+
+ Action help
+ 
+ |
+
+ Action name
+ Help text
+ |
+
+ Shortcut
+ Link
+ |
+
+
+
+ Help
+ 
+ |
+
+ Help text
+ No action name or label because it is already shown in the UI.
+ |
+
+ Shortcut
+ Link
+ |
+
+
+
+
+
+Show a shortcut if an action or a setting has one. Do not show a single shortcut in a tooltip.
+
+{width=230}
+
+Provide a link to a source that can further explain the action or the setting. A link can navigate to a place in the IDE or to an external help article.
+
+| Local link | External link |
+|---------------------------------------------|-------------------------------------------|
+| {width="300"} | {width="300"} |
+
+Do not show just an action name and a link to a help article. Provide help text so that the user does not need to switch to a web browser.
+
+{width=516}
+
+### Text length and formatting
+
+The text width in an action tooltip is not limited. The text width in a help tooltip is limited by 250px.
+
+Show no more than 10 lines of help text. If the text does not fit, leave only the essential information and add a link to a help article.
+
+Incorrect
+
+{width=601}
+
+Correct
+
+{width=601}
+
+Text style formatting:
+
+* Avoid using style formatting in the help text. Usually, the text is short and no bold or italics are needed.
+
+ Incorrect
+
+ {width=461}
+
+ Correct
+
+ {width=461}
+
+* Use formatting for code, console commands or parameters. Use HTML tags. Enclosing the text in `` tags is not needed.
+
+ {width=407 style=block}
+ *Editor breadcrumbs*
+
+* Action name, shortcut and link do not allow HTML tagging.
+
+If the help text is longer than 5 lines, separate the text into paragraphs with the `` tag. The `
` tag adds vertical space between paragraphs to visually separate them. Do not use the `
` tag as it does not add space.
+
+{width=300}
+
+
+
+
+```kotlin
+val LONG_TEXT = """A new overloading method will be created with
+ the new parameter added to this method definition.
+ The method with the old signature will be kept and the call
+ to the new method will be added to it. The necessary value
+ or expression will be passed to the new method call."""
+HelpTooltip().setDescription(LONG_TEXT).installOn(component)
+```
+
+
+
+
+```java
+String LONG_TEXT = "A new overloading method will be created with " +
+ "the new parameter added to this method definition." +
+ "The method with the old signature will be kept and the call " +
+ "to the new method will be added to it. The necessary value " +
+ "or expression will be passed to the new method call.";
+new HelpTooltip().setDescription(LONG_TEXT).installOn(component);
+```
+
+
+
+
+### Writing guidelines
+
+Make the help text [short and descriptive](writing_short.md).
+
+In a help tooltip, do not repeat an action or a setting name in the text.
+
+{width=394}
+
+### Question mark icon for help tooltips
+
+Always use the help tooltip with the question mark icon. Without the icon, it is unclear which component has help information.
+
+Always place the question mark icon to the right of the corresponding UI component.
+
+Examples with different controls:
+
+#### Checkbox
+
+{width=543}
+
+#### Tree item
+
+{width=390}
+
+#### Combo box
+
+{width=467}
+
+#### Group header
+
+{width=409}
+
+#### Settings breadcrumbs
+
+{width=458}
+
+#### Stand-alone button not at the bottom of a dialog
+
+{width=476}
+
+**Exception:** do not use the help tooltip with buttons at a dialog’s bottom.
+Put the information into the help article that is opened with the question mark button in the bottom left corner.
+
+Incorrect
+
+{width=372}
+
+## Style
+
+{width=723}
+
+## Built-in behavior
+
+All tooltips appear on hover (not on click), including the help tooltip with the question mark icon.
+
+All tooltips are hidden when the mouse cursor leaves the area that triggers the tooltip.
+
+If the mouse cursor stays in the tooltip trigger area, tooltips are also hidden after a timeout specified in the table below.
+
+
+
+ |
+ Tooltip
+ |
+
+ Appears after
+ |
+
+ Hides after
+ If cursor is in the tooltip trigger area
+ |
+
+
+ |
+ Action
+ |
+
+ 300 milliseconds
+ ide.tooltip.initialReshowDelay registry key
+ |
+
+ 10 seconds
+ ide.helptooltip.regular.dismissDelay
+ |
+
+
+ |
+ Action help
+ |
+
+ |
+
+ 30 seconds
+ ide.helptooltip.full.dismissDelay
+ |
+
+
+ |
+ Help
+ |
+
+ |
+
+ Never hides
+ |
+
+
+
+
+If a tooltip has a link, it is possible to move the mouse cursor over the tooltip. The tooltip does not close automatically when the cursor is over it.
+
+Tooltips are positioned automatically depending on the mouse cursor location.
+
diff --git a/topics/ui/principles/context_help.md b/topics/ui/principles/context_help.md
new file mode 100644
index 000000000..a90f96df7
--- /dev/null
+++ b/topics/ui/principles/context_help.md
@@ -0,0 +1,97 @@
+
+
+# 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 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.
+
+{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.
+
+ {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.
+
+ {width=734}
+
+* The control that needs explanation is an icon or does not have a label.
+
+ {width=305}
+
+## When to use context help
+
+Explain complex behavior that a short action or a setting name cannot convey clearly.
+
+{width=543}
+
+{width=380}
+
+Explain IDE-specific entities.
+
+{width=300}
+
+Provide input format requirements and examples.
+
+{width=478}
+
+Suggest alternative ways.
+
+{width=418}
+
+Warn about possible problems.
+
+{width=361}
+
+Explain limitations.
+
+{width=432}
+
+Provide quick navigation to related settings.
+
+{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.
+
+Incorrect
+
+{width=418}
+
+Do not explain common actions and entities. Show a regular tooltip with an action name and shortcut in this case.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width=300} | {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.
+
+Incorrect
+
+{width=317}
+
+## How to use
+
+See [Inline help text](inline_help_text.md) and [Tooltip](tooltip.md).
+
diff --git a/topics/ui/principles/data_formats.md b/topics/ui/principles/data_formats.md
new file mode 100644
index 000000000..05cd6c778
--- /dev/null
+++ b/topics/ui/principles/data_formats.md
@@ -0,0 +1,236 @@
+
+
+
+
+**Related:** [](ui_faq.md#text)
+
+
+
+# Data Formats
+
+Choosing proper date formats to display data to users.
+
+## Numbers
+
+> If there is a space between the number and the unit, use a non-breaking space.
+>
+{style="note"}
+
+
+
+ |
+ Example |
+ When and how to use |
+
+
+ | Numbers |
+ 4,255,165.00 |
+ Space is not limited, e.g. Settings dialog
+ 
+ |
+
+
+ | Numbers short |
+ 10.5k
+ 3.3M
+ |
+ Space is limited, e.g. in table or lists |
+
+
+ | Percentage |
+ 13% |
+ |
+
+
+ | Ratios |
+ 3 of 10 |
+ |
+
+
+ | Ratios short |
+ 3/10 |
+ Space is limited, e.g. in table or lists |
+
+
+ | Currency |
+ $10 |
+ |
+
+
+
+## Date and time
+
+By default, the date and time formats are taken from the system settings. The format can be changed on the Settings | Appearance & Behavior | System Settings | Date Formats page.
+
+See the table below to understand in which cases to show date and time.
+
+
+ |
+ Example |
+ When and how to use |
+
+ | Date |
+ Today
+ 05 Jan
+ 05 Jan 2017
+ |
+ Omit the time for events if the exact time does not matter, e.g., Annotate panel
+ Use Today and Yesterday for the last two days, use exact date for all other days
+ Do not show the year if it’s within the current calendar year
+ |
+
+
+ | Date and time |
+ Today, 14:04
+ 05 Jan, 14:04
+ 05 Jan 2019, 14:04
+ |
+ When it is important to know the exact sequence of actions, e.g., Version Control Log |
+
+
+ | Time |
+ 22:49 |
+ Omit date if the event happened today and it’s clear from the context |
+
+
+ | Date and day of week |
+ Tuesday, 30 August |
+ Use as headers in timelines, e.g., Event Log. The day of the week helps to quickly understand how long ago was the event
+ Use Today and Yesterday for the last two days, use exact date for all other days
+ |
+
+
+ | Approximate time |
+ A moment ago
+ 10 minutes ago
+ 2 hours ago
+ |
+ Use for a single event that happened recently, e.g., in the Status bar:
+ 
+ Do not use in tables as it’s harder to compare.
+ If more than 12 hours have passed since the event, use Date format
+ |
+
+
+
+{width=1053 style=block}
+*Version Control Log (in IntelliJ IDEA incorrect format is used at the moment)*
+
+{width=1053 style=block}
+*Event Log*
+
+## Duration
+
+
+
+ |
+ Example |
+ When and how to use |
+
+
+ | Period |
+ 10 milliseconds
+ 10 seconds
+ 10 minutes
+ 1 hour
+ |
+ Space is not limited, e.g. Settings dialog
+ 
+ |
+
+
+ | Time-lapse |
+ 1 h 30 m 30 s
+ 1 h 30 m 30.035 s
+ 1 h
+ 1 h 0 m 30 s
+ 1 m 30 s
+ 05 Jan 2019, 14:04
+ |
+ Use for changing duration. Select units depending on the process type. E.g., Unit tests usually run less than a minute, so show only seconds and milliseconds. Build tasks usually run more than a minute, so show minutes and seconds.
+ Omit hours and seconds that do not provide additional data
+ |
+
+
+ | Time-lapse condensed ISO 8601 standard |
+ 1:30:01.350 |
+ Use when space is limited or to describe a range, e.g. 1:30:01.350 – 1:30:02.350 |
+
+
+
+
+{width=518}
+
+## Quantities of data
+
+Use decimal numeral system.
+
+
+
+ | bits |
+ 10 bits |
+
+
+ | bytes |
+ 10 B |
+
+
+ | kilobytes |
+ 10 KB |
+
+
+ | megabytes |
+ 10 MB |
+
+
+ | gigabytes |
+ 10 GB |
+
+
+ | terabytes |
+ 10 TB |
+
+
+
+{width=511}
+
+## Units
+
+All numeric values should be given a unit or clearly labeled if they do not have suitable units, e.g. counters.
+
+{width=242}
+
+{width=264}
+
+Select the most convenient units.
+
+| Incorrect | Correct |
+|---------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
+| {width="284"} | {width="259"} |
+
+Place units after the input field.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="196"} | {width="242"} |
+
+## Tables
+
+Use the rules below to make it easier to compare numbers in one column.
+
+Right-align numeric values.
+
+{width=299}
+
+Include the unit in the column header if all values share the same unit. Convert each number to use the same unit.
+If it’s not possible, e.g., the scatter of numbers is too large, include the unit with each value.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="110"} | {width="110"} |
+
+Be consistent with the precision of the significand.
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="110"} | {width="110"} |
diff --git a/topics/ui/principles/empty_state.md b/topics/ui/principles/empty_state.md
new file mode 100644
index 000000000..3fd7f8132
--- /dev/null
+++ b/topics/ui/principles/empty_state.md
@@ -0,0 +1,146 @@
+
+
+# Empty State
+
+Providing instructions in an empty UI area on how to fill it with data.
+
+
+
+**Implementation:** [`ComponentWithEmptyText`](%gh-ic%/platform/platform-api/src/com/intellij/util/ui/ComponentWithEmptyText.java)
+
+
+
+Provide instructions in an empty UI area on how to fill it with data. Empty UI areas described here are:
+
+* [Tool window, list, tree or table](#tool-windows-lists-trees-and-tables)
+* [Details area in a master-detail layout](#master-detail-layout)
+* Empty search results — TBD
+
+## Tool windows, lists, trees and tables
+
+Instructional text for these UI areas consists of three parts:
+
+{width=626}
+
+### 1. Reason why empty
+
+Explain the current state.
+
+The default pattern is "_No [entity] added._" If _added, created, configured_ or other such verbs act as synonyms in a particular case, use the verb _added_ for consistency.
+
+| Incorrect | Correct |
+|-------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
+| {width="241"} Avoid "Nothing to show" as it is not informative. | {width="241"} |
+
+Make the reason descriptive:
+
+Incorrect
+
+{width=456 style=block}
+*The word mapping introduces a new entity while there are already two in the table header — path and SQL dialect. In the instructions, it is better to use already existing entities to connect them to what users see on the screen.*
+
+Correct
+
+{width=456 style=block}
+*The word "individual" is used in contrast with the project SQL dialect above the table. The verb specified is used instead of added because, in the table, SQL dialects are not added but selected from a drop-down list in the SQL Dialect column.*
+
+### 2. Actions to fill the area
+
+Required part. An action makes it easier to understand what to start with, instead of searching for the appropriate icon on the toolbar. It can also educate about the shortcut.
+
+Use one or two actions. Three or more actions would make it harder to choose what to start from.
+
+{width=300}
+
+If an action opens a menu, open it at the same position where it would be opened with the corresponding toolbar button. This would explain which toolbar icon opens the menu.
+
+If an action cannot be tied to a link, explain what to do.
+
+{width=574}
+
+Hide the area's toolbar if it does not have the same action as in the empty state. Usually, all other toolbar actions are not relevant in this case.
+
+Incorrect
+
+{width=574}
+
+### 3. Help topic
+
+**Tool windows:** provide a link to a help topic that explains the functionality. Add the question mark icon in the beginning.
+
+{width=262}
+
+**Tables, trees and lists:** provide instructions according to the [Context help](context_help.md) rules. Smaller UI areas rarely require an in-depth explanation compared to complex tool windows. A short help text should be enough, and it does not require switching contexts.
+
+Incorrect
+
+{width=456 style=block}
+*Do not use a help topic link in a table and UI areas other than tool windows.*
+
+Correct
+
+{width=456 style=block}
+*Place an inline help text under the table.*
+
+### Writing guidelines
+
+See [Punctuation](punctuation.md) and [Capitalization](capitalization.md).
+
+Make the reason text short and descriptive. See [Writing short and clear](writing_short.md).
+
+In actions, avoid words that describe physical actions like _press_ or _click_ — they are obvious from how the link works.
+
+Avoid saying _add new_. Just use _add_ because all that is added is new in the context of an empty UI area.
+
+## Master-detail layout
+
+Provide only the action part for the detail area in a master-detail layout. The detail area is filled when an item is selected in the master part. This behavior is obvious and does not need to be explained.
+
+The default pattern for the action is "_Select_ [entity] _to configure_".
+
+The master area is usually a list or a tree, its empty state instructions should follow the guidelines for lists and trees.
+
+{width=586}
+
+{width=720 style=block}
+*The "Add Java application configuration" link is a shortcut to creating a new configuration instead of clicking the + button in the toolbar.*
+
+## Sizes and placement
+
+The minimum text width is 40 characters. If an area is too narrow to show the minimum text width, show text in area fields, and if no fields are left, under the area borders.
+
+Use non-breaking spaces in an action name and shortcut, so it is not split into two lines.
+
+Use non-breaking spaces for articles and prepositions in the instructional text.
+
+Incorrect
+
+{width=379}
+
+Correct
+
+{width=379}
+
+The text is center-aligned. If possible, the center for the help topic link should be calculated with a 16px inset on the left. This helps visually align the help link with the lines above it.
+
+{width=300}
+
+Fields and vertical spaces:
+
+{width=530}
+
+The text should wrap when a UI area’s width changes:
+
+{width=579}
+
+{width=300}
+
+## Style
+
+The link should not be underlined.
+
+In Darcula:
+
+{width=300}
+
+
diff --git a/topics/ui/principles/groups_of_controls.md b/topics/ui/principles/groups_of_controls.md
new file mode 100644
index 000000000..6d4c5bbf3
--- /dev/null
+++ b/topics/ui/principles/groups_of_controls.md
@@ -0,0 +1,42 @@
+
+
+# Groups of Controls
+
+Grouping content to help users locate the necessary controls faster.
+
+Group controls to organize content on a screen and help people locate the necessary controls faster.
+
+Use the following controls or layouts:
+
+* [Group headers](group_header.md)
+* [Tabs](tabs.md)
+* Master-detail layout
+
+## What grouping to choose
+
+Use **group headers** if all rules apply:
+
+> If there are less than 3 controls in all groups, consider separating with [vertical insets](group_header.md#how-to-use).
+>
+{style="note"}
+
+* Each group contains **no** more than 10 controls
+
+* All groups occupy no more than 2 heights of the dialog in its default size
+
+{width=396}
+
+Use **tabs** if all rules apply:
+
+* One of the groups contains more than 10 controls, or groups occupy more than 2 heights of a dialog
+* There are **no** more than 8 groups
+
+{width=565}
+
+Use the **master-detail layout** if either of the rules applies:
+
+* There are more than 8 groups
+* The number of groups can change
+
+{width=565}
+
diff --git a/topics/ui/principles/icons_style.md b/topics/ui/principles/icons_style.md
new file mode 100644
index 000000000..fc039164c
--- /dev/null
+++ b/topics/ui/principles/icons_style.md
@@ -0,0 +1,527 @@
+
+
+# Icons
+
+Guidelines on designing and creating icons.
+
+Follow these guidelines to create a new icon or redesign an existing one for IntelliJ-based products.
+
+> See all icons in the [Icons list](https://intellij-icons.jetbrains.design).
+> Use the [IntelliJ Icons Figma plugin](https://www.figma.com/community/plugin/948276470997072333/IntelliJ-Icons)
+> to quickly find and use icons in UI mockups.
+>
+{style="note"}
+
+## Style
+
+A common style unites several icons into a set and makes them recognizable.
+
+Use a flat geometric icon style with straight corners and edges. Flat icons remain legible even in small sizes.
+
+Use flat shapes instead of complex 3D forms:
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="190"} | {width="190"} |
+
+Use straight corners and lines instead of curves. It’s recommended to use 45° and 90° angles, or 30° and 60° where possible:
+
+| Incorrect | Correct |
+|-----------------------------------------------------|-----------------------------------------------------|
+| {width="144"} | {width="144"} |
+
+Icons should be as simple as possible without losing their meaning. Clean and simple icons ensure readability and reduce visual clutter.
+
+
+
+ | Incorrect |
+ Correct |
+
+
+  |
+  |
+
+
+ | Reduced the icon to its minimal form, without losing its meaning. |
+
+
+
+## Grid and size
+
+Basically, icons fit into a square artboard. Leave a transparent padding around the perimeter. For default 16px icons, the transparent border is 1px, so the icon’s visible part should be inside the 14px x 14px area.
+
+{width=251 style=block}
+*14px x 14px is the area where the visible part of the icon should fit for a 16px icon.*
+
+Content should only go beyond the borders if a [modifier](#modifier) is added, or if additional visual weight is required.
+
+Sizes for other icon sizes can be found in the table below:
+
+
+
+| Icon Type |
+ Icons Size |
+ Transparent Border |
+
+ | Gutter, status bar |
+ 12px x 12px |
+ — |
+
+
+ | Tool window |
+ 13px x 13px |
+ — |
+
+
+ | Default: toolbar icons, project tree, etc. |
+ 16px x 16px |
+ 1px, except for modifier |
+
+
+ | Dialogs |
+ 32px x 32px |
+ 2px |
+
+
+ | Logo app icon |
+ 32px x 32px
64px x 64px
128px x 128px
256px x 256px
512px x 512px |
+ — |
+
+
+
+## Basic shapes
+
+Use basic shapes to build icons, such as squares, circles and rectangles. Using a grid and basic shapes ensures consistent visual proportions and placement.
+
+| {width="192"} _Square 12px x 12px_ | {width="195"} _Circle 14px_ |
+|--------------------------------------------------------------------------------|----------------------------------------------------------------------------|
+| {width="192"} _Horizontal rectangle 10px x 14px_ | {width="192"} _Vertical rectangle 14px x 10px_ |
+
+{style=none}
+
+Make sure that icons have the same visual weight. The more filled an icon is, the less space it needs. Following this rule, circles, rhombuses, triangles and other non-square shapes should have larger height and width to be optically balanced with square figures.
+
+{width=542 style=block}
+*Make the circle diameter 2px bigger than square icons’ height to compensate for the visual weight.*
+
+Icons with more details should occupy more space.
+
+{width=542 style=block}
+*The eye icon is less detailed and occupies less space than a more complex scissors icon.*
+
+Icon weight can often take priority over the basic shape sizing. For more examples on visual weight compensation, see [Optical Effects in User Interfaces](https://medium.muz.li/optical-effects-9fca82b4cd9a).
+
+## Stroke
+
+Use a 2px stroke as the main drawing line. Consistent line weight makes icons cohesive.
+
+
+
+  |
+  |
+
+
+ | Use consistent stroke width. |
+ A thinner stroke can be used for subtle tweaks to the legibility of an icon and for optical correction. |
+
+
+
+Align pixels on the X and Y axis and round to the nearest whole pixel, or 0.5px if it’s not possible to align to integer pixels. Aligning icons off the pixel grid will make the icon blurry when it’s rasterized.
+
+> To check what an icon will look like when rasterized use the View | Canvas | Show Pixels on Zoom option Ctrl+P in Sketch,
+> View | Pixel Preview Alt+Ctrl+Y in Illustrator.
+>
+{style="note"}
+
+
+
+ | Incorrect |
+ Correct |
+
+
+ 
+ If an icon is positioned off pixels,
it becomes blurry when rasterized. |
+ 
+ Position stokes on integer pixels where possible. |
+
+
+
+Use the 30°, 45° and 60° angles for diagonal lines as they look sharper than diagonals with other angles.
+
+Round shapes, small details and some letters cannot be aligned to the pixel grid. Make sure that the significant pixels have sufficient saturation.
+
+Reduce the number of anchors as they increase the size of the image and takes longer to process it.
+
+
+
+ | Incorrect |
+ Correct |
+
+
+ 
+ Unneeded anchors are added. |
+ 
+ Use the minimum number of anchors. |
+
+
+
+## Modifier
+
+A modifier is a small shape added over the base icon.
+
+The default modifier position is the bottom right corner. If the base shape is badly recognizable with a modifier in the bottom right corner, or if several modifiers are needed, the modifier can be placed in other corners.
+
+
+
+ 
+ Place the modifier in the left corner
if the base shape is badly recognizable
with the modifier in the right corner. |
+ 
+ Place the modifier in the left corner
if there are several modifiers. |
+
+
+
+A modifier size is from 6px to 9px, depending on the shape's weight.
+Leave a 1-2px spacing between the modifier and the main shape, to make the modifier clearly visible.
+
+{width=577 style=block}
+*Modifier sizes*
+
+## Arrows
+
+General rules for arrows: arrowhead is a filled triangle with a 90° pointing angle, a 2px body ends in a square stroke. An arrow’s orientation is horizontal, vertical, 45° or round.
+
+{width=515 style=block}
+*Basic arrow icons*
+
+Unfilled arrowhead can be used if there is only one arrow on an icon to reduce excessive visual weight, for example, for navigation arrows, such as back and forward, up and down.
+
+
+
+  |
+  |
+
+
+ | 90° arrowhead and 2px square stroke body. |
+ Back arrow with unfilled arrowhead to compensate visual weight. |
+
+
+
+Do **not** use other arrow styles, for example, unfilled arrows or arrows with thinned tails.
+
+Incorrect
+
+{width=510}
+
+## Color
+
+Do not use color as the only differentiator between icons (except for the [Noun icon](#noun-icons)) because some people do not distinguish colors. Make sure that icons are easily distinguishable by their shape.
+
+Do not use gradients or shadows.
+
+### Action icons
+
+An action icon is an icon that triggers an action. It usually appears on toolbars and in dialogs.
+There are 5 colors in the action icons palette.
+The dark version is for Darcula theme.
+
+[//]: # (Download a Sketch file with the color palette.)
+
+[//]: # (FIXME: colors are wrong, dark are rendered)
+
+
+
+
+ 
+
+ Red #DB5860
+ |
+
+ 
+
+ Red dark #C75450
+ |
+
+
+
+ 
+
+ Yellow #EDA200
+ |
+
+ 
+
+ Yellow dark #F0A732
+ |
+
+
+
+ 
+
+ Green #59A869
+ |
+
+ 
+
+ Green dark #499C54
+ |
+
+
+
+ 
+
+ Blue #389FD6
+ |
+
+ 
+
+ Blue dark #3592C4
+ |
+
+
+
+ 
+
+ Grey #6E6E6E
+ |
+
+ 
+
+ Grey dark #AFB1B3
+ |
+
+
+
+
+Use these colors according to the following rules:
+
+1. By default, action icons are grey and monochromatic:
+
+ {width=319}
+
+2. If an icon falls into one of the categories below, use the corresponding color:
+
+
+
+ | Green Positive actions: run, create
 |
+ Red Destructive actions: stop, remove, force
 |
+
+
+ | Blue Accent color to highlight popular icons based on usage statistics, highlight small elements in complex icons
 |
+ Yellow Warning actions: attract attention to the places (e.g., code) that can be optimized or improved
 |
+
+
+
+3. Preserve colors in icon combinations. If an icon is colored in its full size, it should have the same color when reduced.
+
+ {width=248}
+
+4. Use green and red colors for paired icons. Color helps distinguish between similar icons faster.
+
+ {width=233}
+
+5. Use grey color for tool window icons. Icons are placed on the perimeter of the IDE, so they should not attract too much attention and distract users.
+
+ {width=750}
+
+### Status icons
+
+Color is a great way to provide status information. Use status icons that are already present in the IDE repository:
+
+{width=308}
+
+If you need a new icon, color it according to its semantics. Make sure that the status icons are easily distinguishable by their form, as many colorblind people find it difficult to distinguish between red and green.
+
+### Noun icons
+
+A noun icon is an icon that appears in the tree view to mark different file types. It helps to locate items in the list faster and does not trigger an action.
+
+The palette for noun icons is wider, because there are lots of icons in one set:
+
+
+
+
+ 
+
+ Grey #9AA7B0
+ |
+
+ 
+
+ Grey 80% #9AA7B0 op. 80%
+ |
+
+ 
+
+ Grey 60% #9AA7B0 op. 60%
+ |
+
+
+
+ 
+
+ Blue #40B6E0
+ |
+
+ 
+
+ Blue 70% #40B6E0 op. 70%
+ |
+
+ 
+
+ Blue 60% #40B6E0 op. 60%
+ |
+
+
+
+ 
+
+ Green #62B543
+ |
+
+ 
+
+ Green 70% #62B543 op. 70%
+ |
+
+ 
+
+ Green 60% #62B543 op. 60%
+ |
+
+
+
+ 
+
+ Yellow #F4AF3D
+ |
+
+ 
+
+ Yellow 70% #F4AF3D op. 70%
+ |
+
+ 
+
+ Yellow 60% #F4AF3D op. 60%
+ |
+
+
+
+ 
+
+ Purple #B99BF8
+ |
+
+ 
+
+ Purple 70% #B99BF8 op. 70%
+ |
+
+ 
+
+ Purple 60% #B99BF8 op. 60%
+ |
+
+
+
+ 
+
+ Pink #F98B9E
+ |
+
+ 
+
+ Pink 70% #F98B9E op. 70%
+ |
+
+ 
+
+ Pink 60% #F98B9E op. 60%
+ |
+
+
+
+ 
+
+ Red #F26522
+ |
+
+ 
+
+ Red 70% #F26522 op. 70%
+ |
+
+ 
+
+ Red 60% #F26522 op. 60%
+ |
+
+
+
+ 
+
+ Red status #E05555
+ |
+
+ 
+
+ Red status 70% #E05555 op. 70%
+ |
+
+
+
+ 
+
+ Yellow dark #D9A343
+ |
+
+
+
+ 
+
+ Green Android #A4C639
+ |
+
+
+
+ 
+
+ Black text #231F20 op. 70%
+ |
+
+
+
+Select colors for new icons based on existing colors and users’ habits.
+
+Use colors with 60% opacity and grey 80% for big parts, like folder icons:
+
+{width=86}
+
+Transparent icons are used in both light and dark themes, so in most cases there’s only one version.
+
+Use colors with 70% opacity for medium size elements that occupy about half of an icon, like file type icons:
+
+{width=111}
+
+Use colors without opacity for small elements, like modifiers.
+
+{width=87}
+
+## Font
+
+To make a new icon with a letter, reuse letters from existing icons. If there's no suitable letter in existing icons, use a common sans-serif font like Arial or Open Sans.
+
+## Export Icons
+
+> Install the [Svgo-compressor plugin](https://www.sketchapp.com/extensions/plugins/svgo-compressor/) in Sketch to optimize icons before save.
+>
+{style="note"}
+
+Use the SVG format for icons files. Use camelCase capitalization for icon names:
+
+iconName.svg
+
+If an icon is not the same in the dark theme, then also create:
+
+iconName_dark.svg
diff --git a/topics/ui/principles/layout.md b/topics/ui/principles/layout.md
new file mode 100644
index 000000000..e8e02d0a9
--- /dev/null
+++ b/topics/ui/principles/layout.md
@@ -0,0 +1,234 @@
+
+
+# Layout
+
+UI guidelines on laying out the controls in dialogs.
+
+Arrange UI controls in dialogs according to the rules below to help people locate the necessary settings faster and understand how they are related.
+
+Independent controls:
+
+- [Labeled input controls](#labeled-input-controls): fields, combo boxes, text areas, etc.
+- [Checkboxes and radio buttons](#checkboxes-and-radio-buttons)
+- [Buttons and links](#buttons-and-links)
+- [Lists, trees, tables](#lists-trees-and-tables)
+
+[Dependent controls ](#dependent-controls)— controls that depend on a parent control.
+
+Organize controls into easily readable groups with [vertical and horizontal insets](layout.md#organize-with-insets).
+
+[//]: # (TODO: See [Dialog window](dialog_window.md) for buttons and other controls at the bottom of a dialog.)
+
+## Independent controls
+
+### Labeled input controls
+
+Labeled input controls are: [input field](input_field.md), [combo box](combo_box.md), [drop-down list](drop_down.md), [text area](text_area.md), and spinner.
+
+By default, put input controls with labels of similar length on different lines and align their input boxes on the left side.
+
+{width=391}
+
+Do **not** align input boxes on the left side if one label is twice as long as the other one or even longer.
+
+{width=391}
+
+{width=391}
+
+If several related input controls have labels of up to 10 characters and their input boxes are short, organize them in two columns. Do **not** use more than two columns.
+
+{width=391}
+
+If an input box is long, and the horizontal space is limited, place the label above the box. Otherwise, always put the label and the box on the same line.
+
+{width=412}
+
+#### Separated by other controls
+
+If there are two input controls with labels of similar length that are separated from each other by a single control, align their input boxes on the left side.
+
+{width=452}
+
+Align only the input boxes of the neighboring input controls. If there are several input controls on a page, and they are separated from each other by two or more other UI elements, do **not** align their input boxes.
+
+{width=452}
+
+If input groups are separated by a group of other UI controls, align only the boxes located within one group.
+
+{width=616}
+
+#### Labels and right borders
+
+Always left-align labels.
+
+> This alignment is inconsistent with macOS guidelines, but the aim is to maintain consistency in all JetBrains IDEs on all supported platforms.
+>
+{style="note"}
+
+{width=464}
+
+Align the right borders of input boxes that have a similar length. For alignment, use [built-in icons](built_in_button.md). Do **not** use buttons.
+
+{width=302}
+
+### Checkboxes and radio buttons
+
+By default, put independent checkboxes and radio button groups on different lines.
+
+{width=358}
+
+If there is a group of 2–3 checkboxes with short labels (1–3 words), place them on the same line.
+The same rule applies to radio buttons.
+With this alignment, controls form a short sentence, making it easier to understand their meaning compared to when they are split into several lines.
+
+{width=358}
+
+When there is an input control on one line and a group of checkboxes or radio buttons on the next line, and their labels are of similar length
+(one is no more than 5 characters longer than the other), align the input box with the checkbox/radio button.
+
+If one label is much longer than the other, do **not** align these UI elements.
+
+{width=461}
+
+If a checkbox group does not have a label, align it with other independent controls by the left side.
+
+{width=417}
+
+4 and more checkboxes can be arranged in columns:
+
+* Arrange checkboxes with labels of up to 30 characters in 2 columns.
+
+{width=417}
+
+* Arrange checkboxes with labels of up to 15 characters in 3 columns.
+
+{width=417}
+
+Do **not** arrange radio buttons from one group in several columns. Splitting a group of radio buttons into two or more columns makes it unclear that all these radio buttons belong to the same setting.
+
+{width=417}
+
+### Buttons and links
+
+Align an independent button or link to the left with other controls.
+
+{width=361}
+
+{width=361}
+
+If there are 2–3 buttons or links with labels of up to 30 characters each, place them on one line.
+
+{width=361}
+
+Do **not** arrange buttons or links in several columns. Such a layout takes more time to parse visually.
+
+{width=361}
+
+### Lists, trees and tables
+
+Choose a control width such that most of the common values are visible. Take the whole width of the dialog if necessary.
+
+{width=638}
+
+If the dialog containing the control is noticeably wider than the control itself, reduce the length of the control.
+
+Do **not** put other independent controls to the right of a list, tree, or table.
+They would look like dependent controls in the master-detail layout.
+
+{width=638}
+
+If there are several lists, trees, or tables in a dialog, make them of the same width.
+
+{width=452}
+
+## Dependent controls
+
+Align controls according to the rules below to show that they are related.
+
+Place 2–3 related UI controls on the same line if each control takes up to 30 characters. This way the user needs to read just one line, and it is quicker to see that the controls depend on each other.
+
+{width=497}
+
+In all other cases, place interrelated controls on different lines:
+
+Main control: **labeled input control**.
+
+* Align other dependent elements with the left border of the input box.
+
+{width=281}
+
+{width=281}
+
+* If an input's label is long or the input box is very short, align by the label and add a horizontal inset.
+
+{width=489}
+
+Main control: **checkbox** or **radio button**. Align dependent controls by the label.
+
+{width=342}
+
+When the main control or one of the dependent controls takes the whole width of a panel, left align all elements.
+
+{width=475 style=block}
+*The text area is the main control, the button is the dependent control.*
+
+{width=475 style=block}
+*The checkbox is the main control, the table is the dependent control.*
+
+When the main control takes the whole width of a panel, and there is one small dependent control (for example, a drop-down list), place this dependent control to the top-right corner, above the main control.
+
+{width=475}
+
+[//]: # (TODO: See [Master-detail layout](masterdetail_layout.md) for more information on how to lay out controls if they depend on lists or trees.)
+
+See the [Inline help text](inline_help_text.md#placement) and [Tooltip](tooltip.md#question-mark-icon-for-help-tooltips) articles for details on how to arrange help information in dialogs.
+
+If controls do **not** depend on each other, left-align them all. Otherwise, the user might think that controls are linked.
+
+{width=517 style=block}
+*The spinners do not depend on the top checkbox.*
+
+## Organize with insets
+
+Use vertical insets to break a list of controls into easily readable groups. Compare:
+
+Incorrect
+
+{width=396 style=block}
+*The list of controls is hard to scan quickly because the controls "stick" together.*
+
+Correct
+
+{width=396 style=block}
+*Scanning a list of controls becomes easier when vertical insets are added between the groups of controls.*
+
+Treat insets with extra care and make sure that elements within a group are actually related. An unnecessary inset may create a false impression that the controls are grouped. This complicates the UI and might cause confusion.
+
+Incorrect
+
+{width=396 style=block}
+*The first checkbox depends on the combo box which is shown with the horizontal inset. However, the checkboxes appear grouped because they are closer.*
+
+Correct
+
+{width=396 style=block}
+*The first checkbox is closer to its main control, and it is easier to see that the combo box and checkbox are related.*
+
+Horizontal insets also matter for grouping controls.
+
+Incorrect
+
+{width=396 style=block}
+*The checkboxes and the "Length" fields look independent because the horizontal inset between them is bigger than the vertical inset below the second checkbox.*
+
+Better
+
+{width=396 style=block}
+*With smaller horizontal and bigger vertical insets, the checkboxes and the "Length" fields look related. However, it could be made better if the repeating word "Separator" appears only once.*
+
+Correct
+
+{width=396 style=block}
+*Correct grouping and no duplicates help understand the UI quicker.*
+
+See [Groups of controls](groups_of_controls.md) for how to organize a bigger group of controls.
diff --git a/topics/ui/principles/mnemonics.md b/topics/ui/principles/mnemonics.md
new file mode 100644
index 000000000..2d77fef3d
--- /dev/null
+++ b/topics/ui/principles/mnemonics.md
@@ -0,0 +1,72 @@
+
+
+# Mnemonics
+
+Guidelines on using mnemonics.
+
+A mnemonic is an alphanumeric character, which indicates the key to press to activate a command or navigate to a component.
+
+There are *regular* and *numeric* mnemonics.
+
+* Regular mnemonics are used inside the text. The mnemonic is underlined in this case to be distinguishable.
+
+ In a control:
+
+ {width=264}
+
+ In a menu:
+
+ {width=288}
+
+ Activate the control by pressing the mnemonic with:
+
+ * Alt modifier key on Windows/Linux
+
+ * Ctrl+Alt modifier keys on macOS.
+
+* Numeric mnemonics are used as the first numeric character of an action in a popup:
+
+ {width=373 style=block}
+ *Invoke the action by pressing the corresponding number key.*
+
+## When to use
+
+Specify mnemonics wherever possible in menus and controls. Mnemonics make the functionality more usable for power users who interact through the keyboard. Moreover, mnemonics make the functionality accessible for users with disabilities.
+
+If there are many actions and/or controls, and it is not possible to assign mnemonics for all of them:
+
+* Provide mnemonics for the most frequently used actions/controls.
+
+* Provide mnemonics for [group headers](group_header.md) for quick navigation to the first element of the group.
+
+Note: The rules for using numeric mnemonics in popups are under discussion. [Contact us](https://youtrack.jetbrains.com/issues/IJSDK) if you have questions.
+
+## How to use
+
+{width=555}
+
+Make mnemonics in the label discoverable, they must be easy to find:
+
+* Use letters at the beginning of the first or second word of the label.
+
+* Use letters with wide widths, such as w, m, and capital letters.
+
+* Avoid using letters that are difficult to see when they are assigned to underlined keys. These letters include:
+
+ * Letters with descenders, such as g, j, p, q, or y.
+
+ * Letters next to a letter with a descender.
+
+ * Letters that are only one pixel wide, such as i or l.
+
+Make it easy to remember for the most frequently used actions:
+
+* Use standard Windows mnemonic if any. For example, Properties, Rename, Delete, Cut, Copy, Paste, Exit, etc.
+ Note that Windows users are more likely to form habits for mnemonics as mnemonics are not that common on macOS or Linux.
+
+* Do **not** use silent letters. For example, Design, Column, etc.
+
+Do **not** assign mnemonics to the default or Cancel buttons. The default button is typically assigned to the ENTER key, and Cancel is assigned to the ESC key.
+
+Do **not** use the same mnemonic letter twice in the same window; duplicated mnemonics confuse users. If you need to assign a new mnemonic in an existing context, check that it's not already taken. If it is, prioritize the mnemonic for the more frequently used action.
+
diff --git a/topics/ui/principles/platform_theme_colors.md b/topics/ui/principles/platform_theme_colors.md
new file mode 100644
index 000000000..07ea19323
--- /dev/null
+++ b/topics/ui/principles/platform_theme_colors.md
@@ -0,0 +1,100 @@
+
+
+# Platform Theme Colors
+
+Guidelines on working with themes.
+
+There are two default color themes: IntelliJ Light and Darcula.
+
+{width=689}
+
+Use the colors consistently within the default themes. To do so, follow these guidelines:
+
+* [Icons](icons.md)
+* UI components
+* Editor scheme TBD
+* Chart TBD
+
+## UI components
+
+Colors for UI components are specified with **color keys**.
+A color key is a name of a color property in a particular component, e.g. `ComboBox.background`, or a generic color property for several components, e.g. `Component.borderColor`.
+
+{width=735}
+
+*Color keys of a combo box*
+
+Each key has two default color values: one for IntelliJ Light and another for Darcula. Example: `ComboBox.background` is #FFFFFF in IntelliJ Light and #3C3F41 in Darcula.
+
+Keys allow creating [custom color themes](themes_getting_started.md). A custom theme is one of the default themes plus a set of color keys with new values in a JSON file. Example: the High contrast theme is a custom theme based on Darcula. New color values are stored in the [`HighContrast.theme.json`](%gh-ic%/platform/platform-resources/src/themes/HighContrast.theme.json) JSON file.
+
+See custom themes in the plugins repository.
+
+See the meanings of the parts in a color key in the [key naming scheme](themes_metadata.md#key-naming-scheme).
+
+See a complete list of keys with their descriptions in the JSON files: [`IntelliJPlatform.themeMetadata.json`](%gh-ic%/platform/platform-resources/src/themes/metadata/IntelliJPlatform.themeMetadata.json), [`JDK.themeMetadata.json`](%gh-ic%/platform/platform-resources/src/themes/metadata/JDK.themeMetadata.json).
+
+See the color values for the currently selected theme in the LaF Defaults dialog:
+
+> To store color values between theme switching, use a scratch *.theme.json file.
+> This might be useful if you want to test colors before implementing them.
+> See guidelines for the [Theme JSON Structure](themes_customize.md#defining-named-colors).
+
+* The dialog is available in the [internal mode](enabling_internal.md). See Tools | Internal Actions | UI in the main menu or find it with Help | Find Action.
+* Some color keys are not shown in the dialog by default because they are loaded at runtime with a corresponding UI component. Open the UI with this component to see such keys in the dialog.
+* Edit a color in the dialog to preview it in the IDE. The edited color is stored until the theme is switched.
+
+{width=641}
+
+> For IntelliJ designers:
+> * Provide color keys in design specifications to be sure that correct keys are used.
+> * When a new key is implemented, check that [`IntelliJPlatform.themeMetadata.json`](%gh-ic%/platform/platform-resources/src/themes/metadata/IntelliJPlatform.themeMetadata.json) has the new key with the `since` parameter and description, and the old keys are deprecated.
+>
+{style="note"}
+
+If a color is needed:
+
+1. Choose a color value for all default themes:
+
+* Try reusing any of the existing colors first. Use the LaF Defaults dialog to see the existing colors.
+* If none of them fit, choose two new color values that are consistent with IntelliJ Light and Darcula palettes in hue and contrast.
+
+2. Choose a color key if a component does not have it:
+
+* Use an existing color key if it fits semantically. Otherwise, a UI component might get an unexpected color in a custom color theme.
+* Create a new key if none of the existing ones fit semantically. Follow the naming scheme.
+
+**Example**
+
+Incorrect: A new component with a light-blue background reuses Focus.borderColor which has a light-blue color in the default themes. A theme author decides they need a bright focus border and changes the color value for Focus.borderColor. As a result, the new component has a bright background with the text unreadable over it.
+
+Correct: A new component with a light-blue background has its own color key ComponentName.background.
+
+
+**Implementation**
+Use `JBColor.namedColor` to set a color key and fallback color values:
+
+
+
+
+```kotlin
+val SELECTED_BACKGROUND_COLOR: Color =
+ JBColor.namedColor(
+ "CompletionPopup.selectionBackground",
+ JBColor(0xc5dffc, 0x113a5c)
+ )
+```
+
+
+
+
+```java
+private static final Color SELECTED_BACKGROUND_COLOR =
+ JBColor.namedColor(
+ "CompletionPopup.selectionBackground",
+ new JBColor(0xc5dffc, 0x113a5c)
+ );
+```
+
+
+
diff --git a/topics/ui/principles/typography.md b/topics/ui/principles/typography.md
new file mode 100644
index 000000000..e2f2eb556
--- /dev/null
+++ b/topics/ui/principles/typography.md
@@ -0,0 +1,307 @@
+
+
+# Typography
+
+UI guidelines on using proper fonts in different contexts.
+
+
+
+**Implementation:** [`JBFont`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/JBFont.java)
+
+
+
+## IDE font
+
+The system fonts are used for the IDE user interface by default. The default font sizes are below:
+
+
+
+ | macOS |
+ SF Pro Text |
+ 13 |
+
+
+ | Window |
+ Segoe UI |
+ 12 |
+
+
+ | Linux |
+ Ubuntu |
+ 15 |
+
+
+
+
+Users can change the default font size in Settings. If the default font size is changed, other font sizes used in the UI are scaled respectively.
+
+Use the built-in text styles from the table below whenever possible.
+
+> Implementation example for font styles: [`LabelSizeDemoAction`](%gh-ic%/platform/platform-impl/src/com/intellij/internal/LabelSizeDemoAction.kt)
+>
+{style="note"}
+
+
+
+ | Name |
+ Font size |
+ Usage Examples |
+
+
+ H0 bold
JBFont.h0().asBold() |
+ Default + 12 |
+
+ Rich text headers. See the "What’s New" page example below.
+ |
+
+
+
+ H1 bold
JBFont.h1().asBold() |
+ Default + 9 |
+ |
+
+
+
+ H2
JBFont.h2() |
+ Default + 5 |
+ |
+
+
+
+ H2 bold
JBFont.h2().asBold() |
+ |
+
+ Small page header. Examples: Plugin name, GitHub timeline header
+ |
+
+
+
+ H3
JBFont.h3() |
+ Default + 3 |
+
+ Accent body text
+ |
+
+
+
+ H3 bold
JBFont.h3().asBold() |
+ |
+
+ Headers in dialogs with a small number of elements (Customize page on Welcome screen, Login page in Get from VCS dialog)
+ |
+
+
+
+ H4 bold
(Default bold)
JBFont.h4().asBold()
JBFont.regular().asBold() |
+ Default |
+
+ Header in dialogs with a large number of elements (Run configurations dialog), notification header, breadcrumbs in settings, header in navigation popup, accent elements in lists and trees.
+ Use Group header to divide the page on groups, but not to draw too much attention to the headings.
+ |
+
+
+
+ Default
JBFont.regular() |
+ Default |
+
+ Labels, inputs, links, trees, tables and other controls; text outputs, notifications, shortcuts
+ |
+
+
+
+ | Paragraph |
+
+ Default
+ Line height default + 3
+ |
+
+ Multiline description text
+ |
+
+
+
+ Medium
JBFont.medium() |
+
+ macOS: Default - 1
+ Win: Default
+ Linux: Default - 1
+ |
+
+ Tool window header, navigation bar, editor breadcrumbs, editor tabs (small on macOS)
+ |
+
+
+
+ Medium bold
JBFont.medium().asBold() |
+ |
+
+ Module in the navigation bar
+ |
+
+
+
+ Small
JBFont.small() |
+
+ macOS: Default - 2
+ Win: Default
+ Linux: Default - 2
+ |
+
+ Status bar, tool window buttons, inline help, help text in tooltips, separators in lists
+ |
+
+
+
+If none of the built-in sizes work and a custom one is needed, define it as the default size +/- constant value. Do **not** hardcode font sizes.
+
+Use the underlined text style for hovered links.
+
+## Editor font
+
+JetBrains Mono font is used by default for the Editor.
+
+
+| Name |
+ Font size |
+ Usage |
+
+ | Default |
+ Default |
+ Editor |
+
+
+ | Small |
+ Default - 1 |
+ Line number |
+
+
+
+## Colors
+
+The IDE text colors are in the table below. The editor text colors are managed by the editor color theme.
+
+
+| Name |
+ Light |
+ Dark |
+ Usage |
+ Color key |
+
+
+ | Default |
+ 000 |
+ BBB |
+
+ Labels, inputs, trees, etc.
+ |
+
+ .foreground keys for various UI controls.
+
Examples:
+ Label.foreground
+ Button.foreground
+ ComboBox.foreground
+ MenuItem.foreground
+ |
+
+
+
+ | Info panel |
+ 808080 |
+ 8C8C8C |
+
+ Inline help, shortcuts
+ |
+
+ Label.infoForeground
+ |
+
+
+
+ | Info input |
+ 999999 |
+ 787878 |
+
+ Additional info in lists (paths, counters), placeholder
+ |
+
+ Component.infoForeground
+ |
+
+
+
+ | Disabled |
+ 8C8C8C |
+ 777777 |
+
+ Disabled labels, disabled links
+ |
+
+ .disabledForeground and .disabledText keys for various UI controls.
+
Examples:
+ Label.disabledForeground
+ ComboBox.disabledForeground
+ MenuItem.disabledForeground
+ CheckBox.disabledText
+ Button.disabledText
+ |
+
+
+
+ | Selected |
+ FFF on BACKGROUND |
+ FFF on BACKGROUND |
+
+ Selected text
+ |
+
+ .selectionForeground keys for various UI controls.
+
Examples:
+ MenuItem.selectionForeground
+ Table.selectionForeground
+ |
+
+
+
+ | Link |
+ 2470B3 |
+ 589DF6 |
+
+ Links
+ |
+
+ Use the component LinkLabel
+
Color keys:
+ Link.activeForeground
+ Link.hoverForeground
+ Link.pressedForeground
+ Link.visitedForeground
+ |
+
+
+
+ | Error |
+ C7222D |
+ FF5261 |
+
+ Inline errors text
+ |
+
+ Label.errorForeground
+ |
+
+
+
+## Examples
+
+What’s New page that appears in the Editor tab:
+
+{width=802}
+
+Plugin page in the Settings dialog:
+
+{width=439}
+
+Log in to GitHub page in the dialog:
+
+{width=587}
+
diff --git a/topics/ui/principles/validation_errors.md b/topics/ui/principles/validation_errors.md
new file mode 100644
index 000000000..b1fe81ab6
--- /dev/null
+++ b/topics/ui/principles/validation_errors.md
@@ -0,0 +1,735 @@
+
+
+# Validation Errors
+
+UI guidelines on displaying and writing texts of validation errors.
+
+Validation is the process of checking the values specified by the user, and displaying the errors that are found.
+
+An error can appear in a **tooltip**:
+
+{width=235}
+
+Or **inline**, above the confirmation buttons:
+
+{width=358}
+
+## Principles
+
+
+Always try not to let the user enter invalid data. To achieve this:
+
+
+Use controls that are constrained to valid values. For example, use a combo box or a slider instead of the input field.
+
+Limit the characters users can enter. For example, if only numbers are supported in a field, and this is obvious to the user, ignore input of letters instead of showing an error:
+
+{width=188}
+
+If it’s not obvious that only numbers can be entered, allow entering any sign and perform validation.
+
+{width=301}
+
+Provide a default value if possible. Even if the user decides to change the default value, it gives a clue on the expected input format.
+
+Write instructions and examples on how to fill a form using [context help](context_help.md).
+
+If it’s not possible to limit input, try to show an error as soon as possible so that the user can quickly return and fix it.
+
+## Validation types and usage
+
+
+
+
+ | |
+ What to validate |
+ Validation type |
+ Format |
+
+
+ 1 |
+ Non-allowed characters
+ Too big or long values
+ |
+ Immediately on input |
+ Tooltip |
+
+
+ 2 |
+ Non-allowed values in dialogs.
+ For example, an existing file name, a value that does not match the pattern, or a value that’s too small
+ |
+ On sending the form or on focus loss |
+ Tooltip |
+
+
+ 3 |
+ Empty required fields in dialogs |
+ Disable the confirmation button or check on sending the form |
+ Tooltip |
+
+
+ 4 |
+ Non-allowed or empty values in the main window |
+ On Enter or focus loss |
+ Tooltip |
+
+
+ 5 |
+ Remote connection |
+ On sending the form |
+ Tooltip or inline |
+
+
+ 6 |
+ Complex values in multi-page dialogs |
+ On reopening the form or when the values are used |
+ Tooltip, inline or notification |
+
+
+
+### 1. Non-allowed characters or too big values
+
+If a non-allowed character is entered, or the maximum input size or value is exceeded, validate it immediately on input.
+
+#### How it works {id="how-it-works_1"}
+
+The field is highlighted with red, and the error appears in the tooltip.
+
+{width=373}
+
+If the maximum value is exceeded, specify what values are allowed (e.g. a range for numeric values, or the number of symbols):
+
+{width=461}
+
+Hide the error when the incorrect symbol is deleted.
+
+#### Implementation {id="implementation_1"}
+
+
+
+
+```kotlin
+val MESSAGE =
+ "The port number must be between 0 and 65535";
+textField()
+ .validationOnInput {
+ val portString = it.text
+ if (portString.isNotEmpty()) {
+ try {
+ val portValue = portString.toInt()
+ if (portValue < 0 || portValue > 65535) {
+ error(MESSAGE)
+ } else {
+ null
+ }
+ } catch (_: NumberFormatException) {
+ error(MESSAGE)
+ }
+ } else {
+ null
+ }
+ }
+```
+
+
+
+
+```java
+// Fields initializers
+private JTextField myPort = new JTextField();
+private static final String MESSAGE =
+ "The port number must be between 0 and 65535";
+
+// Components initialization
+new ComponentValidator(parentDisposable).withValidator(() -> {
+ String pt = myPort.getText();
+ if (StringUtil.isNotEmpty(pt)) {
+ try {
+ int portValue = Integer.parseInt(pt);
+ if (portValue >= 0 && portValue <= 65535) {
+ return null;
+ } else {
+ return new ValidationInfo(MESSAGE, myPort);
+ }
+ } catch (NumberFormatException nfe) {
+ return new ValidationInfo(MESSAGE, myPort);
+ }
+ } else {
+ return null;
+ }
+}).installOn(myPort);
+myPort.getDocument().addDocumentListener(new DocumentAdapter() {
+ @Override
+ protected void textChanged(@NotNull DocumentEvent e) {
+ ComponentValidator.getInstance(myPort)
+ .ifPresent(v -> v.revalidate());
+ }
+});
+```
+
+
+
+
+### 2. Non-allowed values in dialogs
+
+A non-allowed value is a value that can be checked only when fully entered. For example, an existing file name, value that does not match the pattern or a value that’s too small/short.
+
+If a non-allowed value is entered, validate it on focus loss or on sending the form, depending on what happens faster.
+
+Do **not** validate non-allowed values on input, it will interrupt the user.
+
+Do **not** validate empty fields on focus loss. Users should be able to fill the form in a random order, so do not interrupt them.
+
+#### How it works {id="how-it-works_2"}
+
+On sending the form, the field is highlighted in red and the error tooltip appears.
+
+{width=257}
+
+If validated on focus loss, highlight the field in light-red. Do not return focus to the field with the error automatically.
+
+{width=169}
+
+The error tooltip appears when the invalid field gets the focus or on hovering over the field.
+
+When the user changes the value, the tooltip disappears and error highlighting is replaced with the regular focus:
+
+{width=480}
+
+When the focus is returned to the field with an error, use validation on input. Otherwise, it can be unclear for the user how to initiate validation.
+
+#### Implementation {id="implementation_2"}
+
+
+
+
+[//]: # (TODO: wait for confirmation)
+
+```kotlin
+textField()
+ .validationOnApply { ... }
+```
+
+
+
+
+Add `andStartOnFocusLost()` call on [`ComponentValidator`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/ComponentValidator.java) before installing it on a component:
+
+```java
+new ComponentValidator(parentDisposable)
+ .withValidator(...)
+ .andStartOnFocusLost()
+ .installOn(textField);
+```
+
+
+
+
+### 3. Empty required fields in dialogs
+
+#### Simple form
+
+If a form is simple, move the focus to the first required field and disable the confirmation button until all required fields have been filled. It is clear from the form behavior that input is required, showing validation messages is redundant.
+
+{width=373}
+
+#### Complex form
+
+If a form is complex, always enable the confirmation button. Otherwise, it can be hard to understand what should be done to complete the form.
+
+Complex forms are:
+
+* Forms with more than 3 input fields or combo boxes.
+* Forms with at least one control (checkbox, table, and so on) apart from an input field and a combo box.
+
+**Never** validate empty required fields on input or focus loss. Users should be able to fill the form in a random order, so do not interrupt them.
+
+#### How to use
+
+Validation is performed when the user clicks the confirmation button (for example, the "Add" button).
+
+Highlight all invalid fields, move the focus to the first invalid field and show the tooltip.
+
+{width=912}
+
+Hide the tooltip and the red highlighting when the user starts editing the invalid value or entering symbols into the empty required field.
+
+Show the error tooltip for the next field when it gets the focus, hover, or the user clicks the "Add" button one more time.
+
+#### Implementation {id="implementation_3"}
+
+By default, [`DialogWrapper`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) disables OK button until
+all fields that participate in validation become valid.
+
+Explicitly enable OK button for each input field:
+
+
+
+```kotlin
+error("The host cannot be reached")
+ .withOkEnabled()
+```
+
+
+
+
+```java
+new ValidationInfo("The host cannot be reached", myHostField)
+ .withOkEnabled();
+```
+
+
+
+
+### 4. Non-allowed or empty values in the main window
+
+If a non-allowed or an empty value is entered into a field that’s within the Properties view, for example, in UI Designers like the Android Studio Layout Editor, validate it on pressing Enter or focus loss.
+
+#### How it works
+
+On Enter, the field is highlighted with red and the error tooltip appears.
+
+{width=379}
+
+If validated on focus loss, the field is highlighted with light-red. The focus is not returned to the field automatically.
+
+Hide the field highlighting and the tooltip when the user fixes the invalid value.
+
+### 5. Remote connection
+
+If validation is slow or attempts are limited, for example, due to connection to a remote server, validate values on sending the form.
+
+If it’s not possible to detect the fields with errors, show the error message inline under the fields:
+
+{width=358}
+
+An inline error only appears on clicking the confirmation button. The dialog is resized to fit the error message. Do **not** leave an empty space for the error in advance.
+
+Hide the error messages once any field related to the error is edited. Set the dialog to its original size when the error disappears.
+
+#### Implementation {id="implementation_4"}
+
+[`ValidationInfo`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/ui/ValidationInfo.java) for messages in inline area is created with `null` component:
+
+```java
+new ValidationInfo(
+ "The host cannot be reached. Check the address and credentials.");
+```
+
+### 6. Complex values in multi-page dialogs
+
+If a value is complex, for example, a list of values, a regexp, or a value copied from another place, and it appears in a multi-page dialog, such as Settings, Project Structure or Run Configurations, show a dialog informing the user about an error on clicking the confirmation button.
+
+For example, in a complex Resource patterns field
+
+{width=694}
+
+show the following dialog on pressing the confirmation button:
+
+{width=409}
+
+It should be possible to close the Settings dialog and save the entered data if the user wants to fix the values later or needs additional data outside of the modal Settings dialog.
+
+If an invalid field is not empty, highlight it on reopening the Settings dialog or report the error when the entered data is used.
+
+## Tooltip
+
+
+An error tooltip appears in two cases:
+
+
+If the field with an error gets focus:
+
+{width=235}
+
+If the field loses focus, hide the tooltip and highlight the field with light-red:
+
+{width=206}
+
+On hover over the field or the element with an error:
+
+{width=235}
+
+{width=429}
+
+Show the tooltip above the field and move it 40px right, so that the controls above it are not overlapped.
+If there is important info above the field, the tooltip can be shown on the right.
+
+## Error message text
+
+An error message describes the problem and provides the way to solve it if it’s not clear from the problem description.
+
+{width=319 style=block}
+*It’s clear how to fix the error from the error description.*
+
+{width=456 style=block}
+*The way to solve the problem is provided.*
+
+Describe the problem in terms of target users’ actions or goals, not in terms of the program’s architecture.
+
+
+
+ | Incorrect |
+ Invalid Git Executable. Error running "git.exe". File not found: "git.exe". |
+
+
+ | Correct |
+ Cannot run "git.exe". The file is not found. |
+
+
+
+Provide specific names, locations, and values of the objects involved:
+
+
+
+ | Incorrect |
+  |
+
+
+ | Correct |
+  |
+
+
+
+
+
+For a period at the end of an error message, see [Punctuation](punctuation.md#period).
+
+Make the error message short and descriptive. See [Writing short and clear](writing_short.md).
+
+Examples of common errors and corresponding error messages:
+
+
+
+ | Error type |
+ Error message |
+
+
+ | Empty required field |
+ Specify the port number |
+
+
+ | Incorrect symbol |
+ "/" is not an allowed symbol |
+
+
+ | Incorrect value |
+ The port number should be between XXX and XXXX
+ The file name should be at least 4 symbols
+ The name is already in use
+ The username or password is incorrect
+ |
+
+
+ | Incorrect format |
+ The email format should be xxx@xxx.com |
+
+
+ | Missing file |
+ The file is not found |
+
+
+
+Use encouraging tone:
+
+
+
+ | Use |
+ Do not use |
+
+
+ | Problem |
+ Error, failure |
+
+
+ | Unable |
+ Failed to |
+
+
+ | Incorrect |
+ Illegal, invalid, bad |
+
+
+ | Should be |
+ Must |
+
+
+
+## Warning
+
+{width=336}
+
+A warning informs the user that something is configured incorrectly, but does not prevent them from applying the changes.
+
+A warning can appear on input, focus loss, or on reopening a filled form. For example, make the empty field Target name show a warning on reopening:
+
+{width=580}
+
+The warning can be shown:
+
+In a tooltip for a specific field. Follow the rules for [the error tooltip](tooltip.md).
+
+
+
+```kotlin
+warning("Target name is not specified")
+```
+
+
+
+
+```java
+new ValidationInfo("Target name is not specified", myNameField)
+ .asWarning();
+```
+
+
+
+
+
+On the form under the controls. Show the message with the yellow warning icon.
+
+{width=303}
+
+On the "Problems" page in complex multipage dialogs. Show warnings and fix options:
+
+{width=418 style=block}
+*Problems page in the Project Structure dialog.*
+
+Mark all navigation elements for areas that contain warnings with yellow icons.
+
+Update the problem counter when a problem is detected. When all problems have been fixed, do not show the "Problems" tab.
+
+On a particular page, highlight the element that contains a warning in yellow or add a warning icon next to it.
+
+## UI elements with validation errors
+
+### Input field
+
+{width=235}
+
+Add a red light bulb on the right side of the input field if an action to fix the error is available:
+
+{width=729}
+
+### Combo box
+
+{width=235}
+
+### Tables and lists
+
+{width=429}
+
+When the field in a table loses focus, show an error icon. An error tooltip appears on mouse hover or when the line gets focus:
+
+{width=429}
+
+Use a warning icon for warnings:
+
+{width=429}
+
+#### Implementation
+
+
+
+
+```kotlin
+val cellEditor = JTextField()
+cellEditor.putClientProperty(DarculaUIUtil.COMPACT_PROPERTY, true)
+cellEditor.document.addDocumentListener(object : DocumentAdapter() {
+ override fun textChanged(e: DocumentEvent) {
+ val outline =
+ if (cellEditor.text.contains(".")) "error" else null
+ cellEditor.putClientProperty("JComponent.outline", outline)
+ }
+})
+val firstColumn = table.columnModel.getColumn(0)
+firstColumn.cellEditor = DefaultCellEditor(cellEditor)
+firstColumn.cellRenderer = object : DefaultTableCellRenderer() {
+ override fun getPreferredSize(): Dimension {
+ val size = super.preferredSize
+ val editorSize = cellEditor.preferredSize
+ size.height = max(size.height, editorSize.height)
+ return size
+ }
+}
+```
+
+
+
+
+```java
+JTextField cellEditor = new JTextField();
+cellEditor.putClientProperty(
+ DarculaUIUtil.COMPACT_PROPERTY, Boolean.TRUE);
+cellEditor.getDocument().addDocumentListener(new DocumentAdapter() {
+ @Override
+ protected void textChanged(@NotNull DocumentEvent e) {
+ Object outline = cellEditor.getText().contains(".") ?
+ "error" : null;
+ cellEditor.putClientProperty("JComponent.outline", outline);
+ }
+});
+TableColumn firstColumn = table.getColumnModel().getColumn(0);
+firstColumn.setCellEditor(new DefaultCellEditor(cellEditor));
+firstColumn.setCellRenderer(new DefaultTableCellRenderer() {
+ @Override
+ public Dimension getPreferredSize() {
+ Dimension size = super.getPreferredSize();
+ Dimension editorSize = cellEditor.getPreferredSize();
+ size.height = Math.max(size.height, editorSize.height);
+ return size;
+ }
+});
+```
+
+
+
+
+### Trees and lists
+
+Add an error or warning icon on the right side of the invalid line.
+
+{width=647}
+
+### Multi-page dialog
+
+If validation in a multipage form can be performed only by clicking the confirmation button, then:
+
+* Use red highlighting for navigation elements such as tabs, menu and list items for areas that contain errors so that the user can quickly locate the error.
+* Open the first page with an error or stay on the opened page if it has errors on clicking the confirmation button.
+
+{width=1014}
+
+## Avoid mistakes
+
+Do not show an error in a message box. Users are pulled out of the context, they need to close the dialog and locate the invalid field.
+
+{width=472}
+
+Do not allow to click "OK" button if a form contains empty required fields. For this, the Cancel button should be used, and the OK button should be disabled. Otherwise, if users accidentally leave the field empty, they can expect that the value was entered correctly.
+
+{width=521}
+
+Do not show an error message inside the empty required field. It looks like a prefilled field, not like an error message.
+
+{width=438}
+
+Do not underline the field label. It looks like a spell error and poorly visible.
+
+{width=278}
+
+Do not shake a form and show an error with a delay. A shaking form is distracting and time-consuming.
+
+{width=445}
+
+Do not show an error immediately after opening a form. It distracts the user from filling the form.
+
+{width=350}
+
+Do not allow submitting the form with the error.
+When the form is opened again, the value is reset, so users don’t know if they entered incorrect data.
+
+{width=471}
+
+## Insets and colors
+
+{width=534}
+
+{width=354}
+
+
diff --git a/topics/ui/resources/UI_kit.md b/topics/ui/resources/UI_kit.md
new file mode 100644
index 000000000..842fe2925
--- /dev/null
+++ b/topics/ui/resources/UI_kit.md
@@ -0,0 +1,14 @@
+
+
+# UI Kit
+
+IntelliJ Platform UI resources for Figma.
+
+Resources for Figma:
+
+- IntelliJ Platform UI Kit
+- IntelliJ Icons plugin
+
+{width=1111}
+
+
diff --git a/topics/ui/resources/how_to_write_guidelines.md b/topics/ui/resources/how_to_write_guidelines.md
new file mode 100644
index 000000000..2e8a9203e
--- /dev/null
+++ b/topics/ui/resources/how_to_write_guidelines.md
@@ -0,0 +1,301 @@
+
+
+# How to Write Guidelines
+
+Workflow and basic rules of writing articles for IntelliJ Platform UI Guidelines.
+
+This page describes the workflow and basic rules of writing articles for IntelliJ Platform UI Guidelines.
+
+## Workflow
+
+Follow these steps if you want to add a new article to the guidelines:
+1. Write an article in the Google doc.
+2. Share the Google doc with the designers team, so they can review and comment the document.
+3. When all comments are resolved, send the Google doc to tech writers for grammar review. [Create ticket](https://youtrack.jetbrains.com/newIssue?project=DOC&clearDraft=true&c=Type+Task&c=Assignee+Anna.Gasparyan&c=Subsystem+IntelliJ+IDEA) in YouTrack project “Documentation”, subsystem “IntelliJ IDEA”, auto-assigned to Anna Gasparyan.
+4. After the review, add the article to the guidelines. Follow the instructions on [https://github.com/JetBrains/ui](https://github.com/JetBrains/ui).
+4. Contact developers to add Code Snippets to the article.
+
+## Text
+
+The text should be short and clear. Follow the rules:
+
+### Grammar
+
+
+
+ | Use present tense. |
+ A progress bar informs user about the progress of a lengthy operation. |
+
+
+ | Write in the active voice. |
+ Progress bar is shown.
Progress bar appears. |
+
+
+ | Avoid unnecessary modal verbs. |
+ Label should use sentence-style capitalization.
Use sentence capitalization in labels. |
+
+
+ | Use imperatives. |
+ The cursor changes to the pointing hand.
Change the cursor to the pointing hand. |
+
+
+ | Do not address the reader. |
+ Use combobox if..., Follow guidelines... |
+
+
+ | When describing user behavior, write: |
+ A user looks forward to what will appear after completion. |
+
+
+ | Avoid bracketed text, it complicates reading. If information is important — put it in a new sentence, if not — remove it. |
+ Provide a header (bold) for each progress.
Provide a bold header for each progress. |
+
+
+
+
+### Contents
+
+* Omit common introductory phrases.
+
+* Write one idea per sentence.
+
+* Split the text to subsections and short paragraphs.
+
+* Use bulleted lists when the order of points does not matter, and numbered list when they do.
+
+* When giving a recommendation, explain why it is useful.
+ *Bad: *If a process is started by a user, provide a notification when the process finishes*.
+ * Good>: *If a process is started by a user, provide a notification when the process finishes. This way the user, if switched to another task while waiting for a process to finish, would know they can return back and see the results*.
+
+* Add links if you refer to other sections. Links should be descriptive, do not use *Click here* links.
+
+
+### Word-level recommendations
+
+
+
+ | Would be — use is instead, when possible. |
+ Displaying indicator would be distracting.
Displaying indicator is distracting. |
+
+
+ | Then — omit if possible. |
+ If a process is started by the user, then. provide notification. |
+
+
+ | He/she — replace with they. |
+ If a process lasts less than 1 second, the user won’t be able to read the process name and showing it would just distract them. |
+
+
+ | Select a word with bold to emphasise or with italic to quote. |
+
+
+
+
+## Structure
+
+If an article is about a control, add a control's class name under the article title:
+
+
+codename: JButton
+
+
+Structure a single guideline as follows:
+* Start each guideline with a text description and provide an image *under* it if necessary. Do **not** use a reversed order (image than text).
+* Place an additional text under the image only if it does not make sense placing it with the text above the image.
+
+Guideline numbered anchors:
+* Each paragraph `` is assigned a numbered anchor. An anchor helps referencing a particular guideline. Structure the article so that each guideline is a single paragraph.
+* To start a new paragraph, add an empty line above.
+* To create a text block without an anchor, do not add an empty line above. Add two spaces in the end of the previous text block.
+* To add extra vertical space without creating a paragraph, use `
`.
+* If some element gets an unnecessary anchor, use the class `noanchor`. Note that Markdown does not work inside the `
` tag, replace it with HTML. Example:
+{% highlight html %}
+
+For when to use the empty state, see the
+Empty State.
+
+
+
+The article structure can vary depending on whether a control, component or principle is described. Generally, use the sections that are described below.
+
+### Introduction paragraph
+
+In the first paragraph describe a control, component or principle and provide an illustration. If there are different types of the control, describe all of them.
+
+### When to use
+
+Describe when to use the control or when to apply the principle.
+
+If the control is often used incorrectly, describe cases when the control should not be used.
+
+### How to use
+
+Provide guidelines on how to use the control, component or principle. Group guidelines by their subject. For a control it can be:
+* Behavior details for a single control and for a group of such controls (if applicable)
+* Wording — how to write a label for the control
+* Using the control with other controls
+* Any other recommendations specific to this control
+
+Use notes for links to additional materials, sources, useful facts and examples. To insert a note, use:
+{% highlight html %}<note>Note text</note>
+
+Use formatting for shortcuts:
+{% highlight html %}<shortcut>Ctrl+Space</shortcut>
+
+To add a horizontal line in a table, use:
+{% highlight html %}
+
+
+### Sizes and placement
+
+Give recommendations for:
+* Minimum and maximum sizes in pixels
+* How to layout with other controls. Refer to [Layout](layout.md) if possible.
+* Insets between controls in pixels
+
+Illustrate sizes and insets as [described below](#colors-insets-and-sizes).
+
+
+### Style
+
+Provide [an illustration](#style) how a control or component looks in different look-and-feels.
+
+List color keys used for this control.
+
+Do not provide font properties and specific hex colors.
+
+
+## Images
+
+Illustrate all statements with interface examples. Use **default macOS** theme as the main themes for illustrations. Add a section with examples for Darcula theme in the Google doc, but do not move it to the official guidelines.
+
+If an image description appears above the image, end it with a colon:
+
+{width=312}
+
+If under, do not use a period at the end:
+
+{width=312}
+
+*Image description*
+
+Several not wide images can be placed in two or three columns:
+
+{width=760}
+
+If there is a set of images that illustrates the sequence of states, place them horizontally or vertically and link with an arrow:
+
+{width=565}
+
+If there is a common mistake in UI, provide Correct/Incorrect images:
+
+{width=417}
+
+The “Correct/Incorrect” can be placed above the image or on the left:
+
+{width=285}
+
+If there is one image and it’s not big, cross out the image with 1px line instead of “Incorrect” header:
+
+{width=268}
+
+Use html to add Correct/Incorrect label:
+{% highlight html %}<p>Incorrect</p>
+
+
+{width=530}
+
+Save all images in two sizes: example.png and example@2x.png.
+
+
+### Callouts
+
+All text on images should be horizontally oriented.
+
+Font-style: Gotham Book
+Font-size: 14px
+Line height: 20px
+Max width: 300px
+Color: #999999
+
+Place callouts around the image at a distance of at least 30px:
+
+{width=474}
+
+Or use leader lines to sign specific items on the image:
+
+{width=330}
+
+**Leader line** is 1px line, color: #000000 op. 0.3.
+
+Line is vertical or horizontal. It can be bent once if there is not enough space for the text. Do not intersect lines.
+
+Leave 1px between the line and the element to which it refers or place line over the element:
+
+{width=182}
+
+Lines go beyond the image by 20px:
+
+{width=353}
+
+Text position:
+
+{width=452}
+
+If line is horizontal, center it with the first comment line.
+
+### Colors, insets and sizes
+
+Use the Hex Code format to specify colors:
+
+{width=252}
+
+Use colored rectangles to specify sizes inside the element and lines to specify external sizes:
+
+{width=377}
+
+* Main rectangle: #DA769D op. 0.4.
+* Secondary rectangle: #6D9AE6 op. 0.4.
+* Text and line: #BD136B, #0054C0.
+* Distance between image and line, between line and text is 5px.
+* Align all sizes on the right.
+
+Use line to show that text is aligned with an element:
+
+{width=155}
+
+Specify the element sizes in the following format:
+{width=54}
+
+For text labels, specify insets from the bounding box:
+
+{width=216}
+
+{width=125}
+
+Parameters for regular labels that make bounding boxes in Sketch the same size as in Java (already used in Sketch libraries symbols):
+- *macOS*: SF UI Text Medium / 13 size / –0.1 character spacing / 16 line spacing
+- *Windows*: Segoe UI Regular / 12 size / 16 line spacing
+- *Linux*: Ubuntu Regular / 15 size / 18 line spacing
+
+
+If unsure about a bounding box size for other font sizes, check with UI Inspector.
+
+
+
+## Code snippets
+Provide code snippets along the article to help developers implement the described look and behavior.
+
+If a code snippet is too big, put it at the end of the article and provide a link.
+
+To insert a snippet, use:
+
+{% highlight html %}{{ "{% highlight java " }}%}
+Code snippet
+{{ "{% endhighlight " }}%}
+
+
+
diff --git a/topics/ui/resources/icons_list.md b/topics/ui/resources/icons_list.md
new file mode 100644
index 000000000..49b2938c9
--- /dev/null
+++ b/topics/ui/resources/icons_list.md
@@ -0,0 +1,14 @@
+---
+title: Icons list
+category: Resources
+type: full
+---
+
+
+
\ No newline at end of file
diff --git a/topics/ui/text/capitalization.md b/topics/ui/text/capitalization.md
new file mode 100644
index 000000000..55fc99053
--- /dev/null
+++ b/topics/ui/text/capitalization.md
@@ -0,0 +1,67 @@
+
+
+# Capitalization
+
+UI guidelines for using title and sentence capitalization in various contexts.
+
+## Title
+
+> The current Windows guidelines use sentence capitalization for actions. Some Microsoft products still title-capitalize actions according to the previous guidelines. macOS also title-capitalizes actions. Since IntelliJ IDEs are cross-platform, we use title capitalization as well.
+>
+{style="note"}
+
+Use for:
+
+* Actions in buttons, menus and tooltips
+* Headers in tables, popups, message boxes and dialogs
+* Headers of UI control groups
+
+Do **not** use for:
+
+* Actions in links
+* Actions in the popup on Alt+Enter: quick-fixes, intention actions, and others
+* Headers in notifications
+
+### Rules {id="rules_1"}
+
+Always capitalize the first and the last words.
+
+Capitalize the words in-between except:
+
+* articles: *a, an, the*,
+* coordinating conjunctions: *and, or, but*,
+* prepositions of four and fewer letters which are not a part of a phrasal verb: *in, with*.
+
+In hyphenated phrases, capitalize all nouns, adjectives and adverbs: *Auto-Indent, Command-Line Launcher*.
+Do not capitalize articles, prepositions and conjunctions: *Side-by-Side, Drag-and-Drop*.
+
+### Examples {id="examples_1"}
+
+*Compare With…* — the short preposition *with* is capitalized as the last word.
+
+*Compare with Latest Repository Version* — *with* is not capitalized when in the middle.
+
+*Check Out from Version Control* — *out* is a part of the phrasal verb *check out* and is capitalized.
+
+## Sentence
+
+Use for:
+
+* Labels of UI controls: text boxes, checkboxes, radio buttons, combo boxes, etc.
+* Items in combo boxes, lists, trees and tables
+* Links
+* Actions in the popup on Alt+Enter
+* Header and body text in notifications
+* Body text in error messages, tooltips, status descriptions and any kind of instructions
+
+### Rules
+
+Capitalize the first word in a sentence, proper nouns and adjectives, and abbreviations.
+
+### Examples
+
+Control+Shift+F — keyboard button names are considered proper nouns.
+
+Accept the terms of the License Agreement — License Agreement is a proper noun.
+
+Side-by-side layout — only the first word of a hyphenated phase is capitalized.
diff --git a/topics/ui/text/inspections.md b/topics/ui/text/inspections.md
new file mode 100644
index 000000000..9cd9be273
--- /dev/null
+++ b/topics/ui/text/inspections.md
@@ -0,0 +1,126 @@
+
+
+# Inspections
+
+UI guidelines on writing texts used in inspections.
+
+{width=834 style=block}
+*Inspections configuration on Settings | Editor | Inspections page or in Configure Inspections dialog.*
+
+Inspection names, descriptions, and editor messages should be short and descriptive.
+Follow the rules for [short and clear texts](writing_short.md) and [punctuation](punctuation.md) in addition to the rules described below.
+
+### Group Names
+
+Use the names of technologies and frameworks as titles for inspection groups, for example, Ant, Android, Java.
+
+### Inspection Names
+
+Limit a name by ~50 symbols so that it fits the line in the list of inspections in settings.
+
+An inspection name should reflect the code problem that this inspection detects, for example:
+
+{width=245}
+
+Do not just describe the type of code that is being checked:
+
+{width=613}
+
+When describing a problem, prefer adjectives to complex nouns:
+
+{width=557}
+
+{width=471}
+
+Do not repeat the group titles in the inspection name:
+
+{width=557}
+
+Do not use the word "problems" or other words that describe how inspections function in general (i.e. "check", "inspection", or "issue"). An inspection is supposed to check code for problems, so mentioning it in its name is not needed.
+
+{width=613}
+
+Do not use the words "warning" and "error" in inspection names. Such a name will become incorrect and misleading if the inspection severity level changes.
+
+{width=613}
+
+Do not use parentheses in inspection names. All supporting information can be moved to inspection descriptions.
+
+{width=513}
+
+If an inspection is powered by a third-party code quality tool, use the name of this tool in the inspection name.
+
+{width=245}
+
+### Descriptions
+
+Start descriptions with a verb, e.g. "Reports". Use "Run" for external tools. Do not begin a description with "This inspection".
+
+{width=520}
+
+Provide details, such as:
+
+* A quick-fix if applicable:
+
+{width=520}
+
+* A link to the language or framework docs explaining the correct usage of the syntax or feature, if applicable.
+
+{width=520}
+
+* Two code samples: the code with a problem and the code that bypasses this problem. By comparing the good code and the bad code, users can work out what causes the problem and how to avoid it.
+ For example, for Java | Probable bugs | 'equals()' called on array adding such an example helps to understand the inspection quicker:
+
+{width=520}
+
+* Information from external validators.
+ Prefer separating inspections so that a user can control them individually.
+ If it is not possible, list all problems that an inspection can detect:
+
+{width=520}
+
+Be very specific about the code problems that an inspection can detect:
+
+{width=520}
+
+Remove unnecessary words:
+
+* Do not duplicate an inspection’s name in its description.
+
+* Inspections highlight code problems, it's their primary functionality. Don't explain it in descriptions:
+
+ {width=520}
+
+For text formatting, see [Description text](description_text.md).
+
+### Editor messages
+
+Describe the problem in the highlighted code in the current context.
+
+{width=592 style=block}
+*For example, Unresolved reference inspection provides the exact reference name which is unresolved.*
+
+Use single quotes for the highlighted piece of code if it is referenced in the error message.
+
+If a quick-fix is not available, describe in more detail a way to resolve the problem:
+
+{width=478}
+
+### Quick-fixes
+
+Describe the action that fixes the problem. For wording, follow the rules for [buttons](button.topic#label).
+
+[//]: # (TODO: and [menu actions](menu.md).)
+
+Use single quotes for the referenced piece of code.
+
+{width=354}
+
+### Capitalization
+
+Use [sentence case](capitalization.md#sentence) for everything:
+
+* Inspection names and descriptions
+* Names of inspection groups and subgroups in settings
+* Inspection texts in editor tooltips and quick-fixes
+
diff --git a/topics/ui/text/punctuation.md b/topics/ui/text/punctuation.md
new file mode 100644
index 000000000..979f92a84
--- /dev/null
+++ b/topics/ui/text/punctuation.md
@@ -0,0 +1,159 @@
+
+
+# Punctuation
+
+Punctuation rules for labels and description texts.
+
+Use the following rules for labels and description texts in IntelliJ user interfaces. For punctuation in numbers and times, see [Data formats](data_formats.md).
+
+## Ellipsis
+
+End an action name with an ellipsis if it opens a dialog where input is required or possible. An ellipsis helps users understand if an action is immediate, or additional interaction is to follow.
+
+This rule applies to actions in the following controls: button, link, menu item.
+
+Examples:
+
+
+
+ Save All
+ Build Project
+ |
+
+ Happens immediately, no ellipsis
+ |
+
+
+
+ Import Settings…
+ Export to HTML…
+ |
+
+ Opens dialogs that require input
+ |
+
+
+ |
+ Project Structure…
+ |
+
+ Opens a complex dialog where input is not required but possible
+ |
+
+
+
+ Tip of the Day
+ About IntelliJ IDEA
+ |
+
+ Opens dialogs that just show information, no input is either required or possible
+ |
+
+
+
+Use an ellipsis at the end of a truncated text if there is no scrollbar and this is not a table column, see [truncation in table columns](table.md#sizes-and-placement). Provide a way to show the full text, for example, expand the control or show a tooltip on hover.
+
+{width=399 style=block}
+*A notification can be expanded to show the full text.*
+
+Use an ellipsis with verbs describing an ongoing process, for example, Searching… See more examples in [Progress text](progress_text.md).
+
+Use the ellipsis character … (`U+2026` in Unicode). Do not use three separate "dot" characters.
+
+## Period
+
+Do **not** put a period at the end of a single sentence, even if it is a complete sentence.
+
+{width=385}
+
+{width=396}
+
+If a text consists of several sentences, put a period after each sentence.
+{width=488}
+
+Do **not** put a period at the end of an IDE action.
+
+{width=385 style=block}
+*The empty text consists of two sentences, but the second one is an IDE action, so it should not have a period.*
+
+Note that links that are not IDE actions can have a period in the end.
+
+{width=376}
+
+## Comma
+
+Use a comma:
+
+Before a conjunction in a list of three or more items (the Oxford or serial comma).
+
+*Border for a text field, combo box, or spinner*
+
+Between symbols in series.
+
+*Use the following characters: &, $, ., and \**
+
+## Colon
+
+Use a colon after labels for inputs and radio button / checkbox groups.
+
+{width=153}
+
+{width=213}
+
+Do **not** use a colon if a label and text inside the input element make a phrase.
+
+{width=247}
+
+## Contractions
+
+Generally, do not use contractions.
+
+*Path can’t be found → Path cannot be found*
+
+Use contractions only if the action name has 4 and more words, and the contracted word does not affect the meaning significantly.
+
+*What’s New in IntelliJ IDEA*
+
+*Don’t* or *Do not*:
+
+* Always contract in the phrase *Don’t [some verb] again*. The phrase is common, and the meaning is easily recognized.
+ {width=399}
+* In other cases, do not contract. The full form reduces chances that the relevant meaning might be missed.
+
+*Don’t send → Do not send*
+
+*Do not save, forget passwords after restart*
+
+## Quotation marks
+
+Use single quotation marks by default.
+
+> Use a straight single quotation mark ' (`U+0027`). Do not use opening and closing quotation marks ‘ ’ (`U+2018`/`U+2019`).
+>
+{style="note"}
+
+
+Indexing library 'KotlinJavaRuntime'
+Error parsing '.mvn/maven.config'
+Add 'root=true' to the beginning of the file
+Show 'Scratches and Consoles' in the Project view
+
+Do not use quotation marks for keyboard key names.
+
+*Type an expression and press 'Enter' → press Enter*
+
+Do not use double quotation marks.
+
+## Question marks
+
+Use only in alerts when asking for confirmation.
+
+*A file with this name already exists. Do you want to overwrite it?*
+
+Avoid in other cases.
+
+*Forgot password? → Remind password*
+
+## Exclamation points
+
+Do not use. Exclamation points can cause the sentence tone to be interpreted as aggressive, condescending, or overly informal.
diff --git a/topics/ui/text/writing_short.md b/topics/ui/text/writing_short.md
new file mode 100644
index 000000000..d122b202d
--- /dev/null
+++ b/topics/ui/text/writing_short.md
@@ -0,0 +1,248 @@
+
+
+# Writing Short and Clear
+
+Tips on writing short and clear UI texts.
+
+
+Texts in user interfaces should be short and clear. Short texts save reading time. Clear texts lead to fewer mistakes. Editing methods described below can help with that.
+
+
+## Use simple constructions
+
+Use simple verb forms. Prefer present tense.
+
+Use simple sentences: one idea per sentence.
+
+Avoid passive voice.
+
+This way, the same meaning can be expressed with fewer words. Compare:
+
+Those resources that are available locally → Local resources
+
+Maven has to use → Maven uses
+
+The use of a secure connection is required → Use secure connection
+
+## Remove or elaborate generic words
+
+Words like *general*, *advanced*, and *options* do not add useful information and can be removed with no harm to the meaning:
+
+{width=540}
+
+{width=540 style=block}
+*No meaning is lost after removing group headers "General" and "Options".*
+
+Some generic words cannot be removed. They can appear in actionable elements like buttons, checkboxes, or links. Or removing a group header could break a dialog layout. In such cases, use a more informative label instead:
+
+{width=576 style=block}
+*The link "Learn more" does not explain what useful information could be there for the user to click it.*
+
+## Remove obvious objects and actions
+
+Remove verbs that explain the function of a UI control:
+
+{width=403 style=block}
+*Text boxes are made for input — an explicit instruction "specify" duplicates the meaning expressed by the text field. Additional information can be given under the field — see [Context help](context_help.md).*
+
+
+
+  A selected radio button means its option is "preferred". |
+  A checked checkbox means its feature is "allowed". |
+
+
+
+Remove words with a meaning that is already expressed in the label:
+
+
+ 
+ The clipboard’s purpose is to keep information so the infinitive "to keep" is implying the obvious and can be removed. |
+ 
+ The word "functionality" is already implied by "Drag’n’Drop" and can be removed. |
+
+
+
+## Do not address the user
+
+A user interface is for a person who uses it. Addressing this person is unnecessary because they by default perceive the text they see as for them:
+
+{width=674}
+
+{width=674 style=block}
+*The whole phrase after the comma is not needed because its meaning is already expressed by the verb "configure".*
+
+## Remove duplicates
+
+If the repeating word appears in element labels, move it to the beginning. Finding a setting becomes faster as you scan only meaningful words:
+
+{width=438}
+
+Remove duplicates in meaning:
+
+{width=498}
+
+
+
+| Before |
+ After |
+ Explanation |
+
+
+ | Help improve IntelliJ IDEA by sending anonymous usage statistics to JetBrains s.r.o. |
+ Help improve IntelliJ IDEA |
+ The purpose of the header is to attract attention. The shorter and clearer header does that better. |
+
+
+ | if you want to help make IntelliJ IDEA better |
+ Allow sending anonymous usage statistics to JetBrains s.r.o. |
+ "Help make IntelliJ IDEA better" is already expressed in the message header. The body text now explains how the user can do that. |
+
+
+ | more... |
+ Terms and conditions |
+ The link more... does not tell what is behind it — unclear for the user why to click it. |
+
+
+
+
+
+| Removed |
+ Explanation |
+
+
+
+ | click I agree |
+ The verb "click" is obvious from context: you cannot do much with a link other than click. |
+
+
+ | click... I don’t agree otherwise |
+ The link "I don’t agree" duplicates the notification "Close" button which appears on hover. |
+
+
+  |
+ The icon is not needed because the message is purely informative, not an error or a warning. Texts are information by default, there is no need to specify that meaning explicitly. |
+
+
+
+## Translate from tech to human
+
+When you make a feature, you know how it works from the inside and can describe it from the implementation point of view:
+
+{width=560}
+
+A person not familiar with implementation details won’t know what the Automatic indent options detector is, why file’s indent options have been overwritten and what indent size=2 means. Translated to the "human" language, the message reads:
+
+{width=560}
+
+Always write UI text from a user’s perspective. Avoid technical terms, jargon and descriptions of inner logic that a user might not know.
+
+## Write for first-time users
+
+After writing a UI text, imagine seeing it for the first time and try to understand what might be unclear or confusing. Then correct if necessary.
+
+{width=474 style=block}
+*For a first-time user, Enable File Colors enables or disables the other two options (but it does not).*
+
+{width=474 style=block}
+*Rewritten: now all options are equal.*
+
+More examples:
+
+{width=318 style=block}
+*Before: The title can be read as "Auto-insert when only one checkbox is on" making you ask how it works when both checkboxes are on. After: Replacing choice with completion option makes the title unambiguous.*
+
+{width=318 style=block}
+*Before: What do smart Home and End keys do? What do they do if they are not smart? After: The added text explains what the options do so that the reader can make an informed choice.*
+
+## Examples
+
+{width=642}
+
+
+
+
+| Before |
+ After |
+ Explanation |
+
+
+
+ | Project name Project SDK Project language level |
+ Project name SDK Language level |
+ "Project" can be left only for the first field. All others will be understood as project settings because they appear in the same group of UI elements. |
+
+
+ | This path is used to store |
+ This path stores |
+ Simple verb form |
+
+
+ | store all project compilation results |
+ stores project compilation output |
+ "all" is extra because it is implied by default. "results" is another word for "output" — having different words for the same meaning complicates understanding. |
+
+
+ | A directory corresponding to each module is created under this path. This directory contains two subdirectories... |
+ It has a separate directory for each module, with the Production and Test subdirectories. |
+ "is created" is not relevant to the meaning of this phrase. "two" is obvious from context: you see that there are two subdirectories because only two are named. |
+
+
+
+
+
+| Moved |
+ Moved |
+
+ | This [field name] is default for all project modules. A module specific [field name] can be configured for each of the modules is required. |
+ This phrase is repeated for all fields. Can be shown only once at the bottom of the dialog. |
+
+
+
+{width=566}
+
+
+| Before |
+ After |
+ Explanation |
+
+
+ | visits the remote repositories and checks for updates |
+ checks remote repositories for updates |
+ "Checks" already includes the meaning of "visits". |
+
+
+ | When you switch to offline mode |
+ In the offline mode |
+ The action "switched" is not relevant for the meaning of this phrase. Also, an unnecessary reference to the user — "you". |
+
+
+ | Maven has to use |
+ Maven uses |
+ Not relevant that a technology must do something, enough to say it just works this way. |
+
+
+ | those resources that are available locally |
+ local resources |
+ |
+
+
+ | reports about the problems if something is missing |
+ reports if something is missing |
+ |
+
+
+
+
+
+| Removed |
+ Explanation |
+
+
+ | The offline mode is helpful when you need to work offline |
+ The phrase does not explain when the offline mode is helpful. It should either be elaborated or removed. |
+
+
+ | or when your network connection is slow |
+ Only one of possible uses for the offline mode and an obvious one. It can be removed for a more concise text. |
+
+
diff --git a/topics/ui/ui_guidelines_welcome.md b/topics/ui/ui_guidelines_welcome.md
new file mode 100644
index 000000000..c966297e9
--- /dev/null
+++ b/topics/ui/ui_guidelines_welcome.md
@@ -0,0 +1,105 @@
+
+
+# UI Guidelines
+
+Creating consistent and usable user interfaces.
+
+When working on an IntelliJ Platform-based IDE or a plugin, use these guidelines to create consistent and usable user interfaces.
+
+> Topics in gray text are not available yet.
+>
+{style="note"}
+
+## Controls
+
+- [](button.topic)
+ - [](built_in_button.md)
+ - [](split_button.md)
+- [](checkbox.md)
+- [](combo_box.md)
+- [](context_help.md)
+ - [](inline_help_text.md)
+ - [](tooltip.md)
+ - [](empty_state.md)
+- [](description_text.md)
+- [](drop_down.md)
+- [](got_it_tooltip.md)
+- [](group_header.md)
+- [](input_field.md)
+- [](link.md)
+- List
+- Menu
+ - Context Menu
+ - Menu List
+- [](notification_types.md)
+ - Alert
+ - [](balloon.md)
+ - [](banner.md)
+ - Tool Window Balloon
+- [](progress_indicators.md)
+ - [](loader.md)
+ - [](progress_bar.md)
+ - [](progress_text.md)
+- [](radio_button.md)
+- [](scrollbar.md)
+- [](search_field.md)
+- Slider
+- [](table.md)
+- [](tabs.md)
+- [](text_area.md)
+- [](toggle_button.md)
+- [](toolbar.md)
+ - [](icon_button.md)
+ - [](split_icon_button.md)
+ - [](toolbar_drop_down.md)
+- Tree
+- {columns="4"}
+
+## Components
+
+- Dialog Window
+- Popup
+- Status Bar
+- [](tool_window.md)
+- {columns="4"}
+
+## Text
+
+- [](capitalization.md)
+- [](inspections.md)
+- [](punctuation.md)
+- Notification and Error Texts
+- Terminology
+- [](writing_short.md)
+- {columns="4"}
+
+## Principles
+
+- Accessibility
+- Dangerous Actions
+- [](data_formats.md)
+- Default Values
+- Discoverability
+- [](icons_style.md)
+- [](layout.md)
+ - [](groups_of_controls.md)
+ - Master-detail Layout
+ - Sizes and Insets
+- [](mnemonics.md)
+- [](platform_theme_colors.md)
+- Search
+ - Search Results
+ - Speed Search
+- Sharing Settings
+- [](typography.md)
+- UI Feedback
+- [](validation_errors.md)
+- {columns="4"}
+
+## Resources
+
+- [Icons List](https://intellij-icons.jetbrains.design)
+- [](UI_kit.md)
+- {columns="4"}
+
+
diff --git a/topics/user_interface_components/dialog_wrapper.md b/topics/user_interface_components/dialog_wrapper.md
index 7414ce919..fba0a45a5 100644
--- a/topics/user_interface_components/dialog_wrapper.md
+++ b/topics/user_interface_components/dialog_wrapper.md
@@ -6,7 +6,7 @@
-**Platform UI Guidelines:** [Layout](https://jetbrains.design/intellij/principles/layout), [Validation errors](https://jetbrains.design/intellij/principles/validation_errors/)
+**UI Guidelines:** [](layout.md), [](validation_errors.md)
@@ -47,7 +47,7 @@ The `DialogWrapper` class is often used together with [GUI Designer forms](https
In this case, bind a GUI Designer form to the class extending `DialogWrapper`, bind the top-level panel of the form to a field and return that field from the `createCenterPanel()` method.
When using Kotlin, use [Kotlin UI DSL](kotlin_ui_dsl_version_2.md) to provide the dialog's contents.
-> See [Layout](https://jetbrains.design/intellij/principles/layout) topic in IntelliJ Platform UI Guidelines for recommendations on arranging UI controls in dialogs.
+> See [](layout.md) topic in UI Guidelines for recommendations on arranging UI controls in dialogs.
>
> Existing dialogs can be inspected at runtime using [UI Inspector](internal_ui_inspector.md), e.g., to locate the underlying implementation of UI components.
>
@@ -62,7 +62,7 @@ Use `action.putValue(DialogWrapper.DEFAULT_ACTION, true)` to set the default but
### Input Validation
-Please see also [Validation errors](https://jetbrains.design/intellij/principles/validation_errors/) topic in the IntelliJ Platform UI Guidelines.
+Please see also [](validation_errors.md) topic in UI Guidelines.
To validate the data entered into the dialog, override the `doValidate()` method.
The method will be called automatically by timer.
diff --git a/topics/user_interface_components/kotlin_ui_dsl.md b/topics/user_interface_components/kotlin_ui_dsl.md
index 62192ff1c..603ee106d 100644
--- a/topics/user_interface_components/kotlin_ui_dsl.md
+++ b/topics/user_interface_components/kotlin_ui_dsl.md
@@ -1,12 +1,12 @@
-# Kotlin UI DSL Version 1
+
-
+# Kotlin UI DSL Version 1
Kotlin DSL for creating UI forms with input components bound to state object.
-**Platform UI Guidelines:** [Layout](https://jetbrains.design/intellij/principles/layout)
+**UI Guidelines:** [](layout.md)
@@ -32,7 +32,7 @@ The _Kotlin UI DSL Version 1_ functions are located in the [`com.intellij.ui.lay
## Layout Structure
-> See [Layout](https://jetbrains.design/intellij/principles/layout) topic in IntelliJ Platform UI Guidelines for recommendations on arranging UI controls in dialogs.
+> See [](layout.md) topic in UI Guidelines for recommendations on arranging UI controls in dialogs.
>
Use [`panel`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/layout/layout.kt) to create UI:
diff --git a/topics/user_interface_components/kotlin_ui_dsl_version_2.md b/topics/user_interface_components/kotlin_ui_dsl_version_2.md
index 8d8cffe1e..27900fb10 100644
--- a/topics/user_interface_components/kotlin_ui_dsl_version_2.md
+++ b/topics/user_interface_components/kotlin_ui_dsl_version_2.md
@@ -6,7 +6,7 @@
-**Platform UI Guidelines:** [Layout](https://jetbrains.design/intellij/principles/layout)
+**UI Guidelines:** [](layout.md)
@@ -17,7 +17,7 @@
{style="warning"}
Kotlin UI DSL Version 2 allows creating UI forms with input components bound to state objects.
-The forms are built by using a declarative Kotlin syntax and follow the official IntelliJ Platform UI conventions described in the [IntelliJ Platform UI Guidelines](https://jetbrains.design/intellij/).
+The forms are built by using a declarative Kotlin syntax and follow the official IntelliJ Platform UI conventions described in the [](ui_guidelines_welcome.md).
The library is written in [Kotlin](using_kotlin.md) and makes it easy to develop user interfaces like dialogs and settings pages.
The Kotlin UI DSL is not intended to build general UIs, like tool windows controls that trigger some actions and do not contain any input components bound to state objects.
diff --git a/topics/user_interface_components/misc_swing_components.md b/topics/user_interface_components/misc_swing_components.md
index 29c860d07..14733b99c 100644
--- a/topics/user_interface_components/misc_swing_components.md
+++ b/topics/user_interface_components/misc_swing_components.md
@@ -33,6 +33,6 @@ It has a significantly different look & feel compared to the standard Swing tabs
### Toolbars
-See [Toolbar](https://jetbrains.design/intellij/controls/toolbar/) in the IntelliJ Platform UI Guidelines for an overview.
+See [](toolbar.md) in the UI Guidelines for an overview.
[Building UI from Actions](basic_action_system.md#building-ui-from-actions) covers creating `AnAction`-based toolbars.
diff --git a/topics/user_interface_components/notifications.md b/topics/user_interface_components/notifications.md
index af8f7a959..6eb18cf0d 100644
--- a/topics/user_interface_components/notifications.md
+++ b/topics/user_interface_components/notifications.md
@@ -6,7 +6,7 @@
-**Platform UI Guidelines:** [Notifications](https://jetbrains.design/intellij/controls/notifications/), [Banner](https://jetbrains.design/intellij/controls/banner/), [Got It tooltip](https://jetbrains.design/intellij/controls/got_it_tooltip/), [Balloon](https://jetbrains.design/intellij/controls/balloon/)
+**UI Guidelines:** [](notification_types.md), [](banner.md), [](got_it_tooltip.md), [](balloon.md)
@@ -27,7 +27,7 @@ Other [`HintManager`](%gh-ic%/platform/platform-api/src/com/intellij/codeInsight
### Editor Banner
-For UI reference, see [Banner](https://jetbrains.design/intellij/controls/banner/) in the IntelliJ Platform UI Guidelines.
+For UI reference, see [](banner.md) in UI Guidelines.
Notifications that appear at the top of the file editor are a great way to ask the user to take an important action that would otherwise impede their experience if ignored (e.g., missing SDK, setup/project configuration requiring user input).
@@ -37,9 +37,10 @@ If access to indexes is not required, it can be marked [dumb aware](indexing_and
A commonly used UI implementation is [`EditorNotificationPanel`](%gh-ic%/platform/platform-api/src/com/intellij/ui/EditorNotificationPanel.java).
### "Got It" Notification
+{id="gotIt"}
Use to highlight important new/changed features via [`GotItTooltip`](%gh-ic%/platform/platform-impl/src/com/intellij/ui/GotItTooltip.kt).
-See [Got It tooltip](https://jetbrains.design/intellij/controls/got_it_tooltip/) in IntelliJ Platform UI Guidelines for an overview.
+See [](got_it_tooltip.md) in UI Guidelines for an overview.
### Top-Level Notifications (Balloons)
{id="balloons"}
@@ -51,7 +52,7 @@ It has two main advantages:
* The user can control the way each notification type is displayed under Settings | Appearance & Behavior | Notifications
* All displayed notifications are gathered in the Event Log tool window and can be reviewed later
-For UI reference, see [Balloon](https://jetbrains.design/intellij/controls/balloon/) in the IntelliJ Platform UI Guidelines.
+For UI reference, see [](balloon.md) in UI Guidelines.
> See [](tool_windows.md#tool-window-notification) for showing balloons for a specific tool window.
diff --git a/topics/user_interface_components/tool_windows.md b/topics/user_interface_components/tool_windows.md
index b2344d7d8..def7bd689 100644
--- a/topics/user_interface_components/tool_windows.md
+++ b/topics/user_interface_components/tool_windows.md
@@ -8,7 +8,7 @@
**Product Help:** [Tool windows](https://www.jetbrains.com/help/idea/tool-windows.html)
-**Platform UI Guidelines:** [Tool window](https://jetbrains.design/intellij/components/tool_window/)
+**UI Guidelines:** [](tool_window.md)
@@ -32,7 +32,7 @@ The extension point attributes specify all the data which is necessary to displa
* The `id` attribute (required) of the tool window which corresponds to the text displayed on the tool window button.
To provide a localized text, specify matching `toolwindow.stripe.[id]` message key (escape spaces with `_`) in the [resource bundle](plugin_configuration_file.md#idea-plugin__resource-bundle) (code insight supported in 2020.3 and later).
-* The `icon` to display on the tool window button (13x13 pixels, grey and monochromatic; see [Tool window](https://jetbrains.design/intellij/components/tool_window/#07) in IntelliJ Platform UI Guidelines and [](icons.md))
+* The `icon` to display on the tool window button (13x13 pixels, grey and monochromatic; see [](tool_window.md) in UI Guidelines and [](icons.md))
* The `anchor`, meaning the side of the screen on which the tool window is displayed ("left" (default), "right" or "bottom")
diff --git a/topics/user_interface_components/ui_faq.md b/topics/user_interface_components/ui_faq.md
index fa33bdb70..197375ec5 100644
--- a/topics/user_interface_components/ui_faq.md
+++ b/topics/user_interface_components/ui_faq.md
@@ -31,6 +31,12 @@ A number of hardcoded colors is defined in `JBColor`, [`Gray`](%gh-ic%/platform/
## Text
+
+
+**UI Guidelines:** [](data_formats.md)
+
+
+
Use [`NaturalComparator`](%gh-ic%/platform/util/base/src/com/intellij/openapi/util/text/NaturalComparator.java) for "natural" sorting of items.
[`StringUtil`](%gh-ic%/platform/util/src/com/intellij/openapi/util/text/StringUtil.java) contains a number of useful methods for manipulating text for UI usage:
@@ -57,6 +63,13 @@ To determine the current [Theme](themes_getting_started.md)'s style, use [`JBCol
## Borders and Insets
+
+
+
+**UI Guidelines:** [](layout.md)
+
+
+
Always create borders and insets via factory methods from [`JBUI.Borders`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/JBUI.java) and [`JBUI.Insets`](%gh-ic%/platform/util/ui/src/com/intellij/util/ui/JBUI.java), which create DPI-aware instances.
Using standard DPI-agnostic instances (reported by inspection Plugin DevKit | Code | Use DPI-aware borders and Plugin DevKit | Code | Use DPI-aware insets)
can result in UI layout problems.
diff --git a/topics/user_interface_components/user_interface_components.md b/topics/user_interface_components/user_interface_components.md
index 75b42262f..fbde48fd3 100644
--- a/topics/user_interface_components/user_interface_components.md
+++ b/topics/user_interface_components/user_interface_components.md
@@ -1,4 +1,4 @@
-
+
# User Interface Components
@@ -6,7 +6,7 @@
-**Platform UI Guidelines:** [Overview](https://jetbrains.design/intellij/)
+**UI Guidelines:** [Overview](ui_guidelines_welcome.md)
@@ -27,9 +27,9 @@ Using those components in your plugins will ensure that your plugin looks and wo
>
{style="note"}
-Please refer to [Writing short and clear](https://jetbrains.design/intellij/text/writing_short/) in IntelliJ Platform UI Guidelines on writing UI-related texts.
+Please refer to [](writing_short.md) in UI Guidelines on writing UI-related texts.
-See [UI Kit](https://jetbrains.design/intellij/resources/UI_kit/) when using [Figma](https://www.figma.com) to design UI.
+See [](UI_kit.md) when using [Figma](https://www.figma.com) to design UI.
The following components are particularly noteworthy: