prime-ui-kit 0.7.13 → 0.9.1

package/src/components/button-group/COMPONENT.md

@@ -1,143 +1,155 @@
 # ButtonGroup
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** actions
+**Kind:** control
 
-## Canonical
+> Joined buttons and toggle segments in one neutral bar.
 
-- **What:** `ButtonGroup` groups native **`<button>`** segments that share one outline, inner dividers, and corner radius only on the outer shell; **`Root`** sets **`size`** and optional **`orientation`**, wraps **`ControlSizeProvider`**.
-- **Pieces:** namespace **`ButtonGroup.Root`**, **`ButtonGroup.Item`**, **`ButtonGroup.Icon`** (decorative wrapper, **`aria-hidden`**); **`Item`** must live inside **`Root`**.
-- **Selection look:** optional **`pressed`** on **`Item`** → **`data-state="on"`** and **`aria-pressed`** when boolean; mutual exclusivity is **parent state**, not enforced by the component.
-- **Forms:** **`Item`** supports **`type="button" | "submit" | "reset"`** (default **`"button"`**).
-- **Defaults:** **`size="m"`**, **`orientation="horizontal"`**; no **`variant`** or built-in **`fullWidth`** — widen via layout/`className` on **`Root`** and items if needed.
-- **Prefer something else:** true **one-of-N** field with radio semantics → [Radio](../radio/COMPONENT.md); kit segmented control API → [SegmentedControl](../segmented-control/COMPONENT.md); single CTA → [Button](../button/COMPONENT.md).
+## When to use
+- A few related actions shown as one control (Undo / Redo, Submit / Reset, export formats).
+- Toolbar toggles: independent on/off segments with `pressed`.
+- A one-of-several switch that behaves like toolbar buttons (period, view mode), with `pressed` on the active segment.
+- A vertical stack of related options (`orientation="vertical"`).
 
