prime-ui-kit 0.7.13 → 0.9.1

package/src/components/button/COMPONENT.md

@@ -1,106 +1,162 @@
 # Button
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** actions
+**Kind:** primitive
 
-## 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        <button> (or the single child with asChild); variant, tone, size; size tier for nested icons
+├─ (Spinner)       rendered by Root while loading, aria-hidden
+└─ Button.Icon     decorative icon wrapper (aria-hidden), sized to the tier
+```
 
 ## API
 
-### Button.Root
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-| 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. |
+### Button.Root
+`ref` → `HTMLButtonElement`. The `<button>`, or the single child with `asChild`; sets variant, tone and size and passes the tier to nested icons.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"solid" \| "soft" \| "outline" \| "ghost"` | `"solid"` | Visual treatment. |
+| `tone` | `"accent" \| "neutral" \| "danger" \| "inherit"` | `"accent"` | Meaning of the action; `danger` for destructive actions. `inherit` takes the host's text color for an action on a colored host (a solid Banner); it needs `variant` `ghost`, `soft` or `outline`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier: height 28 · 32 · 36 · 40 · 48, padding, text, icon, radius. Without it the button takes the tier of its host (LoginForm, Popover, a field, a panel with a size), else `m`. |
+| `fullWidth` | `boolean` | — | Stretches to the container width. |
+| `loading` | `boolean` | `false` | Shows a `Spinner` in place of the leading icon or over the label, sets `aria-busy`, blocks clicks; width does not change. With `asChild` no spinner is added — the child owns its content. |
+| `asChild` | `boolean` | `false` | Merges Button props and styles onto the single child element instead of rendering `<button>`. `disabled`/`loading` become `aria-disabled`. |
+| `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; give it `aria-label`. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size">` | — | `onClick`, `className`, `aria-*`, `data-*` and the other button attributes. |
 
 ### Button.Icon
