docs/buttons: edit styleguide

packages/documentation/docs/controls/buttons/_button_styleguide.md

@@ -2,57 +2,61 @@ Buttons initiate actions, apply actions to selected objects and activate/deactiv
 
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1097-5037&mode=design&t=KAxDgJoFX436Uk0b-11)
 
-1. Button label
-2. Button icon
+1. Label
+2. Icon
 
 ## Variants
 
-- **Primary button:** In our applications, we most often use the primary button variant.
-- **Secondary button:** The secondary button variant has a grayscale appearance to distinguish it from the primary button.
-- **Danger button:** We use the danger button variant to emphasize particularly dangerous, destructive or critical actions that cannot easily be undone. Consider this especially in confirmation dialogs. 
+![Variants](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=4571-3823&t=2rIp5WSkgCodTQq7-4)
 
-**Note:** Please be aware that the terms *primary* and *secondary* are not used in accordance to common UX terminology for primary, secondary and ghost button.
+1. **Primary:** Use as a default for all actions.
+2. **Secondary:** Use when the primary buttons catch too much attention.
+3. **Danger:** Use for destructive or critical actions like "delete" or "remove". We typically use the danger button for actions that are irreversible or have a significant impact on the user’s data or the application state.
+
+:::info
+
+In design system, our button definitions are different than typical UX conventions:
+
+- **Primary**: Corresponds directly to the traditional primary button in UX.
+- **Primary outline**: Equivalent to what is usually termed a secondary button in UX nomenclature.
+- **Primary ghost**: Functions similarly to the tertiary button in standard UX terminology.
+
+:::
 
 ## Options
-- **Default:** Use for the most important or most-likely next action within the user interface. These are typically actions that advance the user through a process, such as "Submit", "Save" or "Add". We use these sparingly and recommend only one per layout. These are typically called *primary* buttons in UX. 
-- **Outline:** Use for standard actions that need to be easily recognizable or for actions supporting the default (primary) action. These could include actions like "Cancel", "Reset" or "Advanced Options". These are typically called *secondary* buttons in UX.
-- **Ghost:** Use for actions that are typically not part of the core user journey but serve specialized or conditional purposes. Tertiary buttons can represent actions such as "Advanced settings", "More options", "Help" or "Customize". They may also be used for conditional actions like "Change preferences" or "View details".
-- **Icon:** Icons can also be displayed with button labels.
-- **Disabled:** Buttons can be disabled (see also button states).
-- **Loading:** A loading spinner is displayed on the button. The spinner replaces an icon when available.
-- **Type:** A submit button is available. Submit buttons are typically used in forms and trigger a submit event. Apply this type to make a submit button more accessible.
+
+- **Label**: The label is the text displayed on the button. We typically use short, descriptive labels that clearly communicate the action the button triggers.
+- **Icon:** An icon can be displayed on the button. We typically use icons to support the label and make the button more easy to discover by the user. The icon should be widely known for representing the action or function among your users.
+- **Type:** Use the type "submit" when sending user input from a form to a server. For all other actions, use the default type "button".
+- Use a plain button for actions that do not involve form submission, such as triggering dialogs or performing navigation. Otherwise, use a submit button to send user input from a form to a server.
+- **Outline:** Use outline buttons for standard actions that need to be easily recognizable or for actions supporting the primary action, e.g. "Cancel", "Reset" or "Advanced Options". These are typically called *secondary* buttons in UX.
+- **Ghost:** Use ghost buttons for actions that are not part of the core user journey but serve specialized or conditional purposes, e.g. "Advanced settings", "More options", "Help" or "Customize", "Change preferences" or "View details".
 
 ## Behavior in context
+
 - **Interaction:** Buttons can be triggered by pressing anywhere within the button container. When buttons are focused, they can be triggered by pressing `Space`.
 - **Text truncation:** Button labels are not truncated. All text on buttons is one line only. 
-- **Ellipsis (…):** Ellipsis can be used to indicate that an action requires further input or choice from the user, such as "Save as…" which opens a further list of file types to choose from. Ellipses is typically not used for actions with a subsequent confirmation dialog.
-- **Alignment:** Buttons can be left-justified or right-justified or fully span a container’s width.
-- **Cluster buttons:** Buttons can be clustered in groups based on their relationship. A cluster can contain a mixture of buttons, e.g. a combination of a primary button with two primary ghost buttons. We recommend a minimum distance of `0.5rem` between adjacent buttons, and we typically cluster buttons if actions/functions are related but not excluding each other. Otherwise, consider using a `button group`. 
-- **Button width:** Button width depends on its content. In addition, buttons have a default minimum width of 5rem to lay out common combinations such as "OK" and "Cancel" more harmoniously with equal widths. The minimum width is customizable to accommodate other combinations.
+- **Alignment:** Buttons can be left- or right-aligned or fully span a container’s width.
+- **Cluster buttons:** Cluster buttons in groups with related functions. A cluster might include various types of buttons, e.g. a primary and  secondary ghost button. We recommend a gap of `0.5rem` between buttons.
+- **Button width:** Buttons dynamically adjust their width based on content but have a default minimum width of `5rem` to ensure harmonious alignment for common pairs like "OK" and "Cancel." The minimum width can be customized for different needs.
 
 ## States
 
