Docs/badge guide

.env.pullrequest

@@ -0,0 +1,4 @@
+IX_REPO_BRANCH='main'
+IX_REPO_TYPE='pull request' # For pull requests use "pull request" as value
+
+IX_REPO_PR='2645'

docs/components/badge/code.mdx

@@ -0,0 +1,34 @@
+---
+doc-type: 'tab-item'
+description: 'Code examples and API documentation for the ix-badge'
+---
+
+import PropsApi from '@site/docs/autogenerated/api/ix-badge/api.mdx';
+import BadgePlayground from '@site/docs/autogenerated/playground/badge.mdx';
+import BadgeCounterPlayground from '@site/docs/autogenerated/playground/badge-counter.mdx';
+import BadgeLabelPlayground from '@site/docs/autogenerated/playground/badge-label.mdx';
+import BadgeDotPlayground from '@site/docs/autogenerated/playground/badge-dot.mdx';
+import BadgeStatusIconPlayground from '@site/docs/autogenerated/playground/badge-status-icon.mdx';
+
+# Badge - Code
+
+## Basic
+
+<BadgePlayground height="15rem" />
+
+## Counter
+
+<BadgeCounterPlayground height="24rem" />
+## Label
+
+<BadgeLabelPlayground height="24rem" />
+
+## Dot
+
+<BadgeDotPlayground height="20rem" />
+
+## Status icon
+
+<BadgeStatusIconPlayground height="19rem" />
+
+<PropsApi />

docs/components/badge/guide.md