-## Extended
-
-### About
-
-A row or column of native buttons that share one bordered outline: one size tier for the whole group, internal dividers, and rounded corners only on the outer edges.
-
-- **Use** for toolbars, filters, and view switches where segments should read as one control but keep separate button semantics (`type`, `disabled`, per-item handlers).
-- **Use** for compact action pairs such as submit and reset inside a form.
-- **Use** when you control which segment looks active with `pressed` and parent state (toggle or single-choice UX).
-- **Do not use** when you need a true “one of N” form field with radio semantics and native submission — prefer [Radio](../radio/COMPONENT.md) or native radios.
-- **Do not use** when the kit’s segmented switcher API fits better — see [SegmentedControl](../segmented-control/COMPONENT.md).
-- **Do not use** for a single standalone call to action — use [Button](../button/COMPONENT.md) instead.
-
-### Scenarios (examples)
-
-Copy-ready demos live under **`examples/`** (same folder as this file):
-
-| Scenario | File | Idea |
-|----------|------|------|
-| Editor toolbar | [`examples/editor-toolbar.tsx`](examples/editor-toolbar.tsx) | Icon segments + optional **`pressed`** for active format; **`aria-label`** on icon-only **`Item`**. |
-| Form footer | [`examples/form-footer.tsx`](examples/form-footer.tsx) | **`type="submit"`** / **`type="reset"`** (or **`button`**) in one group; name **`Root`** with **`aria-label`**. |
-| View switcher | [`examples/view-switcher.tsx`](examples/view-switcher.tsx) | Single choice in React state; exactly one **`pressed={true}`** at a time. |
-| Wizard actions | [`examples/wizard-actions.tsx`](examples/wizard-actions.tsx) | Step **Back** / **Next** as a horizontal group; **`disabled`** on **Back** for the first step. |
-| Full width | [`examples/full-width.tsx`](examples/full-width.tsx) | **`Root`** `className` for container width (e.g. **`w-full`**); **`flex-1`** / **`min-w-0`** on **`Item`** to split the row (no built-in **`fullWidth`** prop). |
-
-Playground demos match `playground/sections/ButtonGroupSection.tsx` (order and `?raw` sources):
-
-| Snippet | File | Idea |
-|---------|------|------|
-| Sizes | [`playground/snippets/button-group/sizes.tsx`](../../../playground/snippets/button-group/sizes.tsx) | Four rows **`s`**, **`m`**, **`l`**, **`xl`**; each row is a real three-segment group. |
-| States | [`states.tsx`](../../../playground/snippets/button-group/states.tsx) | Default, **`pressed`**, **`disabled`** in one group. |
-| Orientation | [`orientation.tsx`](../../../playground/snippets/button-group/orientation.tsx) | Default horizontal vs **`orientation="vertical"`**. |
-| Controlled | [`controlled.tsx`](../../../playground/snippets/button-group/controlled.tsx) | Parent state; exactly one **`pressed={true}`** at a time (**day** / **week** / **month**). |
-| Composition | [`composition.tsx`](../../../playground/snippets/button-group/composition.tsx) | **`ButtonGroup.Icon`**, **`aria-label`** on icon-only **`Item`**, text + chevron, two toolbar rows. |
-| Full width | [`full-width.tsx`](../../../playground/snippets/button-group/full-width.tsx) | **`Root`** **`className="w-full"`**; items **`className="min-w-0 flex-1"`** inside a bounded container. |
-| Form features | [`form-features.tsx`](../../../playground/snippets/button-group/form-features.tsx) | Form with **`type="submit"`** and **`type="reset"`** segments. |
-
-### Composition
-
-- **`ButtonGroup`** is a namespace object: **`Root`**, **`Item`**, **`Icon`**.
-- **`ButtonGroup.Root`** — wrapper `div` with `data-size={size}`; for `orientation="vertical"` it sets `data-orientation="vertical"`. It provides group context and **`ControlSizeProvider`**, so nested controls inherit the same size tier.
-- Place one or more **`ButtonGroup.Item`** elements inside **`Root`** (they call the group context; using **`Item`** outside **`Root`** throws).
-- Optionally put **`ButtonGroup.Icon`** inside an **`Item`** to wrap an SVG: it renders a **`span`** with **`aria-hidden="true"`**.
-
-### Minimal example
+## When not to use
+- Choosing a value from a set as a form control → use [SegmentedControl](../segmented-control/COMPONENT.md) (radio semantics, `value` / `onValueChange`).
+- Switching between content panels → use [Tabs](../tabs/COMPONENT.md).
+- Independent actions with their own visual weight (primary + cancel) → use separate [Button](../button/COMPONENT.md)s.
+- Many actions or overflow → use [Dropdown](../dropdown/COMPONENT.md).
 
+## Import
 ```tsx
 import { ButtonGroup } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <ButtonGroup.Root aria-label="Options">
-      <ButtonGroup.Item type="button">One</ButtonGroup.Item>
-      <ButtonGroup.Item type="button">Two</ButtonGroup.Item>
-    </ButtonGroup.Root>
-  );
-}
 ```
 
