Docs/icon button square

docs/components/buttons-menus/buttons.md

@@ -4,42 +4,22 @@
 
 ## Usage ---
 
-Use buttons to trigger an action.
-The labels describe what will happen when the user interacts with it, such as Add, Save, or Delete.
+Use buttons to trigger actions.
+Labels should clearly describe the purpose and effect of the action, such as Add, Save, or Delete.
 
-<si-docs-component example="buttons/buttontypes" editor="false" height="480"></si-docs-component>
+There are three semantic types:
 
-Buttons are categorized by visual weight and semantic meaning to convey
-the importance of the action and its potential consequences.
+- **Default buttons** for standard actions such as Save or Submit.
+- **Warning buttons** for cautious decisions such as Overwrite or Restart.
+- **Danger buttons** for destructive actions such as Delete or Remove.
 
-### Semantic meaning
+Each button also carries a visual weight:
 
-Buttons are defined by the type of action they represent:
+- **Primary buttons** highlight the main action of the page or task.
+- **Secondary buttons** for supporting actions.
+- **Tertiary buttons** for low-priority or less prominent actions.
 
-- **Default buttons** represent regular, non-destructive actions like submitting forms or saving changes.
-- **Warning buttons** signify actions that require extra caution (e.g. confirming risky decisions).
-- **Danger buttons** are used for destructive or irreversible actions (e.g. deleting data).
-
-### Visual weight
-
-Buttons can be primary, secondary, or tertiary, regardless of their semantic meaning
-(default, warning, or danger). Visual weight indicates the importance of the action:
-
-- **Primary buttons** highlight the main action of the page or task, guiding users to the most important action
-  (e.g. Save or Delete).
-- **Secondary buttons** are less visually striking but still important (e.g. Cancel or Edit).
-- **Tertiary buttons** are for lower-priority actions that need to be noticeable but not distracting.
-
-### Categories
-
-Buttons can have text or a combination of text and labels, or they can be purely icon-based.
-When the button contains only an icon, it adopts a circular shape.
-
-<si-docs-component example="buttons/buttoncategories" editor="false" height="150"></si-docs-component>
-
-The circular variant also includes a ghost button style.
-Ghost buttons are subtle and blend into the interface, used for low-priority or optional actions.
-They signal availability without drawing attention, ideal for less critical or contextual options.
+![Button](images/buttons.png)
 
 ### Button link
 
@@ -60,45 +40,39 @@ where a regular button would be too bulky.
 - Use only one primary button per page.
 - Ensure call-to-action labels are straightforward and concise.
 - Use single-line text for button labels; avoid multi-line text.
-- Use circular shapes for icon-only buttons.
 - When truncating text, ensure at least three characters of the content remain visible.
 - Use the loading button to indicate ongoing processes.
+- Use `spacing-6` to define the space between buttons and other components/containers.
 
 ## Design ---
 
-### Button content
+### Variants
 
-![Button content](images/button-content.png)
+Buttons support text, icon, or a combination of both.
 
-### Button shapes
+![Button types](images/button-types.png)
 
-#### Rectangular buttons
+Icon-only buttons adapt their shape based on layout constraints and visual context.
 
-| Property           | Value        | Comment                                                 |
-| ------------------ | ------------ | ------------------------------------------------------- |
-| Padding left/right | `$spacing-l` |                                                         |
-| Padding top/bottom | `$spacing-s` |                                                         |
-| Spacing(margin)    | `$spacing-l` | Spacing between buttons and other components/containers |
-| Min-width          | 100px        | Minimum width of button irrespective of text length     |
+**Circle buttons** are used when the button is placed inside a circular container (e.g., pills) or in unconstrained,
+free-form contexts for standalone actions (e.g., overlays, floating controls, wizard).
+The circular shape signals a self-contained action and visually separates it from structured layouts.
 
-#### Circle buttons
+**Square buttons** are used in structured layouts where consistent alignment is required (e.g., inputs, tables, cards).
+The rectangular shape anchors the action to the surrounding layout and scales better when multiple actions are placed side by side.
 
-- **Large**
+![Button icon](images/button-icon.png)
 
-| Property     | Value | Comment |
-| ------------ | ----- | ------- |
-| height/width | 40px  |         |
+### Size
 
-- **Small**
+Buttons are available in three height variants:
 
-| Property     | Value | Comment |
-| ------------ | ----- | ------- |
-| height/width | 32px  |         |
+- **Small** (24px) for compact areas such as inside input fields.
+- **Default** (32px) for general use across most layouts.
+- **Large** (40px) for high-visibility actions or spacious layouts.
 
 ### Button placement
 
-#### Arrangement
-
 The position and alignment of buttons is defined in relationship to their container.
 Buttons can be aligned right or center in relation to the parent container.
 
@@ -109,25 +83,17 @@ This is the case of two or more buttons that display related actions (e.g: save/
 - Related buttons should all be the same width
 - Spacing (margin) between related buttons is `spacing-s`
 
-#### Scaling and adaptation
-
-When scaling the viewport, buttons can adapt their visual presentation and
-arrangement to fit different contexts and user needs.
-
-#### Responsive grid
+### Responsive grid
 
 Typically, buttons are placed side by side. However, if the viewport becomes
 too narrow to display all the text label, buttons should be stacked
 following the responsive grid.
 
 #### Text truncation
 
-If the text label is too long, use and ellipsis `...` at the end of the line.
-
-Be mindful about text truncation, since hides content that can be relevant to users.
-For example, `Delete, to destroy all buildings!` should not become `Del...`
-
-Instead, work with responsive design and prefer line wrapping for very important text.
+Text labels should be short and concise.
+When a long label cannot be avoided, truncate it with an ellipsis `(…)` at the end of the line.
+Only wrap the text when the full label is critical and truncation would cause loss of meaning.
 
 ## Code ---