prime-ui-kit 0.7.11 → 0.9.0

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

@@ -1,25 +1,27 @@
-import { Breadcrumb, type BreadcrumbSize } from "prime-ui-kit";
+/** All five size tiers; text and chevron follow the control tier. Use to match the trail to the page header or the panel it sits in. */
+import { Breadcrumb, type ControlSize, Typography } from "prime-ui-kit";
 
-function BreadcrumbSizeRow({ size }: { size: BreadcrumbSize }) {
-  return (
-    <Breadcrumb.Root size={size}>
-      <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
-      <Breadcrumb.Separator />
-      <Breadcrumb.Item href="/catalog">Catalog</Breadcrumb.Item>
-      <Breadcrumb.Separator />
-      <Breadcrumb.Item current>Page</Breadcrumb.Item>
-    </Breadcrumb.Root>
-  );
-}
+import styles from "./examples.module.css";
+
+const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
 
-/** Four stacked trails: `size` `s` → `xl` on `Breadcrumb.Root` (matches playground `snippets/breadcrumb/sizes.tsx`). */
 export default function BreadcrumbSizesExample() {
   return (
-    <>
-      <BreadcrumbSizeRow size="s" />
-      <BreadcrumbSizeRow size="m" />
-      <BreadcrumbSizeRow size="l" />
-      <BreadcrumbSizeRow size="xl" />
-    </>
+    <div className={styles.stack}>
+      {sizes.map((size) => (
+        <div key={size} className={styles.sizeRow}>
+          <Typography.Root as="span" variant="code" tone="muted" className={styles.caption}>
+            {size}
+          </Typography.Root>
+          <Breadcrumb.Root size={size} className={styles.trail}>
+            <Breadcrumb.Item href="#">Главная</Breadcrumb.Item>
+            <Breadcrumb.Separator />
+            <Breadcrumb.Item href="#">Заказы</Breadcrumb.Item>
+            <Breadcrumb.Separator />
+            <Breadcrumb.Item current>№ 48 213</Breadcrumb.Item>
+          </Breadcrumb.Root>
+        </div>
+      ))}
+    </div>
   );
 }

package/src/components/button/COMPONENT.md

@@ -1,106 +1,163 @@
 # Button
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** actions
 
-## About
+> A button for explicit actions, with variants, tones, sizes and a built-in loading state.
 
-Compound control for actions: a root that renders a native `<button>` (or merges props into one child with `asChild`), plus optional icon and loading indicator parts that share size via context.
+## When to use
+- Primary, secondary and destructive actions in forms, toolbars, dialogs, cards and empty states.
+- Async actions: `loading` shows a spinner, blocks clicks and keeps the width.
+- Compact toolbars: icon-only buttons (only `Button.Icon` inside) are square.
+- Action-styled navigation: `asChild` with an `<a>` or a router link.
 
-- **Use** for primary, secondary, or destructive actions in forms, toolbars, dialogs, and empty states; submit/reset in forms; triggers that must look like a button.
-- **Use** for async actions where you set `loading` on `Button.Root` and optionally render `Button.Spinner` next to the label.
-- **Use** for full-width actions in narrow layouts via `fullWidth`.
-- **Do not use** for navigation that should be a plain link semantically (consider [Link button](../link-button/COMPONENT.md) or `asChild` with a link).
-- **Do not use** for binary on/off or multi-option selection (use [Switch](../switch/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Segmented control](../segmented-control/COMPONENT.md), etc.).
-- **Do not use** when several related buttons need shared chrome and spacing (see [Button group](../button-group/COMPONENT.md)).
-
-## Composition
-
-- **`Button.Root`** — required wrapper. Provides size to descendants via `ControlSizeProvider` (including in `asChild` mode). Place all other parts inside it.
-- **`Button.Icon`** — optional; wraps the icon in a `span` with `aria-hidden="true"`. Use for decorative icons next to text.
-- **`Button.Spinner`** — optional; renders nothing unless the nearest `Button.Root` has `loading={true}`. Place it inside `Button.Root` with visible text or a clear `aria-label`; order relative to the label is up to you.
-
-### Minimal example
+## When not to use
+- Inline text link or quiet navigation in text → use [LinkButton](../link-button/COMPONENT.md).
+- Several joined buttons or a toggle row → use [ButtonGroup](../button-group/COMPONENT.md).
+- Choosing one value from a few options → use [SegmentedControl](../segmented-control/COMPONENT.md).
+- On/off setting → use [Switch](../switch/COMPONENT.md) or [Checkbox](../checkbox/COMPONENT.md).
+- A button that opens a list of actions → use [Dropdown](../dropdown/COMPONENT.md) with a Button as its trigger.
 