-### Rules
-
-- There is no `variant` prop: appearance is always the shared-outline segment style; vary **`size`**, **`orientation`**, **`pressed`**, and **`disabled`** instead.
-- **`pressed`**: when `true`, the segment gets `data-state="on"` and `aria-pressed="true"`; when `false`, you get `aria-pressed="false"`; when omitted, `aria-pressed` is not set.
-- The component does not enforce a single selected segment: for mutually exclusive choice, keep state in the parent and set **`pressed`** (and handlers) accordingly; avoid multiple **`pressed`** items unless that is intentional.
-- Give **`Root`** an accessible name with **`aria-label`** or **`aria-labelledby`** when the group is not labeled by visible text.
-- For icon-only segments, set **`aria-label`** on **`ButtonGroup.Item`**; do not rely on **`ButtonGroup.Icon`** for a name (it is hidden from assistive tech).
-- Segments always render as **`<button>`** (no `asChild`); there is no built-in **`fullWidth`** — widen the group with layout on the root and items if needed.
-- **`ButtonGroup.Item`** supports **`type="button" | "submit" | "reset"`** (default **`"button"`**) for correct form behavior.
-
-### API
-
-#### ButtonGroup.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | no | Layout direction of segments. |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Size tier for the group (height, radius, typography, icon scale). |
-| children | `React.ReactNode` | — | yes | Usually several `ButtonGroup.Item` nodes. |
-| className | `string` | — | no | Additional class on the root element. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | no | Other div attributes (e.g. `aria-label`, `role`, event handlers). |
-
-#### ButtonGroup.Item
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| pressed | `boolean` | — | no | Selected look: `data-state="on"` when `true`; `aria-pressed` mirrors the prop when it is a boolean. |
-| type | `"button" \| "submit" \| "reset"` | `"button"` | no | Native button type inside forms. |
-| disabled | `boolean` | — | no | Disables the segment. |
-| children | `React.ReactNode` | — | no | Label content; optional `ButtonGroup.Icon` for icons. |
-| className | `string` | — | no | Additional class on the button. |
-| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | no | Other native button attributes. |
-
-#### ButtonGroup.Icon
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Typically an SVG icon. |
-| className | `string` | — | no | Additional class on the wrapper span. |
-| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | no | Other span attributes (not `children`). |
-
-### Related
-
-- [Button](../button/COMPONENT.md) — single actions, variants, loading.
-- [SegmentedControl](../segmented-control/COMPONENT.md) — alternative segmented switcher API.
-- [Radio](../radio/COMPONENT.md) — form “one of N” with radio semantics.
-
-## LLM note
-
-```yaml
-component: ButtonGroup
-exports: [ButtonGroup.Root, ButtonGroup.Item, ButtonGroup.Icon]
-defaults: { size: m, orientation: horizontal }
-behavior:
-  items_are: native button elements
-  pressed: optional boolean per Item; parent owns mutual exclusion for single-choice UX
-  no_variant: true
-  no_fullWidth_prop: true  # use layout / className on Root and Items
-forms:
-  Item_type: [button, submit, reset]
-a11y:
-  name_Root: aria-label or aria-labelledby when no visible label
-  icon_only_Item: aria-label on Item (not on Icon)
-anti_patterns:
-  - Using as native radio group for form submit semantics → Radio
-  - Single CTA → Button
-  - Prefer SegmentedControl when that composable API is a better fit
-doc_examples_dir: src/components/button-group/examples/
-playground_snippets: playground/snippets/button-group/
-playground_snippet_files: [sizes, states, orientation, controlled, composition, full-width, form-features]
+## Anatomy
 ```
