siemens · flxlst09 · Dec 6, 2024 · Dec 6, 2024 · Dec 9, 2024 · Dec 9, 2024
diff --git a/packages/documentation/docs/controls/_card-list_styleguide.md b/packages/documentation/docs/controls/_card-list_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Card lists are UI controls that display a large number of cards or items of the same type in a lightweight, grouped manner. Users can hide and reveal the card list content by clicking on a control element. We typically use card lists on dashboards to show a huge amount of information in an organized and hierarchical way.
+Users can hide and reveal the card list content by clicking on a control element. We typically use card lists on dashboards to show a huge amount of information in an organized and hierarchical way.
 
 Card lists consist of a header section at the top and a content section below. The header section includes an icon button with a chevron on the left, followed by the card list's label. In the content section, items of the same type can be arranged in two different layout styles: stack and scroll.
 

diff --git a/packages/documentation/docs/controls/_card_styleguide.md b/packages/documentation/docs/controls/_card_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Cards are UI controls used to neatly organize and group related information about a specific subject. They make it easy for users to quickly scan small chunks of information. We typically use cards to create dashboards or modular, flexible designs that adapt seamlessly to various screen sizes. Additionally, cards can be used to draw attention to important content and serve as an entry point to deeper levels of navigation or detailed views.
+Cards make it easy for users to quickly scan small chunks of information. We typically use cards to create dashboards or modular, flexible designs that adapt seamlessly to various screen sizes. Additionally, cards can be used to draw attention to important content and serve as an entry point to deeper levels of navigation or detailed views.
 
 Cards are interactive elements. The entire container is clickable and triggers a single action.
 

diff --git a/packages/documentation/docs/controls/_category-filter_styleguide.md b/packages/documentation/docs/controls/_category-filter_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-The category filter component enhances data navigation and user experience. We typically use a category filter to efficiently navigate large data sets, allowing users to quickly narrow their search by selecting predefined categories. It’s particularly useful in scenarios with complex data. The filter also enhances user experience by providing autocomplete suggestions and customizable filter conditions.
+The category filter component enhances data navigation and user experience. We typically use a category filter to efficiently navigate large data sets, being particularly useful in scenarios with complex data. The filter also enhances user experience by providing autocomplete suggestions and customizable filter conditions.
 
 ![Category filter overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1799-38402&mode=design&t=hgAA8GogE70JbHHy-1)
 

diff --git a/packages/documentation/docs/controls/_chip_styleguide.md b/packages/documentation/docs/controls/_chip_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Chips are components used to display small pieces of information in a compact and visually appealing way. Typically chips contain a concise label and sometimes an icon, and they are clickable and closable.
+Typically chips contain a concise label and sometimes an icon, and they are clickable and closable.
 
 ![Chip overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1149-41643&mode=design&t=ruQOzpPQJMKwnk8f-1)
 

diff --git a/packages/documentation/docs/controls/_content-header_styleguide.md b/packages/documentation/docs/controls/_content-header_styleguide.md
@@ -1,7 +1,6 @@
 ## Guidelines
 
-The content header provides a brief overview of the content on a page. It helps our users understand what the page is about.
-We typically use it at the very top of the page to show a clear hierarchy of the page.
+The content header helps our users understand what the page is about. We typically use it at the very top of the page to show a clear hierarchy of the page.
 
 ![Content header overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=2250-4784&mode=design&t=XmCepM9jPR9PImPw-4)
 

diff --git a/packages/documentation/docs/controls/_custom-field_styleguide.mdx b/packages/documentation/docs/controls/_custom-field_styleguide.mdx
@@ -1,6 +1,6 @@
 ## Guidelines
 
-The custom field is a wrapper component that can host any forms component. Its properties allows you to control the validation state of the field and the helper text. The custom field is a versatile tool to create your own form fields, that can be used in combination with the 'Form' components to create complex forms.
+The custom field's properties allow you to control the validation state of the field and the helper text. The custom field is a versatile tool to create your own form fields, that can be used in combination with the 'Form' components to create complex forms.
 
 ![Custom field](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3303-3291&t=SikqVQr6LWjMEjKI-4)
 

