siemens · bettiifr · Aug 14, 2024
diff --git a/packages/documentation/docs/controls/buttons/_button_styleguide.md b/packages/documentation/docs/controls/buttons/_button_styleguide.md
@@ -2,24 +2,22 @@ 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. 
+- **Primary:** The primary button variant has a solid background in the primary color. We typically use primary buttons for the most important or most-likely next action within the user interface. 
+- **Secondary:** The secondary button variant has a transparent background in the secondary color. We typically use secondary buttons for standard actions that need to be easily recognizable or for actions supporting the default (primary) action. 
+- **Danger:** The danger button variant has a red background and is used for destructive or critical actions like "delete" or "remove", especially in confirmation dialogs. 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.  
+- **Ghost :** The ghost button variant has a transparent background and a border in the primary color. We typically use ghost buttons for actions that are not part of the core user journey but serve specialized or conditional purposes. 
+- **Outline**: All Button variants have also an outline variant. The outline variant has a transparent background and a border in the corresponding color. This variant is used when the button needs to be more subtle or when it is placed on a dark background. 
 
 **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.
 
 ## 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.
+- **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:** 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.
 
 ## Behavior in context
@@ -34,6 +32,13 @@ Buttons initiate actions, apply actions to selected objects and activate/deactiv
 
 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.
 
+- **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".
+- **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.
+- **Focused:** Buttons can be focused via keyboard navigation. The focus state is used to indicate that the button is currently selected. 
+
 ![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

diff --git a/packages/documentation/docs/controls/buttons/_dropdown-button_styleguide.md b/packages/documentation/docs/controls/buttons/_dropdown-button_styleguide.md
@@ -1,16 +1,17 @@
-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.
 
 ## Options
 - **Label:** Set a label for the dropdown button. We typically use short labels including verbs.
+- 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.
 - **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 example](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1504-2203&mode=design&t=5MYmq6zAbfw7xIkC-11)
@@ -23,9 +24,11 @@ All the variants, options and states of the ix button component apply to the dro
 ## 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.
 
-## 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)

diff --git a/packages/documentation/docs/controls/buttons/_icon-button_styleguide.md b/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.

diff --git a/packages/documentation/docs/controls/buttons/_split-button_styleguide.md b/packages/documentation/docs/controls/buttons/_split-button_styleguide.md
@@ -29,7 +29,7 @@ All the variants, options and states of the ix button and the ix dropdown button
 ## 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.
 
-## Does and Don'ts
+## Dos 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