prime-ui-kit 0.14.0 → 0.16.0

package/src/components/banner/examples/page-strip.tsx

@@ -1,32 +1,26 @@
 /** An edge-to-edge strip above a page and a rounded block inside a card — `placement`. */
-import { Banner, Button, Card, Icon, Typography } from "prime-ui-kit";
+import { Banner, Button, Card, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
 export default function BannerPageStripExample() {
   return (
     <div className={styles.sections}>
-      <Card.Root>
-        <Banner.Root
-          tone="warning"
-          placement="page"
-          role="region"
-          aria-label="Пробный период"
-          onDismiss={() => undefined}
-        >
-          <Banner.Content>
-            <Banner.Icon>
-              <Icon name="status.warning" />
-            </Banner.Icon>
-            <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
-          </Banner.Content>
-        </Banner.Root>
-        <div className={styles.pageBody}>
-          <Typography as="h3" variant="heading-s">
-            Отчёты
-          </Typography>
-        </div>
-      </Card.Root>
+      {/* In an app the strip stands first in the page, edge to edge above its content. */}
+      <Banner.Root
+        tone="warning"
+        placement="page"
+        role="region"
+        aria-label="Пробный период"
+        onDismiss={() => undefined}
+      >
+        <Banner.Content>
+          <Banner.Icon>
+            <Icon name="status.warning" />
+          </Banner.Icon>
+          <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
+        </Banner.Content>
+      </Banner.Root>
       <Card.Root variant="panel">
         <Card.Header>
           <Card.Title>Оплата</Card.Title>

package/src/components/breadcrumb/COMPONENT.md

@@ -22,7 +22,7 @@ import { Breadcrumb } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels; auto-collapse
+Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels; auto-collapse into a «…» menu
 ├─ Breadcrumb.Item        <li>: a link (href → LinkButton), text, or the current page (current)
 └─ Breadcrumb.Ellipsis    <li> with «…» for levels skipped on purpose
 ```
@@ -32,11 +32,11 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Breadcrumb.Root
-`ref` → `HTMLElement` (the `<nav>`). `<nav aria-label>` with an `<ol>`; draws the chevrons between levels, sets the size and collapses the middle levels on narrow containers.
+`ref` → `HTMLElement` (the `<nav>`). `<nav aria-label>` with an `<ol>`; draws the chevrons between levels, sets the size and, on narrow containers, collapses the middle levels into a «…» menu button that lists them.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Text of the links, the current page and the ellipsis; chevrons and icons take the same tier. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Text of the links, the current page and the ellipsis; chevrons, icons and the collapse menu take the same tier. Without it the tier of its host, else `m`. |
 | `labels` | `Partial<BreadcrumbLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | `Breadcrumb.Item`s and `Breadcrumb.Ellipsis`, in order; no separators by hand. |
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other `nav` attributes; an `aria-label` here overrides `labels.nav`. |
@@ -73,7 +73,7 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 ### Item kind
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| link (`href`) | muted text, medium weight; primary text on hover and focus, no underline | every ancestor level | |
+| link (`href`) | a `LinkButton` in the muted trail tone (`tone="muted"`): muted text, primary on hover and focus, no underline | every ancestor level | |
 | text (no `href`, no `current`) | muted text | a level without its own page | yes |
 | current (`current`) | primary text, medium weight | the last item — this page | |
 | icon link (`href` + `aria-label`, `Icon` child) | icon at the tier icon size | a «home» root | |
@@ -85,28 +85,35 @@ Use links for every ancestor and `current` on the last item; `s` above a `headin
 |---|---|---|
 | current | `current` | `aria-current="page"` on the text span, or on the link when the item has `href` |
 | hover / focus-visible on links | pointer / keyboard | text → primary; focus ring from LinkButton |
-| truncation | width | each level truncates with an ellipsis, max width `2 × --prime-space-24` (192; `--prime-space-24 + --prime-space-6`, 120, in a container below 30rem); the last item shrinks last |
-| auto-collapse | 3+ levels and a container `< 30rem` | `data-collapsible="true"`; middle levels are `display: none` and replaced by «… ›», whose hidden text (`labels.ellipsis`) names them |
+| truncation | width | each level truncates with an ellipsis, max width `2 × --prime-space-24` (192; `--prime-space-24 + --prime-space-6`, 120, when its container is below 30rem — its own for 3+ levels, the nearest one above for 1–2); the last item shrinks last |
+| auto-collapse | 3+ levels and a container `< 30rem` | `data-collapsible="true"`; middle levels are `display: none` and replaced by «… ›»: a ghost menu button (`Dropdown.Trigger`, named by `labels.ellipsis`) whose menu lists them — links stay links, a level without `href` is a disabled row |
+| collapse menu open | a press, `Enter` or `ArrowDown` on the «…» | `aria-expanded="true"` on the button; a `role="menu"` panel at the tier size |
 
 Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 
 ## Layout & spacing
-- The root is a size container (`container-type: inline-size`, `inline-size: 100%`): inside a flex row give it `flex: 1 1 auto; min-width: 0`.
+- A path of 1–2 levels takes its content width (at most the row), so in a flex row — the `AppHeader` start, before `AppHeader.Separator` and the title — what follows stands right after it. A path of 3+ levels is a size container (`container-type: inline-size`, `inline-size: 100%`) that folds its middle levels by its own width: inside a flex row give it `flex: 1 1 auto; min-width: 0`.
+- In an `AppHeader` the path up holds the list a record belongs to (1–2 levels); the record itself is the `AppHeader.Title` after the separator, not the breadcrumb's `current` item.
 - Above a page title: `gap: var(--prime-space-2)` between the trail and the title row.
 - The list never wraps. Chevrons sit inside each level after the first, in the placeholder text color, at the tier icon size.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
-| `Tab` | Moves focus between the level links; the current page is not focusable. |
-| `Enter` | Follows the link. |
+| `Tab` | Moves focus between the level links and the «…» of a collapsed path; the current page is not focusable. |
+| `Enter` | Follows the link; on the «…» opens the menu of the hidden levels. |
+| `ArrowDown` · `ArrowUp` · `Escape` | In the menu of hidden levels: move between them, close it and return to the «…». |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `nav` landmark with `aria-label` from `labels.nav`; an ordered list.
 - The current page has `aria-current="page"`; the chevrons are `aria-hidden` spans inside the levels, so every list item is a level.
-- Collapsed middle levels leave the layout and the tab order (no invisible focus stops); the automatic «…» reads as `labels.ellipsis`.
+- Collapsed middle levels leave the layout and the tab order (no invisible focus stops); the automatic «…» is a menu button (`aria-haspopup="menu"`) named by `labels.ellipsis`, and its menu lists them as links.
 - Icon-only links need `aria-label` on the Item.
 
 ### Labels
@@ -115,7 +122,7 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 | Key | Default | Used for |
 |---|---|---|
 | `nav` | `"Навигационная цепочка"` | `aria-label` of the `nav` landmark. |
-| `ellipsis` | `"Скрытые разделы"` | Hidden text of `Breadcrumb.Ellipsis`. |
+| `ellipsis` | `"Скрытые разделы"` | Name of the collapse menu button and hidden text of `Breadcrumb.Ellipsis`. |
 
 ## Examples
 | Example | Shows |
@@ -123,8 +130,8 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 | [overview.tsx](examples/overview.tsx) | The path to this page: links to the levels above and the current page last — `href`, `current`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; text and chevrons follow the control tier — `size`. |
 | [with-icon.tsx](examples/with-icon.tsx) | The root level as a home icon; a link without text is named for screen readers — `aria-label`. |
-| [overflow.tsx](examples/overflow.tsx) | A long path: levels truncate, and in a 320px container the middle ones collapse into «…», which screen readers announce as hidden levels — `Breadcrumb.Item`, `current`. |
-| [ellipsis.tsx](examples/ellipsis.tsx) | Levels skipped on purpose shown as «…» with hidden text for screen readers — `Breadcrumb.Ellipsis`. |
+| [overflow.tsx](examples/overflow.tsx) | A long path: levels truncate, and in a 320px container the middle ones collapse into a «…» menu that lists them — `Breadcrumb.Item`, `current`. |
+| [ellipsis.tsx](examples/ellipsis.tsx) | Levels skipped on purpose shown as «…» whose hidden text names them for screen readers — `Breadcrumb.Ellipsis`, `labels`. |
 
 ## Mistakes
 - Separators by hand between items → the root draws the chevrons.
@@ -133,5 +140,5 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 - Home icon link without `aria-label` → add `aria-label="Главная"`.
 
 ## Related
-- **Built from:** [LinkButton](../link-button/COMPONENT.md), Icon (`nav.chevronRight`)
+- **Built from:** [LinkButton](../link-button/COMPONENT.md) (`tone="muted"`), [Button](../button/COMPONENT.md) and [Dropdown](../dropdown/COMPONENT.md) (the collapse menu), Icon (`nav.chevronRight`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Tabs](../tabs/COMPONENT.md), [PageContent](../page-content/COMPONENT.md), [Stepper](../stepper/COMPONENT.md)

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

@@ -1,9 +1,9 @@
-/** Levels skipped on purpose shown as «…» with hidden text for screen readers — `Breadcrumb.Ellipsis`. */
+/** Levels skipped on purpose shown as «…» whose hidden text names them for screen readers — `Breadcrumb.Ellipsis`, `labels`. */
 import { Breadcrumb } from "prime-ui-kit";
 
 export default function BreadcrumbEllipsisExample() {
   return (
-    <Breadcrumb.Root>
+    <Breadcrumb.Root labels={{ ellipsis: "Скрытые разделы: Мебель, Офисные кресла" }}>
       <Breadcrumb.Item href="#catalog">Каталог</Breadcrumb.Item>
       <Breadcrumb.Ellipsis />
       <Breadcrumb.Item current>Кресло «Оптима»</Breadcrumb.Item>

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

@@ -7,5 +7,5 @@
 
 /* 320px — the narrowest supported width. */
 .narrow {
-  width: min(100%, calc(var(--prime-drawer-width-s) - var(--prime-space-10)));
+  width: min(100%, var(--prime-layout-min-width));
 }

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

@@ -1,4 +1,4 @@
-/** A long path: levels truncate, and in a 320px container the middle ones collapse into «…», which screen readers announce as hidden levels — `Breadcrumb.Item`, `current`. */
+/** A long path: levels truncate, and in a 320px container the middle ones collapse into a «…» menu that lists them — `Breadcrumb.Item`, `current`. */
 import { Breadcrumb } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

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

@@ -1,24 +1,22 @@
 /** Every size tier; text and chevrons follow the control tier — `size`. */
 import { Breadcrumb, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function BreadcrumbSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <div key={size} className={styles.wide}>
-          <Typography as="span" variant="caption" tone="muted">
-            {size}
-          </Typography>
+        <div key={size}>
           <Breadcrumb.Root size={size}>
             <Breadcrumb.Item href="#orders">Заказы</Breadcrumb.Item>
             <Breadcrumb.Item current>№ 48 213</Breadcrumb.Item>
           </Breadcrumb.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
         </div>
       ))}
-    </>
+    </div>
   );
 }

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

@@ -1,14 +1,21 @@
 /** The root level as a home icon; a link without text is named for screen readers — `aria-label`. */
-import { Breadcrumb, Icon } from "prime-ui-kit";
+import { Breadcrumb, Icon, Typography } from "prime-ui-kit";
 
 export default function BreadcrumbWithIconExample() {
   return (
-    <Breadcrumb.Root>
-      <Breadcrumb.Item href="#home" aria-label="Главная">
-        <Icon name="nav.home" />
-      </Breadcrumb.Item>
-      <Breadcrumb.Item href="#invoices">Счета</Breadcrumb.Item>
-      <Breadcrumb.Item current>Счёт № 2041</Breadcrumb.Item>
-    </Breadcrumb.Root>
+    <div>
+      <div>
+        <Breadcrumb.Root>
+          <Breadcrumb.Item href="#home" aria-label="Главная">
+            <Icon name="nav.home" />
+          </Breadcrumb.Item>
+          <Breadcrumb.Item href="#invoices">Счета</Breadcrumb.Item>
+          <Breadcrumb.Item current>Счёт № 2041</Breadcrumb.Item>
+        </Breadcrumb.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          aria-label
+        </Typography>
+      </div>
+    </div>
   );
 }

package/src/components/button/COMPONENT.md

@@ -12,7 +12,9 @@
 - Destructive actions without a dialog: `holdToConfirm` needs a held press.
 - Compact toolbars: icon-only buttons (only `Button.Icon` inside) are square.
 - Round icon actions — the disk is the control (play, download, cancel or retry of a transfer, a floating main action): `shape="circle"`; over a picture or a video, `variant="shade"`. A transfer it can cancel shows its share as the circle's `progress` ring.
-- Action-styled navigation: `asChild` with an `<a>` or a router link.
+- Action-styled navigation: `asChild` with an `<a>` or a router link; the current page of a set (page numbers) is `current`.
+- A single toggle (favourite, pin): the `pressed` / `defaultPressed` / `onPressedChange` triad.
+- A floating action beside a glass bar: `variant="glass"`; a host that sets its own height (the BottomNav capsule) gives it through `--prime-control-height`.
 
 ## When not to use
 - Inline text link or quiet navigation in text → use [LinkButton](../link-button/COMPONENT.md).
@@ -31,7 +33,7 @@ import { Button } from "prime-ui-kit";
 Button.Root        <button> (or the single child with asChild); variant, tone, size; size tier for nested icons
 ├─ (fill)          progress / hold wash under the label, rendered by Root once used, aria-hidden
 ├─ (ring)          a circle's progress ring along its inner edge (internal/ring), once used, aria-hidden
-├─ (Spinner)       rendered by Root while loading, aria-hidden
+├─ (Spinner)       rendered by Root while loading: the leading icon's glyph, else over the label; aria-hidden
 ├─ (label)         text children; a changed label flows in letter by letter
 └─ Button.Icon     decorative icon wrapper (aria-hidden), sized to the tier
 (hold hint)        visually hidden description beside the button with holdToConfirm
@@ -46,22 +48,27 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `variant` | `"solid" \| "soft" \| "outline" \| "ghost" \| "shade"` | `"solid"` | Visual treatment: fill, soft fill, line or transparent. `shade` — the media shade with a light glyph for a button over a picture or video; with `tone="danger"` — the error disk. |
+| `variant` | `"solid" \| "soft" \| "outline" \| "ghost" \| "shade" \| "glass"` | `"solid"` | Visual treatment: fill, soft fill, line or transparent. `shade` — the media shade for a button over a picture or video (with `tone="danger"`, the error disk); `glass` — the glass of a floating bar. |
 | `shape` | `"square" \| "circle"` | `"square"` | Outline. `circle` — a disk as wide as it is tall, with only a `Button.Icon` inside; same tiers, tones and variants. Requires `aria-label`. |
 | `tone` | `"accent" \| "neutral" \| "success" \| "danger" \| "inherit"` | `"accent"` | Meaning: primary, secondary, done (`success`) or destructive (`danger`). `inherit` takes the host's text color for an action on a colored host; only with `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`. |
+| `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`. |
+| `density` | `"regular" \| "tight" \| "inline"` | `"regular"` | `tight` — a number in a row of controls: tabular figures and 4px side air, so two digits stay square (page numbers). `inline` — a chip inside a line of text, as tall as the line, in its type. |
+| `align` | `"center" \| "start"` | `"center"` | Where the content sits: `start` reads from the start edge, for a column of choices (presets). |
 | `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. |
-| `pressed` | `boolean` | — | A toggle button: `true` on, `false` off (`aria-pressed`). On takes the selected look, an accent soft fill that glides in and out. Leave it out for an ordinary action; a set of toggles is a ButtonGroup. |
+| `loading` | `boolean` | `false` | A `Spinner` takes the leading icon's glyph (or stands over the label), sets `aria-busy`, blocks clicks; width does not change. With `asChild` no spinner is added — the child owns its content. |
+| `pressed` | `boolean` | — | A toggle button: `true` on, `false` off (`aria-pressed`); on takes the selected look (accent soft). Leave the triad out for an ordinary action; a set of toggles is a ButtonGroup. |
+| `defaultPressed` | `boolean` | — | The initial state of an uncontrolled toggle; a click, `Enter` or `Space` flips it. |
+| `onPressedChange` | `(pressed: boolean) => void` | — | Fires with the new state when the toggle is pressed; an `onClick` that calls `preventDefault()` keeps the state. |
+| `current` | `boolean` | `false` | The current page of a set (a page number): `aria-current="page"` and the selected look. A router link with its own `aria-current` gets the same look. |
 | `progress` | `number \| null` | — | Progress of a long action, `0…1`; `null` — the share is unknown. Sets `aria-busy`, stays pressable (to cancel); a square fills from the start edge, a circle draws a ring. Remove the prop when done. |
 | `holdToConfirm` | `boolean` | `false` | The action needs a held press (pointer, `Space` or `Enter`): the fill runs for 1.2 s, then `onConfirm` fires; releasing earlier rolls it back. |
 | `onConfirm` | `() => void \| Promise<void>` | — | Fires when a `holdToConfirm` press completes; the action goes here, not in `onClick`. Return the request's promise to keep the button `loading` until it settles. |
 | `labels` | `Partial<ButtonLabels>` | — | Built-in strings, see Labels. |
-| `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 → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. |
-| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size">` | — | `onClick`, `className`, `aria-*`, `data-*` and the other button attributes. |
+| `asChild` | `boolean` | `false` | Merges Button props and styles onto the single child element (a link) instead of rendering `<button>`. `disabled`/`loading` become `aria-disabled`; `progress` and `holdToConfirm` need a `<button>`. |
+| `disabled` | `boolean` | — | Disabled state; `loading` also disables. With `asChild` the child leaves the Tab order and a link loses its `href`. |
+| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. With `asChild`, the one child element. |
+| `aria-label` | `string` | — | The name of a button without a visible label; required with `shape="circle"`. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size" \| "aria-pressed">` | — | `onClick`, `type` (`"button"` by default, not passed on with `asChild`), `className`, `aria-*`, `data-*` and the other button attributes. |
 
 ### Button.Icon
 `ref` → `HTMLSpanElement`. Decorative icon wrapper (`aria-hidden`) sized to the button tier.
@@ -69,7 +76,8 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="action.copy" />`; `Icon` without `size` takes the button tier. A new icon (another `name`) cross-fades in and plays its gesture once (`fast`). |
-| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+| `className` | `string` | — | Class on the icon box. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | The other span attributes. |
 
 ## Variants
 
@@ -95,10 +103,11 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | `outline` + `inherit` | 1px inset line in a `currentColor` wash, the host's text color | an action with an edge on a colored host | |
 | `shade` (+ `accent` / `neutral` / `success`) | the media disk ground (`--prime-color-media-disk`, lighter than the pills' `media-shade`) under a gentle backdrop blur (`--prime-media-disk-blur`), so the frame shows through, and its light glyph (≥ 3:1 even over a white frame); the same in both themes and the same look as the still play mark of a video frame | a button over a picture, a video or a video circle (edit a cover, cancel an upload) | |
 | `shade` + `danger` | the danger fill, danger-fg glyph | a failed transfer over media: the retry | |
+| `glass` | the glass of a floating bar (`--prime-color-bg-glass`) over a strong backdrop blur (`--prime-glass-blur`), ink text; the solid floating fill where the user asks for less transparency; the host draws the rim and the lift | a floating action beside a glass bar, a labelled action over a photo | |
 
 `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).
+`outline` is the only variant with a visible line. `current` (or `aria-current="page"` set by a router link through `asChild`) and an on toggle take the selected look — accent soft — over any tone × variant.
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -117,48 +126,68 @@ A Button lines up exactly with Input, Select, Datepicker trigger, SegmentedContr
 | `square` | the tier's radius; with only `Button.Icon`, a square | every labelled button, toolbar icon buttons | yes |
 | `circle` | a disk: width = the tier height, full radius; the focus ring, the touch area and the press (`press-scale-compact`, 0.96) follow the circle; `progress` draws a ring along the inner edge in the glyph's color | play / download / cancel / retry disks, a floating main action; only `Button.Icon` inside, `aria-label` required | |
 
+### density
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `regular` | the tier's padding | every button | yes |
+| `tight` | 4px side air, tabular figures; one or two digits stay square (the height is the minimum width) | page numbers, a count in a row of controls | |
+| `inline` | as tall as the line of text it sits in, the text's own type, 4px side air, a pill; the touch area still applies | a chip inside a caption line (a playback speed) | |
+
+### align
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `center` | content centred | every button | yes |
+| `start` | content from the start edge | a column of choices or actions (`fullWidth` rows, presets) | |
+
 ### 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` | — |
-| `pressed` | on: accent soft fill and accent text over any variant; off: the variant's own look | a single toggle (favourite, pin, «show archived») | — (not a toggle) |
+| `pressed` / `defaultPressed` | on: accent soft fill and accent text over any variant; off: the variant's own look | a single toggle (favourite, pin, «show archived») | — (not a toggle) |
+| `current` | the selected look, `aria-current="page"` | the current page of a set (page numbers) | off |
 
 **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))` |
+| hover / active | pointer | hover fill per variant; press gives to `--prime-motion-press-scale` (`-compact` on a circle) through the shared `internal/press`; not while disabled, loading or busy |
 | focus-visible | keyboard | outer focus ring with `--prime-focus-offset`; `tone="inherit"` draws it in `currentColor` |
 | disabled | `disabled`, or a disabled `Fieldset` around it | 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"`) |
