docs(pill): add ux guidelines (#964)

Co-authored-by: lzeiml <lukas.zeiml@siemens.com>
Co-authored-by: Lukas Maurer <lukas.maurer@siemens.com>
Co-authored-by: Silvio Wolf <115155312+silviowolf@users.noreply.github.com>
Co-authored-by: Julian Lamplmair <151610373+jul-lam@users.noreply.github.com>
Co-authored-by: Daniel Leroux <daniel.leroux@siemens.com>
Co-authored-by: linstedt <katrin.linstedt@siemens.com>
Co-authored-by: tokyojen <143795032+tokyojen@users.noreply.github.com>

packages/documentation/docs/controls/_chip_styleguide.md

@@ -33,7 +33,7 @@ Chip variants:
 
 - **Reactive**: Chips react or change their appearance or behavior based on user actions. For example, updates occur as a response to system actions, providing real-time information about system changes or events.
 - **Multi-selection**: Chips can visualize multi-selection and filter actions. This helps users to easily identify and understand their choices.
-- **Placement**: We typically place chips inline with other objects to inform users about their state, within tables or grouped together to show selected options and filters. We do not place chips within input and filter components as they have their own chip component variation, the input chip. Currently, input chips are not implemented as independent components.
+- **Placement**: We typically place chips inline with other objects to inform users about their state, within tables or grouped together to show selected options and filters. We do not place chips within input and filter components as these components have similar components already built-in.
 - **Dismiss**: When users select close, chips are dismissed from the list or interface and are removed visually.
 - **Text truncation**: When a width is set for chips, long labels are truncated to fit the available space.
 

packages/documentation/docs/controls/_pill_code.md

@@ -0,0 +1,45 @@
+import Playground from '@site/src/components/Playground';
+
+import Props from './../auto-generated/ix-pill/props.md';
+import Events from './../auto-generated/ix-pill/events.md';
+
+import SourcePill from './../auto-generated/previews/web-component/pill.md';
+import SourceReactPill from './../auto-generated/previews/react/pill.md';
+import SourceAngularPill from './../auto-generated/previews/angular/pill.ts.md';
+import SourceVuePill from './../auto-generated/previews/vue/pill.md';
+
+import SourcePillVariants from './../auto-generated/previews/web-component/pill-variants.md';
+import SourceAngularPillVariants from './../auto-generated/previews/angular/pill-variants.ts.md';
+import SourceReactPillVariants from './../auto-generated/previews/react/pill-variants.md';
+import SourceVuePillVariants from './../auto-generated/previews/vue/pill-variants.md';
+
+<Playground
+name="pill" height="24rem"
+frameworks={{
+  react: SourceReactPill,
+  angular: SourceAngularPill,
+  javascript: SourcePill,
+  vue: SourceVuePill
+}}>
+</Playground>
+
+## Variants
+<Playground
+name="pill-variants" height="24rem"
+frameworks={{
+  angular: SourceAngularPillVariants,
+  javascript: SourcePillVariants,
+  react: SourceReactPillVariants,
+  vue: SourceVuePillVariants
+}}>
+</Playground>
+
+## Properties
+
+### Props
+
+<Props />
+
+### Events
+
+<Events />

packages/documentation/docs/controls/_pill_styleguide.md

@@ -0,0 +1,52 @@
+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.
+
+
+![Pill overview](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1377%3A3110&mode=design&t=ZmcRP4ggXtr8b7vZ-1)
+
+1. Container
+2. Icon
+3. Label text
+
+## Variants
+With our pill variants, you can apply different colors based on their purpose, importance or context. We use chip variants to show class, status and levels of importance. The custom variant is often used for pills that visualize a high number of different categories.
+
+Pill variants:
+
+- **Primary**: For high visual emphasis.
+- **State-related variants**: Alarm, critical, warning, success, info and neutral.
+- **Custom**: For a customized background and label color.
+
+![Pill variants](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1375%3A1985&mode=design&t=ZmcRP4ggXtr8b7vZ-1)
+
+## Options
+
+- **Align left**: Position the pill content to the left side.
+- **Background**: Use to set a custom background color when you require more flexibility in styling the pill. Only available for the custom pill variant.
+- **Color**: Customize font and icon color for pill. This allows users to specify a unique font color in combination with a custom background color (only applicable when the variant is set to 'custom').
+- **Icon**: Pills can include a close icon within the element which is positioned before the pill label.
+- **Outline**: Use for lower visual emphasis.
+- **Width**: Pill width can be set to a specific value, but content length normally determines pill width with a minimum width of '2rem'. 
+
+## Behavior
+
+- **Placement**: We usually position pills inline with other elements to convey their status or category. We do not place pills within input and filter components as these already contain similar components. However, it's possible to add components similar to pills to tabs and navigation menu items. These counter or notification components are provided as component options. 
+- **Text truncation**: When you set a width for pills, long labels are truncated to fit the available space.
+
+## States
+
+Pills are read-only. 
+
+## Dos and Don'ts
+
+- Do use pills to communicate tags and categories
+- Do use pills to indicate the status or characteristics of an item
+- Don't overuse pills as this leads to cluttered and overwhelming interfaces
+- Don't use different styles for pills with the same or similar use
+- Don't use pills if users can interact with the component (e.g. click, close) use chips instead
+
+## Related patterns
+
+- [Chip](chip.md)
+
+
+

packages/documentation/docs/controls/pill.md

@@ -1,49 +1,12 @@
-import Playground from '@site/src/components/Playground';
+---
+title: Pill
+---
+import Playground from '@site/src/components/Playground'
+import DocsTabs from '@site/src/components/DocsTabs';
 
-import Props from './../auto-generated/ix-pill/props.md';
-import Events from './../auto-generated/ix-pill/events.md';
-
-import SourcePill from './../auto-generated/previews/web-component/pill.md';
-import SourceReactPill from './../auto-generated/previews/react/pill.md';
-import SourceAngularPill from './../auto-generated/previews/angular/pill.ts.md';
-import SourceVuePill from './../auto-generated/previews/vue/pill.md';
-
-import SourcePillVariants from './../auto-generated/previews/web-component/pill-variants.md';
-import SourceAngularPillVariants from './../auto-generated/previews/angular/pill-variants.ts.md';
-import SourceReactPillVariants from './../auto-generated/previews/react/pill-variants.md';
-import SourceVuePillVariants from './../auto-generated/previews/vue/pill-variants.md';
+import DocsUx from './\_pill_styleguide.md'
+import DocsCode from './\_pill_code.md'
 
 # Pill
 
-## Usage
-
-<Playground
-name="pill" height="24rem"
-frameworks={{
-  react: SourceReactPill,
-  angular: SourceAngularPill,
-  javascript: SourcePill,
-  vue: SourceVuePill
-}}>
-</Playground>
-
-## Variants
-<Playground
-name="pill-variants" height="24rem"
-frameworks={{
-  angular: SourceAngularPillVariants,
-  javascript: SourcePillVariants,
-  react: SourceReactPillVariants,
-  vue: SourceVuePillVariants
-}}>
-</Playground>
-
-## Properties
-
-### Props
-
-<Props />
-
-### Events
-
-<Events />
+<DocsTabs styleguide={DocsUx} code={DocsCode} />