+## Import
 ```tsx
 import { Button } from "prime-ui-kit";
-
-export function Example() {
-  return <Button.Root>Save</Button.Root>;
-}
 ```
 
-### Canonical composition (reference)
-
-For **icon + label**, **several `variant` / `mode` pairs**, and **`loading` with `Button.Spinner`**, open **`examples/canonical-composition.tsx`** next to this file. Imports use **`"prime-ui-kit"`** so the same snippets work in an app after installing the package.
-
-The playground Button section (`playground/sections/ButtonSection.tsx`) renders snippets from `playground/snippets/button/*.tsx`. The examples **`sizes-ladder`**, **`icon-composition`**, and **`full-width-stack`** mirror the **Размеры**, **Композиция**, and **Full width** demos there (same structure and labels; app-ready imports).
-
-### Example files in `examples/`
-
-| File | Scenario |
-|------|----------|
-| `sizes-ladder.tsx` | `size` `s`–`xl` at `variant="primary"` `mode="filled"` (playground: `snippets/button/sizes.tsx`) |
-| `icon-composition.tsx` | `Button.Icon` left/right and icon-only with `aria-label`; primary filled + neutral stroke rows (`snippets/button/composition.tsx`) |
-| `full-width-stack.tsx` | `fullWidth` primary filled and neutral stroke at `m` (`snippets/button/full-width.tsx`) |
-| `canonical-composition.tsx` | Icon + text, variant/mode mix, loading + spinner |
-| `form-submit-row.tsx` | English form footer: cancel vs submit, async loading |
-| `destructive-confirm.tsx` | English confirm dialog: `error` + `Modal` |
-| `toolbar.tsx` | English editor-style toolbar: ghost row + primary action |
-| `marketing-cta.tsx` | English CTA column: `fancy` + `xl` / `l` with `fullWidth` (marketing emphasis; see also `full-width-stack.tsx`) |
-
-### Note for LLMs
-
-- **Imports:** `Button` (and `Icon`, `Modal` where needed) from **`"prime-ui-kit"`** in these examples; paths are relative to `src/components/button/examples/`.
-- **`loading`** is **controlled** on `Button.Root` only; there is no internal async state. When `loading` or `disabled` is true, the native `<button>` is disabled.
-- **`Button.Spinner`** only appears when `loading` is true; keep button text or `aria-label` meaningful while loading (`aria-busy` is set on the root).
-- **Forms:** default `type` is **`"button"`**; use **`"submit"`** / **`"reset"`** explicitly when the control lives in a `<form>`.
-- **Destructive actions:** use **`variant="error"`**; pair **filled** confirm with **stroke/lighter** or neutral cancel for hierarchy.
-- **`asChild`:** exactly one element child; `disabled`/`loading` map to `aria-disabled` and blocked clicks, not native `disabled` on non-button hosts.
-
-## Rules
-
-- `loading` is controlled only by the `loading` prop on `Button.Root`; there is no internal async state. When `loading` or `disabled` is true, the native `<button>` is disabled and `onClick` does not run.
-- With `asChild`, pass exactly one React element child. `type` is not forwarded; `disabled`/`loading` become `aria-disabled`, blocked `onClick`, and styles—native `disabled` is not set on non-button elements.
-- The `asChild` child must accept `className`, `aria-*`, `data-*`, and event props merged from the root.
-- For icon-only buttons, set a clear `aria-label` or `aria-labelledby` on `Button.Root`.
-- `variant` sets color role (`primary`, `neutral`, `error`); `mode` sets visual weight (`filled`, `stroke`, `lighter`, `ghost`, `fancy`).
+## Anatomy
+- `Button.Root` — the `<button>` (or the single child with `asChild`); sets variant, tone, size and passes the size tier to nested icons.
+- `Button.Icon` — decorative icon wrapper (`aria-hidden`), sized to the tier.
+- `Button.Spinner` — optional explicit spinner position; renders only while `Root` is `loading`.
 
 ## API
 
 ### Button.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| variant | `"primary" \| "neutral" \| "error"` | `"primary"` | No | Color semantics. |