+| loading | `loading` (native `<button>`) | `data-loading="true"`, native `disabled`, `aria-busy="true"`, colors kept (busy, not unavailable), no hover or press; the leading (or only) icon's glyph cross-fades into a `Spinner` (`aria-hidden`) and back, otherwise the spinner is centered over the hidden label (`data-loading-overlay="true"`) |
 | progress | `progress` (0…1) | `data-progress="true"`, `aria-busy="true"`, still pressable; a plate of the text color with the button's radius slides in from the start edge (`fast` · standard), so corners match at any value; removing the prop fades it where it is |
-| progress unknown (square) | `progress={null}` | `data-spinner="true"`, `aria-busy="true"`, still pressable; a `Spinner` takes the leading icon's place as with `loading` |
+| progress unknown (square) | `progress={null}` | `aria-busy="true"`, still pressable; a `Spinner` takes the leading icon's glyph (or stands over the label, `data-loading-overlay="true"`) as with `loading` |
 | progress (circle) | `shape="circle"` + `progress` (0…1 or `null`) | `aria-busy="true"`, still pressable; the kit ring at the line weight along the inner edge, arc in the glyph's color over a 32% track, always turning (3 × `--prime-motion-loop` a turn, slower but never still under reduced motion; never under 8%; `null` a quarter arc); the share glides (`base`); removing the prop fades the ring where it is (`data-shown="false"`, its turn paused) |
 | glyph change | a new icon in `Button.Icon` (another `name`) | the old glyph shrinks to 0.6 and fades, the new one grows in (`fast`) and plays its gesture once; reduced motion swaps at once |
 | holding | `holdToConfirm` + a held pointer, `Space` or `Enter` | `data-hold="holding"`: the fill runs linearly for 1.2 s (kept under reduced motion — it is a gesture clock), then `onConfirm` and `data-hold="done"` (on release the fill fades in place, `data-hold="idle"`); releasing, leaving the button or losing focus earlier → `data-hold="cancel"`, the fill rolls back (`fast` · exit) |
 | confirming | `onConfirm` returned a pending promise | `data-hold="confirming"`: the full fill stays, the button is `loading` (spinner, `aria-busy`, disabled) even after the release; resolve → `data-hold="idle"`, the fill fades; reject → `data-hold="cancel"`, the fill rolls back (say why with a notification) |
 | label change | new text children | the old letters leave upward, the new ones rise from below one short step apart (`base` · emphasized, blur `--prime-motion-blur`) while the width glides; digits-only changes and reduced motion change in place |
