prime-ui-kit 0.7.13 → 0.9.1

package/src/components/scroll-container/examples/edge-fade.tsx

@@ -0,0 +1,53 @@
+/** Edges fade where more content is hidden; the horizontal strip also hides its scrollbar — `fade`, `scrollbar`. */
+import { Badge, Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = [
+  "Заказ № 1040 оплачен",
+  "Счёт № 318 выставлен",
+  "Заказ № 1041 передан в доставку",
+  "Возврат по заказу № 1032 одобрен",
+  "Заказ № 1042 оплачен",
+  "Акт № 77 подписан",
+  "Заказ № 1043 отменён клиентом",
+  "Счёт № 319 оплачен",
+  "Заказ № 1044 собран на складе",
+  "Заказ № 1045 оплачен",
+];
+const TAGS = ["Новые", "В работе", "Ждут оплаты", "Отгружены", "Возвраты", "Архив", "Черновики"];
+
+export default function ScrollContainerEdgeFadeExample() {
+  return (
+    <div className={styles.layout}>
+      <Card.Root role="region" className={styles.card} aria-label="Лента событий">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          Лента событий
+        </Typography>
+        <ScrollContainer fade>
+          <ul className={styles.list}>
+            {EVENTS.map((event) => (
+              <li key={event}>
+                <Typography as="span" variant="body-m" tone="secondary">
+                  {event}
+                </Typography>
+              </li>
+            ))}
+          </ul>
+        </ScrollContainer>
+      </Card.Root>
+      <Card.Root role="region" className={styles.card} aria-label="Фильтры">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          Фильтры
+        </Typography>
+        <ScrollContainer axis="horizontal" fade scrollbar="hidden">
+          <div className={styles.strip}>
+            {TAGS.map((tag) => (
+              <Badge.Root key={tag}>{tag}</Badge.Root>
+            ))}
+          </div>
+        </ScrollContainer>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/scroll-container/examples/examples.module.css

@@ -0,0 +1,66 @@
+/* Layout of the ScrollContainer scenarios: a fixed-height card that owns the scroll region. */
+
+.layout {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(calc(var(--prime-space-24) * 2.5), 1fr));
+  gap: var(--prime-space-4);
+  width: 100%;
+}
+
+/* The Card's size: a fixed height, so the region inside scrolls. */
+.card {
+  width: min(100%, calc(var(--prime-space-24) * 4));
+  height: calc(var(--prime-space-24) * 2.5);
+}
+
+.layout > .card {
+  width: auto;
+}
+
+.cardTitle {
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  padding: 0 var(--prime-space-4) var(--prime-space-3);
+  list-style: none;
+}
+
+.list li {
+  padding-block: var(--prime-space-2);
+  border-bottom: var(--prime-border-width) solid var(--prime-color-border-subtle);
+}
+
+/* Dividers only between items. */
+.list li:last-child {
+  border-bottom: 0;
+}
+
+.strip {
+  display: flex;
+  gap: var(--prime-space-2);
+  width: max-content;
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+/* Two-axis scroller: the side padding lives on the scrolling element itself (foundation §7). */
+.canvas {
+  padding: 0 var(--prime-space-4) var(--prime-space-3);
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(12, var(--prime-space-24));
+  gap: var(--prime-space-1);
+  width: max-content;
+}
+
+.cell {
+  padding: var(--prime-space-2);
+  border-radius: var(--prime-radius-s);
+  background: var(--prime-color-fill-subtle);
+  font-variant-numeric: tabular-nums;
+}

package/src/components/scroll-container/examples/overscroll.tsx

@@ -0,0 +1,27 @@
+/** At the end of the list the scroll passes on to the page instead of stopping — `overscrollBehavior`. */
+import { Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const HOURS = Array.from({ length: 12 }, (_, index) => `${String(9 + index).padStart(2, "0")}:00`);
+
+export default function ScrollContainerOverscrollExample() {
+  return (
+    <Card.Root role="region" className={styles.card} aria-label="Журнал">
+      <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+        Журнал выгрузок
+      </Typography>
+      <ScrollContainer overscrollBehavior="auto" tabIndex={0} aria-label="Журнал выгрузок">
+        <ul className={styles.list}>
+          {HOURS.map((hour) => (
+            <li key={hour}>
+              <Typography as="span" variant="body-m" tone="secondary">
+                {hour} — отчёт выгружен
+              </Typography>
+            </li>
+          ))}
+        </ul>
+      </ScrollContainer>
+    </Card.Root>
+  );
+}

package/src/components/scroll-container/examples/overview.tsx

@@ -0,0 +1,27 @@
+/** A feed that scrolls on its own inside a fixed-height card, with the kit's thin scrollbar. */
+import { Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EVENTS = Array.from({ length: 16 }, (_, index) => `Заказ № ${1040 + index} оплачен`);
+
+export default function ScrollContainerOverviewExample() {
+  return (
+    <Card.Root role="region" className={styles.card} aria-label="Лента событий">
+      <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+        Лента событий
+      </Typography>
+      <ScrollContainer>
+        <ul className={styles.list}>
+          {EVENTS.map((event) => (
+            <li key={event}>
+              <Typography as="span" variant="body-m" tone="secondary">
+                {event}
+              </Typography>
+            </li>
+          ))}
+        </ul>
+      </ScrollContainer>
+    </Card.Root>
+  );
+}

package/src/components/scroll-container/examples/variants.tsx

@@ -0,0 +1,54 @@
+/** A strip that scrolls sideways and a wide schedule that scrolls both ways — `axis`. */
+import { Badge, Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TAGS = ["Новые", "В работе", "Ждут оплаты", "Отгружены", "Возвраты", "Архив", "Черновики"];
+const HOURS = Array.from({ length: 12 }, (_, index) => `${String(9 + index).padStart(2, "0")}:00`);
+const ROOMS = Array.from({ length: 16 }, (_, index) => `Зал ${index + 1}`);
+
+export default function ScrollContainerVariantsExample() {
+  return (
+    <div className={styles.layout}>
+      <Card.Root role="region" className={styles.card} aria-label="Фильтры">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          horizontal
+        </Typography>
+        <ScrollContainer axis="horizontal">
+          <div className={styles.strip}>
+            {TAGS.map((tag) => (
+              <Badge.Root key={tag}>{tag}</Badge.Root>
+            ))}
+          </div>
+        </ScrollContainer>
+      </Card.Root>
+      <Card.Root role="region" className={styles.card} aria-label="Расписание залов">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          both
+        </Typography>
+        <ScrollContainer
+          axis="both"
+          tabIndex={0}
+          aria-label="Сетка расписания"
+          className={styles.canvas}
+        >
+          <div className={styles.grid}>
+            {ROOMS.flatMap((room) =>
+              HOURS.map((hour) => (
+                <Typography
+                  key={`${room}-${hour}`}
+                  as="div"
+                  variant="caption"
+                  tone="secondary"
+                  className={styles.cell}
+                >
+                  {room} · {hour}
+                </Typography>
+              )),
+            )}
+          </div>
+        </ScrollContainer>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/segmented-control/COMPONENT.md

@@ -1,121 +1,195 @@
 # SegmentedControl
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** selection
+**Kind:** control
 
-## About
+> A switch between 2–5 mutually exclusive options or modes that takes effect immediately.
 
-A single-choice control: a horizontal `radiogroup` whose options are segment buttons, with a floating pill indicator under the active segment.
+## When to use
+- Choosing one value or view mode with an instant effect: report period, list / board / calendar view, theme.
+- A compact one-of-many choice inside a toolbar, next to inputs and buttons of the same size.
+- A status picker where each option has its own palette hue (`color` on the item).
+- A status overview where each option carries a metric (two-line segments with `Count` and `Description`).
 
-- **Use** when there are few mutually exclusive options that should stay visible (period toggles, layout mode, compact filters).
-- **Use** with **`SegmentedControl.Icon`** plus visible or visually hidden text when a segment is icon-led.
-- **Do not use** for long lists or many options—prefer [Select](../select/COMPONENT.md) or a dropdown.
-- **Do not use** when each choice should show its own panel and tab keyboard model—prefer [Tabs](../tabs/COMPONENT.md).
-- **Do not use** for independent or multi-select actions—prefer [Button group](../button-group/COMPONENT.md) or other patterns.
-- **Do not use** expecting a vertical stack or orientation prop; layout is horizontal only.
-
-## Composition
-
-- **`SegmentedControl.Root`** — outer `div` with **`role="radiogroup"`**, **`data-size`**, focus and arrow-key handling, **`ControlSizeProvider`** for descendants, and a decorative indicator layer (`aria-hidden`).
-- **`SegmentedControl.Item`** — direct children of **`Root`** (and only in that role for correct behavior). Each item is a **`button`** with **`role="radio"`**; order in the tree is the visual order of segments.
-- **`SegmentedControl.Icon`** — optional **`span`** with **`aria-hidden="true"`** inside an **`Item`**; pair with visible label text or an accessible name in **`Item`** **`children`**.
-
-### Minimal example
+## When not to use
+- Switching between panels of content (navigation) → use [Tabs](../tabs/COMPONENT.md).
+- One choice with descriptions in a form, or more than 5 options → use [Radio](../radio/COMPONENT.md) or [Select](../select/COMPONENT.md).
+- A single on/off setting → use [Switch](../switch/COMPONENT.md).
+- Several actions in a row (not a selection) → use [ButtonGroup](../button-group/COMPONENT.md).
 
+## Import
 ```tsx
 import { SegmentedControl } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <SegmentedControl.Root defaultValue="a">
-      <SegmentedControl.Item value="a">A</SegmentedControl.Item>
-      <SegmentedControl.Item value="b">B</SegmentedControl.Item>
-    </SegmentedControl.Root>
-  );
-}
 ```
 
-### Canonical composition (reference)
-
-For a **single file** that combines **controlled mode**, **`SegmentedControl.Icon` + text**, **icon-only segments with visually hidden labels**, and layout notes (remember **`Root` does not forward `aria-label`**), see **`examples/canonical-composition.tsx`**. Imports use **`"prime-ui-kit"`** so the same patterns work in an app after installing the package.
-
-The **playground** (`playground/sections/SegmentedControlSection.tsx`) renders the same scenarios as **`playground/snippets/segmented/*.tsx`** (internal `@/` imports). The **`examples/`** files below mirror those snippets with **`"prime-ui-kit"`** imports.
-
-### Example files in `examples/`
-
-| File | Scenario (aligned with `playground/snippets/segmented/`) |
-|------|----------|
-| `sizes.tsx` | All four **`size`** values `s`–`xl` with identical segment labels |
-| `states.tsx` | Default group; **`disabled`** on one **`Item`**; **`disabled`** on **`Root`** |
-| `controlled.tsx` | **`value`** + **`onValueChange`** (no **`defaultValue`**) |
-| `composition.tsx` | **`Icon`** + label text; icon-only rows with visually hidden text in **`Item`** |
-| `full-width.tsx` | Narrow container; **`className`** overrides root **`width: fit-content`** so segments share width |
-| `features.tsx` | Two, three, and four segments; keyboard (**ArrowLeft** / **ArrowRight** on the group) |
-
-Additional English product-style recipes:
-
-| File | Scenario |
-|------|----------|
-| `canonical-composition.tsx` | Combined: icons, controlled period, icon-only (superset demo) |
-| `view-mode.tsx` | Catalog view: List / Grid / Table |
-| `pricing-toggle.tsx` | Billing: Monthly / Annual |
-| `catalog-filters.tsx` | Compact availability filter; **`size="s"`** |
-
-### Note for LLMs
-
-- **Imports:** `SegmentedControl`, `Icon`, and `Typography` from **`"prime-ui-kit"`** in **`examples/`**; paths are relative to `src/components/segmented-control/examples/`. Playground snippets use **`@/…`** but should stay behavior-identical to these files.
-- **Values are strings:** map `onValueChange` to app enums with a type guard or narrow union; **`Item` does not accept `aria-label`**—accessible names come from **visible** `children` and/or **visually hidden** text inside **`Item`**.
-- **`SegmentedControl.Icon`** is **`aria-hidden`**; always pair with visible text or a visually hidden span inside the same **`Item`**.
-- **`Root`** does **not** forward **`aria-label`**, **`aria-labelledby`**, or **`style`**: use a **wrapper** and visible copy, or **`aria-labelledby`** on a wrapper that references visible page text—not on **`Root`**.
-- **Keyboard:** **ArrowLeft** / **ArrowRight** move among **enabled** items; **`disabled`** on **`Item`** is skipped; **`defaultValue=""`** leaves no selection and **`Root`** is focusable until the user picks a segment.
-- **Many options or vertical layout:** prefer [Select](../select/COMPONENT.md); **tabbed panels** → [Tabs](../tabs/COMPONENT.md).
-
-## Rules
-
-- **Controlled:** pass **`value`** and handle changes with **`onValueChange`**. **Uncontrolled:** use **`defaultValue`** (defaults to **`""`**).
-- **`defaultValue=""`** (and no controlled **`value`**) means **no** segment is selected; **`Root`** gets **`tabIndex={0}`** so the group can be focused until a segment is chosen.
-- Values are **strings**; mapping to app enums or unions is the consumer’s responsibility.
-- **`disabled`** on **`Root`** sets **`aria-disabled`** on the group and **`data-disabled`**; all segments are inactive.
-- **`disabled`** on an **`Item`** skips that segment for **Left/Right** arrow navigation among enabled radios.
-- **Roving tabindex:** **Tab** focuses the group (when nothing is selected) or the checked segment; **ArrowLeft** / **ArrowRight** move selection and focus across enabled items.
-- **`SegmentedControl.Icon`** is **`aria-hidden`**; the segment’s accessible name must come from **`Item`** **`children`** (visible text and/or visually hidden text). **`Item`** does not forward extra attributes—there is no **`…rest`**—so you cannot set **`aria-label`** on the segment via props.
-- **No `asChild`** and no merging **`Root`** with an arbitrary element.
-- **`Root`** does **not** forward arbitrary HTML attributes (**`aria-label`**, **`style`**, etc.); wrap **`Root`** in another element when you need extra semantics or layout hooks.
-- The indicator position follows the active segment’s layout; updates use **`ResizeObserver`** and **`MutationObserver`** on the root—avoid unpredictable segment size changes without expecting a reflow/recalc.
+## Anatomy
+```
+SegmentedControl.Root                 role="radiogroup"; track + sliding thumb, scrolling row, keyboard
+└─ SegmentedControl.Item              role="radio" button, one option
+   ├─ SegmentedControl.Icon           icon slot (optional; icon-only → square segment)
+   ├─ SegmentedControl.Label          title, truncates (optional; plain text is wrapped automatically)
+   ├─ SegmentedControl.Count          counter Badge after the label (optional)
+   └─ SegmentedControl.Description    second line; makes the segment two-line (optional)
+```
 
 ## API
 
-### SegmentedControl.Root
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string` | — | No | Selected value in controlled mode |
-| defaultValue | `string` | `""` | No | Initial value when uncontrolled; empty string means no segment selected |
-| onValueChange | `(value: string) => void` | — | No | Called when the selected value changes |
-| disabled | `boolean` | `false` | No | Disables the entire group |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Segment dimensions and typography |
-| children | `React.ReactNode` | — | Yes | `Item` nodes (and their content) |
-| className | `string` | — | No | Extra class on the container (e.g. full-width override when the default **`width: fit-content`** is too narrow—see **`examples/full-width.tsx`**) |
+### SegmentedControl.Root
+`ref` → `HTMLDivElement`. `<div role="radiogroup">`: the track with the sliding thumb, keyboard handling and a horizontally scrolling `ScrollContainer` row.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Selected value (controlled). |
+| `defaultValue` | `string` | `""` | Initial value (uncontrolled); `""` — nothing selected. |
+| `onValueChange` | `(value: string) => void` | — | Called with the new value on click or arrow keys. |
+| `disabled` | `boolean` | `false` | Disables the whole group. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier; the outer height equals the control height 28 · 32 · 36 · 40 · 48. Without it the tier of its host (a toolbar, a panel with a size), else `m`. |
+| `fullWidth` | `boolean` | `false` | Fills the container; single-line segments share the width equally and truncate. |
+| `children` | `ReactNode` | — | `SegmentedControl.Item`s (may be wrapped, e.g. in `Tooltip.Trigger`). |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange">` | — | `aria-label` / `aria-labelledby` (name the group), `className` and the other div attributes. |
 
 ### SegmentedControl.Item
+`ref` → `HTMLButtonElement`. One option, a `<button role="radio">` with roving `tabIndex`; plain text is wrapped to truncate.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string` | — | Yes | Segment identifier |
-| disabled | `boolean` | `false` | No | Disables this segment |
-| children | `React.ReactNode` | — | Yes | Label and/or `SegmentedControl.Icon` |
-| className | `string` | — | No | Extra class on the button |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Option value compared with the root value. |
+| `disabled` | `boolean` | `false` | Disables this option; arrow keys skip it. |
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | — | Palette hue: a dot before the content; while selected the thumb takes a soft fill of the hue with a ring of it. |
+| `children` | `ReactNode` | — (required) | Text, `Icon`, `Label`, `Count`, `Description`. Only an icon → square segment; give it `aria-label`. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" \| "type" \| "role">` | — | `aria-label`, `onClick` (runs first and can `preventDefault()` the selection), `className` and the other button attributes. |
 
 ### SegmentedControl.Icon
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | Yes | Icon node |
-| className | `string` | — | No | Extra class on the `span` |
-| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other `span` attributes |
+`ref` → `HTMLSpanElement`. Decorative icon (`aria-hidden`) sized to the tier.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="theme.light" />`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### SegmentedControl.Label
+`ref` → `HTMLSpanElement`. Segment title; truncates with an ellipsis. Plain text is wrapped automatically.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Title text. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### SegmentedControl.Count
+`ref` → `HTMLSpanElement`. Counter `Badge` after the label, one tier below the control, tabular numbers.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Badge hue. |
+| `children` | `ReactNode` | — (required) | The number. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### SegmentedControl.Description
+`ref` → `HTMLSpanElement`. Muted second line; makes the segment two-line and becomes its `aria-describedby`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Second-line text; wrap a key value in `<strong>`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+## Variants
+No `variant` / `tone`. Axes: `size` and `fullWidth` (Root), `color` (Item, Count), structural content (icon-only, two-line).
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28px track, radius 8, 12/16 text | dense table toolbars next to `xs` controls | |
+| `s` | 32px track, radius 10, 13/20 text | compact toolbars and filters | |
+| `m` | 36px track, radius 12, 14/20 text | default toolbars and page headers | yes |
+| `l` | 40px track, radius 12, 16/24 text | spacious headers next to `l` controls | |
+| `xl` | 48px track, radius 16, 16/24 text | touch-first screens, hero filters | |
+
+Track is `fill-muted` with a faint 1px ring; the selected segment is a floating thumb (`control-selected`, faint ring, `shadow-raised`); segment radius = track radius − padding. A single-line group is as tall as Button, Input, Select and Datepicker trigger of the same size.
+
+### color (Item)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| none | no dot; selected thumb is neutral | ordinary modes and periods | yes |
+| `gray` · `blue` · `green` · `orange` · `red` · `yellow` · `purple` · `sky` · `pink` · `teal` | dot of the hue before the content; selected thumb gets the hue's soft fill and a ring of the hue text | statuses where each value has a meaning | |
+
+### color (Count)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `gray` | neutral soft badge (text wash so it reads on track and thumb) | plain counters | yes |
+| other palette hues | soft badge of the hue | the count has a status meaning | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fullWidth` | fills the container; single-line segments are equal and truncate, two-line segments grow from their content | modals, mobile panels, overview strips | off |
+| `disabled` | every segment disabled, thumb `fill-muted-hover` without shadow | the choice is temporarily unavailable | off |
+| icon-only (only `SegmentedControl.Icon`) | square segment (`data-icon-only`) | toolbar view toggles; needs `aria-label` | — |
+
+Colour all items or none; do not give an item and its Count the same hue; prefer content width or two-line segments over `fullWidth` with many long labels.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| selected | root `value` = item `value` | `aria-checked="true"`, `data-state="checked"`; thumb under the segment, `text-primary` |
+| unselected | — | `aria-checked="false"`, `data-state="unchecked"`; `text-secondary`, hover → `text-primary` (no fill) |
+| no selection | `value` / `defaultValue` = `""` | thumb hidden; the first enabled segment takes Tab focus |
+| item disabled | item `disabled` | `data-disabled="true"`, native `disabled`, `text-disabled`, skipped by arrows |
+| group disabled | root `disabled` | root `data-disabled="true"`, `aria-disabled`; every segment disabled |
+| focus-visible | keyboard | focus ring inside the segment |
+| overflow | row wider than the container | root `data-overflow-start` / `data-overflow-end`: edge fades in the track color |
+
+Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `data-value`, `data-color`. The thumb glides (`emphasized` + `base`, `data-animate`) only into a user's choice (click, arrows); a value set from outside and layout changes snap it; it stays still under `prefers-reduced-motion`. It sits inside the segment track, which clips it, so moving the selection never changes the row's scroll area; when the row scrolls, the chosen segment is scrolled into view.
+
+## Layout & spacing
+- Width is content-based by default; segments never wrap. In a narrow container the row scrolls horizontally with fading edges.
+- In a toolbar: gap `--prime-space-3` between controls; keep every control at one size.
+- Caption under a group: gap `--prime-space-2`.
+- `fullWidth` inside modals and mobile sheets.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `ArrowRight` · `ArrowDown` | Next option, wrapping and skipping disabled ones; focus and selection move together. |
+| `ArrowLeft` · `ArrowUp` | Previous option. |
+| `Home` · `End` | First and last enabled option. |
+| `Tab` | Enters the group on the selected option (or the first enabled one) and leaves it. |
+
+### ARIA
+- Root `role="radiogroup"` — always name it with `aria-label` / `aria-labelledby`; `aria-disabled` when disabled.
+- Items are `<button role="radio" aria-checked>` with roving `tabIndex`.
+- Two-line items: `aria-labelledby` = label (+ count), `aria-describedby` = description.
+- Icons are `aria-hidden`; icon-only items need `aria-label` (and a Tooltip for sighted users).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | One value out of a few, with a sliding thumb on the chosen segment — `defaultValue`, `aria-label`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier; the outer height equals the control height of the same tier — `size`. |
+| [states.tsx](examples/states.tsx) | No selection yet, a disabled segment and a disabled group next to the default — `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and square icon-only segments named for screen readers — `SegmentedControl.Icon`, `aria-label`. |
+| [colors.tsx](examples/colors.tsx) | A status per option: a dot of its hue before the label and a tinted thumb when chosen — `color`. |
+| [full-width.tsx](examples/full-width.tsx) | The group fills its column; segments share the width equally and truncate long labels — `fullWidth`. |
+| [scroll.tsx](examples/scroll.tsx) | Segments never wrap: in a column narrower than the row it scrolls with edge fades and brings the chosen segment into view. |
+| [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a metric on the second — `SegmentedControl.Label`, `SegmentedControl.Count`, `SegmentedControl.Description`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the choice and updates other content from it — `value`, `onValueChange`. |
+
+## Mistakes
+- Using it as tabs that show different panels → use `Tabs`.
+- No `aria-label` on the root → the radiogroup has no name.
+- Icon-only item without `aria-label` → add `aria-label` and wrap in `Tooltip`.
+- `variant="…"` or `tone="…"` on the root → there is none; use `color` on items for hue.
+- Different `size` than neighbouring controls in a toolbar → use the same tier so heights match.
+- Expecting segments to wrap on narrow screens → they scroll; use `fullWidth` or fewer options.
 
 ## Related
-
-- [Tabs](../tabs/COMPONENT.md) — separate panels and tab keyboard model.
-- [Button group](../button-group/COMPONENT.md) — grouped actions, not a single required choice.
-- [Radio](../radio/COMPONENT.md) — standalone radio field primitive.
-- [Select](../select/COMPONENT.md) — many options or list in a dropdown.
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Badge](../badge/COMPONENT.md)
+- **See also:** [Tabs](../tabs/COMPONENT.md), [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md)

package/src/components/segmented-control/examples/colors.tsx

@@ -0,0 +1,18 @@
+/** A status per option: a dot of its hue before the label and a tinted thumb when chosen — `color`. */
+import { SegmentedControl } from "prime-ui-kit";
+
+export default function SegmentedControlColorsExample() {
+  return (
+    <SegmentedControl.Root defaultValue="paid" aria-label="Статус счёта">
+      <SegmentedControl.Item value="paid" color="green">
+        Оплачен
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value="pending" color="orange">
+        Ожидает
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value="overdue" color="red">
+        Просрочен
+      </SegmentedControl.Item>
+    </SegmentedControl.Root>
+  );
+}

package/src/components/segmented-control/examples/controlled.tsx

@@ -1,23 +1,28 @@
+/** The parent owns the choice and updates other content from it — `value`, `onValueChange`. */
 import { SegmentedControl, Typography } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./segmented-examples.module.css";
+import styles from "./examples.module.css";
 
-/** Controlled selection with `value` and `onValueChange` (mirrors playground/snippets/segmented/controlled). */
-export default function SegmentedControlledExample() {
-  const [controlled, setControlled] = React.useState("week");
+const REVENUE: Record<string, string> = {
+  day: "Выручка за день: 48 200 ₽",
+  week: "Выручка за неделю: 312 700 ₽",
+  month: "Выручка за месяц: 1 284 000 ₽",
+};
+
+export default function SegmentedControlControlledExample() {
+  const [period, setPeriod] = React.useState("week");
 
   return (
-    <div className={styles.demoStack}>
-      <SegmentedControl.Root value={controlled} onValueChange={setControlled}>
-        <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
-        <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
-        <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
+    <div className={styles.stack}>
+      <SegmentedControl.Root value={period} onValueChange={setPeriod} aria-label="Период отчёта">
+        <SegmentedControl.Item value="day">День</SegmentedControl.Item>
+        <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
+        <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
       </SegmentedControl.Root>
-      <Typography.Root as="p" variant="body-compact" tone="muted" className={styles.demoCaption}>
-        Selected: <strong>{controlled}</strong> — state is held in React (<code>value</code> +{" "}
-        <code>onValueChange</code>).
-      </Typography.Root>
+      <Typography variant="body-m" tone="secondary">
+        {REVENUE[period]}
+      </Typography>
     </div>
   );
 }

package/src/components/segmented-control/examples/examples.module.css

@@ -0,0 +1,9 @@
+/* Layout of the SegmentedControl scenarios: semantic tokens only. */
+
+/* controlled.tsx: the group and the content it drives, start-aligned in one column. */
+.stack {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--prime-space-3);
+}

package/src/components/segmented-control/examples/full-width.tsx

@@ -1,16 +1,12 @@
+/** The group fills its column; segments share the width equally and truncate long labels — `fullWidth`. */
 import { SegmentedControl } from "prime-ui-kit";
 
-import styles from "./segmented-examples.module.css";
-
-/** Override root `width: fit-content` with a full-width class in a narrow shelf (mirrors playground/snippets/segmented/full-width). */
-export default function SegmentedFullWidthExample() {
+export default function SegmentedControlFullWidthExample() {
   return (
-    <div className={styles.fullWidthShelf}>
-      <SegmentedControl.Root defaultValue="day" className={styles.fullWidthRoot}>
-        <SegmentedControl.Item value="day">Day</SegmentedControl.Item>
-        <SegmentedControl.Item value="week">Week</SegmentedControl.Item>
-        <SegmentedControl.Item value="month">Month</SegmentedControl.Item>
-      </SegmentedControl.Root>
-    </div>
+    <SegmentedControl.Root fullWidth defaultValue="card" aria-label="Способ оплаты">
+      <SegmentedControl.Item value="card">Картой</SegmentedControl.Item>
+      <SegmentedControl.Item value="sbp">СБП</SegmentedControl.Item>
+      <SegmentedControl.Item value="invoice">По счёту для юрлиц</SegmentedControl.Item>
+    </SegmentedControl.Root>
   );
 }