-| mode | `"filled" \| "stroke" \| "lighter" \| "ghost" \| "fancy"` | `"filled"` | No | Visual weight / style. |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Height, radius, text, and icon scale. |
-| fullWidth | `boolean` | — | No | Full-width layout (`data-full-width`). |
-| loading | `boolean` | `false` | No | Disables interaction, sets `aria-busy`, exposes loading to `Button.Spinner`. |
-| asChild | `boolean` | `false` | No | Merge props into the single child instead of rendering `<button>`. |
-| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Native button type; not forwarded when `asChild` is true. |
-| disabled | `boolean` | — | No | Inactive state; combined with `loading` for effective disabled behavior. |
-| className | `string` | — | No | Additional class on the root. |
-| children | `React.ReactNode` | — | No | Label, `Button.Icon`, `Button.Spinner`, etc. |
-| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "size">` | — | No | Other button attributes (`onClick`, `aria-*`, `data-*`, etc.); `size` is the component size prop, not the HTML attribute. |
+`forwardRef` → `HTMLButtonElement`. + native `<button>` props (except `size`).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"solid" \| "soft" \| "outline" \| "ghost"` | `"solid"` | Visual treatment. |
+| `tone` | `"accent" \| "neutral" \| "danger"` | `"accent"` | Meaning of the action; `danger` for destructive actions. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier: height, padding, text, icon, radius. |
+| `fullWidth` | `boolean` | — | Stretches to the container width (`display: flex; width: 100%`). |
+| `loading` | `boolean` | `false` | Shows the spinner, sets `aria-busy`, blocks clicks; width does not change. With `asChild` no spinner is added automatically — place `Button.Spinner` yourself. |
+| `asChild` | `boolean` | `false` | Merges Button props and styles onto the single child element instead of rendering `<button>`. `disabled`/`loading` become `aria-disabled`; no automatic loading spinner. |
+| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type; not forwarded with `asChild`. |
+| `disabled` | `boolean` | — | Disabled state; `loading` also disables. |
+| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → square icon-only button. |
 
 ### Button.Icon