-| pressed | `pressed` | `aria-pressed="true" \| "false"`; on adds `data-pressed="true"` and the selected fill (accent soft), which glides in and out with the color transition (`fast`) |
-| asChild disabled / loading | `asChild` + `disabled`/`loading` | `aria-disabled="true"`, `pointer-events: none`, click `preventDefault`; no native `disabled`, no automatic spinner |
+| pressed | `pressed`, or `defaultPressed` flipped by a press | `aria-pressed="true" \| "false"`; on adds `data-pressed="true"` and the selected fill (accent soft), which glides in and out with the color transition (`fast`); `onPressedChange` gets the new state |
+| current | `current` | `aria-current="page"`, `data-current="true"`, the selected fill |
+| asChild disabled / loading | `asChild` + `disabled`/`loading` | `aria-disabled="true"`, `tabIndex=-1`, a link child loses its `href`, `pointer-events: none`, the click is stopped; no native `disabled`, no automatic spinner |
 
-Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`, `data-shape`, `data-full-width`, `data-icon-only`, `data-leading-icon`, `data-trailing-icon`.
+Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-shape`, `data-density`, `data-align`, `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).
+- Buttons in a row: a gap of space step 2–3 (8–12px); toolbar icon buttons step 1 (4px).
+- Form footer: actions at the end, primary last; in a narrow container they stack full width (`fullWidth` in a column).
+- Height: the tier's (`size`), or the host's through `--prime-control-height` (a glass action as tall as the BottomNav capsule).
 - `max-width: 100%`, the label does not wrap (`white-space: nowrap`).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
-| `Enter` · `Space` | Presses the button (native `<button>`); with `holdToConfirm` the key is held until the fill completes. |
-| `Tab` | Moves focus; a disabled button is skipped, with `asChild` it stays focusable with `aria-disabled`. |
+| `Enter` · `Space` | Presses the button (native `<button>`); a toggle flips its state; with `holdToConfirm` the key is held until the fill completes. |
+| `Tab` | Moves focus; a disabled button is skipped, the `asChild` child too (`tabIndex=-1`, `aria-disabled`). |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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`.
 - `progress` is visual only: put the share in the label or in `aria-describedby` («Скачивание 42%»).