diff --git a/packages/documentation/docs/controls/_date-input_styleguide.mdx b/packages/documentation/docs/controls/_date-input_styleguide.mdx
@@ -1,6 +1,6 @@
 ## Guidelines
 
-The date input component enables users to enter and select a date in a standardized format. We typically use this component in forms, filters and scheduling tools to ensure consistent and accurate date entries.
+The date input component is typically used in forms, filters, and scheduling tools to ensure consistent and accurate date entries. By standardizing date input, it helps maintain data integrity and improves the user experience in applications requiring precise date information.
 
 ![Date input overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3629-6200&t=ADQCetGKOEH1WG2r-4)
 

diff --git a/packages/documentation/docs/controls/_dropdown_styleguide.md b/packages/documentation/docs/controls/_dropdown_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Dropdown containers display a menu with additional items when users click on the trigger element, e.g. a dropdown button. Clicking on one of the items in the dropdown performs the action. We typically use dropdowns to allow users to select one option from a list.
+We typically use dropdowns to allow users to select one option from a list. Selecting one of the items in the dropdown performs the action. 
 
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=2353-2278&mode=design&t=OVHeXvLZYLkP2CzN-4)
 

diff --git a/packages/documentation/docs/controls/_forms-checkbox_styleguide.md b/packages/documentation/docs/controls/_forms-checkbox_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-A checkbox is a small interactive box that allows the user to toggle between an affirmative or negative choice. Checkboxes are commonly used when there are multiple options that can be selected or to easily enable or disable a setting. They are often utilized in forms where users can choose multiple options, such as selecting items or categories that apply to a specific product or service.
+Checkboxes are commonly used when there are multiple options that can be selected or to easily enable or disable a setting. They are often utilized in forms where users can choose multiple options, such as selecting items or categories that apply to a specific product or service.
 
 ![Checkbox anatomy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3364-8247&t=VCAAFzKIYCDb7nIX-4)
 

diff --git a/packages/documentation/docs/controls/_input_styleguide.md b/packages/documentation/docs/controls/_input_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-An input field is a user interface element that allows users to enter and edit text, numbers and symbols. It’s commonly used in forms, search bars, and other areas where data input is required.
+Input fields are commonly used in forms, search bars, and other areas where data input is required.
 
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3054-593&t=jhhv5OZGqmBpgXcs-4)
 

diff --git a/packages/documentation/docs/controls/_layout-grid_styleguide.md b/packages/documentation/docs/controls/_layout-grid_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Grids are typically used to make layouts more cohesive and consistent. With layout grids, a two-dimensional layout system is available to create responsive layouts. Our layout grids are made of three elements: a grid, row(s) and column(s). The layout grid adapts to screen size and orientation.
+With layout grids, a two-dimensional layout system is available to create responsive layouts. Our layout grids are made of three elements: a grid, row(s) and column(s). The layout grid adapts to screen size and orientation.
 
 Commonly, the layout grid is based on a 12 column layout. Columns are nested in rows and adapt in width according to the available space. Content is placed within columns. Column widths are set as percentage.
 

diff --git a/packages/documentation/docs/controls/_number-input_styleguide.mdx b/packages/documentation/docs/controls/_number-input_styleguide.mdx
@@ -1,6 +1,6 @@
 ## Guidelines
 
-The number input component allows users to enter and adjust numerical values. It’s commonly used in forms, calculators, and other areas where precise numerical input is required. We typically use the number input component to ensure accurate and efficient data entry.
+The number input component is commonly used in forms, calculators, and other areas where precise numerical input is required. We typically use the number input component to ensure accurate and efficient data entry.
 
 ![Number input overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3805-24565&t=DtCmoFcLwhf7ke3S-4)
 

