prime-ui-kit 0.9.0 → 0.9.1

package/src/components/button/COMPONENT.md

@@ -1,6 +1,7 @@
 # Button
 
 **Category:** actions
+**Kind:** primitive
 
 > A button for explicit actions, with variants, tones, sizes and a built-in loading state.
 
@@ -23,41 +24,39 @@ import { Button } from "prime-ui-kit";
 ```
 
 ## 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`.
+```
+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
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### Button.Root
-`forwardRef` → `HTMLButtonElement`. + native `<button>` props (except `size`).
+`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"` | `"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. |
+| `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. |
+| `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
-+ native `<span>` props.
-
-| 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.
+`ref` → `HTMLSpanElement`. Decorative icon wrapper (`aria-hidden`) sized to the button tier.
 
 | 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. |
+| `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
 
@@ -65,99 +64,99 @@ import { Button } from "prime-ui-kit";
 | 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` + `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 that must look lighter than solid | |
+| `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 (Delete project) | |
+| `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 | |
 
-`outline` is the only variant with a visible line. With `asChild` and `aria-current="page"`, `ghost`/`soft` show the `fill-subtle-active` selected look.
+`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`.
 
-**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.
+`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 chips rows | |
+| `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 / marketing CTA, mobile footers | |
+| `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.
 
-### Visual flags
+### 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).
+**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(0.98)` |
-| focus-visible | keyboard | outer focus ring with `--prime-focus-offset` |
+| 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"`, `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 |
+| 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` (when `fullWidth` is set), `data-icon-only`, `data-leading-icon`, `data-trailing-icon`. `loading` is controlled by the parent (see `controlled.tsx`).
+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%`, label does not wrap (`white-space: nowrap`).
+- `max-width: 100%`, the label does not wrap (`white-space: nowrap`).
 
 ## Accessibility
-- Native `<button>`, `type="button"` by default.
+
+### 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`; disabled buttons are not focusable (native `disabled`); with `asChild` they stay focusable with `aria-disabled`.
-- Keyboard: Enter/Space (native). No `labels` keys.
+- `loading` sets `aria-busy="true"` and blocks the press.
+- With `asChild` the disabled state is `aria-disabled="true"` without a native `disabled`.
 
-## 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 |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```tsx
-import { Button } from "prime-ui-kit";
+No `labels`.
 
-export function SaveButton() {
-  return <Button.Root onClick={() => {}}>Сохранить</Button.Root>;
-}
-```
+## 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"`.
-- Adding `<Button.Spinner />` for every loading button → just set `loading`.
+- 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
-- [ButtonGroup](../button-group/COMPONENT.md)
-- [LinkButton](../link-button/COMPONENT.md)
-- [Dropdown](../dropdown/COMPONENT.md)
-- [Input](../input/COMPONENT.md)
+- **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

@@ -1,39 +1,15 @@
-/** `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";
+/** 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 (
     <>
-      <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>
+      <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

@@ -1,90 +1,32 @@
-/* Layout for the Button examples: semantic tokens only. */
+/* Layout of the Button scenarios: 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 {
+/* Field → actions: group gap (foundation §1). */
+.form {
   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);
+  gap: var(--prime-space-5);
 }
 
-.editorBar {
-  box-sizing: border-box;
+/* A colored strip: buttons with tone="inherit" take its text color. */
+.accentHost,
+.inverseHost {
   display: flex;
-  flex-wrap: wrap;
   align-items: center;
   gap: var(--prime-space-2);
-  width: 100%;
+  padding: var(--prime-space-2) var(--prime-space-2) var(--prime-space-2) var(--prime-space-4);
+  border-radius: var(--prime-radius-l);
 }
 
-.spacer {
-  flex: 1 1 auto;
+.accentHost {
+  background: var(--prime-color-accent-default);
+  color: var(--prime-color-accent-fg);
 }
 
-.footer {
-  display: flex;
-  flex-wrap: wrap;
-  justify-content: flex-end;
-  gap: var(--prime-space-3);
-  width: 100%;
+.inverseHost {
+  background: var(--prime-color-bg-inverse);
+  color: var(--prime-color-text-inverse);
 }
 
-/* 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;
-  }
+.hostText {
+  flex: 1;
+  min-width: 0;
 }

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

@@ -1,26 +1,32 @@
-/** Native form with `type="submit"` and `type="reset"` full-width buttons. Use in forms; the default `type="button"` never submits by accident. */
+/** 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.stack}
-      onSubmit={(e) => {
-        e.preventDefault();
-      }}
-    >
-      <Input.Root label="Поиск">
+    <form className={styles.form} onSubmit={submit}>
+      <Input.Root label="Рабочая почта" required>
         <Input.Wrapper>
-          <Input.Field name="query" placeholder="Запрос" />
+          <Input.Field
+            type="email"
+            name="email"
+            placeholder="name@company.ru"
+            autoComplete="email"
+          />
         </Input.Wrapper>
       </Input.Root>
-      <Button.Root type="submit" fullWidth>
-        Найти
-      </Button.Root>
-      <Button.Root variant="outline" tone="neutral" type="reset" fullWidth>
-        Очистить
+      <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

@@ -1,19 +1,17 @@
-/** All five size tiers in one row (28 · 32 · 36 · 40 · 48). Use to pick the tier that matches neighbouring fields; default is `m`. */
+/** Every size tier, 28 to 48 px high — `size`. */
 import { Button, 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 ButtonSizesExample() {
   return (
-    <div className={styles.sizeRow}>
-      {sizes.map((size) => (
-        <div key={size} className={styles.sizeCell}>
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
           <Button.Root size={size}>Сохранить</Button.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/examples/states.tsx

@@ -1,47 +1,37 @@
-/** 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. */
+/** Disabled and loading next to the default; the spinner keeps the width — `disabled`, `loading`. */
 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}>
+    <div>
+      <div>
         <Button.Root>Сохранить</Button.Root>
-        <Caption>default</Caption>
+        <Typography as="span" variant="caption" tone="muted">
+          default
+        </Typography>
       </div>
-      <div className={styles.sizeCell}>
+      <div>
         <Button.Root disabled>Сохранить</Button.Root>
-        <Caption>disabled</Caption>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
       </div>
-      <div className={styles.sizeCell}>
+      <div>
         <Button.Root loading>Сохранить</Button.Root>
-        <Caption>loading</Caption>
+        <Typography as="span" variant="caption" tone="muted">
+          loading
+        </Typography>
       </div>
-      <div className={styles.sizeCell}>
+      <div>
         <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>
+        <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>
+      ))}
+    </>
+  );
+}