UX-3157, Small text fixes, added alternative texts

topics/Window-sizes.md

@@ -6,19 +6,19 @@
 
 Follow these guidelines to select the correct size when creating a dialog or a popup for IntelliJ-based products.
 
-For simple cases use default sizes for [dialogs](Window-sizes.md#default-sizes) and [popups](Window-sizes.md#popup). When default sizes don't work well, set [minimum sizes for components](Window-sizes.md#minimum-sizes-for-components).
+For simple cases use [default sizes](Window-sizes.md#default-sizes). When they don't work well, set [minimum sizes for components](Window-sizes.md#minimum-sizes-for-components).
 
 ## Default sizes
 
 ### Dialog
 
-There are four recommended window sizes for dialogs: **extra small**, **small**, **medium**, and **large**. Select the size depending on the amount of content to keep the important information visible.
+There are four recommended window sizes for dialogs: **small**, **medium**, **large**, and **extra large**. Select the size depending on the amount of content to keep the important information visible.
 
 ![A preview of recommended window sizes for dialogs: extra small, small, medium, and large](dialog_popup_sizes.png){width="706"}
 
-<note>When setting the default size for your dialog, it should be impossible to make it smaller.</note>
+<note>A dialog can't be made smaller than the default size.</note>
 
-#### Extra small
+#### Small
 
 Size: 350×250 px.
 
@@ -26,7 +26,7 @@ Best for: several components that are stacked vertically.
 
 ![The Rename dialog with two input fields, two checkboxes, and actions in the dialog footer. The components are stacked vertically in one column](dialog_popup_sizes_extra_small.png){width="706"}
 
-#### Small
+#### Medium
 
 Size: 500×350 px
 
@@ -39,207 +39,216 @@ For example, the <control>Evaluate Expressions</control> dialog has an input fie
 
 ![The Evaluate Expressions dialog that has an input field with long text and a tree with code stacked vertically](dialog_popup_sizes_small.png){width="706"}
 
-#### Medium
+#### Large
 
 Size: 750×525 px
 
 Best for:
 * A full-width table with four or more columns.
-* Two-column layout with an image or a video in any of the columns. In this case, the image or the video takes the most space.
+* A master-detail layout.
 * Two-column layout with a code snippet or an input field with long text in any of the columns.
 * Two code snippets or input fields with long texts in a row.
+* Two-column layout with an image or a video in any of the columns. In this case, the image or the video takes the most space.
 
-For example, the <control>Run/Debug Configuration</control> dialog has a two-column layout with a tree in the first column and the list of controls with long texts in the second column:
+For example, the <control>Run/Debug Configuration</control> dialog has a master-detail layout with a tree in the first column and the list of controls with long texts in the second column:
 
 ![The Run/Debug Configuration dialog that has a two-column layout. There is a navigation in the first column and the list of settings in the second column](dialog_popup_sizes_medium.png){width="706"}
 
-#### Large
+#### Extra Large
 
 Size: 1000×700 px
 
 Best for:
-* Two-column layout with input fields with long texts, code snippets.
+* Two-column layout with code snippets or input fields with long texts in both columns.
 * Three-or-more-column layout regardless of the content.
 
 For example, <control>Code Style</control> settings for Java in the <control>Settings</control> dialog. The dialog has three columns with a tree, a table, and a code snippet in different columns:
 
 ![The Code Style settings in the Settings dialog. The dialog has three columns with a tree, a table, and a code snippet in different columns](dialog_popup_sizes_large.png){width="706"}
 
+#### Maximum width and height {id="maximum-width-and-height_dialog"}
+
+Set the dialog's maximum dimensions to match screen size to prevent resizing beyond screen bounds.
+
 ### Popup
 
-#### Minimum width
+Popups should have the same default width as dialogs. In addition, there is an **extra small** size for popups – 200 px wide, when the content is narrow.
+
+<note>A popup can't be made smaller than the default size.</note>
+
+#### Action Popups
+
+If a popup has a vertical list of actions or options, set a default width to either **extra small** (200 px) or **small** (350 px).
+
+The width and height are adaptable based on the content if it exceeds the set dimensions.
 
-Popups should have the same default width as dialogs. In addition, there is a smaller size for popups – 200 px wide, when the content is narrow.
 
 <table style="none" border="false">
    <tr>
       <td width="50%">
-         <p><format style="bold">Insert</format></p>
+         <p><control>Extra small</control></p>
          <img src="dialog_popup_sizes_popup_xxs.png" alt="Insert popup 200 px wide" width="378"/>
       </td>
       <td width="50%">
-         <p><format style="bold">Quick Fixes</format></p>
+         <p><control>Small</control></p>
          <img src="dialog_popup_sizes_popup_xs.png" alt="Quick Fixes popup 350 px wide" width="378"/>
       </td>
    </tr>
 </table>
+
+#### Content-rich Popups
+
+If a popup has several sections and features long texts, set a default width to **medium** (500 px) or **large** (750 px).
+
+Height is adaptable based on the content. If a popup has a scrollable content, set the default height respectively: **medium** (350 px) or **large** (525 px).
+
 <table style="none" border="false">
    <tr>
       <td width="100%">
-         <p><format style="bold">Documentation</format></p>
-         <img src="dialog_popup_sizes_popup_s.png" alt="Documentation popup 500 px wide" width="706"/>
+         <p><control>Medium</control></p>
+         <img src="dialog_popup_sizes_popup_adaptive_height.png" alt="Documentation popup 500 px wide" width="706"/>
       </td>
    </tr>
    <tr>
       <td width="100%">
-         <p><format style="bold">Search Everywhere</format></p>
+         <p><control>Large</control></p>
          <img src="dialog_popup_sizes_popup_m.png" alt="Search Everywhere popup 750 px wide" width="706"/>
       </td>
    </tr>
 </table>
 
-#### Minimum height
-
-Unlike dialogs, popups have an adaptive height. Adapt the height of a popup to the amount of content inside.
-
-For example, the height of the <control>Documentation</control> popup is different depending on what is focused in the editor:
-
-<img src="dialog_popup_sizes_popup_adaptive_height.png" alt="The Documentation popup adapts its height based on the content inside"/>
+When the default width doesn't work, set [minimum sizes for components](Window-sizes.md#minimum-sizes-for-components).
 
 #### Maximum width and height
 
-The maximum width and height shouldn't exceed 80% of a screen size. Use a <control>scrollbar</control> if a popup's content doesn't fit within the set dimensions.
+The maximum width and height shouldn't exceed 80% of a screen size. Use a [scrollbar](scrollbar.md) if a popup's content doesn't fit within the set dimensions.
 
 ### Tool windows
 
 Default sizes:
 
-* Vertical tool windows should take 20% of the application width but not less than 200×500&nbsp;px.
-* Horizontal tool windows should take 20% of the application height but not less than 500×200&nbsp;px.
+* Vertical tool windows should take minimum 20% of the application width but not less than 200×500&nbsp;px.
+* Horizontal tool windows should take minimum 20% of the application height but not less than 500×200&nbsp;px.
 
 The default sizes should be set for all the states of the <control>View Mode</control>.
 
-<table style="none" border="false">
-    <tr>
-        <td width="50%">
-            Vertical <control>Project</control> tool window:
-            <img src="dialog_popup_sizes_tool_window_vertical.png" alt="Vertical Project tool window set in the default size for tool windows"/>
-        </td>
-        <td width="50%">
-            Horizontal <control>Build</control> tool window:
-            <img src="dialog_popup_sizes_tool_window_horizontal.png" alt="Horizontal Build window set in the default size for tool windows"/>
-        </td>
-    </tr>
-</table>
+<note>A tool window can't be made smaller than the default size.</note>
+
+For example, the vertical <control>Project</control> tool window and the horizontal <control>Build</control> tool window with minimum sizes in <control>Window</control> mode:
+
+![Vertical Project and horizontal Build tool windows with the default sizes in Window mode](dialog_popup_sizes_tool_window.png){width="706"}
+
 
 ## Minimum sizes for components
 
-When the default sizes are either too big or too small for a window, or the window has a complex layout, add minimum sizes to important content inside the window. This will make the content displayed correctly and reduce any potential issues caused by resizing the window.
+When the default sizes are either too big or too small for a window, or the window has a complex layout, add minimum sizes to content inside the window. This will make the content displayed correctly and reduce any potential issues caused by resizing the window.
 
 ### How to set the size correctly
 
-1. Select how the content is displayed:
+1. Select how the content is displayed.
+2. What type of content is used.
+3. Select the biggest size out of the two to add the minimum size to a component.
 
-    <table style="none" border="false">
-        <tr>
-            <td width="50%">
-               <img src="dialog_popup_sizes_table_cell.png" alt="Example of a table with 3 cells" width="378"/>
-            </td>
-            <td>
-               <p><format style="bold">Table cell</format></p>
-               <p>Width: min&nbsp;65&nbsp;px</p>
-               <p>Height for the whole table: min&nbsp;120&nbsp;px</p>
-               <p>Follow guidelines for <a href="table.md" anchor="sizes">table sizes</a></p>
-            </td>
-        </tr>
-        <tr>
-            <td width="50%">
-                <img src="dialog_popup_sizes_tree.png" alt="Example of a tree" width="378"/>
-            </td>
-            <td>
-               <p><format style="bold">Tree</format></p>
-                <p>Width: min 250&nbsp;px</p>
-            </td>
-        </tr>
-        <tr>
-            <td width="50%">
-                <img src="dialog_popup_sizes_text_area.png" alt="Example of a text area" width="378"/>
-            </td>
-            <td>
-                <p><format style="bold">Text area</format></p>
-                <p>Width: min&nbsp;270&nbsp;px, max&nbsp;600&nbsp;px</p>
-                <p>Height: min&nbsp;55&nbsp;px</p>
-                <p>Follow guidelines for <a href="text_area.md" anchor="size-and-placement">text area sizes</a></p>
-            </td>
-        </tr>
-        <tr>
-            <td width="50%">
-                <img src="dialog_popup_sizes_diagram.png" alt="Example of a diagram" width="378"/>
-            </td>
-            <td>
-                <p><format style="bold">Diagram</format></p>
-                <p>A container with horizontal and vertical insets with 100&nbsp;px</p>
-            </td>
-        </tr>
-    </table>
+#### How the content is displayed
 
-2. What type of content is used:
+<table style="none" border="false">
+   <tr>
+      <td width="50%">
+         <img src="dialog_popup_sizes_table_cell.png" alt="Example of a table with 3 cells" width="378"/>
+      </td>
+      <td>
+         <p><format style="bold">Table cell</format></p>
+         <p>Width: min&nbsp;65&nbsp;px</p>
+         <p>Height for the whole table: min&nbsp;120&nbsp;px</p>
+         <p>Follow guidelines for <a href="table.md" anchor="sizes">table sizes</a></p>
+      </td>
+   </tr>
+   <tr>
+      <td width="50%">
+          <img src="dialog_popup_sizes_tree.png" alt="Example of a tree" width="378"/>
+      </td>
+      <td>
+         <p><format style="bold">Tree</format></p>
+          <p>Width: min 250&nbsp;px</p>
+      </td>
+   </tr>
+   <tr>
+      <td width="50%">
+          <img src="dialog_popup_sizes_text_area.png" alt="Example of a text area" width="378"/>
+      </td>
+      <td>
+          <p><format style="bold">Text area</format></p>
+          <p>Width: min&nbsp;270&nbsp;px, max&nbsp;600&nbsp;px</p>
+          <p>Height: min&nbsp;55&nbsp;px</p>
+          <p>Follow guidelines for <a href="text_area.md" anchor="size-and-placement">text area sizes</a></p>
+      </td>
+   </tr>
+   <tr>
+      <td width="50%">
+          <img src="dialog_popup_sizes_diagram.png" alt="Example of a diagram" width="378"/>
+      </td>
+      <td>
+          <p><format style="bold">Diagram</format></p>
+          <p>A container with horizontal and vertical insets with 100&nbsp;px</p>
+      </td>
+   </tr>
+</table>
 
-   <table style="none" border="false">
-        <tr>
-            <td width="50%">
-                <img src="dialog_popup_sizes_class_test_file.png" alt="Examples of a class, test, and file name" width="378"/>
-            </td>
-            <td>
-                <p><format style="bold">Class/test/file name</format></p>
-                <p>Width: min&nbsp;250&nbsp;px</p>
-            </td>
-        </tr>
-        <tr>
-            <td width="50%">
-                <img src="dialog_popup_sizes_url_path_fqn.png" alt="Examples of a URL, path, and an FQN for class" width="378"/>
-            </td>
-            <td>
-                <p><format style="bold">URL/Path/FQN for class</format></p>
-                <p>Width: min&nbsp;350&nbsp;px</p>
-            </td>
-        </tr>
-        <tr>
-            <td width="50%">
-                <img src="dialog_popup_sizes_class_test_file_url_path_fqn.png" alt="Examples of a class, test, or file name together with a URL, path or an FQN for class" width="378"/>
-            </td>
-            <td>
-                <p><format style="bold">Class/test/file name + URL/Path/FQN for class</format></p>
-                <p>Width: min&nbsp;400&nbsp;px</p>
-            </td>
-        </tr>
-        <tr>
-            <td width="50%">
-                <img src="dialog_popup_sizes_code_snippet.png" alt="Example of a code snippet" width="378"/>
-            </td>
-            <td>
-                <p><format style="bold">Code snippet or editor</format></p>
-                <p>Width: min&nbsp;400&nbsp;px</p>
-                <p>Height (when multiple lines): min&nbsp;120&nbsp;px</p>
-            </td>
-        </tr>
-        <tr>
-            <td width="50%">
-                <img src="dialog_popup_sizes_standalone_text.png" alt="Example of a paragraph" width="378"/>
-            </td>
-            <td>
-                <p><format style="bold">Paragraph or long text</format></p>
-                <p>Width: min&nbsp;300&nbsp;px</p>
-                <p>Height (when multiple lines): min&nbsp;120&nbsp;px</p>
-            </td>
-        </tr>
-    </table>
+#### Types of content
 
-3. Select the biggest size out of the two to add the minimum size to a component
+<table style="none" border="false">
+   <tr>
+      <td width="50%">
+          <img src="dialog_popup_sizes_class_test_file.png" alt="Examples of a class, test, and file name" width="378"/>
+      </td>
+      <td>
+          <p><format style="bold">Class/test/file name</format></p>
+          <p>Width: min&nbsp;250&nbsp;px</p>
+      </td>
+   </tr>
+   <tr>
+      <td width="50%">
+          <img src="dialog_popup_sizes_url_path_fqn.png" alt="Examples of a URL, path, and an FQN for class" width="378"/>
+      </td>
+      <td>
+          <p><format style="bold">URL/Path/FQN for class</format></p>
+          <p>Width: min&nbsp;350&nbsp;px</p>
+      </td>
+   </tr>
+   <tr>
+      <td width="50%">
+          <img src="dialog_popup_sizes_class_test_file_url_path_fqn.png" alt="Examples of a class, test, or file name together with a URL, path or an FQN for class" width="378"/>
+      </td>
+      <td>
+          <p><format style="bold">Class/test/file name + URL/Path/FQN for class</format></p>
+          <p>Width: min&nbsp;400&nbsp;px</p>
+      </td>
+   </tr>
+   <tr>
+      <td width="50%">
+          <img src="dialog_popup_sizes_code_snippet.png" alt="Example of a code snippet" width="378"/>
+      </td>
+      <td>
+          <p><format style="bold">Code snippet or editor</format></p>
+          <p>Width: min&nbsp;400&nbsp;px</p>
+          <p>Height (when multiple lines): min&nbsp;120&nbsp;px</p>
+      </td>
+   </tr>
+   <tr>
+      <td width="50%">
+          <img src="dialog_popup_sizes_standalone_text.png" alt="Example of a paragraph" width="378"/>
+      </td>
+      <td>
+          <p><format style="bold">Paragraph or long text</format></p>
+          <p>Width: min&nbsp;300&nbsp;px</p>
+          <p>Height (when multiple lines): min&nbsp;120&nbsp;px</p>
+      </td>
+   </tr>
+ </table>
 
 #### Example 1
 
-The <control>Rename Inheritors</control> dialog has a table with FQNs. Add 350&nbsp;px as the minimum width for a table column. This will make the dialog wider than the recommended 500&nbsp;px but will show more of FQNs.
+The <control>Rename Inheritors</control> dialog has a table with FQNs. Add 350&nbsp;px as the minimum width for a table column. This will make the dialog wider than the default <control>Small</control> size (500&nbsp;px) but will show more of FQNs.
 
 <table style="none" border="false">
     <tr>
@@ -277,20 +286,20 @@ The <control>Rename Inheritors</control> dialog has a table with FQNs. Add 350&n
 
 #### Example 3
 
-Add horizontal and vertical 100&nbsp;px insets inside the <control>Diagram</control> popup to make it adaptable to the different amounts of content inside.
+Instead of setting a default size for a diagram popup, for example, the <control>Small</control> size, add horizontal and vertical 100&nbsp;px insets inside the <control>Diagram</control> popup, and make the width and height adaptive to its content. This will help small diagrams be more noticeable and make a diagram popup of any size easier to read.
 
 <table style="none" border="false">
     <tr>
-         <td width="706">
+        <td width="706">
             <format color="369650" style="bold">Correct</format>
             <img src="dialog_popup_sizes_example_3_correct.png" alt="Diagram popup has 100 px insets from its borders to its content"/>
-         </td>
+        </td>
     </tr>
     <tr>
-         <td width="706">
+        <td width="706">
             <format color="DarkOrange" style="bold">Acceptable</format>
             <img src="dialog_popup_sizes_example_3_acceptable.png" alt="Diagram popup is set to the default small size"/>
-         </td>
+        </td>
     </tr>
 </table>
 
@@ -302,15 +311,15 @@ For example, the size of the <control>Custom Plugin Repository</control> dialog
 
 <table style="none" border="false">
     <tr>
-         <td width="706">
+        <td width="706">
             <format color="369650" style="bold">Correct</format>
             <img src="dialog_popup_sizes_empty_state_correct.png" alt="The table in the Custom Plugin Repository dialog has the same sizes in both empty and filled states"/>
-         </td>
+        </td>
     </tr>
     <tr>
-         <td width="706">
+        <td width="706">
             <format color="E55765" style="bold">Incorrect</format>
             <img src="dialog_popup_sizes_empty_state_incorrect.png" alt="The table in the Custom Plugin Repository dialog has different sizes in the empty and the filled states"/>
-         </td>
+        </td>
     </tr>
 </table>