@@ -0,0 +1,107 @@
+---
+doc-type: 'tab-item'
+description: 'Usage guide for the badge component'
+---
+# Badge - Usage
+
+Badges are non-interactive visual aids for status, counters and notification cues. We recommend badges when users need a compact signal next to another element or a lightweight standalone status cue. Interaction always belongs to the anchor, not to the badge.
+
+![Badge anatomy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=8141-4052&t=v625YpvIn3UzoFuJ-4)
+
+1. Badge of type `label` as standalone
+2. Badge of type `counter`
+3. Badge of type `dot`
+4. Badge of type `status icon`
+5. Anchor element
+
+Badges work **standalone** or **attached** to an anchor. As a general rule, we use badges for dynamic status or notification information and [chips](../chip) when users need to interact with the item.
+
+## Variants
+
+Badge types define how the indicator appears:
+
+- **Counter:** Default type. Use for notifications that need attention, with integers up to two digits (`99+` for larger values). Short words are an exception, e.g. `new`.
+- **Label:** Use for status, e.g. Online or Offline in a list. Labels can include an icon that matches the semantic meaning of the color.
+- **Dot:** Use for a compact notification that needs attention without a count.
+- **Status icon:** Use for notifications that need attention or to show a status with a semantic glyph.
+
+Semantic color variants communicate meaning, not decoration:
+
+![Badge variants](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=8141-4066&t=v625YpvIn3UzoFuJ-4)
+
+- **Primary:** Highlight new features, discoveries or exploratory information.
+- **Alarm:** Show negative values, removals or high-urgency counts.
+- **Critical:** Emphasize severe conditions that require strong attention.
+- **Warning:** Call attention to information that requires caution, e.g. pending actions.
+- **Info:** Draw attention to new or updated information or informative numeric data.
+- **Success:** Show positive values or additions, e.g. growth metrics.
+- **Neutral:** Use for general-purpose information that doesn’t carry semantic meaning.
+- **Custom:** Set an explicit background and badge color when you need a product-specific palette.
+
+We recommend matching icons on label badges to the meaning of the chosen color. Prefer outlined styles when you need lower visual emphasis on busy surfaces.
+
+:::info
+Badges with type `label` replace the deprecated [pill](../pill). Use a standalone label badge for existing pill use cases, e.g. compact statuses or categories. Attach it to an anchor only when the label supplements that specific element.
+:::
+
+## Options
+
+![Badge options](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=8161-118&t=OTo6nDmRwFCU9cVf-4)
+
+- **Placement:** Use inline (standalone) to show an entity’s status in a list. With an anchor, we typically use `top after` for notifications that need attention and `bottom after` for status on individual elements, e.g. user presence.
+- **Label:** Grows with content unless you set a max width via `--ix-badge-max-width`.
+- **Outline:** Intended for lower visual emphasis on standalone badges. On status icons, outline selects the outline glyph.
+- **Border:** Add a high-contrast border on filled badges when the surface behind them is busy. Ignore border when outline is on.
+- **Offset:** Keep the indicator close to the anchor without covering it fully and without leaving the parent bounding box. Defaults are type-specific in the component.
+- **Pulse animation:** Use `enable-animation` only for immediate, urgent attention. Animation respects `prefers-reduced-motion`.
+- **Custom colors:** With the custom variant, set background and badge color together so contrast stays readable.
+- **Tooltip text**: Provide a specific text to be displayed as the tooltip or set the attribute without a specific value to display the badge's text content. The tooltip works only for standalone badges.
+
+## Behavior in context
+
+![Badge behavior](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=8173-214&t=OTo6nDmRwFCU9cVf-4)
+
+- **Interaction:** Badges are read-only visual cues with no interaction but label text can be selected.
+- **Overflow:** With a max width, label text truncates. We recommend short labels. Badges of type `counter` do not provide an overflow due to limited character count.
+- **Container and overlapping:** An attached badge overlaps the anchor at its edge without extending the parent’s bounding box. This placement leaves the anchor recognizable and its critical content, e.g. the icon that identifies a notification button, visible.
+- **Responsiveness:** In compact layouts, we usually prefer dot or status icon badges over long labels.
+- **Notification context:** Attach badges to the control that opens or represents the related information, e.g. a notification or calendar icon. Use counters when the number helps users decide what to do, dots when only the presence of new information matters and status icons when users need to recognize a state or severity.
+- **Updates:** Keep badges synchronized with the underlying notification state. Update or remove the indicator when users read notifications or when the status changes, and don’t leave stale counts or statuses attached to an anchor.
+- **Accessibility**
+   - **Accessible naming:** When badges are attached, include their meaning in the anchor’s accessible name, e.g. “Notifications, 3 unread”. Standalone dot and status icon badges need an accessible name because they don’t contain readable text.
+   - **Dynamic updates:** We recommend a polite live region when users need to hear an important badge update without moving focus. Reserve assertive announcements for critical conditions that require immediate attention, and don’t announce routine count changes.
+   - **Reading order:** Treat an attached badge and its anchor as one accessible unit. Avoid exposing the same information separately when this causes duplicate announcements.
+
+## States
+
+Badges are read-only. They don’t have hover, active or disabled interaction states of their own. When pulse animation is enabled, it draws attention until the application disables it.
+
+## Dos and Don’ts
+
+<div class="dos-and-donts">
+  <div class="dos">
+    <ul aria-label="Recommended practices">
+      <li>Do use badges for status, counters or notification cues that stay secondary to the anchor</li>
+      <li>Do keep counter labels to integers with at most two digits, using 99+ when needed</li>
+      <li>Do include the badge meaning in the accessible name of its anchor</li>
+      <li>Do announce meaningful dynamic updates without announcing every routine count change</li>
+      <li>Do keep the badge inside the parent and leave enough of the anchor visible</li>
+    </ul>
+  </div>
+  <div class="donts">
+    <ul aria-label="Practices to avoid">
+      <li>Don’t make badges interactive, use chips when users need to click or dismiss</li>
+      <li>Don’t use color alone to convey meaning without supporting text or ARIA on the host or anchor</li>
+      <li>Don’t rely on pulse animation for long-running or low-priority hints</li>
+      <li>Don’t place essential primary content only in a badge</li>
+    </ul>
+  </div>
+</div>
+
+## Related
+
+- [Pill](../pill)
+- [Chip](../chip)
+- [Popover](../popover)
+- [UX writing basics](../../guidelines/language/basics)
+- [Accessibility](../../guidelines/accessibility)

docs/components/badge/ideation.md

