Button page updated

topics/basics/plugin_required_experience.md

@@ -2,7 +2,7 @@
 
 # Required Experience
 
-<link-summary>Required technology knowledge.</link-summary>
+<link-su=mmary>Required technology knowledge.<link-summary>
 
 The IntelliJ Platform is a JVM application, implemented mostly in Java and [Kotlin](https://kotlinlang.org).
 At this time, it's not possible to develop plugins for the IntelliJ Platform in non-JVM languages.
@@ -20,4 +20,4 @@ Developing a plugin will sometimes require digging into the [IntelliJ Platform c
 
 It's highly recommended to get familiar with the [](explore_api.md) section before you start the plugin implementation.
 
-<include from="intellij_platform.md" element-id="pluginAlternatives"/>
+<include from="intellj_platform.md" element-id="pluginAlternatives"/>

topics/ui/controls/button.topic

@@ -9,263 +9,208 @@
 
     <tldr>
         <p>
-            <b>Implementation:</b>
+            <control>Implementation</control>:
-            <a href="https://docs.oracle.com/javase/tutorial/uiswing/components/button.html"><code>JButton</code></a>
+            <a href="https://docs.oracle.com/javase/tutorial/uiswing/components/button.html">JButton</a>
+        </p>
+        <p>
+            <control>Specification</control>: <a href="https://www.figma.com/design/w8GWsQsHF3XdjdcN1E3X3n/Int-UI-Kit?node-id=733-46953">Button</a>
+
         </p>
     </tldr>
 
-    <img src="button_example.png" alt="Cancel and Save buttons" width="156"/>
+    <img src="button_example.png" alt="Cancel and Save buttons" width="706"/>
     <chapter title="When to use" id="when-to-use">
-
+        <p>Use a button to invoke an immediate action:</p>
-        <chapter title="Using a button" id="using-a-button">
+        <img src="when_to_use_button.png" alt="When to use a button" width="706"/>
-            Use a button to invoke an immediate action.
+    </chapter>
-        </chapter>
+        <chapter title="When not to use" id="when-not-to-use">
-
+        <table style="none">
-
-        <chapter title="Using a link" id="using-a-link">
-        <p>Use a <a href="link.md">link</a> instead a button if:</p>
-        <list>
-            <li>
-                <p>The action takes the user to another page of the same dialog or an external source like
-                    documentation:</p>
-                <img src="link_after.png" alt="The 'Manage scopes' button next to a combo box" width="465"/>
-                <p>
-                    <emphasis>The Manage scope link takes to another page of the Settings dialog.</emphasis>
-                </p>
-                <p>
-                    <b>Exception</b>: Next and Previous buttons in wizard navigation.
-                </p>
-            </li>
-            <li>
-                <p>
-                    The command is a secondary action that is not related to the primary purpose of the window,
-                    and the space is constrained.
-                </p>
-                <table>
-                    <tr>
-                        <td width="50%">
-                            <p>
-                                <format color="Red" style="bold">Incorrect</format>
-                            </p>
-                        </td>
-                        <td width="50%">
-                            <p>
-                                <format color="Green" style="bold">Correct</format>
-                            </p>
-                        </td>
-                    </tr>
-                    <tr>
-                        <td>
-                            <img src="link_incorrect.png"
-                                 alt="A 'Configure...' button next to a checkbox"
-                                 width="313"/>
-                        </td>
-                        <td>
-                            <img src="link_correct.png"
-                                 alt="A 'Configure' link next to a checkbox"
-                                 width="272"/>
-                        </td>
-                    </tr>
-                </table>
-            </li>
-        </list>
-        </chapter>
-        <chapter title="Using a toolbar button" id="using-a-toolbar-button">
-        <p>Use toolbar buttons instead if there are several buttons related to a table or list:</p>
-        <table>
             <tr>
-                <td width="50%">
+                <td width="50%"><img src="link_instead_of_button.png" alt="Using links instead of buttons" width="378"/></td>
-                    <p>
+                <td><p>Use a link instead if:</p>
-                        <format color="Red" style="bold">Incorrect</format>
+                    <list>
-                    </p>
+                    <li><p>The action takes the user to another page of the same dialog or an external source like
-                </td>
+                        documentation.</p>
-                <td width="50%">
+                        <tip>Exception: the <control>Next</control> and <control>Previous</control> buttons in wizard navigation.</tip>
-                    <p>
+                    </li>
-                        <format color="Green" style="bold">Correct</format>
+                    <li>
-                    </p>
+                        The command is a secondary action that isn't related to the primary purpose of the window,
+                        and the space is constrained.
+                    </li>
+                    </list>
                 </td>
             </tr>
             <tr>
-                <td>
+                <td width="50%"><img src="toolbar_button.png" alt="Using toolbar buttons instead of buttons" width="378"/></td>
-                    <img src="many_buttons.png" alt="Many regular buttons in a single place" width="370"/>
+                <td><p>Use a <a href="toolbar.md">toolbar button</a> instead if there are several buttons related to a table or list.</p>
                 </td>
-                <td><img src="toolbar.png" alt="Toolbar buttons" width="220"/></td>
             </tr>
-        </table>
+            <tr>
-        </chapter>
+                <td width="50%"><img src="split_button.png" alt="Using split buttons instead of buttons" width="378"/></td>
-    <chapter title="Use a split button instead" id="use-a-split-button-instead">
+                <td><p>Use a <a href="split_button.md">split button</a> instead if:</p>
-        <p>Use a <a href="split_button.md">split button</a> instead if:</p>
+                    <list>
-        <list>
+                        <li>There are more than two related actions, but the space is limited and/or packed.</li>
-            <li>There are several related actions (more than 2), but the space is limited and/or packed.</li>
+                        <li>The action isn't common and is dangerous, for example, can destroy user data and cannot be easily
-            <li>The action is not common and is dangerous, for example, can destroy user data and cannot be easily
+                            undone.
-                undone.
+                        </li>
-            </li>
+                    </list>
-        </list>
+                </td>
-        <p>Use a <a href="built_in_button.md">built-in button</a> instead if it's related to an input field, combo box,
+            </tr>
-            search field.</p>
+            <tr>
-    </chapter>
+                <td width="50%">
-    </chapter>
+                    <img src="built-in_button.png" alt="Using built-in buttons instead of buttons" width="378"/>
-
+                </td>
+                <td><p>Use a <a href="built_in_button.md">built-in button</a> instead if it's related to an input field, combo box,
+                    search field.</p>
+                </td>
+            </tr>
+</table>
+</chapter>
 
     <chapter title="How to use" id="how-to-use">
-        <chapter title="Label" id="label">
             <p>The label displays the action the button performs.</p>
-            <chapter title="Imperative">
+            <chapter title="Use title capitalization" id="use-title-capitalization">
-            <p>Write the label as an imperative verb, e.g. Save, Print, Cancel. Use title capitalization.</p>
+        <p>Use <a href="capitalization.md">title capitalization</a> for button labels.</p>
-            <note><p>Exceptions: standard buttons like OK, Back/Forward, Previous/Next, Yes/No, Agree, Options, Settings, Details.
-            </p></note>
             </chapter>
-            <chapter title="Specific" id="specific">
+            <chapter title="Use imperative verbs" id="use-imperative-verbs">
+            <p>Write the label as an imperative verb, for example, Save, Print, Cancel. Use title capitalization.</p>
+            <tip><p>Exceptions: standard buttons like <control>OK</control>, <control>Back</control>/<control>Forward</control>,
+                <control>Previous</control>/<control>Next</control>, <control>Yes</control>/<control>No</control>, <control>Agree</control>,
+                <control>Options</control>, <control>Settings</control>, <control>Details</control>.
+            </p></tip>
+            </chapter>
+            <chapter title="Be specific" id="be-specific">
             <p>The button should answer the question in the title, so the user can skip the description. Prefer specific
                 labels over
                 generic ones:</p>
-            <table>
-                <tr>
-                    <td width="50%">
-                        <p>
-                            <format color="Red" style="bold">Incorrect</format>
-                        </p>
-                    </td>
-                    <td width="50%">
-                        <p>
-                            <format color="Green" style="bold">Correct</format>
-                        </p>
-                    </td>
-                </tr>
-                <tr>
-                    <td><img src="default_OK.png" alt="An incorrect button with a generic 'OK' label" width="72"/>
-                        <p>Unclear what happens on the click.</p></td>
-                    <td><img src="default_save.png" alt="A correct button with a clear 'Save' label" width="72"/>
-                        <p>The label indicates what happens on the click.</p></td>
-                </tr>
-            </table>
-            <note>
-                Exception: the Cancel button if it is clear what action is being canceled.
-                For example, use the
-                <control>Cancel</control>
-                button, not the
-                <control>Don’t Create</control>
-                button.
-            </note>
-            </chapter>
-            <chapter title="Short" id="short">
-            <p>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:</p>
-            <table>
-                <tr>
-                    <td width="50%">
-                        <p>
-                            <format color="DarkOrange" style="bold">Acceptable</format>
-                        </p>
-                    </td>
-                    <td width="50%">
-                        <p>
-                            <format color="Green" style="bold">Better</format>
-                        </p>
-                    </td>
-                </tr>
-                <tr>
-                    <td>
-                        <img src="active_edit.png" alt="A button with 'Edit...' label" width="72"/>
-                    </td>
-                    <td>
-                        <img src="active_edit_action_icon.png"
-                             alt="A button with 'Edit Action Icon...' label"
-                             width="146"/>
-                    </td>
-                </tr>
-            </table>
-            </chapter>
-            <chapter title="Ellipsis" id="ellipsis">
-            <p>
-                Add an ellipsis if additional actions such as adding more info or confirming the action are required:
-                <img src="buttons_with_ellipsis.png" alt="Buttons with ellipsis" width="146" style="block"/>
-            </p>
-            <p>Do
-                <control>not</control>
-                add ellipsis if another window is opened, but no more input from the user is required. For example,
-                About, Details.
-            </p>
-            <p>Do <b>not</b>
-                use the word
-                <emphasis>Now</emphasis>
-                in the label because buttons always trigger an immediate action:
-            </p>
-
-            <table>
-                <tr>
-                    <td width="50%">
-                        <p>
-                            <format color="Red" style="bold">Incorrect</format>
-                        </p>
-                    </td>
-                    <td width="50%">
-                        <p>
-                            <format color="Green" style="bold">Better</format>
-                        </p>
-                    </td>
-                </tr>
-                <tr>
-                    <td><img src="check_now.png" alt="A button with 'Check Now' label" width="336"/></td>
-                    <td>
-                        <img src="check_for_updates.png" alt="A button with 'Check for Updates' label" width="384"/>
-                    </td>
-                </tr>
-            </table>
-            </chapter>
-        </chapter>
-    </chapter>
-
-
-    <chapter title="Button states" id="button-states">
-        <chapter title="Default" id="default">
             <table style="none">
                 <tr>
                     <td width="50%">
-                        <img src="default_save.png" alt="'Save' button on macOS" width="72"/>
                         <p>
-                            <emphasis>macOS</emphasis>
+                            <format color="369650" style="bold">Correct</format>
                         </p>
                     </td>
                     <td width="50%">
-                        <img src="default_save_win.png" alt="'Save' button on Windows" width="72"/>
                         <p>
-                            <emphasis>Windows</emphasis>
+                            <format color="E55765" style="bold">Incorrect</format>
                         </p>
                     </td>
                 </tr>
+                <tr>
+                    <td><img src="default_button_save.png" alt="A correct button with a clear 'Save' label" width="378"/></td>
+                    <td><img src="default_OK.png" alt="An incorrect button with a generic 'OK' label" width="378"/></td>
+                </tr>
             </table>
-            The default button confirms the main purpose of a dialog. It is triggered by pressing
+            <tip>
-            <shortcut>Enter</shortcut>
+                Exception: the <control>Cancel</control> button if it's clear what action is being canceled.
-            or
+                For example, use
-            <shortcut>Ctrl+Enter</shortcut>
+                <control>Cancel</control> instead of <control>Don’t Create</control>.
-            on Windows/Linux and
+            </tip>
-            <shortcut>Enter</shortcut>
+                <p>Do not
-            or
+                    use the word
-            <shortcut>Cmd+Enter</shortcut>
+                    <control>Now</control> in labels because buttons always trigger an immediate action:
-            on macOS.
+                </p>
-            <note>Exception: If the focus is on an element that uses the
+                <table style="none">
-            <shortcut>Enter</shortcut>
+                    <tr>
-            key (e.g., a text area), the default button is triggered only by
+                        <td width="50%">
-            <shortcut>Ctrl+Enter</shortcut>
+                            <p>
-            on Windows/Linux and
+                                <format color="369650" style="bold">Correct</format>
-            <shortcut>Cmd+Enter</shortcut>
+                            </p>
-            on macOS.</note>
+                        </td>
-            <p>The default button should always be present in a dialog. Only one button in a dialog can be the default
+                        <td width="50%">
-                one.</p>
+                            <p>
-            <p>If the action is dangerous, e.g., can lead to data loss, provide an easy way to undo the command.</p>
+                                <format color="E55765" style="bold">Incorrect</format>
-            <p>If it's not possible to undo the action, make a secondary button the default one:
+                            </p>
+                        </td>
+                    </tr>
+                    <tr>
+                        <td>
+                            <img src="check_for_updates.png" alt="A button with 'Check for Updates' label" width="384"/>
+                        </td>
+                        <td><img src="check_now_button.png" alt="A button with 'Check Now' label" width="336"/></td>
+                    </tr>
+                </table>
+            </chapter>
+            <chapter title="Be short and clear" id="short_and_clear">
+            <p>The label should be short, not more than five 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 ones:</p>
+                <table style="none">
+                    <tr>
+                        <td width="50%">
+                            <p>
+                                <format color="369650" style="bold">Correct</format>
+                            </p>
+                        </td>
+                        <td width="50%">
+                            <p>
+                                <format color="DarkOrange" style="bold">Acceptable</format>
+                            </p>
+                        </td>
+
+                    </tr>
+                    <tr>
+                        <td><img src="active_edit_action.png"
+                                 alt="A button with the 'Edit Action Icon...' label"
+                                 width="378"/></td>
+                        <td><img src="active_edit.png" alt="A button with 'Edit...' label" width="378"/></td>
+                    </tr>
+                </table>
+            </chapter>
+            <chapter title="Ellipsis" id="ellipsis">
+                <list>
+                    <li>Add an ellipsis if additional actions such as adding more info or confirming the action are required.
+                    </li>
+                    <li>Don't add an ellipsis if another window is opened, but no more input from the user is required. For example,
+                        <control>About</control>, <control>Details</control>.</li>
+                </list>
+            <img src="buttons_with_ellipsis.png" alt="Buttons with ellipsis" width="706"/>
+            </chapter>
+        </chapter>
+<!--        <chapter title="Icons" id="icons">
+            <p>Don't 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 three buttons
+                are placed nearby, their labels can be scanned quickly, and icons aren't required.
+            </p>
+        </chapter>-->
+
+    <chapter title="Button states" id="button-states">
+        <chapter title="Default" id="default">
+
+            <img src="default_button.png" alt="Default button on macOS and Windows" width="706"/>
+            <list>
+                <li>The default button confirms the main purpose of a dialog. It is triggered by pressing
+                    <shortcut>Enter</shortcut>
+                    or
+                    <shortcut>Ctrl+Enter</shortcut>
+                    on Windows/Linux and
+                    <shortcut>Enter</shortcut>
+                    or
+                    <shortcut>Cmd+Enter</shortcut>
+                    on macOS.
+                    <tip>Exception: if the focus is on an element that uses the
+                        <shortcut>Enter</shortcut>
+                        key, for example, a text area, the default button is triggered only by
+                        <shortcut>Ctrl+Enter</shortcut>
+                        on Windows/Linux and
+                        <shortcut>Cmd+Enter</shortcut>
+                        on macOS.</tip>
+                </li>
+                <li>The default button should always be present in a dialog. Only one button in a dialog can be the default
+                one.
+                </li>
+                <li>If an action is dangerous, for example, it can lead to data loss, provide an easy way to undo the command.</li>
+                <li>If it's not possible to undo the action, make a secondary button the default one:
                 <img src="merge_dialog.png"
                      alt="A dialog with secondary and primary buttons"
-                     width="426"
+                     width="706"/>
-                     style="block"/>
+            </li>
-            </p>
+            </list>
         </chapter>
 
 
         <chapter title="Focused" id="focused">
-            <img src="focused.png" alt="'Cancel' button in a focused state" width="78"/>
+            <img src="focused_button.png" alt="'Cancel' button in a focused state" width="706"/>
             <p>All buttons can get focus, even on macOS if the
                 <control>Full Keyboard Access</control>
                 option is disabled in Preferences &gt; Keyboard &gt;
@@ -278,26 +223,18 @@
                 <list>
                     <li>
                         <p>A focused button is invoked by pressing
-                            <shortcut>Space</shortcut>
+                            <shortcut>Space</shortcut>. Focused and default buttons are
-                            . Focused and default buttons are
+                            <b>independent</b>,
-                            <b>independent</b>
-                            ,
                             so when
                             the focus moves from one button to another, the default button does not change.
                         </p>
                     </li>
                     <li>
                         <p>
-                            Make the second most popular button in the dialog focused.
+                            Make the second most popular button in the dialog focused.It’s recommended to have one default and one focused button, so that most of the actions can be
-                            For example, the
+                            triggered using
-                            <control>New Window</control>
+                            the keyboard.
-                            button in the
+
-                            <control>Open Project</control>
-                            dialog:
-                            <img src="open_project_dialog.png"
-                                 width="448"
-                                 alt="A dialog with buttons: 'New Window' (focused), 'Cancel', and 'This Window' (default)."
-                                 style="block"/>
                         </p>
                     </li>
                     <li>
@@ -305,21 +242,21 @@
                             triggered using
                             the keyboard.</p>
                         <p>
-                            <format color="Red" style="bold">Incorrect</format>
+                            <format color="369650" style="bold">Correct</format>
+                            <img src="open_project_dialog.png"
+                                 width="706"
+                                 alt="A dialog with buttons: 'New Window' (focused), 'Cancel', and 'This Window' (default)."
+                                 style="block"/>
+
+                        </p>
+                        <p>
+                            <format color="E55765" style="bold">Incorrect</format>
                         </p>
                         <img
-                                src="open_project_dialog_incorrect_focus.png"
+                                src="open_project_dialog_incorrect.png"
                                 alt="A dialog with buttons: 'New Window', 'Cancel', and 'This Window' (default and focused)."
-                                width="448"/>
+                                width="706"/>
-                        <emphasis>
+
-                            The
-                            <control>This Window</control>
-                            button is the default and the focused one, while it’s
-                            better to place the focus on the
-                            <control>New Window</control>
-                            button, so that the user can
-                            access both options using the keyboard.
-                        </emphasis>
                     </li>
                 </list>
             </tab>
@@ -329,14 +266,13 @@
                     <shortcut>Enter</shortcut>
                     or
                     <shortcut>Space</shortcut>
-                    . If non-default
+                    . If a non-default
                     button gets focus, the default button is invoked using
-                    <shortcut>Ctrl+Enter</shortcut>
+                    <shortcut>Ctrl+Enter</shortcut>.
-                    .
+<!-- TODO                   <img src="open_project_dialog_win.png"
-                    <img src="open_project_dialog_win.png"
                          alt="A Windows dialog with buttons: 'This Window' (default), 'New Window' (focused), and 'Cancel'."
-                         width="672"/>
+                         width="672"/>-->
-                    <emphasis>On pressing the
+                    <p>On pressing the
                         <shortcut>Tab</shortcut>
                         key, the
                         <control>New Window</control>
@@ -348,11 +284,10 @@
                         The original
                         <control>This Window</control>
                         button is triggered with
-                        <shortcut>Ctrl+Enter</shortcut>
+                        <shortcut>Ctrl+Enter</shortcut>.</p>
-                        .
+                    <p>
-                    </emphasis>
+                    If the focus moves to the control that’s not a button, the original default button is triggered by
-                    If the focus moves to a control that’s not a button, the original default button is triggered by
+                    <shortcut>Enter</shortcut>.</p>
-                    <shortcut>Enter</shortcut>.
                 </li>
             </list>
                </tab>
@@ -361,43 +296,39 @@
 
 
         <chapter title="Disabled" id="disabled">
-            <img src="button_disabled.png"
+            <img src="disabled_button.png"
-                 alt="Disabled 'Cancel' button"
+                 alt="Disabled button"
-                 width="72"/>
+                 width="706"/>
             <p>Disable a button if:</p>
             <list>
                 <li>It’s an
-                    <control>Apply</control>
+                    <a anchor="apply">Apply</a>
                     button and no changes have been made in this dialog.
                 </li>
                 <li>The control to which the button is related is disabled.</li>
                 <li>Not all required fields in the dialog are filled.
                 </li>
             </list>
-            <p>Other common buttons are described below. They can be regular or default buttons.</p>
+            <p>Other <a anchor="standard-buttons">standard buttons</a> are described below. They can be regular or default buttons.</p>
         </chapter>
 
 
         <chapter title="Hover" id="hover">
+
             <p>On hovering over a button, show a tooltip with the shortcut and the action name if it can be clarified.
                 For more details,
                 see <a href="context_help.md">Context help</a>.</p>
-            <table style="none">
+            <table style="none" column-width="fixed">
                 <tr>
-                    <td width="50%">
+                    <td width="378">
-                        <img src="hover_shortcut.png"
+                        <img src="hovered_button.png" alt="Hovered buttons" width="378"/>
-                             alt="A 'Replace' button with a shortcut in hover tooltip"
+
-                             width="77"/>
-                        <p>
-                            <emphasis>If the action is clear, show the shortcut only.</emphasis>
-                        </p>
                     </td>
-                    <td width="50%">
+                    <td width="378">
-                        <img src="hover_name_shortcut.png"
+                        <p>If the action is clear, show the shortcut only.
-                             alt="'Replace' button with an action name and a shortcut in hover tooltip"
+                        </p>
-                             width="155"/>
                         <p>
-                            <emphasis>If the action can be clarified, show the action name and the shortcut.</emphasis>
+                            If the action can be clarified, show the action name and the shortcut.
                         </p>
                     </td>
                 </tr>
@@ -405,64 +336,104 @@
         </chapter>
     </chapter>
     <chapter title="Standard buttons" id="standard-buttons">
-        <chapter title="Cancel" id="cancel">
-            <p>The
-                <emphasis>Cancel</emphasis>
-                button reverts the app to the state before the dialog was invoked, and works equivalent to the
-                <shortcut>
-                    Esc
-                </shortcut>
-                key on Win and Linux, and
-                <shortcut>Esc</shortcut>
-                or
-                <shortcut>Cmd+Period</shortcut>
-                on macOS.
-                If a confirmation button is present in a dialog, e.g.,
-                <control>OK</control>
-                or
-                <control>Save</control>
-                , it’s recommended to have a button that cancels the
-                dialog, e.g.,
-                <control>Cancel</control>
-                ,
-                <control>Continue Editing</control>
-                , etc.
-            </p>
-        </chapter>
         <chapter title="Apply" id="apply">
-            <p>Use the Apply button in dialogs with many settings that affect how data is displayed. The Apply button
+            <table style="none" column-width="fixed">
-                allows you to
+                <tr>
-                save and preview the effect of the selected options, and continue changing the settings, for example,
+                    <td width="378">
-                change a scheme in
+                        <img src="apply.png" alt="Hovered buttons" width="378"/>
-                Settings.</p>
+
+                    </td>
+                    <td width="378">
+                        <p>Use the <control>Apply</control> button in dialogs with many settings that affect how data is displayed. The
+                            <control>Apply</control> 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.</p>
+                    </td>
+                </tr>
+            </table>
+        </chapter>
+        <chapter title="Cancel" id="cancel">
+            <table style="none" column-width="fixed">
+                <tr>
+                    <td width="378">
+                        <img src="cancel.png" alt="Hovered buttons" width="378"/>
+
+                    </td>
+                    <td width="378">
+                        <p>The
+                            <control>Cancel</control>
+                            button reverts the app to the state before the dialog was invoked, and works as an equivalent to the
+                            <shortcut>
+                                Esc
+                            </shortcut>
+                            key on Windows and Linux, and
+                            <shortcut>Esc</shortcut>
+                            or
+                            <shortcut>Cmd+Period</shortcut>
+                            on macOS.
+                            If a confirmation button is present in a dialog, for example,
+                            <control>OK</control>
+                            or
+                            <control>Save</control>
+                            , it’s recommended to have a button that cancels the
+                            dialog, for example,
+                            <control>Cancel</control>
+                            ,
+                            <control>Continue Editing</control>
+                            , and so on.
+                        </p>
+                    </td>
+                </tr>
+            </table>
+
+        </chapter>
+
+        <chapter title="Close">
+            <table style="none" column-width="fixed">
+                <tr>
+                    <td width="378">
+                        <img src="close.png" alt="Hovered buttons" width="378"/>
+
+                    </td>
+                    <td width="378">
+                        <p>Use the
+                            <control>Close</control>
+                            label only if nothing can be changed in the dialog and there is no confirmation button, for example, in
+                            the
+                            <ui-path>Help | My Productivity</ui-path>
+                            dialog.
+                            In all other cases, use the
+                            <control>Cancel</control>
+                            button.
+                        </p>
+                        <p>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.
+                        </p>
+                    </td>
+                </tr>
+            </table>
         </chapter>
         <chapter title="Help" id="help">
-            <p>The help button appears in the bottom-left corner of a dialog and shows help in a tooltip on hover, or
+            <table style="none" column-width="fixed">
-                opens a help
+                <tr>
-                dialog when clicking it. For more details, see <a href="context_help.md">Context help</a>.
+                    <td width="378">
-                <br/>
+                        <img src="help.png" alt="Hovered buttons" width="378"/>
-                <img src="helpButton_mac.png" alt="A question mark in the circle button" width="21"/></p>
+
-        </chapter>
+                    </td>
-        <chapter title="Close">
+                    <td width="378">
-            <p>Use the
+                        <p>The help button appears in the bottom-left corner of a dialog and shows help in a tooltip on hover, or
-                <emphasis>Close</emphasis>
+                            opens a help
-                label only if nothing can be changed in the dialog and there is no confirmation button, for example, in
+                            dialog when clicking it. For more details, see <a href="context_help.md">Context help</a>.</p>
-                the
+                        </td>
-                <ui-path>Help | My Productivity</ui-path>
+                </tr>
-                dialog.
+            </table>
-                In all other cases, use the
-                <control>Cancel</control>
-                button.
-            </p>
-            <p>Do
-                <b>not</b>
-                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.
-            </p>
         </chapter>
     </chapter>
-    <chapter title="Sizes and placement" id="sizes-and-placement">
+<!--    <chapter title="Sizes and placement" id="sizes-and-placement">
         <p>The button width accommodates the length of the label plus standard indents 14px, but not less than the
             72px.</p>
         <img src="button_sizes.png" alt="Example buttons with incorrect and correct sizes and indents" width="491"/>
@@ -470,7 +441,7 @@
         <p>To lay out the button that depends on other control, e.g., input field, follow the rules
             for <a href="layout.md" anchor="dependent-controls">dependent controls</a>. Otherwise, follow
             the rules for <a href="layout.md" anchor="independent-controls">independent controls</a>.</p>
-        <!--
+        &lt;!&ndash;
          <table>
          <col width="140px">
          <col width="200px">
@@ -504,8 +475,8 @@
                  <td> <img src="button_size_5.png" style="margin: -5px 0 0 0"></td>
              </tr>
          </table>
-        -->
+        &ndash;&gt;
-        <!--
+        &lt;!&ndash;
         ### Colors
 
         <table>
@@ -583,7 +554,7 @@
                     <td> Button.disabledBorderColor </td>
                 </tr>
         </table>
-        -->
+        &ndash;&gt;
-    </chapter>
+    </chapter>-->
 
 </topic>