prime-ui-kit 0.9.0 → 0.9.2

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

@@ -1,29 +1,41 @@
-/** `Button.Icon` before or after the label; the icon side gets 4px less padding and `Icon` without `size` takes the button tier. Use when an icon clarifies the action. */
-import { Button, Icon } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** An icon before or after the label, and a square icon-only button — `Button.Icon`, `aria-label`. */
+import { Button, Icon, Typography } from "prime-ui-kit";
 
 export default function ButtonWithIconExample() {
   return (
-    <div className={styles.row}>
-      <Button.Root>
-        <Button.Icon>
-          <Icon name="action.upload" />
-        </Button.Icon>
-        Загрузить файл
-      </Button.Root>
-      <Button.Root variant="outline" tone="neutral">
-        <Button.Icon>
-          <Icon name="field.email" tone="secondary" />
-        </Button.Icon>
-        Написать
-      </Button.Root>
-      <Button.Root variant="soft" tone="neutral">
-        Далее
-        <Button.Icon>
-          <Icon name="nav.chevronRight" />
-        </Button.Icon>
-      </Button.Root>
+    <div>
+      <div>
+        <Button.Root>
+          <Button.Icon>
+            <Icon name="action.upload" />
+          </Button.Icon>
+          Загрузить файл
+        </Button.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          leading
+        </Typography>
+      </div>
+      <div>
+        <Button.Root variant="soft" tone="neutral">
+          Далее
+          <Button.Icon>
+            <Icon name="nav.chevronRight" />
+          </Button.Icon>
+        </Button.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          trailing
+        </Typography>
+      </div>
+      <div>
+        <Button.Root variant="ghost" tone="neutral" aria-label="Копировать ссылку">
+          <Button.Icon>
+            <Icon name="action.copy" />
+          </Button.Icon>
+        </Button.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          icon-only
+        </Typography>
+      </div>
     </div>
   );
 }

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

@@ -1,17 +1,18 @@
 # ButtonGroup
 
 **Category:** actions
+**Kind:** control
 
 > Joined buttons and toggle segments in one neutral bar.
 
 ## When to use
-- A few related actions shown as one control (Undo / Redo, Submit / Reset).
-- Toolbar toggles: independent on/off segments (Bold, Italic) with `pressed`.
+- 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"`).
 
 ## When not to use
-- Choosing a value from a set as a form control → use [SegmentedControl](../segmented-control/COMPONENT.md) (radio semantics, `value`/`onValueChange`).
+- 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).
@@ -22,47 +23,52 @@ import { ButtonGroup } from "prime-ui-kit";
 ```
 
 ## Anatomy
-- `ButtonGroup.Root` — `<div role="group">`; sets size and orientation for every segment.
-- `ButtonGroup.Item` — one segment, a native `<button>`; must be inside `Root`.
-- `ButtonGroup.Icon` — decorative icon wrapper (`aria-hidden`) sized to the group tier; must be inside `Root`.
+```
+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
-`forwardRef` → `HTMLDivElement`. + native `<div>` props.
+`ref` → `HTMLDivElement`. `<div role="group">`; sets the tier and orientation of every segment and passes the tier to nested icons.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction of the segments. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier for every segment; also provided to nested icons. |
+| `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. |
-| `role` | `string` | `"group"` | Override, e.g. `"toolbar"`. |
-| `children` | `ReactNode` | — (required) | `ButtonGroup.Item` segments. |
+| `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
-`forwardRef` → `HTMLButtonElement`. + native `<button>` props.
+`ref` → `HTMLButtonElement`. One segment, a native `<button>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `pressed` | `boolean` | — | Toggle state: sets `aria-pressed` and `data-state="active" \| "inactive"`. Leave undefined for a plain action segment. |
+| `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 (needs `aria-label`). |
+| `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
-+ native `<span>` props.
+`ref` → `HTMLSpanElement`. Decorative icon wrapper (`aria-hidden`) sized to the group tier.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | The icon (SVG). |
-| `className` | `string` | — | Extra class. |
+| `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 |
+| `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
@@ -76,71 +82,74 @@ import { ButtonGroup } from "prime-ui-kit";
 
 A group lines up with Button, Input, Select and SegmentedControl of the same `size`.
 
-### Segment look (`pressed`, icon-only)
+### pressed
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| no `pressed` | `fill-muted` fill, secondary text; hover `fill-muted-hover` + primary text; active `fill-strong` | plain actions | yes |
-| `pressed={true}` | `accent-soft` fill, accent text | the active toggle / selected option | |
-| `pressed={false}` | same as plain, but `aria-pressed="false"` | the non-active members of a toggle set | |
-| icon-only (only `ButtonGroup.Icon`) | square segment, width = height | toolbars | |
-| `fullWidth` | group fills the row, segments `flex: 1` | plan pickers in narrow columns | off |
+| — (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.
 
-**Combinations**
-- Recommended: in a toggle set give every segment a boolean `pressed` (true on active ones, false on the rest).
-- Avoid: mixing action segments and toggle segments in one group; putting a primary action inside the group — place a [Button](../button/COMPONENT.md) of the same size next to it.
+### 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="true"`. Item attributes: `data-icon-only`, `data-leading-icon`, `data-trailing-icon` (optical padding `padX − 4px` on the icon side). Selection is always controlled by the parent: keep the value in state and set `pressed` (see `controlled.tsx`).
+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`; icon-only segments need `aria-label`.
-- Keyboard: Tab moves between segments, Enter/Space activates (native buttons). No arrow-key roving. No `labels` keys.
+- 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`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | Five size tiers | matching neighbouring controls |
-| [states.tsx](examples/states.tsx) | Plain, pressed, disabled segments | state reference |
-| [orientation.tsx](examples/orientation.tsx) | Horizontal and vertical groups | column of options |
-| [controlled.tsx](examples/controlled.tsx) | One of several via parent state + `pressed` | period / view switch |
-| [composition.tsx](examples/composition.tsx) | Editor toolbar: history, toggles, alignment, primary Button | formatting toolbars |
-| [full-width.tsx](examples/full-width.tsx) | `fullWidth` plan picker | narrow forms and cards |
-| [in-form.tsx](examples/in-form.tsx) | `type="submit"` / `type="reset"` segments | search / filter forms |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```tsx
-import { ButtonGroup } from "prime-ui-kit";
+No `labels`.
 
-export function HistoryGroup() {
-  return (
-    <ButtonGroup.Root aria-label="История">
-      <ButtonGroup.Item>Отменить</ButtonGroup.Item>
-      <ButtonGroup.Item>Повторить</ButtonGroup.Item>
-    </ButtonGroup.Root>
-  );
-}
-```
+## 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.
+- 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
-- [Button](../button/COMPONENT.md)
-- [SegmentedControl](../segmented-control/COMPONENT.md)
-- [Tabs](../tabs/COMPONENT.md)
+- **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

@@ -1,10 +1,10 @@
-/** One-of-several choice: the active segment lives in parent state and gets `pressed`. Use for a small view or period switch that acts like toolbar buttons. */
+/** 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 }[] = [
+const PERIODS: { value: Period; label: string }[] = [
   { value: "day", label: "День" },
   { value: "week", label: "Неделя" },
   { value: "month", label: "Месяц" },
@@ -15,7 +15,7 @@ export default function ButtonGroupControlledExample() {
 
   return (
     <ButtonGroup.Root aria-label="Интервал отчёта">
-      {periods.map((item) => (
+      {PERIODS.map((item) => (
         <ButtonGroup.Item
           key={item.value}
           pressed={period === item.value}

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

@@ -1,43 +1,8 @@
-/* Layout for the ButtonGroup examples: semantic tokens only. */
+/* Layout of the ButtonGroup scenarios: semantic tokens only. */
 
-.row {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: flex-start;
-  justify-content: center;
-  gap: var(--prime-space-3);
-}
-
-.sizeRow {
-  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);
-}
-
-.toolbar {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: var(--prime-space-3);
-  width: 100%;
-}
-
-.spacer {
-  flex: 1 1 auto;
-}
-
-.column {
+/* Field → actions: group gap (foundation §1). The group keeps its own width. */
+.form {
   display: grid;
+  justify-items: start;
   gap: var(--prime-space-5);
-  width: 100%;
-  max-width: var(--prime-modal-width-s);
 }

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

@@ -1,23 +1,19 @@
-/** `fullWidth` stretches the group to its column; horizontal segments share the width equally. Use for plan or mode pickers in narrow forms and cards. */
+/** The group fills its column and the segments share the width equally — `fullWidth`. */
 import { ButtonGroup } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
-const plans = ["Базовый", "Про", "Бизнес"] as const;
+const PLANS = ["Базовый", "Команда", "Бизнес"] as const;
 
 export default function ButtonGroupFullWidthExample() {
-  const [plan, setPlan] = React.useState<(typeof plans)[number]>("Про");
+  const [plan, setPlan] = React.useState<(typeof PLANS)[number]>("Команда");
 
   return (
-    <div className={styles.column}>
-      <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 aria-label="Тариф" fullWidth>
+      {PLANS.map((item) => (
+        <ButtonGroup.Item key={item} pressed={plan === item} onClick={() => setPlan(item)}>
+          {item}
+        </ButtonGroup.Item>
+      ))}
+    </ButtonGroup.Root>
   );
 }

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

@@ -1,14 +1,14 @@
-/** Segments are native buttons: `type="submit"` and `type="reset"` work inside one group. Use for a compact submit/reset pair in a search or filter form. */
+/** 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.column} onSubmit={(e) => e.preventDefault()}>
+    <form className={styles.form} onSubmit={(event) => event.preventDefault()}>
       <Input.Root label="Поиск по заказам">
         <Input.Wrapper>
-          <Input.Field name="q" type="search" placeholder="Номер заказа или клиент" />
+          <Input.Field name="query" type="search" placeholder="Номер заказа или клиент" />
         </Input.Wrapper>
       </Input.Root>
       <ButtonGroup.Root aria-label="Отправить или сбросить поиск">

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

@@ -1,21 +1,19 @@
-/** Horizontal (default) and vertical groups side by side. Use `orientation="vertical"` for a column of related options. */
+/** A row of segments and a column of related options — `orientation`. */
 import { ButtonGroup } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 export default function ButtonGroupOrientationExample() {
   return (
-    <div className={styles.row}>
-      <ButtonGroup.Root aria-label="Сортировка">
+    <>
+      <ButtonGroup.Root aria-label="Сортировка заказов">
         <ButtonGroup.Item pressed>Новые</ButtonGroup.Item>
-        <ButtonGroup.Item pressed={false}>Популярные</ButtonGroup.Item>
+        <ButtonGroup.Item pressed={false}>По сумме</ButtonGroup.Item>
         <ButtonGroup.Item pressed={false}>Старые</ButtonGroup.Item>
       </ButtonGroup.Root>
-      <ButtonGroup.Root aria-label="Раздел" orientation="vertical">
+      <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>
-    </div>
+    </>
   );
 }

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

@@ -1,22 +1,20 @@
-/** All five size tiers (28 · 32 · 36 · 40 · 48) set once on the root. Use to match the group to neighbouring controls; default is `m`. */
+/** Every size tier, 28 to 48 px high, set once on the root — `size`. */
 import { ButtonGroup, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
-const sizes = ["xs", "s", "m", "l", "xl"] as const;
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function ButtonGroupSizesExample() {
   return (
-    <div className={styles.sizeRow}>
-      {sizes.map((size) => (
-        <div key={size} className={styles.sizeCell}>
-          <ButtonGroup.Root size={size} aria-label={`Вид, размер ${size}`}>
+    <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.Root as="span" variant="caption" tone="muted">
+          <Typography as="span" variant="caption" tone="muted">
             {size}
-          </Typography.Root>
+          </Typography>
         </div>
       ))}
     </div>

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

@@ -1,12 +1,33 @@
-/** A plain segment, a pressed segment and a disabled segment. Use to see the hover, selected and disabled looks. */
-import { ButtonGroup } from "prime-ui-kit";
+/** A plain segment, a toggled one and a disabled one — `pressed`, `disabled`. */
+import { ButtonGroup, Typography } from "prime-ui-kit";
 
 export default function ButtonGroupStatesExample() {
   return (
-    <ButtonGroup.Root aria-label="Статус задачи">
-      <ButtonGroup.Item>Открыта</ButtonGroup.Item>
-      <ButtonGroup.Item pressed>В работе</ButtonGroup.Item>
-      <ButtonGroup.Item disabled>Архив</ButtonGroup.Item>
-    </ButtonGroup.Root>
+    <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>
+  );
+}