JetBrains · OlyaB · Nov 9, 2025 · Jan 1, 2025 · Jan 1, 2025 · Jan 1, 2025
diff --git a/.idea/gradle.xml b/.idea/gradle.xml
diff --git a/.idea/kotlinc.xml b/.idea/kotlinc.xml
diff --git a/images/ui/radiobutton/01_Radio Button.png b/images/ui/radiobutton/01_Radio Button.png
diff --git a/images/ui/radiobutton/01_Radio Button_dark.png b/images/ui/radiobutton/01_Radio Button_dark.png
diff --git a/images/ui/radiobutton/02_When_to_use_correct.png b/images/ui/radiobutton/02_When_to_use_correct.png
diff --git a/images/ui/radiobutton/02_When_to_use_correct_dark.png b/images/ui/radiobutton/02_When_to_use_correct_dark.png
diff --git a/images/ui/radiobutton/02_When_to_use_incorrect.png b/images/ui/radiobutton/02_When_to_use_incorrect.png
diff --git a/images/ui/radiobutton/02_When_to_use_incorrect_dark.png b/images/ui/radiobutton/02_When_to_use_incorrect_dark.png
diff --git a/images/ui/radiobutton/03_When_to_use_Segmented_button.png b/images/ui/radiobutton/03_When_to_use_Segmented_button.png
diff --git a/images/ui/radiobutton/03_When_to_use_Segmented_button_dark.png b/images/ui/radiobutton/03_When_to_use_Segmented_button_dark.png
diff --git a/images/ui/radiobutton/04_When_to_use_correct.png b/images/ui/radiobutton/04_When_to_use_correct.png
diff --git a/images/ui/radiobutton/04_When_to_use_correct_dark.png b/images/ui/radiobutton/04_When_to_use_correct_dark.png
diff --git a/images/ui/radiobutton/04_When_to_use_incorrect.png b/images/ui/radiobutton/04_When_to_use_incorrect.png
diff --git a/images/ui/radiobutton/04_When_to_use_incorrect_dark.png b/images/ui/radiobutton/04_When_to_use_incorrect_dark.png
diff --git a/images/ui/radiobutton/05_When_to_use_Segmented_button.png b/images/ui/radiobutton/05_When_to_use_Segmented_button.png
diff --git a/images/ui/radiobutton/05_When_to_use_Segmented_button_dark.png b/images/ui/radiobutton/05_When_to_use_Segmented_button_dark.png
diff --git a/images/ui/radiobutton/06_How_to_use.png b/images/ui/radiobutton/06_How_to_use.png
diff --git a/images/ui/radiobutton/06_How_to_use_dark.png b/images/ui/radiobutton/06_How_to_use_dark.png
diff --git a/images/ui/radiobutton/07_How_to_use.png b/images/ui/radiobutton/07_How_to_use.png
diff --git a/images/ui/radiobutton/07_How_to_use_dark.png b/images/ui/radiobutton/07_How_to_use_dark.png
diff --git a/images/ui/radiobutton/08_How_to_use_correct.png b/images/ui/radiobutton/08_How_to_use_correct.png
diff --git a/images/ui/radiobutton/08_How_to_use_correct_dark.png b/images/ui/radiobutton/08_How_to_use_correct_dark.png
diff --git a/images/ui/radiobutton/08_How_to_use_incorrect.png b/images/ui/radiobutton/08_How_to_use_incorrect.png
diff --git a/images/ui/radiobutton/08_How_to_use_incorrect_dark.png b/images/ui/radiobutton/08_How_to_use_incorrect_dark.png
diff --git a/images/ui/radiobutton/09_How_to_use.png b/images/ui/radiobutton/09_How_to_use.png
diff --git a/images/ui/radiobutton/09_How_to_use_dark.png b/images/ui/radiobutton/09_How_to_use_dark.png
diff --git a/images/ui/radiobutton/10_How_to_use.png b/images/ui/radiobutton/10_How_to_use.png
diff --git a/images/ui/radiobutton/10_How_to_use_dark.png b/images/ui/radiobutton/10_How_to_use_dark.png
diff --git a/images/ui/radiobutton/answeryes_correct.png b/images/ui/radiobutton/answeryes_correct.png
diff --git a/images/ui/radiobutton/answeryes_incorrect.png b/images/ui/radiobutton/answeryes_incorrect.png
diff --git a/images/ui/radiobutton/dropdown.png b/images/ui/radiobutton/dropdown.png
diff --git a/images/ui/radiobutton/dropdown_correct.png b/images/ui/radiobutton/dropdown_correct.png
diff --git a/images/ui/radiobutton/dropdown_incorrect.png b/images/ui/radiobutton/dropdown_incorrect.png
diff --git a/images/ui/radiobutton/grouplabel.png b/images/ui/radiobutton/grouplabel.png
diff --git a/images/ui/radiobutton/old/answeryes_correct.png b/images/ui/radiobutton/old/answeryes_correct.png
diff --git a/images/ui/radiobutton/old/answeryes_incorrect.png b/images/ui/radiobutton/old/answeryes_incorrect.png
diff --git a/images/ui/radiobutton/old/dropdown.png b/images/ui/radiobutton/old/dropdown.png
diff --git a/images/ui/radiobutton/old/dropdown_correct.png b/images/ui/radiobutton/old/dropdown_correct.png
diff --git a/images/ui/radiobutton/old/dropdown_incorrect.png b/images/ui/radiobutton/old/dropdown_incorrect.png
diff --git a/images/ui/radiobutton/old/grouplabel.png b/images/ui/radiobutton/old/grouplabel.png
diff --git a/images/ui/radiobutton/old/radio-darcula.png b/images/ui/radiobutton/old/radio-darcula.png
diff --git a/images/ui/radiobutton/old/radio-intellij.png b/images/ui/radiobutton/old/radio-intellij.png
diff --git a/images/ui/radiobutton/old/radio-macos.png b/images/ui/radiobutton/old/radio-macos.png
diff --git a/images/ui/radiobutton/old/radio-windows.png b/images/ui/radiobutton/old/radio-windows.png
diff --git a/images/ui/radiobutton/old/radio_example.png b/images/ui/radiobutton/old/radio_example.png
diff --git a/images/ui/radiobutton/old/radiobutton_label.png b/images/ui/radiobutton/old/radiobutton_label.png
diff --git a/images/ui/radiobutton/old/twoline_label.png b/images/ui/radiobutton/old/twoline_label.png
diff --git a/images/ui/radiobutton/old/tworadio_checkbox.png b/images/ui/radiobutton/old/tworadio_checkbox.png
diff --git a/images/ui/radiobutton/radio-darcula.png b/images/ui/radiobutton/radio-darcula.png
diff --git a/images/ui/radiobutton/radio-intellij.png b/images/ui/radiobutton/radio-intellij.png
diff --git a/images/ui/radiobutton/radio-macos.png b/images/ui/radiobutton/radio-macos.png
diff --git a/images/ui/radiobutton/radio-windows.png b/images/ui/radiobutton/radio-windows.png
diff --git a/images/ui/radiobutton/radio_example.png b/images/ui/radiobutton/radio_example.png
diff --git a/images/ui/radiobutton/radiobutton_label.png b/images/ui/radiobutton/radiobutton_label.png
diff --git a/images/ui/radiobutton/twoline_label.png b/images/ui/radiobutton/twoline_label.png
diff --git a/images/ui/radiobutton/tworadio_checkbox.png b/images/ui/radiobutton/tworadio_checkbox.png
diff --git a/topics/ui/controls/radio_button.md b/topics/ui/controls/radio_button.md
@@ -10,107 +10,131 @@
 
 </tldr>
 