++ native `<span>` props.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | Yes | Icon node. |
-| className | `string` | — | No | Additional class on the `span`. |
-| …rest | `Omit<React.HTMLAttributes<HTMLSpanElement>, "children">` | — | No | Other `span` attributes; root sets `aria-hidden="true"`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="action.copy" />`. `Icon` without `size` takes the button tier. |
+| `className` | `string` | — | Extra class on the span. |
 
 ### Button.Spinner
++ native `<span>` props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Extra class. Renders nothing unless `Button.Root` has `loading`. Not needed in most cases: `loading` adds a spinner by itself. |
+
+## Variants
+
+### variant × tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `solid` + `accent` | accent fill, accent-fg text, hover `accent-hover` | the one primary action of an area (Save, Publish) | yes |
+| `solid` + `neutral` | `fill-muted` fill, primary text | a neutral filled action next to fields (Cancel on canvas) | |
+| `solid` + `danger` | danger fill, danger-fg text | confirming a destructive action in a dialog | |
+| `soft` + `accent` | `accent-soft` fill, accent text | secondary but highlighted action | |
+| `soft` + `neutral` | translucent `fill-subtle` wash, primary text | secondary actions (Cancel, Filters) | |
+| `soft` + `danger` | `danger-soft` fill, danger text | secondary destructive action | |
+| `outline` + `accent` | transparent, 1px `border-default` inset line, accent text | rare; accent action that must look lighter than solid | |
+| `outline` + `neutral` | transparent, 1px inset line, primary text | secondary action that needs an edge (Draft, Back) | |
+| `outline` + `danger` | 1px inset line, danger text, `danger-soft` on hover | destructive trigger that opens a confirm | |
+| `ghost` + `accent` | transparent, accent text, `fill-subtle` on hover | tertiary accent action in text-heavy areas | |
+| `ghost` + `neutral` | transparent, secondary text → primary on hover | toolbar buttons, icon-only buttons | |
+| `ghost` + `danger` | transparent, danger text, `danger-soft` on hover | destructive action set apart in a footer (Delete project) | |
+
+`outline` is the only variant with a visible line. With `asChild` and `aria-current="page"`, `ghost`/`soft` show the `fill-subtle-active` selected look.
+
+**Combinations**
+- Recommended: one `solid accent` per area; others `soft`/`outline`/`ghost` with `tone="neutral"`; destructive = `tone="danger"`, `ghost`/`outline` as a trigger, `solid` in the confirm.
+- Allowed but rare: `outline accent`, `ghost accent`.
+- Avoid: two `solid accent` buttons side by side; `tone="danger"` for non-destructive actions; icon-only `solid accent` in toolbars.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28px high, 12/16 text, padX 8, icon 14 | dense tables and chips rows | |
+| `s` | 32px, 13/20, padX 12, icon 16 | compact toolbars, filters | |
+| `m` | 36px, 14/20, padX 16, icon 16 | default UI | yes |
+| `l` | 40px, 16/24, padX 20, icon 20 | prominent forms | |
+| `xl` | 48px, 16/24, padX 24, icon 20 | hero / marketing CTA, mobile footers | |
+
+A Button lines up exactly with Input, Select, Datepicker trigger, SegmentedControl and Tabs of the same `size`. The icon side gets optical padding `padX − 4px` (never below 8px); icon→label gap is the tier gap.
+
+### Visual flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fullWidth` | button fills the row | narrow forms, cards, mobile footers | off |
+| icon-only (children are only `Button.Icon`) | square, width = height | toolbars; needs `aria-label` | — |
+
+**Hierarchy:** one primary (`solid accent`) per area, the rest neutral `soft`/`outline`/`ghost`; a destructive action is `tone="danger"` and sits apart (start of the footer).
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| hover / active | pointer | hover fill per variant; active `scale(0.98)` |
+| focus-visible | keyboard | outer focus ring with `--prime-focus-offset` |
+| disabled | `disabled` | native `disabled`, `data-disabled="true"`, `fill-muted` + `text-disabled`, `cursor: not-allowed`; ghost stays transparent |
+| loading | `loading` (native `<button>`) | `data-loading="true"`, `data-disabled="true"`, `aria-busy="true"`; an automatic spinner replaces the leading (or only) icon, otherwise it is centered over the hidden label (`data-loading-overlay="true"`) |
+| asChild disabled / loading | `asChild` + `disabled`/`loading` | `aria-disabled="true"`, `pointer-events: none`, click `preventDefault`; no native `disabled`. With `loading` also `aria-busy="true"` and `data-loading="true"`, but no automatic spinner and no `data-loading-overlay` — add `<Button.Spinner />` inside the child to show one |
+
+Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-full-width` (when `fullWidth` is set), `data-icon-only`, `data-leading-icon`, `data-trailing-icon`. `loading` is controlled by the parent (see `controlled.tsx`).
+
+## Layout & spacing
+- Buttons in a row: `gap: var(--prime-space-2)`–`var(--prime-space-3)`; toolbar icon buttons `var(--prime-space-1)`.
+- Form footer: actions right-aligned, primary last; below 480px stack full width (`fullWidth` or a column flex).
+- `max-width: 100%`, label does not wrap (`white-space: nowrap`).
+
+## Accessibility
+- Native `<button>`, `type="button"` by default.
+- Icon-only buttons need `aria-label`; `Button.Icon` is `aria-hidden`.
+- `loading` sets `aria-busy`; disabled buttons are not focusable (native `disabled`); with `asChild` they stay focusable with `aria-disabled`.
+- Keyboard: Enter/Space (native). No `labels` keys.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | Five size tiers | matching the tier of neighbouring controls |
+| [icon-only.tsx](examples/icon-only.tsx) | Square icon-only toolbar at every size | compact toolbars |
+| [variants-tones.tsx](examples/variants-tones.tsx) | Every variant × tone | choosing treatment and meaning |
+| [states.tsx](examples/states.tsx) | Default, disabled, loading (overlay, with icon, icon-only) | showing state feedback |
+| [controlled.tsx](examples/controlled.tsx) | `loading` from parent state on click | async actions |
+| [with-icon.tsx](examples/with-icon.tsx) | Leading and trailing `Button.Icon` | icon clarifies the action |
+| [composition.tsx](examples/composition.tsx) | Editor toolbar + form footer hierarchy | laying out several actions |
+| [surfaces.tsx](examples/surfaces.tsx) | Neutral variants on canvas, card, raised, accent | buttons on non-default backgrounds |
+| [full-width.tsx](examples/full-width.tsx) | `fullWidth` stack | narrow forms, mobile footers |
+| [as-child.tsx](examples/as-child.tsx) | Button look on `<a>`, disabled links | navigation styled as an action |
+| [in-form.tsx](examples/in-form.tsx) | `type="submit"` / `type="reset"` | native forms |
+
+```tsx
+import { Button } from "prime-ui-kit";
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Additional class on the indicator. |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes; not rendered when root `loading` is false. |
+export function SaveButton() {
+  return <Button.Root onClick={() => {}}>Сохранить</Button.Root>;
+}
+```
 
-## Related
+## Mistakes
+- `<Button.Root><Icon name="action.copy" /></Button.Root>` → wrap in `Button.Icon` so the button becomes square and the icon is sized.
+- Icon-only button without `aria-label` → add `aria-label="Копировать"`.
+- `tone="error"` / `variant="primary"` → `tone="danger"`, `variant="solid"`.
+- Adding `<Button.Spinner />` for every loading button → just set `loading`.
+- `<a>` inside `<Button.Root>` → use `asChild` so there is one interactive element.
+- Submit button without `type="submit"` → the default is `"button"` and will not submit.
 
-- [Link button](../link-button/COMPONENT.md) — link-styled control when the action is navigation.
-- [Button group](../button-group/COMPONENT.md) — grouped actions with shared sizing and dividers.
-- [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md) — common hosts for triggers and dialog footers.
-- [Input](../input/COMPONENT.md), [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — form fields alongside submit/reset buttons.
+## Related
+- [ButtonGroup](../button-group/COMPONENT.md)
+- [LinkButton](../link-button/COMPONENT.md)
+- [Dropdown](../dropdown/COMPONENT.md)
+- [Input](../input/COMPONENT.md)

package/src/components/button/examples/as-child.tsx

@@ -0,0 +1,39 @@
+/** `asChild` renders the button look on a real `<a>`; `disabled` becomes `aria-disabled` and blocks navigation. Use when an action-styled control navigates. */
+import { Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ButtonAsChildExample() {
+  return (
+    <>
+      <div className={styles.row}>
+        <Button.Root asChild>
+          <a href="/dashboard">Перейти</a>
+        </Button.Root>
+
+        <Button.Root variant="outline" tone="neutral" asChild>
+          <a href="/next-step">
+            Далее
+            <Button.Icon>
+              <Icon name="nav.chevronRight" tone="secondary" />
+            </Button.Icon>
+          </a>
+        </Button.Root>
+
+        <Button.Root variant="ghost" tone="neutral" asChild>
+          <a href="/settings">Настройки</a>
+        </Button.Root>
+      </div>
+
+      <div className={styles.row}>
+        <Button.Root asChild disabled>
+          <a href="/forbidden">Нет доступа</a>
+        </Button.Root>
+
+        <Button.Root variant="outline" tone="neutral" asChild disabled>
+          <a href="/disabled">Отключено</a>
+        </Button.Root>
+      </div>
+    </>
+  );
+}

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

@@ -0,0 +1,46 @@
+/** Editor toolbar and form footer: secondary actions ghost/outline/soft, one solid accent primary, the destructive action set apart. Use as the hierarchy template for a screen area. */
+import { Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ButtonCompositionExample() {
+  return (
+    <div className={`${styles.stack} ${styles.composition}`}>
+      <div role="toolbar" aria-label="Действия с документом" className={styles.editorBar}>
+        <Button.Root variant="ghost" tone="neutral" aria-label="Копировать ссылку">
+          <Button.Icon>
+            <Icon name="action.copy" />
+          </Button.Icon>
+        </Button.Root>
+        <Button.Root variant="ghost" tone="neutral" aria-label="Доступ">
+          <Button.Icon>
+            <Icon name="status.locked" />
+          </Button.Icon>
+        </Button.Root>
+        <Button.Root variant="ghost" tone="neutral">
+          Предпросмотр
+        </Button.Root>
+        <span className={styles.spacer} aria-hidden />
+        <Button.Root variant="outline" tone="neutral">
+          Черновик
+        </Button.Root>
+        <Button.Root>
+          <Button.Icon>
+            <Icon name="action.upload" />
+          </Button.Icon>
+          Опубликовать
+        </Button.Root>
+      </div>
+      <div className={styles.footer}>
+        <Button.Root variant="ghost" tone="danger">
+          Удалить проект
+        </Button.Root>
+        <span className={styles.spacer} aria-hidden />
+        <Button.Root variant="soft" tone="neutral">
+          Отмена
+        </Button.Root>
+        <Button.Root type="submit">Сохранить изменения</Button.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,18 @@
+/** `loading` driven by parent state while a request runs. Use for async actions: the spinner appears by itself and clicks are blocked. */
+import { Button } from "prime-ui-kit";
+import { useState } from "react";
+
+export default function ButtonControlledExample() {
+  const [loading, setLoading] = useState(false);
+
+  function handleClick() {
+    setLoading(true);
+    window.setTimeout(() => setLoading(false), 1600);
+  }
+
+  return (
+    <Button.Root loading={loading} onClick={handleClick}>
+      Отправить отчёт
+    </Button.Root>
+  );
+}

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

@@ -0,0 +1,90 @@
+/* Layout for the Button examples: semantic tokens only. */
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: var(--prime-space-3);
+}
+
+.stack {
+  display: grid;
+  gap: var(--prime-space-4);
+  width: 100%;
+  max-width: 100%;
+  min-width: 0;
+}
+
+.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;
+  align-items: center;
+  gap: var(--prime-space-1);
+}
+
+.matrixScroll {
+  width: 100%;
+  overflow-x: auto;
+}
+
+/* Centered by auto margins, not justify-content: a wider matrix then scrolls instead of clipping its start. */
+.matrix {
+  display: grid;
+  grid-template-columns: max-content repeat(4, max-content);
+  align-items: center;
+  width: max-content;
+  margin-inline: auto;
+  gap: var(--prime-space-3) var(--prime-space-4);
+}
+
+.editorBar {
+  box-sizing: border-box;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-2);
+  width: 100%;
+}
+
+.spacer {
+  flex: 1 1 auto;
+}
+
+.footer {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: var(--prime-space-3);
+  width: 100%;
+}
+
+/* Narrow host: the form footer stacks full width, primary last (foundation §9). */
+.composition {
+  container-type: inline-size;
+}
+
+@container (max-width: 479.98px) {
+  .footer {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .footer > .spacer {
+    display: none;
+  }
+}

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

@@ -0,0 +1,15 @@
+/** `fullWidth` stretches buttons to the column width. Use in narrow forms, cards and mobile footers. */
+import { Button } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ButtonFullWidthExample() {
+  return (
+    <div className={styles.stack}>
+      <Button.Root fullWidth>Продолжить</Button.Root>
+      <Button.Root variant="outline" tone="neutral" fullWidth>
+        Войти другим способом
+      </Button.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,42 @@
+/** Square icon-only buttons in a toolbar at every size. Use for compact toolbars; always give each button an `aria-label`. */
+import { Button, Icon, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const sizes = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ButtonIconOnlyExample() {
+  return (
+    <div className={styles.sizeRow}>
+      {sizes.map((size) => (
+        <div key={size} className={styles.sizeCell}>
+          <div role="toolbar" aria-label={`Действия, размер ${size}`} className={styles.toolbar}>
+            <Button.Root variant="ghost" tone="neutral" size={size} aria-label="Копировать">
+              <Button.Icon>
+                <Icon name="action.copy" />
+              </Button.Icon>
+            </Button.Root>
+            <Button.Root variant="ghost" tone="neutral" size={size} aria-label="Загрузить">
+              <Button.Icon>
+                <Icon name="action.upload" />
+              </Button.Icon>
+            </Button.Root>
+            <Button.Root variant="ghost" tone="neutral" size={size} aria-label="Скрыть">
+              <Button.Icon>
+                <Icon name="field.password.hide" />
+              </Button.Icon>
+            </Button.Root>
+            <Button.Root variant="outline" tone="neutral" size={size} aria-label="Закрыть">
+              <Button.Icon>
+                <Icon name="action.close" />
+              </Button.Icon>
+            </Button.Root>
+          </div>
+          <Typography.Root as="span" variant="caption" tone="muted">
+            {size}
+          </Typography.Root>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,27 @@
+/** Native form with `type="submit"` and `type="reset"` full-width buttons. Use in forms; the default `type="button"` never submits by accident. */
+import { Button, Input } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ButtonInFormExample() {
+  return (
+    <form
+      className={styles.stack}
+      onSubmit={(e) => {
+        e.preventDefault();
+      }}
+    >
+      <Input.Root label="Поиск">
+        <Input.Wrapper>
+          <Input.Field name="query" placeholder="Запрос" />
+        </Input.Wrapper>
+      </Input.Root>
+      <Button.Root type="submit" fullWidth>
+        Найти
+      </Button.Root>
+      <Button.Root variant="outline" tone="neutral" type="reset" fullWidth>
+        Очистить
+      </Button.Root>
+    </form>
+  );
+}

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

@@ -0,0 +1,21 @@
+/** All five size tiers in one row (28 · 32 · 36 · 40 · 48). Use to pick the tier that matches neighbouring fields; default is `m`. */
+import { Button, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const sizes = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ButtonSizesExample() {
+  return (
+    <div className={styles.sizeRow}>
+      {sizes.map((size) => (
+        <div key={size} className={styles.sizeCell}>
+          <Button.Root size={size}>Сохранить</Button.Root>
+          <Typography.Root as="span" variant="caption" tone="muted">
+            {size}
+          </Typography.Root>
+        </div>
+      ))}
+    </div>
+  );
+}