@@ -166,7 +195,8 @@ Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`,
 - `loading` sets `aria-busy="true"` and blocks the press; `progress` sets `aria-busy` and keeps the button pressable.
 - `holdToConfirm` describes the gesture through `aria-describedby` (`labels.holdHint`); `Space` / `Enter` hold like a pointer.
 - A changed label is announced once: the animated letters are hidden, the name is the new text.
-- With `asChild` the disabled state is `aria-disabled="true"` without a native `disabled`.
+- With `asChild` the disabled state is `aria-disabled="true"` without a native `disabled`; a link child loses its `href`.
+- A toggle (`pressed`, `defaultPressed` or `onPressedChange`) carries `aria-pressed`; `current` sets `aria-current="page"`. Both are named states, never color alone: the selected fill comes with the attribute.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -185,12 +215,15 @@ Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`,
 | [with-icon.tsx](examples/with-icon.tsx) | An icon before or after the label, and a square icon-only button — `Button.Icon`, `aria-label`. |
 | [download.tsx](examples/download.tsx) | A long download inside the button: the fill shows how far it got, the label counts and then offers the file — `progress`. |
 | [circle.tsx](examples/circle.tsx) | Round icon buttons in every treatment, and a disk whose ring tracks an export it can cancel — `shape`, `variant`, `tone`, `progress`. |