-![](radio_example.png){width=213}
+![](01_Radio Button.png){width=706}
 
 ## 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:
+## When not to use
 
-* 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.
+### Several options can be selected
+Use a group of [checkboxes](checkbox.md) when several options can be selected.
 
-![](tworadio_checkbox.png){width=427}
+### Yes or No Options
+For only two opposing yes/no options, use a checkbox.
 
-* There are 5 and more options that can be charted on an axis, e.g., time delay. Use a slider instead.
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="Green" style="bold">Correct</format><img src="02_When_to_use_correct.png" width="378" alt="A correct example of using a checkbox instead of radiobuttons"/>
+    </td>
+    <td>
+      <format color="Red" style="bold">Incorrect</format><img src="02_When_to_use_incorrect.png" width="378" alt="An incorrect example of using radiobuttons instead of a checkbox"/>
+    </td>
+  </tr>
+</table>
 
-* There are 5 and more options. Use a [drop-down list](drop_down.md):
+### 2-5 options with short labels
+If the options have short labels, use a segmented button.
+
+![](03_When_to_use_Segmented_button.png){width=706}
 
-  <table>
-      <tr>
-          <td width="40%"><format color="Red" style="bold">Incorrect</format></td>
-          <td width="60%"><format color="Green" style="bold">Correct</format></td>
-      </tr>
-      <tr>
-          <td><img src="dropdown_incorrect.png" alt="" width="189" /></td>
-          <td><img src="dropdown_correct.png" alt="" width="351" /></td>
-      </tr>
-  </table>
 