@@ -0,0 +1,132 @@
+# Badge - usage guide (outline)
+
+> ![Important]
+> This is a draft outline for the Badge component usage guide. It is intended to be a starting point for discussion and feedback. Please provide your input on the content, structure, and any additional information that should be included.
+
+Writing: consider wording people may not understand what you mean / also consider punctuation within the badge e,g, 1/2 1(1)
+
+## Purpose and usage context
+
+- Badges are **non-interactive, visual aids** for status, counters and notification cues.
+- Badges generally carry dynamic information.
+- ▶️ Badge vs Chip?
+
+## Anatomy
+
+* **Label**: Anchor, Icon, Label
+* **Counter**: Anchor, Label
+* **Dot**: Anchor, Dot
+* **Status icon**: Anchor, Icon
+
+▶️ Add anchor?
+
+## Types
+
+Can be used **standalone or with an anchor element**. When attached to interactive anchors, interaction belongs to anchor.
+
+Supported types:
+
+- **label**: use for showing an entity's status (replaces pill)
+- **counter** (default): use for notifications that need attention
+- **status-icon**: use for notifications that need attention OR showing an entity's status
+- **dot**: use for notifications that need attention
+
+## Variants
+
+- **primary**: highlight new features, discoveries, or exploratory information
+- **alarm**: show negative values, removals, or critical information e.g. when characters are removed from a line of code in Bitbucket, or when displaying critical counts.
+- **critical**: ???
+- **warning**: call attention to information that requires caution or awareness, such as pending actions or items requiring attention
+- **info**: draw attention to new or updated information, or to highlight informative numeric data
+- **success:** show positive values or additions e.g. when characters are added to a line of code in Bitbucket, or when displaying growth metrics.
+- **neutral:** for general-purpose numeric information that doesn't require semantic meaning
+- **custom:** Custom colors should go through variant=custom with explicit background and badgeColor.
+
+▶️ When to use which?
+
+**Rule:** Use semantic variants for meaning, not decoration only. For label variant, choose icons that semantically correspond to the color meaning
+
+> [!NOTE]
+> Show ALL variants with types as figma illustration - esp. the status icon should be shown
+
+
+## Options
+
+- **Placement**:
+    - **Inline** (without anchor element): Use to show entity's status in a list, e.g. a list of devices with "Online", "Offline", "Idle" etc.
+    - **Top after** (default with anchor): Use as notification indicator that needs attention
+    - **Bottom after**: Use for entity status information for individual elements, e.g. user status
+- **Label**:
+    - grows with content unless max width is configured
+- **Counter**:
+    - Use integers only with up to 2 digits (99+ instead of 100)
+    - Should zero counters be hidden by default or visible when explicitly meaningful?
+    - Exception: Use short words (e.g. new)
+- **Status icon**: ?
+- **Pulse animation**:
+    - In which product moments is pulsing allowed? - use it for getting immediate and urgent attention
+    - Should pulsing be stopped after a defined time?
+- **X- and Y-offset**:
+    - By default -10px for label, counter and status icon; -6px for dot
+    - Do not fully overlap the anchor icon.
+    - Do not place badge outside parent bounding box
+    - ▶️ Any recommendations??
+    - ▶️ Do we define minimum visible anchor area when badge is attached?
+    - ▶️ Any mobile-specific adjustments for badge geometry?
+
+## Behavior in context
+
+- **Resizing**:
+    - Labels are hug-width except max-width is applied
+- **Overflow**:
+    - If a max-width is applied on label badges text gets truncated
+
+## Interaction behavior
+
+- no badge interaction
+- label allows text selection
+
+## Accessibility
+
+- Badge styling alone is not conveyed to assistive technologies. Instead, accessible naming should be clear in anchor context.
+- For icon-only modes (dot/status-icon), add explicit aria labeling.
+- Suggested mechanisms from sources:
+    - role/status semantics for standalone use
+    - optional live-region strategy for updates
+    - aria-label support for icon use cases
+- Intentionally define reading order for:
+    - standalone label
+    - standalone counter
+    - standalone dot
+    - standalone status icon
+    - attached anchor+badge combinations
+- Animation: Respects prefers-reduced-motion.
+- ▶️ Default standalone role: status by default, alert for urgency, or product-controlled?
+- ▶️ Should aria-live be default or opt-in?
+
+## Add-on insights from external systems (non-binding)
+
+- MUI - https://mui.com/material-ui/react-badge/:
+    - badge is supplemental status, not primary information container
+    - anchor accessible name should include badge meaning
+    - dot variant for simple state
+- Atlassian - https://atlassian.design/components/badge/:
+    - semantic appearance naming
+    - max value and optional uncapped mode
+- Material 3 - https://m3.material.io/components/badges/overview:
+    - upper-trailing placement pattern
+    - compact character limits
+- Carbon tag guidance (adjacent pattern) - https://carbondesignsystem.com/components/tag/usage/
+    - overflow disclosure via tooltip
+    - avoid multiline tag/badge text
+    - clear separation of read-only vs interactive patterns
+
+## Sources used
+
+- Figma component: Badge node 138139:15345
+- Web component props suggestion (props-v1)
+- Element design system badges docs:
+    - https://element.siemens.io/components/status-notifications/badges/
+    - usage, design and accessibility sections
+- Additional web sources (see above)
+

