prime-ui-kit 0.7.11 → 0.9.0

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

@@ -1,23 +1,22 @@
-import { Avatar, type AvatarSize } from "@/components/avatar/Avatar";
+/** Six diameters: 20 · 24 · 32 · 40 · 48 · 64 px, default `m`; initials take 40% of the diameter. Use xs in dense tables, m in lists, xl/2xl in profile headers. */
+import { Avatar, type AvatarSize, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const sampleSrc =
-  "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=256&h=256&fit=crop";
+const sizes: AvatarSize[] = ["xs", "s", "m", "l", "xl", "2xl"];
 
-const sizes: AvatarSize[] = ["s", "m", "l", "xl", "2xl", "3xl", "4xl", "5xl", "6xl"];
-
-/**
- * Full `size` scale in one row — mirrors `playground/snippets/avatar/sizes.tsx`.
- */
 export default function AvatarSizesExample() {
   return (
-    <div className={styles.row}>
+    <div className={styles.sizes}>
       {sizes.map((size) => (
-        <Avatar.Root key={size} size={size}>
-          <Avatar.Image src={sampleSrc} alt="" />
-          <Avatar.Fallback>{size}</Avatar.Fallback>
-        </Avatar.Root>
+        <div key={size} className={styles.sizeCell}>
+          <Avatar.Root size={size} color="blue" aria-label="Анна Климова">
+            <Avatar.Fallback>АК</Avatar.Fallback>
+          </Avatar.Root>
+          <Typography.Root as="span" variant="caption" tone="muted">
+            {size}
+          </Typography.Root>
+        </div>
       ))}
     </div>
   );

package/src/components/avatar/examples/src-from-state.tsx

@@ -1,6 +1,7 @@
+/** Changing `src` restarts loading; initials show until the new photo arrives. Use when the photo comes from state (upload, profile switch). */
+
+import { Avatar, Button } from "prime-ui-kit";
 import * as React from "react";
-import { Avatar } from "@/components/avatar/Avatar";
-import { Button } from "@/components/button/Button";
 
 import styles from "./examples.module.css";
 
@@ -9,25 +10,21 @@ const sources = [
   "https://images.unsplash.com/photo-1527980965255-d3b416303d12?w=128&h=128&fit=crop",
 ] as const;
 
-/**
- * Parent-owned `src`; image remounts per URL — mirrors `playground/snippets/avatar/src-from-state.tsx`.
- */
 export default function AvatarSrcFromStateExample() {
   const [index, setIndex] = React.useState(0);
-  const src = sources[index];
 
   return (
     <div className={styles.row}>
-      <Avatar.Root size="xl">
-        <Avatar.Image src={src} alt="" />
-        <Avatar.Fallback>?</Avatar.Fallback>
+      <Avatar.Root size="xl" color="sky">
+        <Avatar.Image src={sources[index]} alt="" />
+        <Avatar.Fallback>ИП</Avatar.Fallback>
       </Avatar.Root>
       <Button.Root
-        mode="ghost"
-        type="button"
+        variant="outline"
+        tone="neutral"
         onClick={() => setIndex((i) => (i + 1) % sources.length)}
       >
-        Next portrait
+        Сменить фото
       </Button.Root>
     </div>
   );

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

@@ -1,26 +1,49 @@
-import { Avatar } from "@/components/avatar/Avatar";
+/** Photo, initials without a photo, a broken URL (initials again) and an icon fallback. Always pair `Avatar.Image` with `Avatar.Fallback`. */
+import { Avatar, Icon, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const okSrc = "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
+const photo = "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
 
-/**
- * No `Avatar.Image` (idle), successful load, bad URL (error) — mirrors `playground/snippets/avatar/states.tsx`.
- */
 export default function AvatarStatesExample() {
   return (
-    <div className={styles.row}>
-      <Avatar.Root size="xl">
-        <Avatar.Fallback>AB</Avatar.Fallback>
-      </Avatar.Root>
-      <Avatar.Root size="xl">
-        <Avatar.Image src={okSrc} alt="User" />
-        <Avatar.Fallback>CD</Avatar.Fallback>
-      </Avatar.Root>
-      <Avatar.Root size="xl">
-        <Avatar.Image src="https://example.com/missing-avatar.png" alt="" />
-        <Avatar.Fallback>!</Avatar.Fallback>
-      </Avatar.Root>
+    <div className={styles.sizes}>
+      <div className={styles.sizeCell}>
+        <Avatar.Root size="xl" color="green">
+          <Avatar.Image src={photo} alt="Михаил Котов" />
+          <Avatar.Fallback>МК</Avatar.Fallback>
+        </Avatar.Root>
+        <Typography.Root as="span" variant="caption" tone="muted">
+          фото
+        </Typography.Root>
+      </div>
+      <div className={styles.sizeCell}>
+        <Avatar.Root size="xl" color="purple" aria-label="Ольга Белова">
+          <Avatar.Fallback>ОБ</Avatar.Fallback>
+        </Avatar.Root>
+        <Typography.Root as="span" variant="caption" tone="muted">
+          инициалы
+        </Typography.Root>
+      </div>
+      <div className={styles.sizeCell}>
+        <Avatar.Root size="xl" color="orange">
+          <Avatar.Image src="https://example.com/missing-avatar.png" alt="Сергей Лебедев" />
+          <Avatar.Fallback>СЛ</Avatar.Fallback>
+        </Avatar.Root>
+        <Typography.Root as="span" variant="caption" tone="muted">
+          ошибка загрузки
+        </Typography.Root>
+      </div>
+      <div className={styles.sizeCell}>
+        <Avatar.Root size="xl" aria-label="Гость">
+          <Avatar.Fallback>
+            <Icon name="field.email" size="l" />
+          </Avatar.Fallback>
+        </Avatar.Root>
+        <Typography.Root as="span" variant="caption" tone="muted">
+          иконка
+        </Typography.Root>
+      </div>
     </div>
   );
 }

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

@@ -0,0 +1,70 @@
+/** Team card: a group in the header and a member list with `m` avatars and presence; `--avatar-ring` matches the card fill. Use for team and project overviews. */
+
+import { Avatar, type PaletteColor, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const members: {
+  name: string;
+  role: string;
+  initials: string;
+  color: PaletteColor;
+  online: boolean;
+}[] = [
+  {
+    name: "Анна Климова",
+    role: "Руководитель проекта",
+    initials: "АК",
+    color: "blue",
+    online: true,
+  },
+  {
+    name: "Дмитрий Носов",
+    role: "Фронтенд-разработчик",
+    initials: "ДН",
+    color: "green",
+    online: true,
+  },
+  { name: "Елена Орлова", role: "Дизайнер", initials: "ЕО", color: "pink", online: false },
+];
+
+export default function AvatarTeamCardExample() {
+  const titleId = React.useId();
+
+  return (
+    <section className={styles.team} aria-labelledby={titleId}>
+      <div className={styles.teamHeader}>
+        <Typography.Root as="h3" variant="title-s" id={titleId}>
+          Команда «Витрина»
+        </Typography.Root>
+        <Avatar.Group.Root size="s" className={styles.teamGroup} aria-label="Всего 8 участников">
+          {members.map((m) => (
+            <Avatar.Root key={m.name} color={m.color}>
+              <Avatar.Fallback>{m.initials}</Avatar.Fallback>
+            </Avatar.Root>
+          ))}
+          <Avatar.Group.Overflow aria-label="Ещё 5 участников">+5</Avatar.Group.Overflow>
+        </Avatar.Group.Root>
+      </div>
+      <ul className={styles.members}>
+        {members.map((m) => (
+          <li key={m.name} className={styles.member}>
+            <Avatar.Root color={m.color}>
+              <Avatar.Fallback>{m.initials}</Avatar.Fallback>
+              <Avatar.Status status={m.online ? "online" : "offline"} />
+            </Avatar.Root>
+            <span className={styles.memberText}>
+              <Typography.Root as="span" variant="title-s" truncate>
+                {m.name}
+              </Typography.Root>
+              <Typography.Root as="span" variant="body-s" tone="muted">
+                {m.role}
+              </Typography.Root>
+            </span>
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}

package/src/components/badge/COMPONENT.md

@@ -1,115 +1,191 @@
 # Badge
 
-**Default sizing:** When designing screens or samples, prefer **`size="m"`** unless the scenario explicitly needs another value.
+**Category:** data-display
 
-## About
+> A compact static label for a status, category or count, in a palette color.
 
-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.
+## When to use
+- Status or category of a row in a table or list ("Оплачен", "Черновик", "Бета").
+- Environment, role or feature labels next to a heading.
+- Counters inside buttons and fields ("Входящие 12", "−25%").
+- A workflow state with a leading dot (`Badge.Dot`).
 
-- **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).
+## When not to use
+- The chip can be removed, toggled or used as a filter → use [Tag](../tag/COMPONENT.md).
+- A keyboard key or shortcut → use [Kbd](../kbd/COMPONENT.md).
+- A person's presence (online / busy) → use `Avatar.Status` from [Avatar](../avatar/COMPONENT.md).
+- The label must be clickable → use [Button](../button/COMPONENT.md) or [LinkButton](../link-button/COMPONENT.md).
+- A message about the page or a section → use [Banner](../banner/COMPONENT.md) or [Hint](../hint/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`. |
+## Anatomy
+```
+Badge.Root          span: fill, text, tier dimensions
+├── Badge.Dot       optional leading dot in currentColor (aria-hidden)
+├── Badge.Icon      optional icon wrapper, leading or trailing
+└── text / number
+```
 
-Prefer **`examples/*.tsx`** for product-shaped English samples.
+## API
 
-## Note for LLM consumers
+### Badge.Root
+Forwards `ref` to the `<span>`. No `asChild`.
 
-- **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.
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` (`PaletteColor`) | `"gray"` | Palette hue. Categorizes; the text carries the meaning. |
+| `variant` | `"solid" \| "soft" \| "outline"` | `"soft"` | Treatment. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` (`ControlSize`) | — (inherited, else `"m"`) | Badge tier. Without it the badge follows the surrounding control one tier down; outside a control it is `m`. An explicit value always wins. |
+| `disabled` | `boolean` | — | Muted look for every variant (visual only, no ARIA). |
+| `children` | `ReactNode` | — | Text, `Badge.Dot`, `Badge.Icon`. Only `Badge.Icon` children make a square icon-only badge. |
+| `className` | `string` | — | Extra class on the root. |
 
-## Rules
++ native `<span>` props (`HTMLAttributes<HTMLSpanElement>`).
 
-- 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).
+### Badge.Icon
+No ref forwarding.
 
-## API
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon; sized to the tier icon (12–16px). |
+| `className` | `string` | — | Extra class on the wrapper. |
 
-### Badge.Root
++ native `<span>` props except `children`.
 
-| 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.Dot
+No ref forwarding. Always `aria-hidden="true"`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Extra class on the dot. |
+
++ native `<span>` props.
+
+## Variants
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `soft` | Light palette fill (`palette.<hue>.soft`), hue text, no outline | Status and category labels in tables, lists, headers — the normal case | yes |
+| `solid` | Saturated hue fill (`palette.<hue>.solid`), contrasting text | One label per area that must stand out ("Срочно", a single environment flag) | |
+| `outline` | Transparent fill, 1px inset line in the hue text at 32%, hue text | A quiet secondary label next to soft badges, or on a fill where a soft wash would blend in | |
+
+`variant="ghost"` is not part of Badge (the type excludes it).
+
+### color
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `gray` | Neutral gray wash and text | Neutral or inactive states: draft, archived, cancelled | yes |
+| `blue` | Blue | In progress, informational categories, counters | |
+| `green` | Green | Success, paid, active, published | |
+| `orange` | Orange | Waiting, needs attention, low stock | |
+| `red` | Red | Failed, rejected, urgent | |
+| `yellow` | Yellow | Paused, under review | |
+| `purple` | Purple | Roles, private / premium categories | |
+| `sky` | Sky blue | Channel or type categories distinct from blue | |
+| `pink` | Pink | Extra category hue | |
+| `teal` | Teal | Extra category hue | |
+
+The same hue reads in both themes. Pick one hue per meaning and keep it across the product.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 16px high, padding 4, text 12, icon 12, radius 4 | Inside `xs`/`s` controls, very dense rows | |
+| `s` | 20px high, padding 6, text 12, icon 12, radius 6 | Inside `m` controls (inherited automatically), compact lists | |
+| `m` | 24px high, padding 8, text 12, icon 14, radius 6 | Standalone labels in tables and lists | yes (outside controls) |
+| `l` | 28px high, padding 10, text 13, icon 16, radius 8 | Next to page / section titles | |
+| `xl` | 32px high, padding 12, text 14, icon 16, radius 8 | Large headers, hero areas | |
+
+### Icon-only (structural)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| text (+ Dot / Icon) | Pill with horizontal padding | Any label with words | yes |
+| only `Badge.Icon` children | Square: width = height, no horizontal padding (`data-icon-only`) | A compact type marker; give it `aria-label` | |
+
+### disabled (visual flag)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `false` / unset | Variant colors | Normal | yes |
+| `true` | Muted fill (`fill-muted`), disabled text, no outline, for every variant | The labelled item is inactive or unavailable | |
+
+**Combinations**
+- Recommended: `soft` with any hue for statuses; `soft` + `Badge.Dot` for workflow states; `solid` for a single emphasized label.
+- Allowed but rare: `outline` next to soft badges for a secondary label; `solid` icon-only for a type marker.
+- Avoid: several `solid` badges in one row (they compete); color as the only signal (always keep text); explicit `size` inside a control (breaks the one-tier-down pairing).
+
+**Sizes**
+Without `size` a badge inside a control uses the tier one step down: control `xs`/`s` → `xs`, `m` → `s`, `l` → `m`, `xl` → `l`. Outside any control the default is `m` (24px), which sits well in a 36px row next to `m` buttons and inputs.
+
+**Hierarchy**
+Soft badges carry status in lists; at most one `solid` badge per area; Tag is for anything the user can act on.
+
+## States
+Badge is not interactive: no hover, focus or pressed states.
+
+| State / attribute | Driven by | Notes |
+|---|---|---|
+| `data-color` | `color` | Always set (default `gray`). |
+| `data-variant` | `variant` | Always set (default `soft`). |
+| `data-size` | `size`, else surrounding control size, else `m` | Nominal size. |
+| `data-tier` | resolved visual tier | Equals `data-size` unless the size was inherited from a control (then one step down). Drives all dimensions. |
+| `data-icon-only="true"` | children are only `Badge.Icon` | Square badge. |
+| `data-disabled="true"` | `disabled` | Muted look. |
+
+`Badge.Root` also provides its tier to children through the control-size context, so an `Icon` inside picks the badge tier.
+
+## Layout & spacing
+- Inline-flex, `vertical-align: middle`, never shrinks; `max-width: 100%`, text does not wrap.
+- Several badges in a row: `gap: var(--prime-space-2)`.
+- In a list or table row the badge is the trailing column; give the title column `min-width: 0` and ellipsis so the badge never wraps.
+- Numbers use `tabular-nums`.
+
+## Accessibility
+- Plain text in a `<span>`; screen readers read its content. No role.
+- `Badge.Dot` is `aria-hidden`; the text next to it is what is announced.
+- Icon-only badges need `aria-label` (e.g. `aria-label="Почта"`).
+- Color never carries meaning alone — keep the word.
+- No `labels` keys.
 
-### Badge.Icon
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | Five tiers xs–xl | Picking a size for standalone badges |
+| [variants.tsx](examples/variants.tsx) | `soft` / `solid` / `outline` on the same hues, plus `Badge.Dot` | Choosing emphasis |
+| [palette.tsx](examples/palette.tsx) | All ten hues in `soft` and `solid` | Assigning category colors |
+| [states.tsx](examples/states.tsx) | Normal vs `disabled` for every variant and with a dot | Labels of inactive items |
+| [icons.tsx](examples/icons.tsx) | Dot, leading / trailing icon, icon-only with `aria-label` | Adding an icon to a label |
+| [in-controls.tsx](examples/in-controls.tsx) | Counter in Button s/m/l, badge in an Input affix | Badges inside controls (inherited tier) |
+| [surfaces.tsx](examples/surfaces.tsx) | Status set on canvas, card and floating layer | Checking contrast on any surface |
+| [order-list.tsx](examples/order-list.tsx) | Order list with a status column | Status columns in lists and tables |
 
-| 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. |
+```tsx
+import { Badge } from "prime-ui-kit";
 
-### Badge.Dot
+export function OrderStatus() {
+  return (
+    <Badge.Root color="green">
+      <Badge.Dot />
+      Оплачен
+    </Badge.Root>
+  );
+}
+```
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `className` | `string` | — | No | Extra class on the dot. |
-| … | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes; node is `aria-hidden`. |
+## Mistakes
+- `<Badge.Root onClick={…}>` as a filter → use `Tag` or `Button`.
+- `<Badge.Root color="red" />` with no text → keep a word ("Ошибка"); color alone is not a signal.
+- `<Button.Root><Badge.Root size="m">12</Badge.Root></Button.Root>` → drop `size`; the badge takes the tier one step down by itself.
+- `variant="light"` / `variant="filled"` → use `soft` / `solid`.
+- Icon-only badge without `aria-label` → add `aria-label`.
+- A custom `<span>` styled as a badge → use `Badge.Root`.
 
 ## Related
-
-- [Tag](../tag/COMPONENT.md)
-- [Typography](../typography/COMPONENT.md)
-- [Button](../button/COMPONENT.md)
-- [LinkButton](../link-button/COMPONENT.md)
-- [Kbd](../kbd/COMPONENT.md)
+- [Tag](../tag/COMPONENT.md) — removable and interactive chips with the same tiers.
+- [Kbd](../kbd/COMPONENT.md) — keyboard keys, same tier rule.
+- [Avatar](../avatar/COMPONENT.md) — `Avatar.Status` for presence.
+- [DataTable](../data-table/COMPONENT.md) — status columns.

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

@@ -0,0 +1,77 @@
+.stack {
+  display: grid;
+  gap: var(--prime-space-4);
+  width: 100%;
+  max-width: 100%;
+  min-width: 0;
+}
+
+.sizes {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  justify-content: center;
+  gap: var(--prime-space-6);
+}
+
+.sizeCell {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--prime-space-2);
+}
+
+.matrix {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  align-items: center;
+  column-gap: var(--prime-space-4);
+  row-gap: var(--prime-space-3);
+  width: 100%;
+}
+
+.badges {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-2);
+}
+
+.controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-3);
+}
+
+.field {
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+}
+
+.list {
+  display: grid;
+  width: 100%;
+  max-width: var(--prime-modal-width-m);
+  margin: 0;
+  padding: var(--prime-card-padding-s);
+  list-style: none;
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-card-bg);
+}
+
+.item {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto auto;
+  align-items: center;
+  gap: var(--prime-space-3);
+  padding-block: var(--prime-space-3);
+}
+
+.item + .item {
+  border-top: var(--prime-border-width) solid var(--prime-color-border-subtle);
+}
+
+.tabular {
+  font-variant-numeric: tabular-nums;
+}

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

@@ -0,0 +1,37 @@
+/** A leading dot, a leading or trailing icon, and square icon-only badges with `aria-label`. Use an icon when it speeds up recognition of the label. */
+import { Badge, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function BadgeIconsExample() {
+  return (
+    <div className={styles.badges}>
+      <Badge.Root color="green">
+        <Badge.Dot />
+        Активен
+      </Badge.Root>
+      <Badge.Root color="purple">
+        <Badge.Icon>
+          <Icon name="status.locked" />
+        </Badge.Icon>
+        Приватный
+      </Badge.Root>
+      <Badge.Root variant="outline" color="blue">
+        Подробнее
+        <Badge.Icon>
+          <Icon name="nav.chevronRight" />
+        </Badge.Icon>
+      </Badge.Root>
+      <Badge.Root color="sky" aria-label="Почта">
+        <Badge.Icon>
+          <Icon name="field.email" />
+        </Badge.Icon>
+      </Badge.Root>
+      <Badge.Root variant="solid" color="orange" aria-label="Загрузка">
+        <Badge.Icon>
+          <Icon name="action.upload" />
+        </Badge.Icon>
+      </Badge.Root>
+    </div>
+  );
+}