+### When to use a drop-down instead
 Consider using a [drop-down list](drop_down.md) if:
+* There are more than 5 options:
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="Green" style="bold">Correct</format><img src="04_When_to_use_correct.png" width="378" alt="A correct example of using a drop-down list instead of radiobuttons"/>
+    </td>
+    <td>
+      <format color="Red" style="bold">Incorrect</format><img src="04_When_to_use_incorrect.png" width="378" alt="An incorrect example of using radiobuttons for a list of 5 or more options"/>
+    </td>
+  </tr>
+  </table>
 
+* The options have long labels.
 * 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:
-  ![](dropdown.png){width=575}
-  *The automatic updates setting consists of a checkbox, three lengthy-labeled options in a dropdown and a button.*
+* The setting combines several UI components into one control:
+  ![](05_When_to_use_Segmented_button.png){width=706}
 
 ## How to use
 
 ### Label
 
-A label accompanies each checkbox and is placed next to it.
-
-![](radiobutton_label.png){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.
-
-![](twoline_label.png){width=195}
-
-To implement this, use HTML formatting:
-<tabs group="languages">
-<tab title="Kotlin UI DSL" group-key="kotlin">
-
-```kotlin
-radioButton(
-    "<html>Show options before adding<br>to version control</html>")
-```
-
-</tab>
-<tab title="Java" group-key="java">
-
-```java
-new JRadioButton(
-    "<html>Show options before adding<br>to version control</html>");
-```
-
-</tab>
-</tabs>
+<table style="none" border="false" column-width="fixed">
+    <tr>
+      <td><img src="06_How_to_use.png" alt="Label example" width="378"/></td>
+      <td><p>A label accompanies each radio button and is placed next to it.</p></td>
+    </tr>
+    <tr>
+      <td><img src="07_How_to_use.png" alt="An example of a label spanning two lines." width="378"/></td>
+      <td><p>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.</p></td>
+    </tr>
+</table>
+
+<chapter title="Implementation" collapsible="true">
+  <tabs group="languages">
+  <tab title="Kotlin UI DSL" group-key="kotlin">
+
+  ```kotlin
+  radioButton(
+      "<html>Show options before adding<br>to version control</html>")
+  ```
+
+  </tab>
+  <tab title="Java" group-key="java">
+
+  ```java
+  new JRadioButton(
+      "<html>Show options before adding<br>to version control</html>");
+  ```
+
+  </tab>
+  </tabs>
+</chapter>
 
 ### 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.
-
-<format color="Red" style="bold">Incorrect</format>
-
-![](answeryes_incorrect.png){width=264}
-
-<format color="Green" style="bold">Correct</format>
-
-![](answeryes_correct.png){width=139}
+* 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.
+* Make labels short and intelligible — see [Writing short and clear text](writing_short.md).
+
+
+<table style="none" border="false">
+  <tr>
+    <td>
+      <format color="Green" style="bold">Correct</format><img src="08_How_to_use_correct.png" width="378" alt="A correct example of using a drop-down list instead of radiobuttons"/>
+    </td>
+    <td>
+      <format color="Red" style="bold">Incorrect</format><img src="08_How_to_use_incorrect.png" width="378" alt="An incorrect example of using radiobuttons for a list of 5 or more options"/>
+    </td>
+  </tr>
+  </table>
 
-Make labels short and intelligible — see [Writing short and clear text](writing_short.md).
 
 ### Group label
 
-![](grouplabel.png){width=267}
-
-Always start a radio button group with a group label. It explains what the options are for.
+<table style="none" border="false" column-width="fixed">
+    <tr>
+      <td><img src="10_How_to_use.png" alt="Label example" width="378"/></td>
+      <td><p>Always start a radio button group with a group label to explain what the options are for. Use a colon at the end of a group label.</p></td>
+    </tr>
+    <tr>
+      <td><img src="09_How_to_use.png" alt="An example of a label spanning two lines." width="378"/></td>
+      <td><p>Use a checkbox or another radio button as a group label if the radio button group needs to be turned on or off.</p></td>
+    </tr>
+</table>
 
-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).
+Follow the layout of [checkboxes and radio-buttons](layout.md#checkboxes-and-radio-buttons)