Update welcome page for UI Guidelines, change fromat to .topic

Create Components and Priniples topics
Merge Controls and Components
Update links to welcome page

ijs.tree

@@ -443,8 +443,8 @@
       </toc-element>
     </toc-element>
   </toc-element>
-  <toc-element topic="ui_guidelines_welcome.md">
+  <toc-element topic="ui_guidelines_welcome.topic">
-    <toc-element toc-title="Controls">
+    <toc-element topic="Components.topic">
       <toc-element topic="button.topic">
         <toc-element topic="built_in_button.md"/>
         <toc-element topic="split_button.md"/>
@@ -457,6 +457,7 @@
         <toc-element topic="empty_state.md"/>
       </toc-element>
       <toc-element topic="description_text.md"/>
+      <toc-element toc-title="Dialog Window"/> <!--TODO-->
       <toc-element topic="drop_down.md"/>
       <toc-element topic="got_it_tooltip.md"/>
       <toc-element topic="group_header.md"/>
@@ -474,6 +475,7 @@
         <toc-element topic="banner.md"/>
         <toc-element toc-title="Tool Window Balloon"/> <!--TODO-->
       </toc-element>
+      <toc-element toc-title="Popup"/> <!--TODO-->
       <toc-element topic="progress_indicators.md">
         <toc-element topic="loader.md"/>
         <toc-element topic="progress_bar.md"/>
@@ -483,6 +485,7 @@
       <toc-element topic="scrollbar.md"/>
       <toc-element topic="search_field.md"/>
       <toc-element toc-title="Slider"/> <!--TODO-->
+      <toc-element toc-title="Status Bar"/> <!--TODO-->
       <toc-element topic="table.md"/>
       <toc-element topic="tabs.md"/>
       <toc-element topic="text_area.md"/>
@@ -492,23 +495,10 @@
         <toc-element topic="split_icon_button.md"/>
         <toc-element topic="toolbar_drop_down.md"/>
       </toc-element>
+      <toc-element topic="tool_window.md"/>
       <toc-element toc-title="Tree"/> <!--TODO-->
     </toc-element>
-    <toc-element toc-title="Components">
+    <toc-element topic="Principles.md">
-      <toc-element toc-title="Dialog Window"/> <!--TODO-->
-      <toc-element toc-title="Popup"/> <!--TODO-->
-      <toc-element toc-title="Status Bar"/> <!--TODO-->
-      <toc-element topic="tool_window.md"/>
-    </toc-element>
-    <toc-element toc-title="Text">
-      <toc-element topic="capitalization.md"/>
-      <toc-element topic="inspections.md"/>
-      <toc-element topic="punctuation.md"/>
-      <toc-element toc-title="Notification and Error Texts"/> <!--TODO-->
-      <toc-element toc-title="Terminology"/> <!--TODO-->
-      <toc-element topic="writing_short.md"/>
-    </toc-element>
-    <toc-element toc-title="Principles">
       <toc-element toc-title="Accessibility"/> <!--TODO-->
       <toc-element toc-title="Dangerous Actions"/> <!--TODO-->
       <toc-element topic="data_formats.md"/>
@@ -532,6 +522,14 @@
       <toc-element toc-title="UI Feedback"/> <!--TODO-->
       <toc-element topic="validation_errors.md"/>
     </toc-element>
+    <toc-element toc-title="Writing UI Texts">
+      <toc-element topic="capitalization.md"/>
+      <toc-element topic="inspections.md"/>
+      <toc-element topic="punctuation.md"/>
+      <toc-element toc-title="Notification and Error Texts"/> <!--TODO-->
+      <toc-element toc-title="Terminology"/> <!--TODO-->
+      <toc-element topic="writing_short.md"/>
+    </toc-element>
     <toc-element toc-title="Resources">
       <toc-element href="https://intellij-icons.jetbrains.design" toc-title="Icons List"/>
       <toc-element topic="icons_list.md" hidden="true"/>

topics/basics/plugin_user_experience.md

@@ -77,7 +77,7 @@ If you implement [custom language support](custom_language_support.md), review a
 ## Consistent and Good-Looking UI
 
 If a plugin UI significantly differs from the other application parts, it can feel alien to people and might be considered low quality or neglected.
-Review and follow the rules described in the [](ui_guidelines_welcome.md).
+Review and follow the rules described in the [](ui_guidelines_welcome.topic).
 Pay attention to [icons](icons_style.md) and make them match the IDE style.
 Use the UI controls recommended for a given use case.
 Use [UI Inspector](internal_ui_inspector.md) to see how the existing UI is implemented.
@@ -85,7 +85,7 @@ Use [UI Inspector](internal_ui_inspector.md) to see how the existing UI is imple
 ## High-Quality Texts
 
 Bad-quality labels or texts with typos and grammatical errors make a bad impression.
