[UIK-2755][website] Headings and labels

website/docs/.vitepress/sidebarConfig.ts

@@ -365,16 +365,16 @@ export const sideBarConfig: SidebarConfig = [
             activeMatch: '/components/radio/',
             text: 'Radio',
           },
-          {
-            link: '/components/select/select',
-            activeMatch: '/components/select/',
-            text: 'Select / Multiselect',
-          },
           {
             link: '/components/scroll-area/scroll-area',
             activeMatch: '/components/scroll-area/',
             text: 'ScrollArea',
           },
+          {
+            link: '/components/select/select',
+            activeMatch: '/components/select/',
+            text: 'Select / Multiselect',
+          },
           {
             link: '/components/side-panel/side-panel',
             activeMatch: '/components/side-panel/',

website/docs/components/badge/badge.md

@@ -94,11 +94,11 @@ The feature status can be shown inside most of the components and controls.
 
 ![](static/button_secondary.png)
 
-### Pill
+### Pills
 
 ![](static/pills.png)
 
-### Feature status in the notification
+### Notification
 
 ![](static/notice.png)
 
@@ -108,7 +108,7 @@ Don’t confuse [Tag](/components/tag/tag) and Badge components. Tag is used for
 
 ![](static/table-yes-no.png)
 
-## Location
+## Placement
 
 Badge is usually placed to the right of the element. As an exception, in the [Notice](/components/notice/notice) component, badge is positioned to the left relative to the text. Badge's margins are always multiples of 4.
 

website/docs/components/base-trigger/base-trigger.md

@@ -14,7 +14,7 @@ tabs: Design('base-trigger'), A11y('base-trigger-a11y'), API('base-trigger-api')
 - `FilterTrigger`
 - `LinkTrigger`
 
-## Sizes, margins and paddings
+## Appearance
 
 Table: BaseTrigger sizes, margins and paddings
 

website/docs/components/button/button.md

@@ -219,7 +219,7 @@ You can add addons before and after the text. As addons you can use:
 - [Badge](/components/badge/badge)
 - [Flag](/components/flags/flags)
 
-## Sizes and margins
+## Sizes
 
 Table: Button sizes and margins
 
@@ -228,9 +228,7 @@ Table: Button sizes and margins
 | **M (28px)**               | M         | ![](static/size-m.png) | This is the default size of the button. Use it freely in filters, dropdowns, tables, etc.                                |
 | **L (40px)**               | M         | ![](static/size-l.png) | Use this size in modal windows for main actions, empty pages and page states that need to focus user on the main action. |
 
-## Button types and themes
-
-### Types
+## Types
 
 Intergalactic Design System has three button types (`use` property in API):
 
@@ -242,35 +240,36 @@ All button types can be used on a white and gray background, as well as on a tra
 
 Table: Button types
 
-| Button type | Appearance example               |
+| `use`       | Appearance example               |
 | ----------- | -------------------------------- |
 | `primary`   | ![](static/button-primary.png)   |
 | `secondary` | ![](static/button-secondary.png) |
 | `tertiary`  | ![](static/button-tertiary.png)  |
 
 ### Themes
 
-You can use themes for the buttons according to the visual hierarchy on the page. See the [visual loudness scale](/core-principles/visual-loudness-scale/visual-loudness-scale) guide.
+You can use themes (`theme` property in API) for the buttons according to the visual hierarchy on the page. See the [visual loudness scale](/core-principles/visual-loudness-scale/visual-loudness-scale) guide.
 
 Invert theme button is used on dark or colored background. For example in [Tooltip](/components/tooltip/tooltip), [NoticeBubble](/components/notice-bubble/notice-bubble), etc.
 
 Table: Button themes
 
-| Button type | `muted`                         | `info`                        | `success`                    | `danger`                    | `invert`                               |
+|             | `muted`                         | `info`                        | `success`                    | `danger`                    | `invert`                               |
 | ----------- | ------------------------------- | ----------------------------- | ---------------------------- | --------------------------- | -------------------------------------- |
 | `primary`   | _no theme_                      | ![](static/info-butt.png)     | ![](static/success-butt.png) | ![](static/danger-butt.png) | ![](static/invert-normal.png)          |
 | `secondary` | ![](static/secondary-muted.png) | _deprecated_                  | _no theme_                   | _no theme_                  | ![](static/invert-second-normal.png)   |
 | `tertiary`  | ![](static/tertiary-muted.png)  | ![](static/tertiary-info.png) | _no theme_                   | _no theme_                  | ![](static/invert-tertiary-normal.png) |
 
-## Button states
+<!-- I'D REMOVED THIS SECTION BECAUSE IMO SHOWING STATIC IMAGES OF BUTTON STATES IS A BAD PRACTICE
+## States
 
 Table: States for all buttons types and themes
 
 | Button type | Normal                        | Hover                           | Active                           | Loading                           | Disabled                           |
 | ----------- | ----------------------------- | ------------------------------- | -------------------------------- | --------------------------------- | ---------------------------------- |
 | `primary`   | ![](static/button-normal.png) | ![](static/button-hover.png)    | ![](static/button-active.png)    | ![](static/button-loading.png)    | ![](static/button-disabled.png)    |
 | `secondary` | ![](static/secondary.png)     | ![](static/secondary-hover.png) | ![](static/secondary-active.png) | ![](static/secondary-loading.png) | ![](static/secondary-disabled.png) |
-| `tertiary`  | ![](static/tertiary.png)      | ![](static/tertiary-hover.png)  | ![](static/tertiary-active.png)  | ![](static/tertiary-loading.png)  | ![](static/tertiary-disabled.png)  |
+| `tertiary`  | ![](static/tertiary.png)      | ![](static/tertiary-hover.png)  | ![](static/tertiary-active.png)  | ![](static/tertiary-loading.png)  | ![](static/tertiary-disabled.png)  | -->
 
 ## Button with Link styles
 
@@ -322,23 +321,30 @@ If you need to use a single button we recommend you to set it's width to at leas
 
 ![](static/button-width3.png)
 
-## Margins between buttons
+## Button label
+
+Button label always starts with a capital letter.
+
+![](static/capitalize.png)
+
+**Button label shall not exceed three words.** Too wordy controls are difficult to read. Try to fit the desired meaning into the short label.
+
+![](static/max-length.png)
+
+The label of the button should clearly indicate what happens after user clicks it.
+
+![](static/define-action.png)
 
-**The margin between buttons shall be [multiple of 4](/layout/box-system/box-system#spacing_system)**. If there are several buttons next to each other, use the recommended margins shown in table below.
+## Grouped buttons
+
+**The margin between buttons should be [multiple of 4](/layout/box-system/box-system#spacing_system)**. If there are several buttons next to each other, use the recommended margins shown in table below.
 
-Table: Margins between buttons
+Table: Grouped buttons
 
 | L (40px)                 | M (28px)                 |
 | ------------------------ | ------------------------ |
 | ![](static/margin-1.png) | ![](static/margin-2.png) |
 
-## Usage in UX/UI
-
-- Try to have one call-to-action button on the page in the modal window. _For example, one green button._
-- We recommend you don’t disable CTA, even if something went wrong (especially in filters and modal windows with a single CTA). User needs to understand that the product/service is working. When user clicks on the button, add a message about the error or what user needs to do in this case.
-- If you can't do without a button in the disabled state, be sure to include a tooltip for it explaining why the primary action is disabled.
-- If there are a lot of actions in your interface, first of all set your priorities. Place controls in your interface according to the [visual loudness scale](/core-principles/visual-loudness-scale/visual-loudness-scale) guide. Use inactive "quiet" buttons in the interface. Don't "shout" at the user with your interface, let them work with your product in visual "silence" and comfort.
-
 ## Button variations
 
 ### Text button
@@ -365,21 +371,7 @@ We recommend using the icon-only button if:
 **Add a tooltip with information about button's function to the icon-only buttons**. It helps user to understand functionality of the button if the icon isn’t the obvious one.
 :::
 
-## Button label
-
-Button label always starts with a capital letter.
-
-![](static/capitalize.png)
-
-**Button label shall not exceed three words.** Too wordy controls are difficult to read. Try to fit the desired meaning into the short label.
-
-![](static/max-length.png)
-
-The label of the button should clearly indicate what happens after user clicks it.
-
-![](static/define-action.png)
-
-## Branded buttons
+### Branded buttons
 
 In case when you need to show that button connects or links to some other service, use a branded color for the background or the corresponding color icon of the service.
 
@@ -398,6 +390,9 @@ It may also be helpful checking the following branding guidelines:
 - Youtube – [Branding Guidelines](https://developers.google.com/youtube/terms/branding-guidelines) and [Brand resources](https://www.youtube.com/howyoutubeworks/resources/brand-resources/#overview)
 - Pinterest – [How to use the Pinterest brand in your marketing](https://business.pinterest.com/en-us/brand-guidelines/)
 
-## Grouped buttons
+## Usage in UX/UI
 
-To combine the components such as Button, [Input](/components/input/input), and [Select](/components/select/select), use the [`neighborLocation`](/components/button/button-api) property.
+- Try to have one call-to-action button on the page in the modal window. _For example, one green button._
+- We recommend you don’t disable CTA, even if something went wrong (especially in filters and modal windows with a single CTA). User needs to understand that the product/service is working. When user clicks on the button, add a message about the error or what user needs to do in this case.
+- If you can't do without a button in the disabled state, be sure to include a tooltip for it explaining why the primary action is disabled.
+- If there are a lot of actions in your interface, first of all set your priorities. Place controls in your interface according to the [visual loudness scale](/core-principles/visual-loudness-scale/visual-loudness-scale) guide. Use inactive "quiet" buttons in the interface. Don't "shout" at the user with your interface, let them work with your product in visual "silence" and comfort.

website/docs/components/card/card.md

@@ -77,7 +77,7 @@ Table: Card paddings
 
 ![](static/card-margins2.png)
 
-### Layout
+### Layout with sections
 
 You can divide content into sections if needed.
 

website/docs/components/checkbox/checkbox.md

@@ -96,9 +96,7 @@ Component consists of the following:
 2. `Checkbox.Value`
 3. `Checkbox.Text`
 
-## Sizes and margins
-
-### Sizes
+## Sizes
 
 Checkbox has two sizes: M and L. The text label is always positioned to the right of the checkbox.
 
@@ -109,6 +107,8 @@ Table: Checkbox sizes
 | M (16px * 16px) | ![](static/size-m.png)   |
 | L (20px * 20px) | ![](static/size-l.png)   |
 
+## Appearance
+
 ### Margins
 
 The spacing between options may differ based on the context in which they are used. To maintain consistency, it's recommended to use margins that are multiples of 4. The default margins are displayed below.
@@ -120,7 +120,7 @@ Table: Checkbox margins
 | M (16px * 16px) | ![](static/margins-m.png) ![](static/vert-m.png) |
 | L (20px * 20px) | ![](static/margins-l.png) ![](static/vert-l.png) |
 
-## Checkbox with a paragraph
+## Checkbox with paragraph
 
 All checkbox sizes can be used with the corresponding text paragraphs.
 
@@ -143,7 +143,7 @@ Info icon should have `margin-left: 4px`.
 
 ![](static/info-icon-margin.png)
 
-## Checkbox with a link inside
+## Checkbox with link inside
 
 Text label may contain a [Link component](/components/link/link).
 
@@ -155,27 +155,6 @@ Note, that the checkbox text active zone shouldn't include a link.
 
 ![](static/link-hover-zone.png)
 
-## Interaction
-
-- Hovering over the "Checkbox and text" area changes the cursor to a pointer.
-- Clicking anywhere on the "Checkbox and text" area changes the state of the checkbox.
-- If the text label contains a link or pseudo-link, clicking on the link area doesn't change the checkbox state.
-- When the checkbox is disabled, the text and related words should also be "disabled." It's recommended to include a tooltip explaining why the checkbox is disabled.
-
-### States
-
-Table: Checkbox states
-
-| State                 | Appearance example                            |
-| --------------------- | --------------------------------------------- |
-| Normal                | ![](static/state-unchecked.png)               |
-| Checked               | ![](static/state-checked.png)                 |
-| Indeterminate         | ![](static/state-indetermenate.png)           |
-| Invalid               | ![](static/state-invalid.png)                 |
-| Checked invalid       | ![](static/state-checked-invalid.png)         |
-| Indeterminate invalid | ![](static/state-indetermenate-invalid.png)   |
-| Disabled              | ![](static/state-disabled.png)                |
-
 ## Checkbox group
 
 To save the user's time, use the "Select all" and "Deselect all" options for checkbox groups with more than 6-7 options. These buttons will select or deselect all checkboxes in the group:
@@ -184,7 +163,7 @@ To save the user's time, use the "Select all" and "Deselect all" options for che
 - "Deselect all" deselects all checkboxes at all levels.
 - If at least one checkbox is checked at any level, "Deselect all" changes to "Select all".
 
-![](static/group-1.png) ![](static/group-2.png) ![](static/group-3.png)
+![](static/checkbox-group.png)
 
 If you have a checkbox tree, the top-level checkbox has three states:
 
@@ -209,6 +188,28 @@ When user clicks on a checkbox with the `indeterminate` state, all sub-level che
 
 ![](static/select-all.png) ![](static/deselect-all.png)
 
+## Interaction
+
+- Hovering over the "Checkbox and text" area changes the cursor to a pointer.
+- Clicking anywhere on the "Checkbox and text" area changes the state of the checkbox.
+- If the text label contains a link or pseudo-link, clicking on the link area doesn't change the checkbox state.
+- When the checkbox is disabled, the text and related words should also be "disabled." It's recommended to include a tooltip explaining why the checkbox is disabled.
+
+<!-- I'D REMOVED THIS SECTION BECAUSE IMO SHOWING STATIC IMAGES OF STATES IS A BAD PRACTICE
+### States
+
+Table: Checkbox states
+
+| State                 | Appearance example                            |
+| --------------------- | --------------------------------------------- |
+| Normal                | ![](static/state-unchecked.png)               |
+| Checked               | ![](static/state-checked.png)                 |
+| Indeterminate         | ![](static/state-indetermenate.png)           |
+| Invalid               | ![](static/state-invalid.png)                 |
+| Checked invalid       | ![](static/state-checked-invalid.png)         |
+| Indeterminate invalid | ![](static/state-indetermenate-invalid.png)   |
+| Disabled              | ![](static/state-disabled.png)                | -->
+
 ## Usage in UX/UI
 
 - **Make lists of options vertically and left aligned**, one option per line. If using a horizontal layout, ensure that there is enough space between options to differentiate them.

website/docs/components/color-picker/color-picker.md

@@ -42,17 +42,21 @@ const App = PlaygroundGeneration(Preview);
 - List of ColorPicker.Items
 - Input (optional)
 
-## Trigger
+## Appearance
 
-The trigger for a ColorPicker is a Select with a circle as the leading addon.
+### Trigger
 
-![](static/trigger.png)
-
-### Sizes
+The trigger for a ColorPicker is a Select with a circle as the leading addon, and has 16px * 16px size.
 
 ![](static/trigger-size.png)
 
-## List of colors
+### Item
+
+ColorPicker item has 28px * 28px size.
+
+![](static/colorpicker-item-size.png)
+
+### List of colors
 
 A list of colors can include either a single ColorPicker.Item or multiple ones, which are preview swatches that display all available color values.
 
@@ -62,15 +66,7 @@ Table: List of colors and its items
 | -------------------- | ----------------------------------------------------- |
 | ![](static/colorpicker-item-bg-default.png) | ![](static/colorpicker-inline.png) |
 
-## Size
-
-ColorPicker.Item has 28px * 28px size.
-
-![](static/colorpicker-item-size.png)
-
-## Margins
-
-All margins must be [multiples of 4](/layout/box-system/box-system#spacing_system). The default recommended margins are 4px:
+Margin between the items must be [multiples of 4](/layout/box-system/box-system#spacing_system). The default recommended margins are 4px:
 
 ![](static/colorpicker-margins.png)
 
@@ -85,6 +81,24 @@ Table: Color items
 | Item for background color | ![](static/colorpicker-item-bg-default.png) | Use for changing the background color. For example, a user can pick colors to visually separate their competitors. |
 | Item for text color      | ![](static/colorpicker-item-text-default.png)    | Use for changing the Tag color, for example                                                                                             |
 
+## Dropdown
+
+### Width and height
+
+**The recommended width of a dropdown is 188px.** The height of a dropdown list depends on its content.
+
+Showing all available colors in the DropdownMenu is crucial, however, if a user has added more than 20 custom colors, a scrollbar should be displayed.
+
+Table: DropdownMenu appearance
+
+| DropdownMenu                  | DropdownMenu with more than 20 colors |
+| ----------------------------- | ------------------------------------- |
+| ![](static/dropdown-menu.png) | ![](static/scroll.png)                |
+
+### Margins and paddings
+
+![](static/colorpicker-margins-paddings.png)
+
 ## Interaction
 
 - In the hover state, trigger has a `border: 1px solid var(--border-secondary)`.
@@ -118,24 +132,6 @@ Table: States of item for adding colors
 | ------------------- | ------------------------------- | -------------------------- | ----------------------- | -------------------- |
 | Add color button | ![](static/btn-add-default.png) | ![](static/btn-add-hover.png) | ![](static/btn-add-active.png)| Use Button with icon and change border-radius to 50%.|
 
-## Dropdown
-
-### Width and height
-
-**The recommended width of a dropdown is 188px.** The height of a dropdown list depends on its content.
-
-Showing all available colors in the DropdownMenu is crucial, however, if a user has added more than 20 custom colors, a scrollbar should be displayed.
-
-Table: DropdownMenu appearance
-
-| DropdownMenu                  | DropdownMenu with more than 20 colors |
-| ----------------------------- | ------------------------------------- |
-| ![](static/dropdown-menu.png) | ![](static/scroll.png)                |
-
-### Margins and paddings
-
-![](static/colorpicker-margins-paddings.png)
-
 ## Custom colors (optional)
 
 Users have the ability to add or remove custom colors, but they cannot modify default or existing custom colors.