prime-ui-kit 0.15.0 → 0.16.0

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>
+    </>
+  );
+}

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

@@ -6,26 +6,6 @@
   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);
-}
-
 /* A row of round buttons. */
 .row {
   display: flex;
@@ -34,7 +14,14 @@
   gap: var(--prime-space-3);
 }
 
-/* A listing cover with its round actions at the top end. */
+/* align.tsx: a column of full-width actions, as wide as a side panel. */
+.column {
+  display: grid;
+  gap: var(--prime-space-1);
+  width: min(100%, var(--prime-layout-form-width-s));
+}
+
+/* A listing cover with its round actions at the top end and a glass action at the bottom. */
 .cover {
   position: relative;
 }
@@ -43,12 +30,14 @@
   position: absolute;
   inset-block-start: var(--prime-space-2);
   inset-inline-end: var(--prime-space-2);
-  z-index: 1;
+  z-index: var(--prime-z-raised);
   display: flex;
   gap: var(--prime-space-2);
 }
 
-.hostText {
-  flex: 1;
-  min-width: 0;
+.coverGallery {
+  position: absolute;
+  inset-block-end: var(--prime-space-2);
+  inset-inline-start: var(--prime-space-2);
+  z-index: var(--prime-z-raised);
 }

package/src/components/button/examples/label-morph.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** 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`. */
 import { Button } from "prime-ui-kit";
 import * as React from "react";
 

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

@@ -1,28 +1,28 @@
-/** 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";
+/** Actions on a solid banner take its text color: a soft action and a ghost one beside it — `tone="inherit"`. */
+import { Banner, Button } from "prime-ui-kit";
 
 const HOSTS = [
-  { className: styles.accentHost, text: "Доступна новая версия редактора" },
-  { className: styles.inverseHost, text: "Режим только для чтения" },
-];
+  { tone: "accent", text: "Доступна новая версия редактора", action: "Обновить", later: "Позже" },
+  { tone: "neutral", text: "Режим только для чтения", action: "Запросить доступ", later: "Скрыть" },
+] as const;
 
 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>
+      {HOSTS.map(({ tone, text, action, later }) => (
+        <Banner.Root key={text} variant="solid" tone={tone}>
+          <Banner.Content>
+            <Banner.Title>{text}</Banner.Title>
+          </Banner.Content>
+          <Banner.Actions>
+            <Button.Root variant="soft" tone="inherit">
+              {action}
+            </Button.Root>
+            <Button.Root variant="ghost" tone="inherit">
+              {later}
+            </Button.Root>
+          </Banner.Actions>
+        </Banner.Root>
       ))}
     </>
   );

package/src/components/button/examples/over-media.tsx

@@ -1,4 +1,4 @@
-/** Buttons over a listing's cover stand on the media shade; a failed upload turns its disk danger — `variant`, `shape`, `tone`. */
+/** 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`. */
 import { Button, Icon, Thumbnail } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -31,6 +31,12 @@ export default function ButtonOverMediaExample() {
           </Button.Icon>
         </Button.Root>
       </div>
+      <Button.Root variant="glass" tone="neutral" className={styles.coverGallery}>
+        <Button.Icon>
+          <Icon name="object.image" />
+        </Button.Icon>
+        Все 12 фото
+      </Button.Root>
     </div>
   );
 }

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

@@ -1,17 +1,9 @@
-/** A toggle in a toolbar: the favourite mark turns the button on with the selected fill and back off — `pressed`. */
+/** A toggle in a toolbar keeps its own state: the favourite mark turns the button on with the selected fill and back off — `defaultPressed`. */
 import { Button, Icon } from "prime-ui-kit";
-import * as React from "react";
 
 export default function ButtonToggleExample() {
-  const [favorite, setFavorite] = React.useState(true);
-
   return (
-    <Button.Root
-      variant="ghost"
-      tone="neutral"
-      pressed={favorite}
-      onClick={() => setFavorite((value) => !value)}
-    >
+    <Button.Root variant="ghost" tone="neutral" defaultPressed>
       <Button.Icon>
         <Icon name="status.favorite" />
       </Button.Icon>