-Buttons have six states: Default, hover, active, disabled, loading and focused. In a disabled state, buttons are visually displayed but don’t offer any user interaction.
+Buttons have six states: Default, hover, active, disabled, loading and focused. In a disabled and loading state, buttons are visually displayed but don’t offer any user interaction.
 
 ![Button states](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=132-13020&mode=design&t=KAxDgJoFX436Uk0b-11)
 
 ## Dos and Don’ts
 
-- Do use short button labels to allow users to quickly scan, understand and remember them (follow our writing style guide for more support)
-- Do use only one primary (default) button in one visual unit for a clear and singular focus on the main call to action
-- Do use the danger button for destructive or critical actions like "delete" or "remove", especially in confirmation dialogs
-- Do use a default margin between adjacent buttons of at least `0.5rem`
-- Do adjust default and outline button width to label length or container width
+- Do use short button labels to allow users to quickly scan, understand and remember them (see our [writing style guide](./../../language/writing-style-guide-getting-started.md))
+- Do use ellipsis (...) to indicate that an action requires further input or choice from the user, e.g. "Save as…" which opens a list of file types to choose from.
+- Do use only one primary button in one visual unit for a clear and singular focus on the main call to action
 - Don’t use the danger button excessively or repetitively in lists or tables
-- Don’t extend your ghost button width beyond the label’s available width
-- Don’t rely on standard buttons when many actions/functions are necessary (use dropdown, split or menu buttons or move some functionality to a panel or a dialog)
-- Don’t use buttons for navigation
+- Don’t rely on standard buttons when many actions are necessary (use [dropdown buttons](dropdown-button.md) or [split buttons](split-button.md) instead, or move some functionality to a [pane](./../panes.md) or a [dialog](../modal.md))
 
-## Related patterns:
+## Related patterns
 
 - [Dropdown button](./dropdown-button.md)
 - [Split button](./split-button.md)
 - [Toggle button](./toggle-buttons.md)
 - [Modal](./../modal.md)
-
-

packages/documentation/docs/controls/buttons/_dropdown-button_styleguide.md

@@ -1,31 +1,36 @@
-Dropdown buttons are button elements that allow users to select an action from a list of options by clicking on a button and revealing a dropdown. Clicking on one of the exposed options triggers the action. We typically use dropdown buttons when no default action is available. Dropdown buttons typically group similar or related actions.
+Dropdown buttons are button elements that allow users to select an action from a list of options by clicking on a button and revealing a dropdown. Clicking on one of the options triggers the action. We typically use dropdown buttons when no default action is available. 
 
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1477-13932&mode=design&t=97WS5dUS2rk3MCp2-11)
 
 1. Button container
-2. Button label
+2. Label
 3. Chevron
-4. Button icon
+4. Icon
 
-All the variants, options and states of the ix button component apply to the dropdown button. We've listed additional or deviating specifications here.
+**Note:** All the variants, options and states of the [button](button.md) component apply to the split button. We've listed additional or deviating specifications here.
 
 ## Options
-- **Label:** Set a label for the dropdown button. We typically use short labels including verbs.
-- **Placement:** Define where the dropdown appears when the button is active. Choose between different directions (top, bottom, left, right) and two options for alignment with the button (start, end). When there isn't enough space for the chosen placement, it's automatically corrected.
+- **Placement:** Define where the dropdown appears. Choose between different directions (top, bottom, left, right) and two options for alignment with the button (start, end). When there isn't enough space for the chosen placement, it's automatically corrected.
 
 ![Placement example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1504-2203&mode=design&t=5MYmq6zAbfw7xIkC-11)
 1. Bottom-end placement
 2. Bottom-start placement
 
-- For options of the dropdown triggered when pressing the button, please refer to our separate dropdown component guide.
-- The options **loading** and **type** are not available for split buttons.
+ Note: For options of the dropdown triggered when clicking on the button, see [dropdown](../dropdown.md). The **type** option is not available for dropdown buttons.
+
+# Behavior in context
+- **Interaction:** When users click on the button, the dropdown is shown.
 
 ## States
