Docs/badge guide

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,108 @@
+---
+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.
+
+![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 that represents the related information. As a general rule, we use badges for dynamic status or notification information and [chips](../chip) when users need to interact with the item.
+
+## Types
+
+Badge types define how the indicator appears:
+
+- **Counter (default):** 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 a readable status, e.g. "Online" or "Offline" in a list.
+- **Dot:** Use when only the presence of new information matters, e.g. for a compact notification that needs attention without a count.
+- **Status icon:** Use for showing statuses or notifications that are recognizable by icon alone.
+
+## Variants
+
+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 or exploratory information.
+- **Alarm:** Show negative values, removals or high-urgency counts, e.g. critical equipment faults or imminent system failures.
+- **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
+Use standalone label badges to replace deprecated [pills](../pill) usages, e.g. compact statuses or categories.
+:::
+
+## 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:** We usually show the full status name and use max-width to control lengthy labels. Keep labels short to avoid truncation.
+- **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. Not applicable to outline badges.
+- **Offset:** Keep the indicator close to the anchor without covering it fully and without leaving the parent's visual bounding box, e.g. round elements like avatars need larger negative offsets.
+- **Pulse animation:** Use only for immediate, urgent attention. Note that it might not be visible with certain a11y browser configurations.
+- **Custom colors:** With the custom variant, set background and badge color together so contrast stays readable.
+- **Tooltip text**: For standalone badges, 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.
+
+## Behavior in context
+
+![Badge behavior](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=8173-214&t=OTo6nDmRwFCU9cVf-4)
+
+- **Overflow:** With a max width, label text truncates. Counter badges 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.
+- **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 states, but support text selection. If enabled, badges are pulsing until the application disables them.
+
+## Dos and Don’ts
+
+<div class="dos-and-donts">
+  <div class="dos">
+    <ul aria-label="Recommended practices">
+      <li>Do keep counter labels to integers with at most two digits, using 99+ when needed</li>
+      <li>Do attach badges to the control that opens or represents the related information</li>
+      <li>Do prefer dot or status icon badges over long labels in compact layouts</li>
+      <li>Do keep badges synchronized with the underlying notification state</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>
+      <li>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.</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/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

@@ -159,6 +159,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

@@ -951,6 +951,20 @@ const sidebars: SidebarsConfig = {
       className: 'doc-sidebar-item-bold',
       label: 'System feedback and status',
       items: [
+        createTabItem({
+          id: 'components/badge/index',
+          label: 'Badge',
+          items: [
+            {
+              id: 'components/badge/guide',
+              label: 'Usage',
+            },
+            {
+              id: 'components/badge/code',
+              label: 'Code',
+            },
+          ],
+        }),
         createTabItem({
           id: 'components/empty-state/index',
           label: 'Empty state',