docs(badge): add initial guides and code

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,105 @@
+---
+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 (for larger values).
+- **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 clear meanings:
+
+![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. It loops until explicitly disabled. Note that `prefers-reduced-motion` settings might override this.
+- **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](../tooltip) or set the attribute without a specific value to display the badge's text content (see [writing guide](../../guidelines/language/messaging/tooltips)).
+
+## Behavior in context
+
+![Badge behavior](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=8173-214&t=OTo6nDmRwFCU9cVf-4)
+
+- **Overflow:**
+  - Label badges: If a max-width is applied, label is truncated.
+  - Counter badges: If more than 2 digits are entered, label shows "99+".
+- **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 visible, e.g. the icon that identifies a notification button.
+- **Screen readers:** Labels of standalone badges are read by screen readers. Attached badges are read as part of their anchor’s accessible name.
+
+## States
+
+Badges are read-only. They don't have hover, active or disabled states, but standalone badges support text selection.
+
+## Dos and Don’ts
+
+<div class="dos-and-donts">
+  <div class="dos">
+    <ul aria-label="Recommended practices">
+      <li>Do provide an accessible name for dot and status icon badges by using `aria-label` on the anchor when attached, or on the badge when standalone</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, e.g. update or remove them when users read notifications</li>
+      <li>Do include the badge meaning in the accessible name of its anchor</li>
+      <li>Do announce meaningful dynamic updates while considering cognitive load on the user</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](../chip) 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
 
+:::warning
+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',