-
-| 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"`. |
-
-### Button.Spinner
-
-| 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. |
+`ref` → `HTMLSpanElement`. Decorative icon wrapper (`aria-hidden`) sized to the button tier.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="action.copy" />`; `Icon` without `size` takes the button tier. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+## 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 | |
+| `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 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 | |
+| `ghost` + `inherit` | transparent, the host's text color, a `currentColor` wash on hover / press | close or icon action on a colored host (solid Banner, accent strip) | |
+| `soft` + `inherit` | `currentColor` wash fill, the host's text color | a labelled action on a colored host | |
+| `outline` + `inherit` | 1px inset line in a `currentColor` wash, the host's text color | an action with an edge on a colored host | |
+
+`tone="inherit"` has no `solid` (the type requires `ghost`, `soft` or `outline`); its focus ring and disabled look also derive from the host's text color, so it reads on any host fill in both themes. Never recolor a Button from its host with a CSS override — use `inherit`.
+
+`outline` is the only variant with a visible line. With `aria-current="page"` (usually via `asChild` on a router link), `ghost`/`soft` show the `fill-subtle-active` selected look; soft accent keeps its own accent look, so a current item can be marked with accent explicitly (Pagination).
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28px high, 12/16 text, padX 8, icon 14 | dense tables and chip 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 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.
+
+### 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). Avoid two `solid accent` buttons side by side and `tone="danger"` for non-destructive actions.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| hover / active | pointer | hover fill per variant; active `scale(var(--prime-motion-press-scale))` |
+| focus-visible | keyboard | outer focus ring with `--prime-focus-offset`; `tone="inherit"` draws it in `currentColor` |
+| disabled | `disabled` | native `disabled`, `data-disabled="true"`, `fill-muted` + `text-disabled`, `cursor: not-allowed`; ghost stays transparent |
+| loading | `loading` (native `<button>`) | `data-loading="true"`, native `disabled`, `aria-busy="true"`, colors kept (busy, not unavailable), no hover or press; a `Spinner` (`aria-hidden`) 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`, no automatic spinner |
+
+Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-full-width`, `data-icon-only`, `data-leading-icon`, `data-trailing-icon`.
+
+## 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%`, the label does not wrap (`white-space: nowrap`).
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` · `Space` | Presses the button (native `<button>`). |
+| `Tab` | Moves focus; a disabled button is skipped, with `asChild` it stays focusable with `aria-disabled`. |
+
+### ARIA
+- Native `<button>`, `type="button"` by default, so it never submits a form by accident.
+- Icon-only buttons need `aria-label`; `Button.Icon` is `aria-hidden`.
+- `loading` sets `aria-busy="true"` and blocks the press.
+- With `asChild` the disabled state is `aria-disabled="true"` without a native `disabled`.
+
+### 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) | The primary action with a secondary one next to it — `variant`, `tone`. |
+| [variants.tsx](examples/variants.tsx) | Every treatment on every tone — `variant`, `tone`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier, 28 to 48 px high — `size`. |
+| [states.tsx](examples/states.tsx) | Disabled and loading next to the default; the spinner keeps the width — `disabled`, `loading`. |
+| [with-icon.tsx](examples/with-icon.tsx) | An icon before or after the label, and a square icon-only button — `Button.Icon`, `aria-label`. |
+| [on-colored-host.tsx](examples/on-colored-host.tsx) | Actions on a colored strip take its text color: a ghost icon close and a soft action — `tone="inherit"`. |
+| [as-child.tsx](examples/as-child.tsx) | The button look on a real link; a disabled link blocks navigation — `asChild`, `disabled`. |
+| [in-form.tsx](examples/in-form.tsx) | A full-width submit button that shows the request in progress — `type`, `loading`, `fullWidth`. |
+
+## 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"`.
+- Putting a `<Spinner />` inside a loading button → just set `loading`; the button places it.
+- `<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.
 
 ## Related
-
-- [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.
+- **Built from:** [Spinner](../spinner/COMPONENT.md)
+- **See also:** [ButtonGroup](../button-group/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md)

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

@@ -0,0 +1,15 @@
+/** The button look on a real link; a disabled link blocks navigation — `asChild`, `disabled`. */
+import { Button } from "prime-ui-kit";
+
+export default function ButtonAsChildExample() {
+  return (
+    <>
+      <Button.Root asChild>
+        <a href="#invoices">Открыть счета</a>
+      </Button.Root>
+      <Button.Root variant="outline" tone="neutral" asChild disabled>
+        <a href="#export">Экспорт недоступен</a>
+      </Button.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,32 @@
+/* Layout of the Button scenarios: semantic tokens only. */
+
+/* Field → actions: group gap (foundation §1). */
+.form {
+  display: grid;
+  gap: var(--prime-space-5);
+}
+
+/* A colored strip: buttons with tone="inherit" take its text color. */
+.accentHost,
+.inverseHost {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-2);
+  padding: var(--prime-space-2) var(--prime-space-2) var(--prime-space-2) var(--prime-space-4);
+  border-radius: var(--prime-radius-l);
+}
+
+.accentHost {
+  background: var(--prime-color-accent-default);
+  color: var(--prime-color-accent-fg);
+}
+
+.inverseHost {
+  background: var(--prime-color-bg-inverse);
+  color: var(--prime-color-text-inverse);
+}
+
+.hostText {
+  flex: 1;
+  min-width: 0;
+}

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

@@ -0,0 +1,33 @@
+/** A full-width submit button that shows the request in progress — `type`, `loading`, `fullWidth`. */
+import { Button, Input } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function ButtonInFormExample() {
+  const [sending, setSending] = React.useState(false);
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSending(true);
+    window.setTimeout(() => setSending(false), 1500);
+  };
+
+  return (
+    <form className={styles.form} onSubmit={submit}>
+      <Input.Root label="Рабочая почта" required>
+        <Input.Wrapper>
+          <Input.Field
+            type="email"
+            name="email"
+            placeholder="name@company.ru"
+            autoComplete="email"
+          />
+        </Input.Wrapper>
+      </Input.Root>
+      <Button.Root type="submit" loading={sending} fullWidth>
+        Получить ссылку для входа
+      </Button.Root>
+    </form>
+  );
+}

package/src/components/button/examples/on-colored-host.tsx

@@ -0,0 +1,29 @@
+/** Actions on a colored strip take its text color: a ghost icon close and a soft action — `tone="inherit"`. */
+import { Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const HOSTS = [
+  { className: styles.accentHost, text: "Доступна новая версия редактора" },
+  { className: styles.inverseHost, text: "Режим только для чтения" },
+];
+
+export default function ButtonOnColoredHostExample() {
+  return (
+    <>
+      {HOSTS.map(({ className, text }) => (
+        <div key={text} className={className}>
+          <span className={styles.hostText}>{text}</span>
+          <Button.Root variant="soft" tone="inherit" size="s">
+            Обновить
+          </Button.Root>
+          <Button.Root variant="ghost" tone="inherit" size="s" aria-label="Закрыть">
+            <Button.Icon>
+              <Icon name="action.close" />
+            </Button.Icon>
+          </Button.Root>
+        </div>
+      ))}
+    </>
+  );
+}

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

@@ -0,0 +1,13 @@
+/** The primary action with a secondary one next to it — `variant`, `tone`. */
+import { Button } from "prime-ui-kit";
+
+export default function ButtonOverviewExample() {
+  return (
+    <>
+      <Button.Root variant="soft" tone="neutral">
+        Отмена
+      </Button.Root>
+      <Button.Root>Сохранить</Button.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,19 @@
+/** Every size tier, 28 to 48 px high — `size`. */
+import { Button, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ButtonSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Button.Root size={size}>Сохранить</Button.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,38 @@
+/** Disabled and loading next to the default; the spinner keeps the width — `disabled`, `loading`. */
+import { Button, Icon, Typography } from "prime-ui-kit";
+
+export default function ButtonStatesExample() {
+  return (
+    <div>
+      <div>
+        <Button.Root>Сохранить</Button.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          default
+        </Typography>
+      </div>
+      <div>
+        <Button.Root disabled>Сохранить</Button.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
+      </div>
+      <div>
+        <Button.Root loading>Сохранить</Button.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          loading
+        </Typography>
+      </div>
+      <div>
+        <Button.Root variant="outline" tone="neutral" loading>
+          <Button.Icon>
+            <Icon name="action.upload" />
+          </Button.Icon>
+          Загрузить
+        </Button.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          loading · Button.Icon
+        </Typography>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,31 @@
+/** Every treatment on every tone — `variant`, `tone`. */
+import { Button, Typography } from "prime-ui-kit";
+
+const TONES = [
+  { tone: "accent", label: "Сохранить" },
+  { tone: "neutral", label: "Отмена" },
+  { tone: "danger", label: "Удалить" },
+] as const;
+
+const VARIANTS = ["solid", "soft", "outline", "ghost"] as const;
+
+export default function ButtonVariantsExample() {
+  return (
+    <>
+      {TONES.map(({ tone, label }) => (
+        <div key={tone}>
+          {VARIANTS.map((variant) => (
+            <div key={variant}>
+              <Button.Root variant={variant} tone={tone}>
+                {label}
+              </Button.Root>
+              <Typography as="span" variant="caption" tone="muted">
+                {variant} · {tone}
+              </Typography>
+            </div>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}

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

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