diff --git a/packages/documentation/docs/controls/_panes_styleguide.md b/packages/documentation/docs/controls/_panes_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Panes are interactive components that allow users to access content that isn't constantly visible on the screen. Panes have a header and a content area. When collapsed, panes are either hidden or reduced to a bar. In our applications, we often include contextual information, options, trees and lists inside panes.
+Panes have a header and a content area. When collapsed, panes are either hidden or reduced to a bar. In our applications, we often include contextual information, options, trees and lists inside panes.
 
 Panes help users focus on tasks as related controls are visually grouped and the main content has less information. They are also beneficial for compact and hierarchically organized content and provide a more dynamic layout.
 

diff --git a/packages/documentation/docs/controls/_pill_styleguide.md b/packages/documentation/docs/controls/_pill_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Pills are components used to display small pieces of information in a compact and visually appealing way. Typically pills contain a concise label and sometimes an icon, and they aren't clickable or closable.
+Typically, pills contain a concise label and sometimes an icon. They are not clickable or closable, making them ideal for presenting static information succinctly within an application.
 
 ![Pill overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1377-3110&mode=design&t=ZmcRP4ggXtr8b7vZ-1)
 

diff --git a/packages/documentation/docs/controls/_radio_styleguide.mdx b/packages/documentation/docs/controls/_radio_styleguide.mdx
@@ -1,6 +1,6 @@
 ## Guidelines
 
-A radio button is an interface element that enables the user to choose only one option from a predefined set of mutually exclusive options. They are presented in groups to signify that only one selection is allowed at a time. Selecting a radio button automatically deselects any previously chosen radio button within the same group. We typically use radio buttons to offer users a set of exclusive choices.
+Radio buttons are presented in groups to signify that only one selection is allowed at a time. Selecting a radio button automatically deselects any previously chosen radio button within the same group. We typically use radio buttons to offer users a set of exclusive choices.
 
 ![Anatomy radio button](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3384-108&t=GDd4aJQUrPB3cC9X-4)
 

diff --git a/packages/documentation/docs/controls/_select_styleguide.md b/packages/documentation/docs/controls/_select_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-A select component allows users to choose from a list of options. It supports single or multiple selections and the editable variant allows users to add new items. We typically use select components in forms, filters and settings where users need to choose from predefined options.
+The select component supports single or multiple selections and the editable variant allows users to add new items. We typically use select components in forms, filters and settings where users need to choose from predefined options.
 
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3647-6332&t=DtCmoFcLwhf7ke3S-4)
 

diff --git a/packages/documentation/docs/controls/_textarea-field_styleguide.mdx b/packages/documentation/docs/controls/_textarea-field_styleguide.mdx
@@ -1,6 +1,6 @@
 ## Guidelines
 
-The textarea component allows users to input multi-line text, making it ideal for forms that require longer entries. We typically use textareas in scenarios such as feedback forms, comment sections and message composition.
+The textarea component is typically used in scenarios such as feedback forms, comment sections, and message composition. Its ability to handle extensive text input makes it a versatile tool for collecting detailed user information.
 
 ![Textarea overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3814-1128&t=DtCmoFcLwhf7ke3S-4)
 

diff --git a/packages/documentation/docs/controls/_toast_styleguide.md b/packages/documentation/docs/controls/_toast_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Toasts are small pop-ups that provide simple feedback on a process. They are UI elements where an event causes a small text field to appear on screen. Toasts are informative, last for a few seconds only, and take up a very small part of the screen to avoid interrupting the workflow. They usually follow an action performed by the user and provide information about the success or failure of that action. We typically use toasts for immediate feedback or tips on actions that a user performs, e.g. successful deletion.
+Toasts are UI elements where an event causes a small text field to appear on screen. Toasts are informative, last for a few seconds only, and take up a very small part of the screen to avoid interrupting the workflow. They usually follow an action performed by the user and provide information about the success or failure of that action. We typically use toasts for immediate feedback or tips on actions that a user performs, e.g. successful deletion.
 
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=2550-58743&t=LITgbzwcgm87dQXa-4)
 