-Dropdown buttons have five states: Default, hover, active, disabled and focused. In an active state, dropdown buttons show a dropdown with the available options. The visual appearance of the states is the same as the ix button component.
+Dropdown buttons have five states: Default, hover, active, disabled and focused (loading is not available).
+
+The visual appearance and the behavior of the states is the same as the [button](button.md) and the [dropdown button](dropdown-buttom.md).
 
-## Does and Don'ts
+## Dos and Don'ts
 - Do use dropdown buttons when selecting an option triggers an action
-- Don't use dropdown buttons when there is a frequent or most-important action (use a standard button or a split button instead)
+- Do use dropdown buttons when no default action is available
+- Don't use dropdown buttons for navigation
+- Don't use dropdown buttons when there is a frequent or most-important action (use a standard [button](button.md) or a [split button](split-button.md) instead)
 
 ## Related patterns
 - [Button](button.md)

packages/documentation/docs/controls/buttons/_icon-button_styleguide.md

@@ -2,7 +2,7 @@ Icon buttons are button elements containing only an icon and no text. Due to the
 
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1477-1714&mode=design&t=97WS5dUS2rk3MCp2-1)
 
-1. Container
+1. Button container
 2. Icon
 
 All the variants, options and states of the [button](./button.md) component apply to the icon button. We’ve listed additional or deviating specifications here.

packages/documentation/docs/controls/buttons/_split-button_styleguide.md

@@ -8,33 +8,41 @@ Split buttons are button elements that allow users to either trigger an action w
 4. Button label
 5. Dropdown button icon
 
-All the variants, options and states of the ix button and the ix dropdown button components apply to the split button. We've listed additional or deviating specifications here.
+**Note:** All the variants, options and states of the [button](button.md) component apply to the split button. We've listed additional or deviating specifications here.
 
 ## Options
-- **Disabled:** The disabled option can be applied to the complete component. There is no option to disable each part of the split button independently.
+
 - **Label:** Set a label for the button component (left side). We typically use short labels that contain a verb.
-- **Placement:** Define where the flyout appears which is triggered when the dropdown button is active. You can choose between different directions (top, bottom, left, right) and two options for alignment with the button (start, end). When there is not enough space for the chosen setting, the placement is corrected automatically.
+- **Placement:** Define where the flyout appears when the dropdown button is active. You can choose between different directions (top, bottom, left, right) and two options for alignment with the button (start, end). When there is not enough space for the chosen setting, the placement is corrected automatically.
 
 ![Placement example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1504-2203&mode=design&t=5MYmq6zAbfw7xIkC-11)
 1. Bottom-end placement
 2. Bottom-start placement   
 
-
-- **SplitIcon:** We typically use a chevron icon on the dropdown button, but a custom icon can be set. A common alternative to the chevron is the "more-menu" icon.
+- **Split icon:** We typically use a chevron icon on the dropdown button, but a custom icon can be set. A common alternative to the chevron is the "more-menu" icon.
 - The options **loading** and **type** are not available for split buttons.
 
+ Note: For options of the dropdown triggered when clicking on the dropdown button, see [dropdown](../dropdown.md). The **type** option is not available for dropdown buttons.
 ## Behavior in context
-- **Interaction:** When users press an option from the dropdown list, the action is triggered. Typically the label of the button on the left side stays static. Be aware that updating the left side with the last triggered action may lead to layout changes (e.g. button width) and requires updating the dropdown by adding the action that was removed from the button face.
 
-## States
-Split buttons have five states: Default, hover, active, disabled and focused. States are applied to left and the right part of the split button independently except for the disabled state. The visual appearance and the behavior of the states is the same as the ix button and the ix dropdown button.
+- **Interaction:** When users click on the button, the dropdown is shown.
+
+## Sates
+
+Split buttons have five states: Default, hover, active, disabled and focused (loading is not available).
+
+States are applied to left and the right part of the split button independently except for the disabled state. The disabled state can be applied only to the complete component. 
+
+The visual appearance and the behavior of the states is the same as the [button](button.md) and the [dropdown button](dropdown-buttom.md).
+
+## Dos and Don'ts
 
-## Does and Don'ts
 - Do use split buttons when there is a frequent or most-important action
 - Don't use split buttons for unrelated actions
 - Don't duplicate the default option in the dropdown
 
 ## Related patterns
+
 - [Button](button.md)
 - [Dropdown](../dropdown.md)
 - [Select](../select.md)