-All the UI texts should follow the rules described in the _Text_ section of the [](ui_guidelines_welcome.md).
+All the UI texts should follow the rules described in the _Text_ section of the [](ui_guidelines_welcome.topic).
 It is recommended to proofread the texts or use one of the [spellcheck plugins](https://plugins.jetbrains.com/search?tags=Spellcheck).
 
 ## Plugin Description and Presentation

topics/intro/sdk_style.md

@@ -52,7 +52,7 @@ Every page **should** provide a short excerpt (usually one sentence) using dedic
 A page can highlight related topics and other important links before the actual content using `<tldr>` tag.
 Links must be grouped using "**Bold Category Name**: link1, link2, \[...]" ([Example](language_and_filetype.md)).
 
-Use _Reference_ to link to other topics, _Code_ to link to code/files, _UI Guidelines_ for links to [UI Guidelines](ui_guidelines_welcome.md), and _Product Help_ for links to [IntelliJ IDEA Help](https://www.jetbrains.com/help/idea).
+Use _Reference_ to link to other topics, _Code_ to link to code/files, _UI Guidelines_ for links to [UI Guidelines](ui_guidelines_welcome.topic), and _Product Help_ for links to [IntelliJ IDEA Help](https://www.jetbrains.com/help/idea).
 
 #### Introductory Text
 

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 [](ui_guidelines_welcome.md)
+* delegate component rendering to the platform and make all the inspection options UI consistent and compliant with the [](ui_guidelines_welcome.topic)
 * 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

topics/ui/Components.topic

@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
+<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
+       id="Components" title="Components">
+
+    <title>
+        Components
+    </title>
+    <table>
+        <tr>
+            <td>Component</td>
+            <td>Description</td>
+        </tr>
+        <tr>
+            <td><a href="button.topic"></a></td>
+            <td>Use a button to invoke an immediate action.
+            </td>
+        </tr>
+        <tr>
+            <td><a href="built_in_button.md"></a></td>
+            <td>An icon placed inside an input control.</td>
+        </tr>
+        <tr>
+            <td><a href="checkbox.md"></a></td>
+            <td>Use checkboxes for yes/no choices or for selecting several items in a group.
+            </td>
+        </tr>
+        <tr>
+            <td><a href="combo_box.md"></a></td>
+            <td><p>A combo box combines a <a href="drop_down.md">drop-down list</a> and an <a href="input_field.md">input
+                field</a>, allowing the user to select a value from the list or enter a custom value.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="context_help.md"></a></td>
+            <td><p>Use context help to briefly explain how a functionality works if it is not clear from the UI and the
+                application behavior:
+            </p>
+                <list>
+                    <li><a href="empty_state.md"></a></li>
+                    <li><a href="inline_help_text.md"></a></li>
+                    <li><a href="tooltip.md"></a></li>
+                </list>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="description_text.md"></a></td>
+            <td><p>Description text provides explanatory information about a set of settings or a single item in a list
+                or tree.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><p><a href="drop_down.md"></a></p></td>
+            <td><p>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.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="got_it_tooltip.md"></a></td>
+            <td><p>A Got It tooltip informs users about a new or changed feature and gives basic information about
+                it.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="group_header.md"></a></td>
+            <td><p>A group header clearly labels a group of UI controls.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="icon_button.md"></a></td>
+            <td><p>A toolbar icon button is an icon that appears on a toolbar.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="input_field.md"/></td>
+            <td><p>An input field allows users to enter or edit a text line using the keyboard.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="link.md"></a></td>
+            <td><p>Use a regular link for navigation between pages of the same window.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="notification_types.md"/></td>
+            <td><p>Notifications inform users about the status of user or system initiated operations:</p>
+                <list>
+                    <li><a href="balloon.md"></a></li>
+                    <li><a href="banner.md"></a></li>
+                </list>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="progress_indicators.md"></a></td>
+            <td><p>Progress indicators inform users about an ongoing operation:</p>
+                <list>
+                    <li><a href="loader.md">Loader</a></li>
+                    <li><a href="progress_bar.md">Progress bar</a></li>
+                    <li><a href="progress_text.md">Progress text</a></li>
+                </list>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="radio_button.md"></a></td>
+            <td><p>Use a radio button group to choose one option from 2 to 4 mutually exclusive options.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="scrollbar.md"></a></td>
+            <td><p>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.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="search_field.md"></a></td>
+            <td><p>A search field is an input field that helps users locate objects, actions or text in an
+                application.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="split_button.md"></a></td>
+            <td>A button with two parts — the main action on the left and a dropdown button with secondary actions on the right.</td>
+        </tr>
+        <tr>
+            <td><a href="split_icon_button.md"></a></td>
+            <td><p>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.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="table.md"></a></td>
+            <td><p>Use tables so that users can review, enter or edit uniform sets of data or options. For example:</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="tabs.md"></a></td>
+            <td><p>Tabs organize content in dialogs by grouping similar UI controls.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="text_area.md"></a></td>
+            <td><p>A text area allows users to enter or edit multi-line text.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="toggle_button.md"></a></td>
+            <td><p>The toggle button is used to switch between On and Off states.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="toolbar.md"></a></td>
+            <td><p>A toolbar provides quick access to frequently used actions and filters. It appears in dialogs,
+                pop-ups, tool windows, lists, trees, and tables.</p>
+            </td>
+        </tr>
+
+
+        <tr>
+            <td><a href="toolbar_drop_down.md"></a></td>
+            <td><p>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.</p>
+            </td>
+        </tr>
+        <tr>
+            <td><a href="tool_window.md"></a></td>
+            <td><p>A tool window is a pane inside the main IDE window. For information about tool windows, see <a
+                    href="https://www.jetbrains.com/help/idea/tool-windows.html">IntelliJ IDEA Web Help</a>. For
+                information about implementing tool windows, see <a href="tool_windows.md"></a>.</p>
+            </td>
+        </tr>
+    </table>
+
+
+
+</topic>

topics/ui/Principles.md

@@ -0,0 +1,10 @@
+# Principles
+
+- [](data_formats.md)
+- [](icons_style.md)
+- [](layout.md)
+    - [](groups_of_controls.md)
+- [](mnemonics.md)
+- [](platform_theme_colors.md)
+- [](typography.md)
+- [](validation_errors.md)

topics/ui/ui_guidelines_welcome.md

@@ -4,102 +4,37 @@
 
 <link-summary>Creating consistent and usable user interfaces.</link-summary>
 
-When working on an IntelliJ Platform-based IDE or a plugin, use these guidelines to create consistent and usable user interfaces.
+<section-starting-page>
-
+        <title>UI Guidelines</title>
-> Topics in <format color="Gray">gray text</format> are not available yet.
+        <description>
->
+            Use these guidelines to create consistent and usable user interfaces for When working on an IntelliJ IDEs or plugins.
-{style="note"}
+        </description>
-
+        <spotlight>
-## Controls
+            <a type="tools" summary="Learn how to use standard IntelliJ components" href="Components.topic">Components</a>
-
+            <a type="computer" href="layout.md" summary="Learn how to arrange UI components">Layout</a>
-- [](button.topic)
+        </spotlight>
-    - [](built_in_button.md)
+        <!--    Add several topics that are less important or are relevant only for advanced/experienced users.    -->
-    - [](split_button.md)
+        <primary>
-- [](checkbox.md)
+            <title>Principles</title>
-- [](combo_box.md)
+            <a href="icons_style.md" summary="How to create and customize icons"/>
-- [](context_help.md)
+            <a href="typography.md" summary="IntelliJ font system">Typography</a>
-    - [](inline_help_text.md)
+            <a href="platform_theme_colors.md" summary="Platform theme colors">Colors</a>
-    - [](tooltip.md)
+            <a href="mnemonics.md" summary="Characters that indicate keys for menu actions">Mnemonics</a>
-    - [](empty_state.md)
+            <a href="validation_errors.md" summary="Highlight invalid input">Validation errors</a>
-- [](description_text.md)
+        </primary>
-- [](drop_down.md)
+        <secondary>
-- [](got_it_tooltip.md)
+            <title>Resources</title>
-- [](group_header.md)
+            <a href="https://intellij-icons.jetbrains.design" summary="Full IntelliJ icons set">Icons List</a>
-- [](input_field.md)
+            <a href="https://www.figma.com/community/file/938505862996154830" summary="UI Kit in Figma ">UI Kit</a>
-- [](link.md)
+        </secondary>
-- <format color="Gray">List</format>
+        <!--    Optionally add additional cards and links to topics that are not in this section but may be relevant.    -->
-- <format color="Gray">Menu</format>
+        <misc>
-    - <format color="Gray">Context Menu</format>
+            <cards>
-    - <format color="Gray">Menu List</format>
+                <title>Writing UI texts</title>
-- [](notification_types.md)
+                <a href="capitalization.md" summary="Capitalization rules"/>
-    - <format color="Gray">Alert</format>
+                <a href="inspections.md" summary="Inspection descriptions"/>
-    - [](balloon.md)
+                <a href="punctuation.md" summary="Punctuation rules"></a>
-    - [](banner.md)
+                <a href="writing_short.md" summary="How to write short and clear">General guidelines</a>
-    - <format color="Gray">Tool Window Balloon</format>
+            </cards>
-- [](progress_indicators.md)
+        </misc>
-    - [](loader.md)
+    </section-starting-page>
-    - [](progress_bar.md)
-    - [](progress_text.md)
-- [](radio_button.md)
-- [](scrollbar.md)
-- [](search_field.md)
-- <format color="Gray">Slider</format>
-- [](table.md)
-- [](tabs.md)
-- [](text_area.md)
-- [](toggle_button.md)
-- [](toolbar.md)
-    - [](icon_button.md)
-    - [](split_icon_button.md)
-    - [](toolbar_drop_down.md)
-- <format color="Gray">Tree</format>
-- {columns="4"}
-
-## Components
-
-- <format color="Gray">Dialog Window</format>
-- <format color="Gray">Popup</format>
-- <format color="Gray">Status Bar</format>
-- [](tool_window.md)
-- {columns="4"}
-
-## Text
-
-- [](capitalization.md)
-- [](inspections.md)
-- [](punctuation.md)
-- <format color="Gray">Notification and Error Texts</format>
-- <format color="Gray">Terminology</format>
-- [](writing_short.md)
-- {columns="4"}
-
-## Principles
-
-- <format color="Gray">Accessibility</format>
-- <format color="Gray">Dangerous Actions</format>
-- [](data_formats.md)
-- <format color="Gray">Default Values</format>
-- <format color="Gray">Discoverability</format>
-- [](icons_style.md)
-- [](layout.md)
-    - [](groups_of_controls.md)
-    - <format color="Gray">Master-detail Layout</format>
-    - <format color="Gray">Sizes and Insets</format>
-- [](mnemonics.md)
-- [](platform_theme_colors.md)
-- <format color="Gray">Search</format>
-    - <format color="Gray">Search Results</format>
-    - <format color="Gray">Speed Search</format>
-- <format color="Gray">Sharing Settings</format>
-- [](typography.md)
-- <format color="Gray">UI Feedback</format>
-- [](validation_errors.md)
-- {columns="4"}
-
-## Resources
-
-- [Icons List](https://intellij-icons.jetbrains.design)
-- [](UI_kit.md)
-- {columns="4"}
-
-<include from="snippets.md" element-id="missingContent"/>

topics/ui/ui_guidelines_welcome.topic

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
+<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
+       title="UI Guidelines" id="ui_guidelines_welcome" help-id="ui-guidelines-welcome">
+    <section-starting-page>
+        <title>UI Guidelines</title>
+        <description>
+            Use these guidelines to create consistent and usable user interfaces for When working on an IntelliJ IDEs or plugins.
+        </description>
+
+        <spotlight>
+            <a type="tools" summary="Learn how to use standard IntelliJ components" href="Components.topic">Components</a>
+            <a type="computer" href="layout.md" summary="Learn how to arrange UI components">Layout</a>
+        </spotlight>
+
+        <!--    Add several topics that are less important or are relevant only for advanced/experienced users.    -->
+        <primary>
+            <title>Principles</title>
+            <a href="icons_style.md" summary="How to create and customize icons"/>
+            <a href="typography.md" summary="IntelliJ font system">Typography</a>
+            <a href="platform_theme_colors.md" summary="Platform theme colors">Colors</a>
+            <a href="mnemonics.md" summary="Characters that indicate keys for menu actions">Mnemonics</a>
+            <a href="validation_errors.md" summary="Highlight invalid input">Validation errors</a>
+        </primary>
+        <secondary>
+            <title>Resources</title>
+            <a href="https://intellij-icons.jetbrains.design" summary="Full IntelliJ icons set">Icons List</a>
+            <a href="https://www.figma.com/community/file/938505862996154830" summary="UI Kit in Figma ">UI Kit</a>
+        </secondary>
+
+        <!--    Optionally add additional cards and links to topics that are not in this section but may be relevant.    -->
+        <misc>
+            <cards>
+                <title>Writing UI texts</title>
+                <a href="capitalization.md" summary="Capitalization rules"/>
+                <a href="inspections.md" summary="Inspection descriptions"/>
+                <a href="punctuation.md" summary="Punctuation rules"></a>
+                <a href="writing_short.md" summary="How to write short and clear">General guidelines</a>
+            </cards>
+        </misc>
+    </section-starting-page>
+
+</topic>

topics/user_interface_components/kotlin_ui_dsl_version_2.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 [](ui_guidelines_welcome.md).
+The forms are built by using a declarative Kotlin syntax and follow the official IntelliJ Platform UI conventions described in the [](ui_guidelines_welcome.topic).
 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.

topics/user_interface_components/user_interface_components.md

@@ -6,7 +6,7 @@
 
 <tldr>
 
-**UI Guidelines:** [Overview](ui_guidelines_welcome.md)
+**UI Guidelines:** [Overview](ui_guidelines_welcome.topic)
 
 </tldr>