+ButtonGroup.Root         <div role="group">; size and orientation for every segment
+└─ ButtonGroup.Item      one segment, a native <button>; optional pressed toggle
+   └─ ButtonGroup.Icon   decorative icon wrapper (aria-hidden), sized to the tier
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ButtonGroup.Root
+`ref` → `HTMLDivElement`. `<div role="group">`; sets the tier and orientation of every segment and passes the tier to nested icons.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier of every segment: height 28 · 32 · 36 · 40 · 48, padding, text, icon. Without it the tier of its host (a toolbar, a panel), else `m`. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction of the segments; `vertical` stretches them to the widest. |
+| `fullWidth` | `boolean` | — | Stretches the group; horizontal segments share the width equally. |
+| `children` | `ReactNode` | — | `ButtonGroup.Item` segments. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `aria-label` (name the group), `role` (e.g. `"toolbar"`), `className` and the other div attributes. |
+
+### ButtonGroup.Item
+`ref` → `HTMLButtonElement`. One segment, a native `<button>`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `pressed` | `boolean` | — | Toggle state: `aria-pressed` and `data-state="active" \| "inactive"`. Leave it out for a plain action segment. |
+| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type. |
+| `disabled` | `boolean` | — | Native disabled. |
+| `children` | `ReactNode` | — | Label and `ButtonGroup.Icon`. Only icons → square segment; give it `aria-label`. |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `className`, `aria-*` and the other button attributes. |
+
+### ButtonGroup.Icon
+`ref` → `HTMLSpanElement`. Decorative icon wrapper (`aria-hidden`) sized to the group tier.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="action.copy" />`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+## Variants
+
+### orientation
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `horizontal` | segments in a row, outer left / right corners rounded | toolbars, view and period switches | yes |
+| `vertical` | segments in a column, stretched to the widest; top and bottom corners rounded | a short list of related options in a side column | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28px high, 12/16 text, padX 8 | dense tables | |
+| `s` | 32px, 13/20, padX 12 | compact toolbars | |
+| `m` | 36px, 14/20, padX 16 | default | yes |
+| `l` | 40px, 16/24, padX 20 | prominent forms | |
+| `xl` | 48px, 16/24, padX 24 | hero areas | |
+
+A group lines up with Button, Input, Select and SegmentedControl of the same `size`.
+
+### pressed
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| — (omitted) | `fill-muted` fill, secondary text; hover `fill-muted-hover` + primary text; active `fill-strong` | plain actions | yes |
+| `true` | `accent-soft` fill, accent text | the active toggle / selected option | |
+| `false` | same as plain, but `aria-pressed="false"` | the non-active members of a toggle set | |
+
+Segments have no borders: they sit on the neutral fill and are separated by a 1px gap that shows the surface behind; only the outer corners take the tier radius.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fullWidth` | group fills the row, segments `flex: 1` | plan pickers in narrow columns | off |
+| icon-only (only `ButtonGroup.Icon` inside an Item) | square segment, width = height | toolbars; needs `aria-label` | — |
+
+Do not mix action segments and toggle segments in one group, and do not put the primary action inside the group — place a [Button](../button/COMPONENT.md) of the same size next to it.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| hover / active | pointer | hover `fill-muted-hover` + primary text; active `fill-strong` + `scale(var(--prime-motion-press-scale))` (`-compact` for icon-only segments); disabled never scales |
+| pressed | `pressed` | `aria-pressed`, `data-state="active" \| "inactive"` |
+| disabled | `disabled` | native `:disabled`: `fill-muted` + `text-disabled`, `cursor: not-allowed` |
+| focus-visible | keyboard | outer focus ring, the segment is raised above neighbours (`z-index: 1`) |
+
+Root attributes: `data-size`, `data-orientation="vertical"` (only when vertical), `data-full-width`. Item attributes: `data-icon-only`, `data-leading-icon`, `data-trailing-icon` (optical padding `padX − 4px` on the icon side). Selection is always owned by the parent: keep the value in state and set `pressed`.
+
+## Layout & spacing
+- Groups in a toolbar: `gap: var(--prime-space-3)`; push the primary Button to the end with a flexible spacer.
+- `max-width: 100%`; labels do not wrap. Use `fullWidth` in narrow columns.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus between segments; a disabled one is skipped. |
+| `Enter` · `Space` | Presses the segment (native `<button>`). |
+
+### ARIA
+- `Root` is `role="group"` — give it `aria-label`; set `role="toolbar"` on the outer container of several groups.
+- Toggle segments expose `aria-pressed`; in a toggle set pass `pressed={false}` to the inactive ones.
+- Icon-only segments need `aria-label`; `ButtonGroup.Icon` is `aria-hidden`.
+
+### 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) | Related actions joined into one bar with a group name — `aria-label`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier, 28 to 48 px high, set once on the root — `size`. |
+| [states.tsx](examples/states.tsx) | A plain segment, a toggled one and a disabled one — `pressed`, `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and square icon-only segments — `ButtonGroup.Icon`, `aria-label`. |
+| [orientation.tsx](examples/orientation.tsx) | A row of segments and a column of related options — `orientation`. |
+| [full-width.tsx](examples/full-width.tsx) | The group fills its column and the segments share the width equally — `fullWidth`. |
+| [controlled.tsx](examples/controlled.tsx) | One of several: the active segment lives in parent state and gets `pressed`. |
+| [in-form.tsx](examples/in-form.tsx) | Segments are native buttons, so submit and reset work in one group — `type`. |
+
+## Mistakes
+- `size` on each `ButtonGroup.Item` → set `size` once on `Root`.
+- `<Button.Root>` inside the group → use `ButtonGroup.Item`; Button segments are not joined.
+- Expecting `value` / `onValueChange` → ButtonGroup has none; keep the value in state and set `pressed`, or use SegmentedControl.
+- `pressed` only on the active segment of a toggle set → pass `pressed={false}` to the others so they announce as toggles.
+- Icon-only segment without `aria-label` → add it.
+
+## Related
+- **Built from:** —
+- **See also:** [Button](../button/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Tabs](../tabs/COMPONENT.md)

package/src/components/button-group/examples/controlled.tsx

@@ -0,0 +1,29 @@
+/** One of several: the active segment lives in parent state and gets `pressed`. */
+import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+type Period = "day" | "week" | "month";
+
+const PERIODS: { value: Period; label: string }[] = [
+  { value: "day", label: "День" },
+  { value: "week", label: "Неделя" },
+  { value: "month", label: "Месяц" },
+];
+
+export default function ButtonGroupControlledExample() {
+  const [period, setPeriod] = React.useState<Period>("week");
+
+  return (
+    <ButtonGroup.Root aria-label="Интервал отчёта">
+      {PERIODS.map((item) => (
+        <ButtonGroup.Item
+          key={item.value}
+          pressed={period === item.value}
+          onClick={() => setPeriod(item.value)}
+        >
+          {item.label}
+        </ButtonGroup.Item>
+      ))}
+    </ButtonGroup.Root>
+  );
+}

package/src/components/button-group/examples/examples.module.css

@@ -0,0 +1,8 @@
+/* Layout of the ButtonGroup scenarios: semantic tokens only. */
+
+/* Field → actions: group gap (foundation §1). The group keeps its own width. */
+.form {
+  display: grid;
+  justify-items: start;
+  gap: var(--prime-space-5);
+}

package/src/components/button-group/examples/full-width.tsx

@@ -1,22 +1,19 @@
+/** The group fills its column and the segments share the width equally — `fullWidth`. */
 import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+const PLANS = ["Базовый", "Команда", "Бизнес"] as const;
+
+export default function ButtonGroupFullWidthExample() {
+  const [plan, setPlan] = React.useState<(typeof PLANS)[number]>("Команда");
 
-/**
- * Full width: no dedicated prop — width on Root, equal segments via flex-1 on Items.
- */
-export default function FullWidthExample() {
   return (
-    <div className="w-full max-w-md">
-      <ButtonGroup.Root aria-label="Plan tier" className="w-full">
-        <ButtonGroup.Item className="min-w-0 flex-1" type="button">
-          Basic
-        </ButtonGroup.Item>
-        <ButtonGroup.Item className="min-w-0 flex-1" pressed type="button">
-          Pro
-        </ButtonGroup.Item>
-        <ButtonGroup.Item className="min-w-0 flex-1" type="button">
-          Business
+    <ButtonGroup.Root aria-label="Тариф" fullWidth>
+      {PLANS.map((item) => (
+        <ButtonGroup.Item key={item} pressed={plan === item} onClick={() => setPlan(item)}>
+          {item}
         </ButtonGroup.Item>
-      </ButtonGroup.Root>
-    </div>
+      ))}
+    </ButtonGroup.Root>
   );
 }

package/src/components/button-group/examples/in-form.tsx

@@ -0,0 +1,20 @@
+/** Segments are native buttons, so submit and reset work in one group — `type`. */
+import { ButtonGroup, Input } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ButtonGroupInFormExample() {
+  return (
+    <form className={styles.form} onSubmit={(event) => event.preventDefault()}>
+      <Input.Root label="Поиск по заказам">
+        <Input.Wrapper>
+          <Input.Field name="query" type="search" placeholder="Номер заказа или клиент" />
+        </Input.Wrapper>
+      </Input.Root>
+      <ButtonGroup.Root aria-label="Отправить или сбросить поиск">
+        <ButtonGroup.Item type="submit">Найти</ButtonGroup.Item>
+        <ButtonGroup.Item type="reset">Сбросить</ButtonGroup.Item>
+      </ButtonGroup.Root>
+    </form>
+  );
+}

package/src/components/button-group/examples/orientation.tsx

@@ -0,0 +1,19 @@
+/** A row of segments and a column of related options — `orientation`. */
+import { ButtonGroup } from "prime-ui-kit";
+
+export default function ButtonGroupOrientationExample() {
+  return (
+    <>
+      <ButtonGroup.Root aria-label="Сортировка заказов">
+        <ButtonGroup.Item pressed>Новые</ButtonGroup.Item>
+        <ButtonGroup.Item pressed={false}>По сумме</ButtonGroup.Item>
+        <ButtonGroup.Item pressed={false}>Старые</ButtonGroup.Item>
+      </ButtonGroup.Root>
+      <ButtonGroup.Root aria-label="Раздел настроек" orientation="vertical">
+        <ButtonGroup.Item pressed>Профиль</ButtonGroup.Item>
+        <ButtonGroup.Item pressed={false}>Безопасность</ButtonGroup.Item>
+        <ButtonGroup.Item pressed={false}>Уведомления</ButtonGroup.Item>
+      </ButtonGroup.Root>
+    </>
+  );
+}

package/src/components/button-group/examples/overview.tsx

@@ -0,0 +1,12 @@
+/** Related actions joined into one bar with a group name — `aria-label`. */
+import { ButtonGroup } from "prime-ui-kit";
+
+export default function ButtonGroupOverviewExample() {
+  return (
+    <ButtonGroup.Root aria-label="Экспорт отчёта">
+      <ButtonGroup.Item>CSV</ButtonGroup.Item>
+      <ButtonGroup.Item>Excel</ButtonGroup.Item>
+      <ButtonGroup.Item>PDF</ButtonGroup.Item>
+    </ButtonGroup.Root>
+  );
+}

package/src/components/button-group/examples/sizes.tsx

@@ -0,0 +1,22 @@
+/** Every size tier, 28 to 48 px high, set once on the root — `size`. */
+import { ButtonGroup, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ButtonGroupSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <ButtonGroup.Root size={size} aria-label="Вид">
+            <ButtonGroup.Item pressed>Код</ButtonGroup.Item>
+            <ButtonGroup.Item pressed={false}>Превью</ButtonGroup.Item>
+          </ButtonGroup.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/button-group/examples/states.tsx

@@ -0,0 +1,33 @@
+/** A plain segment, a toggled one and a disabled one — `pressed`, `disabled`. */
+import { ButtonGroup, Typography } from "prime-ui-kit";
+
+export default function ButtonGroupStatesExample() {
+  return (
+    <div>
+      <div>
+        <ButtonGroup.Root aria-label="Статус задачи">
+          <ButtonGroup.Item>Открыта</ButtonGroup.Item>
+        </ButtonGroup.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          default
+        </Typography>
+      </div>
+      <div>
+        <ButtonGroup.Root aria-label="Статус задачи">
+          <ButtonGroup.Item pressed>В работе</ButtonGroup.Item>
+        </ButtonGroup.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          pressed
+        </Typography>
+      </div>
+      <div>
+        <ButtonGroup.Root aria-label="Статус задачи">
+          <ButtonGroup.Item disabled>Архив</ButtonGroup.Item>
+        </ButtonGroup.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/button-group/examples/with-icon.tsx

@@ -0,0 +1,45 @@
+/** An icon before the label and square icon-only segments — `ButtonGroup.Icon`, `aria-label`. */
+import { ButtonGroup, Icon, Typography } from "prime-ui-kit";
+
+export default function ButtonGroupWithIconExample() {
+  return (
+    <div>
+      <div>
+        <ButtonGroup.Root aria-label="Файл">
+          <ButtonGroup.Item>
+            <ButtonGroup.Icon>
+              <Icon name="action.download" />
+            </ButtonGroup.Icon>
+            Скачать
+          </ButtonGroup.Item>
+          <ButtonGroup.Item>
+            <ButtonGroup.Icon>
+              <Icon name="action.copy" />
+            </ButtonGroup.Icon>
+            Копировать
+          </ButtonGroup.Item>
+        </ButtonGroup.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          leading
+        </Typography>
+      </div>
+      <div>
+        <ButtonGroup.Root aria-label="Режим просмотра">
+          <ButtonGroup.Item aria-label="Код" pressed>
+            <ButtonGroup.Icon>
+              <Icon name="view.code" />
+            </ButtonGroup.Icon>
+          </ButtonGroup.Item>
+          <ButtonGroup.Item aria-label="Превью" pressed={false}>
+            <ButtonGroup.Icon>
+              <Icon name="view.preview" />
+            </ButtonGroup.Icon>
+          </ButtonGroup.Item>
+        </ButtonGroup.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          icon-only
+        </Typography>
+      </div>
+    </div>
+  );
+}