-| [over-media.tsx](examples/over-media.tsx) | Buttons over a listing's cover stand on the media shade; a failed upload turns its disk danger — `variant`, `shape`, `tone`. |
-| [toggle.tsx](examples/toggle.tsx) | A toggle in a toolbar: the favourite mark turns the button on with the selected fill and back off — `pressed`. |
+| [over-media.tsx](examples/over-media.tsx) | Buttons over a listing's cover: round actions on the media shade, a labelled one on glass; a failed upload turns its disk danger — `variant`, `shape`, `tone`. |
+| [toggle.tsx](examples/toggle.tsx) | A toggle in a toolbar keeps its own state: the favourite mark turns the button on with the selected fill and back off — `defaultPressed`. |
+| [density.tsx](examples/density.tsx) | Page numbers stay square and the current one takes the selected look; a speed chip sits inside a caption line — `density`, `current`. |
+| [align.tsx](examples/align.tsx) | A column of export actions reads from the start edge, every row the full width — `align`, `fullWidth`. |
 | [hold-to-confirm.tsx](examples/hold-to-confirm.tsx) | A destructive action that needs a held press; letting go early rolls the fill back and does nothing, and the delete request keeps the button loading until the server answers — `holdToConfirm`, `onConfirm`. |
-| [label-morph.tsx](examples/label-morph.tsx) | A new label flows into the button letter by letter while the width glides: save, then saved; a step flow that turns green once paid — `children`, `loading`, `tone`. |
-| [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"`. |
+| [label-morph.tsx](examples/label-morph.tsx) | A new label flows into the button letter by letter while the width glides: save, then saved; a step flow that turns green once paid — `loading`, `tone`. |
+| [on-colored-host.tsx](examples/on-colored-host.tsx) | Actions on a solid banner take its text color: a soft action and a ghost one beside it — `tone="inherit"`. |
 | [as-child.tsx](examples/as-child.tsx) | The button look on a real link; a disabled link blocks navigation — `asChild`, `disabled`. |
+| [controlled.tsx](examples/controlled.tsx) | A toggle whose state the screen owns: pinning an order shows the note under it — `pressed`, `onPressedChange`. |
 | [in-form.tsx](examples/in-form.tsx) | A full-width submit button that shows the request in progress after the email passes validation — `type`, `loading`, `fullWidth`. |
 
 ## Mistakes
@@ -199,6 +232,9 @@ Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`,
 - `tone="error"` / `variant="primary"` → `tone="danger"`, `variant="solid"`.
 - A toggle drawn by switching `variant` or `tone` → `pressed`: it sets `aria-pressed` and the selected look; changing the label instead («Закрепить» / «Открепить») is a plain action, without `pressed`.
 - Putting a `<Spinner />` inside a loading button → just set `loading`; the button places it.
+- A page number styled by a host CSS override (padding, tabular figures, a current fill) → `density="tight"` and `current`.
+- A Button recolored to glass or resized by a host class → `variant="glass"`, and the host height through `--prime-control-height`.
+- `asChild` with `progress` or `holdToConfirm` → the type refuses it: a link has no fill or hold; use a `<button>`.
 - `<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.
 - A destructive `holdToConfirm` action in `onClick` → it fires on any click; put it in `onConfirm`.
@@ -207,5 +243,5 @@ Other data attributes: `data-pressed`, `data-variant`, `data-tone`, `data-size`,
 - Rebuilding a progress label with a new word every tick («Загрузка…» / «Скачивание…») → keep the words, change only the number; digits update in place, words morph.
 
 ## Related
-- **Built from:** [Spinner](../spinner/COMPONENT.md), `internal/ring` (the circle's progress ring), `internal/glyphSwap` (the icon cross-fade), `internal/MorphText` (the label morph)
+- **Built from:** [Spinner](../spinner/COMPONENT.md), `internal/ring` (the circle's progress ring), `internal/glyphSwap` (the icon and spinner cross-fade), `internal/MorphText` (the label morph), `internal/interactiveElement` (`asChild`), `internal/press` (press feedback), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [ButtonGroup](../button-group/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [ProgressCircle](../progress-circle/COMPONENT.md)

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

@@ -0,0 +1,25 @@
+/** A column of export actions reads from the start edge, every row the full width — `align`, `fullWidth`. */
+import { Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const EXPORTS = [
+  { icon: "object.document", label: "Счёт в PDF" },
+  { icon: "object.chart", label: "Отчёт в Excel" },
+  { icon: "action.send", label: "Отправить бухгалтеру" },
+] as const;
+
+export default function ButtonAlignExample() {
+  return (
+    <div className={styles.column}>
+      {EXPORTS.map((item) => (
+        <Button.Root key={item.label} variant="ghost" tone="neutral" align="start" fullWidth>
+          <Button.Icon>
+            <Icon name={item.icon} />
+          </Button.Icon>
+          {item.label}
+        </Button.Root>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,21 @@
+/** A toggle whose state the screen owns: pinning an order shows the note under it — `pressed`, `onPressedChange`. */
+import { Button, Icon, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+export default function ButtonControlledExample() {
+  const [pinned, setPinned] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root variant="ghost" tone="neutral" pressed={pinned} onPressedChange={setPinned}>
+        <Button.Icon>
+          <Icon name="action.pin" />
+        </Button.Icon>
+        Закрепить заказ
+      </Button.Root>
+      <Typography variant="body-s" tone="muted">
+        {pinned ? "Заказ № 4815 закреплён вверху списка" : "Заказ № 4815 в общем списке"}
+      </Typography>
+    </>
+  );
+}

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

@@ -0,0 +1,45 @@
+/** Page numbers stay square and the current one takes the selected look; a speed chip sits inside a caption line — `density`, `current`. */
+import { Button, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PAGES = [1, 2, 3, 4, 12] as const;
+const SPEEDS = ["1×", "1,5×", "2×"] as const;
+
+export default function ButtonDensityExample() {
+  const [page, setPage] = React.useState<number>(3);
+  const [speed, setSpeed] = React.useState(0);
+
+  return (
+    <>
+      <nav aria-label="Страницы счетов" className={styles.row}>
+        {PAGES.map((item) => (
+          <Button.Root
+            key={item}
+            variant="ghost"
+            tone="neutral"
+            density="tight"
+            current={item === page}
+            aria-label={`Страница ${item}`}
+            onClick={() => setPage(item)}
+          >
+            {item}
+          </Button.Root>
+        ))}
+      </nav>
+      <Typography variant="caption" tone="muted">
+        Голосовое сообщение · 0:42 ·{" "}
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          density="inline"
+          aria-label={`Скорость ${SPEEDS[speed]}`}
+          onClick={() => setSpeed((speed + 1) % SPEEDS.length)}
+        >
+          {SPEEDS[speed]}
+        </Button.Root>
+      </Typography>
+    </>
+  );
+}