diff --git a/packages/documentation/docs/controls/application-frame/_content_styleguide.md b/packages/documentation/docs/controls/application-frame/_content_styleguide.md
@@ -2,8 +2,6 @@ import Tags from './../../auto-generated/ix-content/tags.md';
 
 ## Guidelines
 
-The content component is a simple layout component made for hosting content.
-
 ![application content](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1759-25130&mode=design&t=UPXhDWuRHtygtfFI-11)
 
 The purple dotted line illustrates the extent of the content component.

diff --git a/packages/documentation/docs/controls/application-frame/about-and-legal.md b/packages/documentation/docs/controls/application-frame/about-and-legal.md
@@ -8,7 +8,9 @@ import DocsUx from './\_about-and-legal_styleguide.md';
 import DocsCode from './\_about-and-legal_code.md';
 
 # About and legal overlay
-
+<!-- introduction start -->
+The about and legal overlay displays application information, versions, license terms, and other legal content.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/application-frame/application-header.md b/packages/documentation/docs/controls/application-frame/application-header.md
@@ -12,6 +12,10 @@ import Tags from './../../auto-generated/ix-application-header/tags.md';
 
 <Tags />
 
+<!-- introduction start -->
+Application headers provide a structured area for key elements like the brand logo, application name, and user avatar.
+<!-- introduction end -->
+
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/application-frame/application-menu.md b/packages/documentation/docs/controls/application-frame/application-menu.md
@@ -8,7 +8,9 @@ import DocsUx from './\_application-menu_styleguide.md';
 import DocsCode from './\_application-menu_code.md';
 
 # Menu
-
+<!-- introduction start -->
+The navigation menu provides direct access to main application parts, legal and version information, and settings.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/application-frame/application.md b/packages/documentation/docs/controls/application-frame/application.md
@@ -13,6 +13,12 @@ import Tags from './../../auto-generated/ix-application/tags.md';
 
 <Tags />
 
+<br/>
+
+<!-- introduction start -->
+Applications manage the layout and theming of top-level app elements, ensuring a cohesive user experience.
+<!-- introduction end -->
+
 <br/>
 <br/>
 

diff --git a/packages/documentation/docs/controls/application-frame/basic-navigation.md b/packages/documentation/docs/controls/application-frame/basic-navigation.md
@@ -12,7 +12,9 @@ import Tags from './../../auto-generated/ix-basic-navigation/tags.md';
 # Basic Navigation
 
 <Tags />
-
+<!-- introduction start -->
+Basic navigation combines essential infrastructure components to form the foundational layout structure of an application.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/application-frame/content.md b/packages/documentation/docs/controls/application-frame/content.md
@@ -12,7 +12,9 @@ import Tags from './../../auto-generated/ix-content/tags.md';
 # Content
 
 <Tags />
-
+<!-- introduction start -->
+The content component is a simple layout component made for hosting content.
+<!-- introduction end -->
 <br/>
 <br/>
 

diff --git a/packages/documentation/docs/controls/application-frame/map-navigation.md b/packages/documentation/docs/controls/application-frame/map-navigation.md
@@ -12,7 +12,9 @@ import Tags from './../../auto-generated/ix-map-navigation/tags.md';
 # Map Navigation
 
 <Tags />
-
+<!-- introduction start -->
+Map navigation structures layout to present map-like content, supported by a collapsible context panel and temporary overlays.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/application-frame/popover-news.md b/packages/documentation/docs/controls/application-frame/popover-news.md
@@ -8,7 +8,9 @@ import DocsUx from './\_popover-news_styleguide.md';
 import DocsCode from './\_popover-news_code.md';
 
 # Popover news
-
+<!-- introduction start -->
+Popover news present important updates and information when the application starts.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/application-frame/settings.md b/packages/documentation/docs/controls/application-frame/settings.md
@@ -8,7 +8,9 @@ import DocsUx from './\_settings_styleguide.md';
 import DocsCode from './\_settings_code.md';
 
 # Settings overlay
