prime-ui-kit 0.7.13 → 0.9.1

package/src/components/avatar/examples/team-group.tsx

@@ -0,0 +1,21 @@
+/** Project members as an overlapping row with a «+N» cell; the group size goes to every member — `Avatar.Group`, `Avatar.Overflow`, `size`. */
+import { Avatar } from "prime-ui-kit";
+
+const MEMBERS = [
+  { initials: "АК", color: "blue" },
+  { initials: "ДН", color: "green" },
+  { initials: "ЖП", color: "orange" },
+] as const;
+
+export default function AvatarTeamGroupExample() {
+  return (
+    <Avatar.Group size="s" aria-label="Участники проекта: 6">
+      {MEMBERS.map((member) => (
+        <Avatar.Root key={member.initials} color={member.color}>
+          <Avatar.Fallback>{member.initials}</Avatar.Fallback>
+        </Avatar.Root>
+      ))}
+      <Avatar.Overflow aria-label="Ещё 3 участника">+3</Avatar.Overflow>
+    </Avatar.Group>
+  );
+}

package/src/components/avatar/examples/variants.tsx

@@ -0,0 +1,40 @@
+/** Every palette hue of the fallback; derive it from a stable user id — `color`. */
+import { Avatar, Typography } from "prime-ui-kit";
+
+const ROWS = [
+  [
+    { initials: "АК", color: "gray" },
+    { initials: "БС", color: "blue" },
+    { initials: "ВЛ", color: "sky" },
+    { initials: "ГМ", color: "teal" },
+    { initials: "ДН", color: "green" },
+  ],
+  [
+    { initials: "ЕО", color: "yellow" },
+    { initials: "ЖП", color: "orange" },
+    { initials: "ЗР", color: "red" },
+    { initials: "ИС", color: "pink" },
+    { initials: "КТ", color: "purple" },
+  ],
+] as const;
+
+export default function AvatarVariantsExample() {
+  return (
+    <>
+      {ROWS.map((row) => (
+        <div key={row[0].color}>
+          {row.map(({ initials, color }) => (
+            <div key={color}>
+              <Avatar.Root color={color}>
+                <Avatar.Fallback>{initials}</Avatar.Fallback>
+              </Avatar.Root>
+              <Typography as="span" variant="caption" tone="muted">
+                {color}
+              </Typography>
+            </div>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}

package/src/components/badge/COMPONENT.md

@@ -1,115 +1,182 @@
 # Badge
 
-**Default sizing:** When designing screens or samples, prefer **`size="m"`** unless the scenario explicitly needs another value.
-
-## About
-
-A compact, non-interactive label for status, category, or counts. Optional `Badge.Dot` and `Badge.Icon` slots align a decorative dot or an icon with text; `variant="status"` adds a built-in presence dot and live-region semantics.
-
-- **Use** for short metadata next to headings, table rows, or list items (stage, environment, stock, role).
-- **Use** `variant="status"` for presence when visible copy fits; pass **`label`** when assistive tech needs more than `children` alone (see Rules).
-- **Use** semantic **`color`** with **`variant`** (`filled`, `light`, `lighter`, `stroke`) for emphasis on dashboards and catalogs.
-- **Use** **`Badge.Icon`** when the icon should inherit badge sizing from the surrounding `ControlSizeProvider` (root provides it for children).
-- **Do not use** as the primary control for clicks or navigation — use [Button](../button/COMPONENT.md) or [LinkButton](../link-button/COMPONENT.md).
-- **Do not use** for removable or selectable tags — use [Tag](../tag/COMPONENT.md).
-- **Do not use** for keyboard shortcut glyphs — use [Kbd](../kbd/COMPONENT.md).
-
-## Composition
-
-- **`Badge.Root`** — root `div`; wraps `children` in `ControlSizeProvider` so nested icons can inherit control size. With **`variant="status"`**, renders a built-in status dot (`aria-hidden`), sets `role="status"`, optional `aria-label` from `label`, and ignores `color` for styling (dot color follows `status`).
-- **`Badge.Dot`** — optional decorative dot (`span`, `aria-hidden`); use with non-status variants when you need a manual indicator next to text or icons.
-- **`Badge.Icon`** — optional `span` wrapper for an icon node; place it before or after text, or use it alone for icon-only badges.
-
-## Examples
-
-### Canonical
-
-Source of truth: [`examples/canonical.tsx`](./examples/canonical.tsx).
-
+**Category:** data-display
+**Kind:** primitive
+
+> The kit's one chip: a static label for a status, category or count, a removable value or applied filter, and a pressable toggle with a hover action — in a palette color.
+
+## When to use
+- Status or category of a row in a table or list («Оплачен», «Черновик», «Бета»).
+- Counters inside buttons and fields («Входящие 12», «−25%»).
+- A workflow state with a leading dot (`Badge.Dot`).
+- A selected value, keyword or applied filter the user can remove (`onRemove`).
+- Values in a filter panel that toggle on press and hide with a hover action (`onPress`, `Badge.Action`).
+
+## When not to use
+- A multi-select field with chips → use [TagSelect](../tag-select/COMPONENT.md) (it renders badges itself).
+- A keyboard key or shortcut → use [Kbd](../kbd/COMPONENT.md).
+- A person's presence → `Avatar.Status` from [Avatar](../avatar/COMPONENT.md).
+- A command (save, open, go somewhere) → use [Button](../button/COMPONENT.md); a pressable badge toggles a value.
+- A message about the page or a section → use [Banner](../banner/COMPONENT.md).
+
+## Import
 ```tsx
 import { Badge } from "prime-ui-kit";
-
-export default function BadgeCanonicalExample() {
-  return <Badge.Root>New</Badge.Root>;
-}
 ```
 
-### Extended (copy from repo)
-
-| File | Scenario |
-|------|----------|
-| [`examples/status-presence.tsx`](./examples/status-presence.tsx) | Presence: `variant="status"`, `status`, `label` |
-| [`examples/ecommerce-inventory.tsx`](./examples/ecommerce-inventory.tsx) | Stock, promo, secure checkout with `Badge.Icon` |
-| [`examples/inbox-labels.tsx`](./examples/inbox-labels.tsx) | Priority, unread, channel type, `Badge.Dot` |
-| [`examples/admin-tags.tsx`](./examples/admin-tags.tsx) | Environment, access, feature-flag labels |
-
-### Playground snippets
-
-Order matches [`playground/sections/BadgeSection.tsx`](../../../playground/sections/BadgeSection.tsx). Snippets import from `@/components/badge/Badge` in-repo; consumers use **`import { Badge } from "prime-ui-kit"`**.
-
-| File | Scenario |
-|------|----------|
-| `playground/snippets/badge/sizes.tsx` | Explicit `size` `s`–`xl` with `variant="light"` and `color="gray"`. |
-| `playground/snippets/badge/variants.tsx` | `filled`, `light`, `lighter`, `stroke` on one `color`; `variant="status"` with `status` and `label`. |
-| `playground/snippets/badge/disabled.tsx` | `disabled` on `filled`, `stroke`, and `status`. |
-| `playground/snippets/badge/dot-icon.tsx` | `Badge.Dot` before text; `Badge.Icon` with text. |
-| `playground/snippets/badge/icons.tsx` | Icon left, variants/sizes, icon-only row, icon right, `Badge.Dot` + `Badge.Icon`. |
-| `playground/snippets/badge/semantic-colors.tsx` | Every `color` on `variant="light"` and `size="m"`. |
-| `playground/snippets/badge/context-size.tsx` | No `size` on root: `ControlSizeProvider`; context `xs` maps to badge visual `s`. |
-
-Prefer **`examples/*.tsx`** for product-shaped English samples.
-
-## Note for LLM consumers
-
-- **Imports:** In consumer code and doc samples, import **`Badge`** (and **`Icon`** when needed) from **`"prime-ui-kit"`** only — not from `@/components/...`.
-- **Status mode:** When **`variant="status"`**, set **`label`** if visible **`children`** do not carry enough meaning alone (e.g. generic “Away” without whose presence). The built-in dot is **`aria-hidden`**; do not use it as the only state signal.
-- **Tag vs Badge:** **Badge** is read-only metadata; **Tag** is for removable/filter chips — see [Tag](../tag/COMPONENT.md).
-- **Sizing:** Omit **`size`** to follow the nearest **`ControlSizeProvider`**; otherwise default effective size is **`m`** (context **`xs`** maps to badge **`s`**).
-- **Colors:** **`color`** is ignored for styling when **`variant="status"`**; use **`status`** for the dot.
-
-## Rules
-
-- Omit `size` to inherit from the nearest `ControlSizeProvider` / control-surface context; if none is present, the effective size is **`m`**. Context value **`xs`** maps to badge size **`s`**.
-- With **`variant="status"`**, pass **`label`** when visible `children` alone are not enough for assistive tech (e.g. a generic word without whose status it is).
-- **`Badge.Dot`** (both manual and the built-in status dot) is **`aria-hidden`** — do not rely on it alone to communicate state.
-- **`disabled`** dims the badge via `data-disabled`; there is no loading, error, or focus ring — the badge is not keyboard-operable.
-- **`color`** applies only when **`variant` is not `"status"`**; for status mode, dot appearance is driven by **`status`** (default **`online`** when unset).
+## Anatomy
+```
+Badge.Root          <span>: fill, tier dimensions
+├─ [start segment]  Badge.Icon or Badge.Dot at the start edge: full height, mark centred
+├─ body             text, Badge.Dot, inline Badge.Icon
+│                   (a <button> with onPress; a <span> with a trailing segment; none when read-only)
+├─ Badge.Action     optional end segment revealed on hover / focus
+└─ remove segment   with onRemove: full height, the whole end is the hit area (Icon action.close)
+```
 
 ## API
 
-### Badge.Root
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `color` | `"gray" \| "red" \| "blue" \| "green" \| "orange" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | No | Semantic palette; ignored for styling when `variant="status"`. |
-| `variant` | `"filled" \| "light" \| "lighter" \| "stroke" \| "status"` | `"light"` | No | Fill, stroke, or status layout with built-in dot. |
-| `size` | `"s" \| "m" \| "l" \| "xl"` | from context or `"m"` | No | Explicit size; otherwise derived from control surface context, else `"m"`. |
-| `disabled` | `boolean` | — | No | Muted look; sets `data-disabled`. |
-| `status` | `"online" \| "offline" \| "away" \| "busy"` | `"online"` | No | Dot semantics when `variant="status"`; ignored otherwise. |
-| `label` | `string` | — | No | `aria-label` on the root when `variant="status"`. |
-| `children` | `React.ReactNode` | — | No | Text, `Badge.Dot`, `Badge.Icon`, or icons. |
-| `className` | `string` | — | No | Extra class on the root. |
-| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other attributes and `ref` on the root `div`. |
+### Badge.Root
+`ref` → `HTMLSpanElement`. The chip: fill, tier dimensions; a read-only badge is one `<span>`, `onPress` makes the body a `<button>`, `onRemove` adds a remove segment.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Palette hue. Categorizes; the text carries the meaning. |
+| `variant` | `"solid" \| "soft" \| "outline"` | `"soft"` | Treatment. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | — | Badge tier, 16 · 20 · 24 · 28 · 32 px high. Without it the badge follows the surrounding control one tier down; outside a control it is `m`. |
+| `onRemove` | `() => void` | — | Adds the full-height remove segment at the end; called on its click. |
+| `onPress` | `(event: MouseEvent<HTMLButtonElement>) => void` | — | Makes the body a `<button>` covering the whole badge (a toggle chip, a filter value); gets the event, so Alt / Shift clicks can mean more. |
+| `pressed` | `boolean` | — | Toggle state of a pressable badge: `aria-pressed` on the body, `data-pressed` on the root. |
+| `disabled` | `boolean` | — | Muted look for every variant, `aria-disabled`; the body button, remove and action get native `disabled`. |
+| `labels` | `Partial<BadgeLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — | Text, `Badge.Dot`, `Badge.Icon`, one `Badge.Action`. Only `Badge.Icon` children (no remove or action) make a square icon-only badge. |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className`, `aria-label` (icon-only) and the other span attributes. |
 
 ### Badge.Icon
+`ref` → `HTMLSpanElement`. A `<span>` holding one icon at the tier icon size. At the first or last position it becomes a full-height edge segment.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `children` | `React.ReactNode` | — | Yes | Icon node. |
-| `className` | `string` | — | No | Wrapper class. |
-| … | `Omit<React.HTMLAttributes<HTMLDivElement>, "children">` | — | No | Other wrapper attributes. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon (`Icon`). |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Badge.Dot
+`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` dot in the text color; at an edge it becomes a segment like an edge icon. Also usable alone (a marker on an icon, before a label): it takes the tier of the surrounding control (6px, 8px from `l`) and the color set on it.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
+
+### Badge.Action
+`ref` → `HTMLButtonElement`. A `<button>` segment at the end, revealed on hover and focus; the badge reserves its room, so the width never changes. One per badge, not together with `onRemove`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — (required) | Accessible name and tooltip («Скрыть billing»). |
+| `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | — (required) | Runs the action. |
+| `persistent` | `boolean` | `false` | Keeps the action shown, not only on hover and focus (while the state it sets is on). |
+| `pressed` | `boolean` | — | Toggle state of the action: `aria-pressed`. |
+| `disabled` | `boolean` | `false` | The action is unavailable. |
+| `children` | `ReactNode` | — | A custom glyph at the tier icon size; a minus by default. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "onClick" \| "children">` | — | `className` and the other button attributes. |
+
+## Variants
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `soft` | light palette fill, hue text | statuses and categories — the normal case | yes |
+| `solid` | saturated hue fill, contrasting text | one label per area that must stand out | |
+| `outline` | transparent, 1px inset line in the hue text at 32% | a quiet secondary label next to soft badges | |
+
+### color
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `gray` | neutral wash | draft, archived, cancelled | yes |
+| `blue` | blue | in progress, counters | |
+| `green` | green | success, paid, published | |
+| `orange` | orange | waiting, needs attention | |
+| `red` | red | failed, rejected, urgent | |
+| `yellow` | yellow | paused, under review | |
+| `purple` | purple | roles, private categories | |
+| `sky` · `pink` · `teal` | extra hues | more categories | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 16px high, text 12, icon 12 | inside `xs` / `s` controls | |
+| `s` | 20px high, text 12, icon 12 | inside `m` controls (inherited automatically) | |
+| `m` | 24px high, text 12, icon 14 | standalone labels in tables and lists | yes (outside controls) |
+| `l` | 28px high, text 13, icon 16 | next to section titles | |
+| `xl` | 32px high, text 14, icon 16 | large headers | |
+| — (omitted) | one tier below the surrounding control | inside Button, Input, Tabs | yes (inside controls) |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `disabled` | muted fill, disabled text, no outline, for every variant | the labelled item is inactive | `false` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| hue / treatment | `color`, `variant` | `data-color`, `data-variant` (always set) |
+| size | `size`, else the control, else `m` | `data-size`, `data-tier` (visual tier) |
+| icon segments | edge `Badge.Icon` / `Badge.Dot`, icon-only | `data-icon-start`, `data-icon-end`, `data-icon-only` |
+| plain text | read-only, text children only | `data-text-only`: the root is one block box that ellipsizes; otherwise each text run sits in its own block span |
+| removable | `onRemove` | `data-removable`; the remove segment takes a `fill-subtle-active` wash on hover |
+| pressable / pressed | `onPress`, `pressed` | `data-pressable`, `data-pressed`, `aria-pressed` on the body; `fill-subtle` wash on hover |
+| action | `Badge.Action` | `data-action="reveal" \| "persistent"`; the text slides and the segment fades in over `fast` |
+| disabled | `disabled` | `data-disabled`, `aria-disabled`; inner buttons disabled |
+
+## Layout & spacing
+- Inline-flex, `width: fit-content`, `max-width: 100%`; text never wraps and ends in an ellipsis.
+- Segments are `mark + padding + gap` wide and full height; the mark sits with equal space to the edge and to the text.
+- Several badges in a row: `gap: var(--prime-space-2)`.
+- In a list row the badge is the trailing column; the title column gets `min-width: 0` and an ellipsis.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focuses the body of a pressable badge, then its action or remove segment. |
+| `Enter` · `Space` | Presses the focused body, remove or action button. |
+
+### ARIA
+- A read-only badge is plain text in a `<span>`, no role.
+- `onPress` makes the body a `<button>` with `aria-pressed` when `pressed` is set; remove and `Badge.Action` are separate buttons with their own names.
+- Give every remove button a unique name with `labels.remove`; after removing, move focus to a neighbouring badge or the source field.
+- `Badge.Dot` is `aria-hidden`; icon-only badges need `aria-label`. Color never carries meaning alone.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `remove` | `"Удалить"` | Accessible name of the remove segment; include the badge text («Убрать фильтр «Москва»»). |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `className` | `string` | — | No | Extra class on the dot. |
-| … | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes; node is `aria-hidden`. |
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Publication statuses: soft badges where the text carries the meaning and the hue repeats it — `color`. |
+| [variants.tsx](examples/variants.tsx) | Every palette hue in every treatment; the text must read without the color — `variant`, `color`. |
+| [sizes.tsx](examples/sizes.tsx) | Every badge tier, 16 to 32 px high — `size`. |
+| [states.tsx](examples/states.tsx) | An inactive badge, a pressable toggle off and on, and a removable one — `disabled`, `onPress`, `pressed`, `onRemove`. |
+| [with-icon.tsx](examples/with-icon.tsx) | A leading dot, a leading or trailing icon and an icon-only square with a name — `Badge.Dot`, `Badge.Icon`, `aria-label`. |
+| [in-controls.tsx](examples/in-controls.tsx) | Inside a button or a field the badge takes the tier one step down without `size`. |
+| [applied-filters.tsx](examples/applied-filters.tsx) | Applied filters: each badge drops its filter and names it for screen readers — `onRemove`, `labels`. |
+| [filter-values.tsx](examples/filter-values.tsx) | Filter values as toggles with a hide action that slides in without changing the width — `onPress`, `pressed`, `Badge.Action`, `persistent`. |
+
+## Mistakes
+- `<Badge.Root onClick={…}>` → use `onPress` for a toggle, or a `Button` for a command.
+- A custom × or hover button next to a badge → use `onRemove` or `Badge.Action`.
+- Several removable badges with the default «Удалить» → pass `labels.remove` with the badge text.
+- A colored badge with no text → keep a word; color alone is not a signal.
+- An explicit `size` inside a control → drop it; the badge takes the tier one step down.
+- `onRemove` together with `Badge.Action` → one end segment per badge.
 
 ## Related
-
-- [Tag](../tag/COMPONENT.md)
-- [Typography](../typography/COMPONENT.md)
-- [Button](../button/COMPONENT.md)
-- [LinkButton](../link-button/COMPONENT.md)
-- [Kbd](../kbd/COMPONENT.md)
+- **Built from:** Icon
+- **See also:** [TagSelect](../tag-select/COMPONENT.md), [SmartFilter](../smart-filter/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [Avatar](../avatar/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

package/src/components/badge/examples/applied-filters.tsx

@@ -0,0 +1,47 @@
+/** Applied filters: each badge drops its filter and names it for screen readers — `onRemove`, `labels`. */
+import { Badge, Button, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const INITIAL = ["Москва", "Санкт-Петербург", "Есть в наличии", "До 5 000 ₽"];
+
+export default function BadgeAppliedFiltersExample() {
+  const [filters, setFilters] = React.useState(INITIAL);
+  const titleId = React.useId();
+
+  return (
+    <section className={styles.filters} aria-labelledby={titleId}>
+      <div className={styles.filtersHeader}>
+        <Typography as="h3" variant="title-s" id={titleId}>
+          Фильтры
+        </Typography>
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          size="s"
+          onClick={() => setFilters(filters.length > 0 ? [] : INITIAL)}
+        >
+          {filters.length > 0 ? "Сбросить все" : "Вернуть"}
+        </Button.Root>
+      </div>
+      {filters.length > 0 ? (
+        <div className={styles.badges}>
+          {filters.map((label) => (
+            <Badge.Root
+              labels={{ remove: `Убрать фильтр «${label}»` }}
+              key={label}
+              onRemove={() => setFilters((prev) => prev.filter((item) => item !== label))}
+            >
+              {label}
+            </Badge.Root>
+          ))}
+        </div>
+      ) : (
+        <Typography variant="body-s" tone="muted">
+          Фильтры не выбраны — показаны все товары.
+        </Typography>
+      )}
+    </section>
+  );
+}

package/src/components/badge/examples/examples.module.css

@@ -0,0 +1,32 @@
+/* Layout of the Badge scenarios: semantic tokens only. */
+
+/* in-controls.tsx: a button and a field side by side. */
+.controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  justify-content: center;
+  gap: var(--prime-space-3);
+  width: min(100%, var(--prime-modal-width-m));
+}
+
+/* applied-filters.tsx: a filter panel above a list. */
+.filters {
+  display: grid;
+  gap: var(--prime-space-3);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.filtersHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+}
+
+.badges {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-2);
+}

package/src/components/badge/examples/filter-values.tsx

@@ -0,0 +1,39 @@
+/** Filter values as toggles with a hide action that slides in without changing the width — `onPress`, `pressed`, `Badge.Action`, `persistent`. */
+import { Badge } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Mode = "show" | "hide" | undefined;
+
+const VALUES = ["Москва", "Казань", "Новосибирск", "Сочи"];
+
+export default function BadgeFilterValuesExample() {
+  const [modes, setModes] = React.useState<Record<string, Mode>>({ Казань: "show", Сочи: "hide" });
+  const set = (value: string, mode: Exclude<Mode, undefined>) =>
+    setModes((prev) => ({ ...prev, [value]: prev[value] === mode ? undefined : mode }));
+
+  return (
+    <div className={styles.badges}>
+      {VALUES.map((value) => {
+        const mode = modes[value];
+        return (
+          <Badge.Root
+            key={value}
+            color={mode === "show" ? "blue" : mode === "hide" ? "red" : "gray"}
+            pressed={mode === "show"}
+            onPress={() => set(value, "show")}
+          >
+            {mode === "hide" ? `НЕ ${value}` : value}
+            <Badge.Action
+              label={mode === "hide" ? `Не скрывать ${value}` : `Скрыть ${value}`}
+              pressed={mode === "hide"}
+              persistent={mode === "hide"}
+              onClick={() => set(value, "hide")}
+            />
+          </Badge.Root>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/badge/examples/in-controls.tsx

@@ -0,0 +1,23 @@
+/** Inside a button or a field the badge takes the tier one step down without `size`. */
+import { Badge, Button, Input } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function BadgeInControlsExample() {
+  return (
+    <div className={styles.controls}>
+      <Button.Root variant="outline" tone="neutral">
+        Входящие
+        <Badge.Root color="blue">12</Badge.Root>
+      </Button.Root>
+      <Input.Root label="Промокод">
+        <Input.Wrapper>
+          <Input.Field defaultValue="SPRING25" />
+          <Input.InlineAffix side="end">
+            <Badge.Root color="green">−25%</Badge.Root>
+          </Input.InlineAffix>
+        </Input.Wrapper>
+      </Input.Root>
+    </div>
+  );
+}

package/src/components/badge/examples/overview.tsx

@@ -0,0 +1,13 @@
+/** Publication statuses: soft badges where the text carries the meaning and the hue repeats it — `color`. */
+import { Badge } from "prime-ui-kit";
+
+export default function BadgeOverviewExample() {
+  return (
+    <>
+      <Badge.Root>Черновик</Badge.Root>
+      <Badge.Root color="blue">На ревью</Badge.Root>
+      <Badge.Root color="green">Опубликован</Badge.Root>
+      <Badge.Root color="red">Ошибка</Badge.Root>
+    </>
+  );
+}

package/src/components/badge/examples/sizes.tsx

@@ -0,0 +1,21 @@
+/** Every badge tier, 16 to 32 px high — `size`. */
+import { Badge, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function BadgeSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Badge.Root size={size} color="blue">
+            Бета
+          </Badge.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/badge/examples/states.tsx

@@ -0,0 +1,51 @@
+/** An inactive badge, a pressable toggle off and on, and a removable one — `disabled`, `onPress`, `pressed`, `onRemove`. */
+import { Badge, Typography } from "prime-ui-kit";
+
+const noop = () => undefined;
+
+export default function BadgeStatesExample() {
+  return (
+    <div>
+      <div>
+        <Badge.Root color="green" disabled>
+          Оплачен
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
+      </div>
+      <div>
+        <Badge.Root color="blue" onPress={noop} pressed={false}>
+          Москва
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          onPress
+        </Typography>
+      </div>
+      <div>
+        <Badge.Root color="blue" onPress={noop} pressed>
+          Москва
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          pressed
+        </Typography>
+      </div>
+      <div>
+        <Badge.Root labels={{ remove: "Убрать «Москва»" }} onRemove={noop}>
+          Москва
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          onRemove
+        </Typography>
+      </div>
+      <div>
+        <Badge.Root labels={{ remove: "Убрать «Москва»" }} onRemove={noop} disabled>
+          Москва
+        </Badge.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          onRemove · disabled
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/badge/examples/variants.tsx

@@ -0,0 +1,38 @@
+/** Every palette hue in every treatment; the text must read without the color — `variant`, `color`. */
+import { Badge, type PaletteColor, Typography } from "prime-ui-kit";
+
+const COLORS: PaletteColor[] = [
+  "gray",
+  "blue",
+  "sky",
+  "teal",
+  "green",
+  "yellow",
+  "orange",
+  "red",
+  "pink",
+  "purple",
+];
+
+const VARIANTS = ["soft", "solid", "outline"] as const;
+
+export default function BadgeVariantsExample() {
+  return (
+    <>
+      {VARIANTS.map((variant) => (
+        <div key={variant}>
+          {COLORS.map((color) => (
+            <div key={color}>
+              <Badge.Root variant={variant} color={color}>
+                {color}
+              </Badge.Root>
+              <Typography as="span" variant="caption" tone="muted">
+                {variant}
+              </Typography>
+            </div>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}