UX-3614 Tool Window Guideline #1649

eldar-jetbrains · 2025-10-20T15:15:47Z

No description provided.

topics/ui/components/tool_window.md

OlyaB · 2025-11-03T14:59:20Z

topics/ui/components/tool_window.md

+#### Visibility

-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).
+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, <control>Version Control</control> or <control>Problems</control>. Otherwise, hide the tool window button by default. Hidden tool windows are still available under <control>More tool windows</control> menu.


Possibly show an illustration for this case?

Hmm, I think this case is self-explanatory. I also don't know what kind of image could be added here. Do you have suggestions?

OlyaB · 2025-11-03T14:59:43Z

topics/ui/components/tool_window.md

+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, <control>Version Control</control> or <control>Problems</control>. Otherwise, hide the tool window button by default. Hidden tool windows are still available under <control>More tool windows</control> menu.

-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.
+Don't show the tool window button if the tool window is not relevant to the current project configuration. For example, don't show the <control>Maven</control> tool window for a project without Maven configuration files.


Show the More tool window menu illustration?

topics/ui/components/tool_window.md

OlyaB · 2025-11-03T16:02:43Z

topics/ui/components/tool_window.md

+#### Visibility

-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).
+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, <control>Version Control</control> or <control>Problems</control>. Otherwise, hide the tool window button by default. Hidden tool windows are still available under <control>More tool windows</control> menu.


Possibly add a link to the Empty state article for a tool window without content?

I’d suggest adding an empty state for the tool window right here. Or would that make it too heavy? It seems like this is one of the possible states, and I’d expect to see it in this article. Maybe it could be an exercise for the future if Eldar doesn’t want to deal with it right now :)

WildSeaTurtle · 2025-11-03T18:29:55Z

topics/ui/components/tool_window.md

 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.
+## When not to use


For me, it feels like the examples in this paragraph are too specific. I don’t think all these things are shown in the editor only because they contain a small amount of information. The same goes for Settings and SE. Maybe we could rephrase the “When to use” part and remove this section completely?
I tried to make an example:
Tool windows provide access to information, tools, and services that support coding. They let users manage the project, run and debug applications, track changes, and work with external systems — all without leaving the main workspace.

I kinda agree with you. We also wanted to write an article about what kind of layout (tw, popup, or dialog) to use in which case, so we can add a link to it later here

WildSeaTurtle · 2025-11-03T18:34:39Z

topics/ui/components/tool_window.md

+
+<!--**Exception:** <control>Problems</control> and <control>Event Log</control> icons change color and show the current status.-->
+
+### Tabs


I think it would be useful to add a link to the Tabs article (better check my new one) or the Group Controls article

WildSeaTurtle · 2025-11-03T18:37:33Z

topics/ui/components/tool_window.md

+
+### Tabs
+
+Add tabs if all the information does not fit on one screen or refers to similar instances, like run sessions, history for files, find results. The tabs for entities should be closable.


This is partly true. Some tabs don’t close, for example, the Log tab. There’s also a Home tab in the Profiler.

the closable part is only about the same entities. I rewrote this part, hope it's understandable now

WildSeaTurtle · 2025-11-03T18:43:58Z

topics/ui/components/tool_window.md

+
+### Tabs
+
+Add tabs if all the information does not fit on one screen or refers to similar instances, like run sessions, history for files, find results. The tabs for entities should be closable.


I’d suggest rephrasing the sentence. Right now it sounds like if the content doesn’t fit on one screen, you should add tabs. For example, the Log tab can have thousands of screens worth of content, but that’s not really how tabs are meant to work. Maybe we could take a line directly from the Tabs article and say: Use tabs to organize related content.

topics/ui/components/tool_window.md

WildSeaTurtle · 2025-11-03T18:48:38Z

topics/ui/components/tool_window.md

+#### Visibility

-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).
+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, <control>Version Control</control> or <control>Problems</control>. Otherwise, hide the tool window button by default. Hidden tool windows are still available under <control>More tool windows</control> menu.


I’d suggest adding an empty state for the tool window right here. Or would that make it too heavy? It seems like this is one of the possible states, and I’d expect to see it in this article. Maybe it could be an exercise for the future if Eldar doesn’t want to deal with it right now :)

WildSeaTurtle · 2025-11-03T18:51:16Z

topics/ui/components/tool_window.md

-![](tool_window_structure.png){width=483}
+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, the <control>Search Everywhere</control> popup, <control>Settings</control> dialog.
+
+## Tool window structure


Also, maybe it makes sense to add information about speed search. How it works in the tool window, or, if we have a separate article, include a link to it. What do you think?

I'll see what I can do. The Search field guideline is also on me right now. When we publish it, I'll add a link somewhere here

UX-3614 Tool Window Guideline update with texts and images

cffdbca

eldar-jetbrains requested review from OlyaB and WildSeaTurtle October 20, 2025 15:15

eldar-jetbrains self-assigned this Oct 20, 2025

OlyaB requested changes Nov 3, 2025

View reviewed changes

WildSeaTurtle approved these changes Nov 3, 2025

View reviewed changes

UX-3614 Tool Window Guideline update during review

20c8cec


		<!--Exception: <control>Problems</control> and <control>Event Log</control> icons change color and show the current status.-->

		### Tabs


		### Tabs

		Add tabs if all the information does not fit on one screen or refers to similar instances, like run sessions, history for files, find results. The tabs for entities should be closable.

UX-3614 Tool Window Guideline #1649

Are you sure you want to change the base?

UX-3614 Tool Window Guideline #1649

Uh oh!

Conversation

eldar-jetbrains commented Oct 20, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants