prime-ui-kit 0.7.11 → 0.9.0

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

@@ -0,0 +1,48 @@
+/** Default, disabled and loading (centered spinner, spinner in place of the leading icon, icon-only). Use to see that `loading` needs no `Button.Spinner` and keeps the width. */
+import { Button, Icon, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+function Caption({ children }: { children: string }) {
+  return (
+    <Typography.Root as="span" variant="caption" tone="muted">
+      {children}
+    </Typography.Root>
+  );
+}
+
+export default function ButtonStatesExample() {
+  return (
+    <div className={styles.sizeRow}>
+      <div className={styles.sizeCell}>
+        <Button.Root>Сохранить</Button.Root>
+        <Caption>default</Caption>
+      </div>
+      <div className={styles.sizeCell}>
+        <Button.Root disabled>Сохранить</Button.Root>
+        <Caption>disabled</Caption>
+      </div>
+      <div className={styles.sizeCell}>
+        <Button.Root loading>Сохранить</Button.Root>
+        <Caption>loading</Caption>
+      </div>
+      <div className={styles.sizeCell}>
+        <Button.Root variant="outline" tone="neutral" loading>
+          <Button.Icon>
+            <Icon name="action.upload" />
+          </Button.Icon>
+          Загрузить
+        </Button.Root>
+        <Caption>loading + иконка</Caption>
+      </div>
+      <div className={styles.sizeCell}>
+        <Button.Root variant="ghost" tone="neutral" loading aria-label="Копировать">
+          <Button.Icon>
+            <Icon name="action.copy" />
+          </Button.Icon>
+        </Button.Root>
+        <Caption>loading, icon-only</Caption>
+      </div>
+    </div>
+  );
+}

package/src/components/button/examples/surfaces.tsx

@@ -0,0 +1,18 @@
+/** Neutral solid, soft and ghost buttons for checking contrast on canvas, card, raised layer and accent backgrounds. Use when buttons sit on a non-default surface. */
+import { Button } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ButtonSurfacesExample() {
+  return (
+    <div className={styles.row}>
+      <Button.Root tone="neutral">Отмена</Button.Root>
+      <Button.Root variant="soft" tone="neutral">
+        Фильтры
+      </Button.Root>
+      <Button.Root variant="ghost" tone="neutral">
+        Ещё
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/button/examples/variants-tones.tsx

@@ -0,0 +1,39 @@
+/** Every `tone` × `variant` combination as a matrix. Use to choose the treatment (variant) and the meaning (tone) of an action. */
+import { Button, Typography } from "prime-ui-kit";
+import { Fragment } from "react";
+
+import styles from "./examples.module.css";
+
+const tones = [
+  { tone: "accent", label: "Сохранить" },
+  { tone: "neutral", label: "Отмена" },
+  { tone: "danger", label: "Удалить" },
+] as const;
+const variants = ["solid", "soft", "outline", "ghost"] as const;
+
+export default function ButtonVariantsTonesExample() {
+  return (
+    <div className={styles.matrixScroll}>
+      <div className={styles.matrix}>
+        <span />
+        {variants.map((variant) => (
+          <Typography.Root key={variant} as="span" variant="caption" tone="muted">
+            {variant}
+          </Typography.Root>
+        ))}
+        {tones.map(({ tone, label }) => (
+          <Fragment key={tone}>
+            <Typography.Root as="span" variant="caption" tone="muted">
+              {tone}
+            </Typography.Root>
+            {variants.map((variant) => (
+              <Button.Root key={variant} variant={variant} tone={tone}>
+                {label}
+              </Button.Root>
+            ))}
+          </Fragment>
+        ))}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,29 @@
+/** `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";
+
+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>
+  );
+}

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

@@ -1,143 +1,146 @@
 # ButtonGroup
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** actions
 
-## 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).
+- Toolbar toggles: independent on/off segments (Bold, Italic) 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
+## 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).
 
-### 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"`**.
+## Import
+```tsx
+import { ButtonGroup } from "prime-ui-kit";
+```
 
-### Minimal example
+## 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`.
+
+## API
+
+### ButtonGroup.Root
+`forwardRef` → `HTMLDivElement`. + native `<div>` props.
+
+| 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. |
+| `fullWidth` | `boolean` | — | Stretches the group; horizontal segments share the width equally. |
+| `role` | `string` | `"group"` | Override, e.g. `"toolbar"`. |
+| `children` | `ReactNode` | — (required) | `ButtonGroup.Item` segments. |
+
+### ButtonGroup.Item
+`forwardRef` → `HTMLButtonElement`. + native `<button>` props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `pressed` | `boolean` | — | Toggle state: sets `aria-pressed` and `data-state="active" \| "inactive"`. Leave undefined 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`). |
+
+### ButtonGroup.Icon
++ native `<span>` props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon (SVG). |
+| `className` | `string` | — | Extra class. |
+
+## 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`.
+
+### Segment look (`pressed`, icon-only)
+| 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 |
+
+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.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| 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`).
+
+## 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
+- `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.
+
+## 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 |
 
 ```tsx
 import { ButtonGroup } from "prime-ui-kit";
 
-export function Example() {
+export function HistoryGroup() {
   return (
-    <ButtonGroup.Root aria-label="Options">
-      <ButtonGroup.Item type="button">One</ButtonGroup.Item>
-      <ButtonGroup.Item type="button">Two</ButtonGroup.Item>
+    <ButtonGroup.Root aria-label="История">
+      <ButtonGroup.Item>Отменить</ButtonGroup.Item>
+      <ButtonGroup.Item>Повторить</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]
-```
+## 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
+- [Button](../button/COMPONENT.md)
+- [SegmentedControl](../segmented-control/COMPONENT.md)
+- [Tabs](../tabs/COMPONENT.md)

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

@@ -0,0 +1,99 @@
+/** Editor toolbar: history, independent format toggles, one-of-three alignment and a primary Button of the same size. Use for formatting toolbars; icon-only segments need `aria-label`. */
+import {
+  AlignCenter,
+  AlignLeft,
+  AlignRight,
+  Bold,
+  Italic,
+  Redo2,
+  Underline,
+  Undo2,
+} from "lucide-react";
+import { Button, ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Align = "left" | "center" | "right";
+
+export default function ButtonGroupCompositionExample() {
+  const [marks, setMarks] = React.useState({ bold: true, italic: false, underline: false });
+  const [align, setAlign] = React.useState<Align>("left");
+  const toggle = (mark: keyof typeof marks) => setMarks((m) => ({ ...m, [mark]: !m[mark] }));
+
+  return (
+    <div role="toolbar" aria-label="Форматирование" className={styles.toolbar}>
+      <ButtonGroup.Root aria-label="История">
+        <ButtonGroup.Item aria-label="Отменить">
+          <ButtonGroup.Icon>
+            <Undo2 />
+          </ButtonGroup.Icon>
+        </ButtonGroup.Item>
+        <ButtonGroup.Item aria-label="Повторить" disabled>
+          <ButtonGroup.Icon>
+            <Redo2 />
+          </ButtonGroup.Icon>
+        </ButtonGroup.Item>
+      </ButtonGroup.Root>
+
+      <ButtonGroup.Root aria-label="Начертание">
+        <ButtonGroup.Item aria-label="Жирный" pressed={marks.bold} onClick={() => toggle("bold")}>
+          <ButtonGroup.Icon>
+            <Bold />
+          </ButtonGroup.Icon>
+        </ButtonGroup.Item>
+        <ButtonGroup.Item
+          aria-label="Курсив"
+          pressed={marks.italic}
+          onClick={() => toggle("italic")}
+        >
+          <ButtonGroup.Icon>
+            <Italic />
+          </ButtonGroup.Icon>
+        </ButtonGroup.Item>
+        <ButtonGroup.Item
+          aria-label="Подчёркнутый"
+          pressed={marks.underline}
+          onClick={() => toggle("underline")}
+        >
+          <ButtonGroup.Icon>
+            <Underline />
+          </ButtonGroup.Icon>
+        </ButtonGroup.Item>
+      </ButtonGroup.Root>
+
+      <ButtonGroup.Root aria-label="Выравнивание">
+        <ButtonGroup.Item
+          aria-label="По левому краю"
+          pressed={align === "left"}
+          onClick={() => setAlign("left")}
+        >
+          <ButtonGroup.Icon>
+            <AlignLeft />
+          </ButtonGroup.Icon>
+        </ButtonGroup.Item>
+        <ButtonGroup.Item
+          aria-label="По центру"
+          pressed={align === "center"}
+          onClick={() => setAlign("center")}
+        >
+          <ButtonGroup.Icon>
+            <AlignCenter />
+          </ButtonGroup.Icon>
+        </ButtonGroup.Item>
+        <ButtonGroup.Item
+          aria-label="По правому краю"
+          pressed={align === "right"}
+          onClick={() => setAlign("right")}
+        >
+          <ButtonGroup.Icon>
+            <AlignRight />
+          </ButtonGroup.Icon>
+        </ButtonGroup.Item>
+      </ButtonGroup.Root>
+
+      <span className={styles.spacer} aria-hidden />
+      <Button.Root>Сохранить</Button.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,29 @@
+/** 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. */
+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,43 @@
+/* Layout for the ButtonGroup examples: 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 {
+  display: grid;
+  gap: var(--prime-space-5);
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+}

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

@@ -1,21 +1,22 @@
+/** `fullWidth` stretches the group to its column; horizontal segments share the width equally. Use for plan or mode pickers in narrow forms and cards. */
 import { ButtonGroup } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+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.Item>
+    <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>
   );

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

@@ -0,0 +1,20 @@
+/** 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. */
+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()}>
+      <Input.Root label="Поиск по заказам">
+        <Input.Wrapper>
+          <Input.Field name="q" 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>
+  );
+}