-
+<!-- introduction start -->
+The settings overlay provides a centralized location for application settings.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/avatar.md b/packages/documentation/docs/controls/avatar.md
@@ -8,10 +8,9 @@ import Tags from './../auto-generated/ix-avatar/tags.md';
 # Avatar
 
 <Tags />
-
-<br/>
-<br/>
-
+<!-- introduction start -->
+Avatars visually or textually represent individual identities, typically for users logged into a system.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/blind.md b/packages/documentation/docs/controls/blind.md
@@ -5,6 +5,10 @@ import DocsCode from './\_blind_code.md'
 
 # Blind
 
+<!-- introduction start -->
+Blinds enhance content organization by allowing users to toggle visibility through collapsing and expanding sections.
+<!-- introduction end -->
+
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/breadcrumb.md b/packages/documentation/docs/controls/breadcrumb.md
@@ -4,7 +4,9 @@ import DocsUx from './\_breadcrumb_styleguide.md'
 import DocsCode from './\_breadcrumb_code.md'
 
 # Breadcrumb
-
+<!-- introduction start -->
+Breadcrumbs provide a clear path of navigation within an application.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/buttons/_link-button_styleguide.md b/packages/documentation/docs/controls/buttons/_link-button_styleguide.md
@@ -1,7 +1,4 @@
 ## Guidelines
-
-Link buttons are simple button components that lead users to another location within the application or outside of it. Link buttons contain a chevron and a text label.
-
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1506-4003&mode=design&t=5MYmq6zAbfw7xIkC-11)
 
 1. Chevron

diff --git a/packages/documentation/docs/controls/buttons/_split-button_styleguide.md b/packages/documentation/docs/controls/buttons/_split-button_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Split buttons are button elements that allow users to either trigger an action with one click or select an action from a list of options. They consist of two parts: a button labeled with text and/or an icon on the left and a dropdown button labeled with an icon on the right. We typically use split buttons when a default action is available but more options need to be offered. Split buttons group similar or related actions.
+Split buttons consist of two parts: a button labeled with text and/or an icon on the left and a dropdown button labeled with an icon on the right. We typically use split buttons when a default action is available but more options need to be offered. Split buttons group similar or related actions.
 
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1480-30799&mode=design&t=97WS5dUS2rk3MCp2-11)
 

diff --git a/packages/documentation/docs/controls/buttons/_toggle-button_styleguide.md b/packages/documentation/docs/controls/buttons/_toggle-button_styleguide.md
@@ -1,6 +1,6 @@
 ## Guidelines
 
-Toggle buttons are button elements which allow the user to activate/deactivate a function. Toggle buttons with and without text labels are available. We typically use toggle buttons within button groups when users can chose between more than two options or when two available options don't follow the on/off metaphor.
+Toggle buttons with and without text labels are available. We typically use toggle buttons within button groups when users can chose between more than two options or when two available options don't follow the on/off metaphor.
 
 ![Overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1480-33046&mode=design&t=iUJlfIvOwhKY3qk9-4)
 

diff --git a/packages/documentation/docs/controls/buttons/button.md b/packages/documentation/docs/controls/buttons/button.md
@@ -8,7 +8,9 @@ import DocsUx from './\_button_styleguide.md';
 import DocsCode from './\_button_code.md';
 
 # Button
-
+<!-- introduction start -->
+Buttons facilitate user interactions by initiating actions and applying functions within an application.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />

diff --git a/packages/documentation/docs/controls/buttons/dropdown-button.md b/packages/documentation/docs/controls/buttons/dropdown-button.md
@@ -12,10 +12,9 @@ import Tags from './../../auto-generated/ix-dropdown-button/tags.md'
 # Dropdown button
 
 <Tags/>
-
-<br/>
-<br/>
-
+<!-- introduction start -->
+Dropdown buttons reveal a list of actions on click on a button.
+<!-- introduction end -->
 <LinkableDocsTabs>
   <DocsUx />
   <DocsCode />