docs/components/badge/index.mdx

@@ -0,0 +1,5 @@
+---
+doc-type: "tabs"
+description: 'Badges display compact status, counter or notification cues on or next to UI elements.'
+title: 'Badge'
+---

docs/components/checkbox/code.mdx

@@ -34,7 +34,7 @@ Enclosing related checkboxes within a single checkbox group container ensures co
 
 ## Validation
 
-<FormCheckboxValidationPlayground height="34rem" />
+<FormCheckboxValidationPlayground height="36rem" />
 
 <PropsApi />
 

docs/components/overview.md

@@ -154,6 +154,7 @@ import { CategoryButton } from '@site/src/components/CategoryButton';
 | :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [Empty state](./empty-state/index.mdx)            | Empty states inform users that there is no content to display.                                                                                     |
 | [Message bar](./messagebar/index.mdx)             | Message bars display important information to users, e.g. feedback, warnings or errors.                                                            |
+| [Badge](./badge/index.mdx)                        | Badges display compact status, counter or notification cues on or next to UI elements.                                                             |
 | [Pill](./pill/index.mdx)                          | Pills display small pieces of information, e.g. counters or statuses.                                                                              |
 | [Popover](./popover/index.mdx)                    | Popovers display contextual information in a floating panel anchored to a trigger element.                                                         |
 | [Progress indicator](progress-indicator/guide.md) | Progress indicators inform users about the status of ongoing processes, e.g. loading data, submitting forms or processing non-blocking operations. |

docs/components/pill/code.mdx

@@ -9,6 +9,10 @@ import PillVariantsPlayground from '@site/docs/autogenerated/playground/pill-var
 
 # Pill - Code
 
+:::info
+Pills are deprecated and removed in V7.0.0. We recommend using [badges](../badge/index.mdx) with type `label` instead, which support the same compact status and category use cases.
+:::
+
 ## Basic
 
 <PillPlayground />

docs/components/pill/guide.md

@@ -4,6 +4,10 @@ description: 'Usage guide for the ix-pill'
 ---
 # Pill - Usage
 
+:::info
+Pills are deprecated and removed in V7.0.0. We recommend using [badges](../badge/index.mdx) with type `label` instead, which support the same compact status and category use cases.
+:::
+
 Pills typically 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)

sidebars.ts

@@ -1003,6 +1003,20 @@ const sidebars: SidebarsConfig = {
             },
           ],
         }),
+        createTabItem({
+          id: 'components/badge/index',
+          label: 'Badge',
+          items: [
+            {
+              id: 'components/badge/guide',
+              label: 'Usage',
+            },
+            {
+              id: 'components/badge/code',
+              label: 'Code',
+            },
+          ],
+        }),
         createTabItem({
           id: 'components/pill/index',
           label: 'Pill',