prime-ui-kit 0.9.1 → 0.9.3

package/dist/tokens/semantic.d.ts

@@ -1,44 +1,37 @@
-/**
- * Semantic layer (`--prime-*`). Components read only these variables.
- * Path → variable: `color.bg.canvas` → `--prime-color-bg-canvas`, camelCase → kebab-case.
- * Values below are the light theme; `themes/dark.ts` overrides colors and shadows.
- *
- * Design rules (see docs/foundation.md):
- * - Depth comes from fills, not borders. `border.subtle` is a hairline, `border.control` is transparent
- *   (it becomes visible only under `prefers-contrast: more`).
- * - Every size is on the 4px grid. Controls share one size axis: xs 28 · s 32 · m 36 · l 40 · xl 48.
- * - A nested radius equals the outer radius minus the padding between them.
- */
 export declare const semanticTokens: {
     readonly color: {
+        /**
+         * Surface ladder, computed by `layers.ts`: `0` the page … `4` the deepest nested layer, `floating`
+         * for menus, popovers, modals and drawers (`floating1`/`floating2` nest inside it). Each row:
+         * `bg` the layer, `fill` controls on it, `fillHover`, `selected` the thumb on its track.
+         * Components read them through the depth context variables (globals.css), not directly.
+         */
+        readonly layer: Record<string, import("./layers").LayerColors>;
         readonly bg: {
-            /** App background. */
-            readonly canvas: "{color.gray.50}";
-            /** Cards, panels, table bodies. */
-            readonly surface: "{color.gray.0}";
-            /** Floating layers: menus, popovers, modals, drawers. */
-            readonly raised: "{color.gray.0}";
-            /** Inset areas inside a surface: modal footer, table head, code. */
-            readonly sunken: "{color.gray.75}";
             readonly inverse: "{color.gray.925}";
             readonly scrim: "rgba(17, 19, 24, 0.44)";
+            /** Soft shade over an edge that hides scrolled content (DataTable columns). */
+            readonly edgeShadow: "rgba(17, 19, 24, 0.14)";
+            /**
+             * Translucent glass over content (floating BottomNav), always with a light backdrop blur:
+             * clear enough that the content reads through it, as Liquid Glass.
+             */
+            readonly glass: "color-mix(in srgb, var(--prime-ref-color-gray-0) 58%, transparent)";
+            /** The specular top edge of a glass surface: the line that makes it read as glass. */
+            readonly glassEdge: "rgba(255, 255, 255, 0.85)";
         };
+        /**
+         * Translucent state washes: they sit on any background, including ones off the ladder (an
+         * image, a tinted banner). Resting fills of controls come from the ladder instead
+         * (`--prime-color-fill-muted`, `--prime-color-field-bg`).
+         */
         readonly fill: {
-            /** Transparent wash: ghost hover, row hover. Works on any background. */
+            /** Ghost hover, row hover. */
             readonly subtle: "rgba(17, 19, 24, 0.04)";
             readonly subtleActive: "rgba(17, 19, 24, 0.07)";
-            /**
-             * The faintest wash: hover of a tab in the sunken strip (Tabs). Stays below the
-             * sunken → surface step in both themes, so a hovered tab never reads as the selected one.
-             */
+            /** The faintest wash: hover of a tab in the tab strip, below the selected tab's step. */
             readonly faint: "rgba(17, 19, 24, 0.04)";
-            /**
-             * Neutral buttons, chips, segmented track. Translucent ink wash: always one step off whatever
-             * it sits on (canvas, card, sunken tile, a custom container), in both themes.
-             */
-            readonly muted: "color-mix(in srgb, var(--prime-ref-color-gray-925) 7%, transparent)";
-            readonly mutedHover: "color-mix(in srgb, var(--prime-ref-color-gray-925) 10%, transparent)";
-            /** Unchecked checkbox, switch track, slider track. Same wash, stronger. */
+            /** Unchecked checkbox, switch track, slider track. */
             readonly strong: "color-mix(in srgb, var(--prime-ref-color-gray-925) 15%, transparent)";
             readonly strongHover: "color-mix(in srgb, var(--prime-ref-color-gray-925) 22%, transparent)";
         };
@@ -96,39 +89,29 @@ export declare const semanticTokens: {
             readonly soft: "{color.sky.100}";
             readonly text: "{color.sky.800}";
         };
-        /**
-         * Field fill depends on what it sits on. `bg` is the canvas value; every surface component
-         * (Card, Modal, Drawer, Popover, Sidebar…) sets `--prime-color-field-bg: var(--prime-color-field-bg-surface)`.
-         */
+        /** The field fill at rest, hover and focus comes from the ladder (`--prime-color-field-bg*`). */
         readonly field: {
-            /** Translucent wash, visible on any background; `bgSurface` kept equal for surface contexts. */
-            readonly bg: "color-mix(in srgb, var(--prime-ref-color-gray-925) 6%, transparent)";
-            readonly bgSurface: "color-mix(in srgb, var(--prime-ref-color-gray-925) 6%, transparent)";
-            /** Hover wash of a field: the `bg` wash, twice as dense (≈ `bg` mixed 94% with the text color). */
-            readonly bgHover: "color-mix(in srgb, var(--prime-ref-color-gray-925) 12%, transparent)";
-            readonly bgFocus: "{color.gray.0}";
+            /** A disabled field: a faint wash on whatever it sits on. */
             readonly bgDisabled: "color-mix(in srgb, var(--prime-ref-color-gray-925) 4%, transparent)";
         };
-        /**
-         * Card fill depends on what it sits on (same idea as `field`). On the canvas a card is white and raised;
-         * every surface plane (AppShell content, Card, Modal, Drawer, Popover) sets
-         * `--prime-color-card-bg: var(--prime-color-bg-sunken)`, and a card on a sunken fill drops its shadow.
-         */
-        readonly card: {
-            readonly bg: "{color.bg.surface}";
-        };
         readonly focus: {
             readonly ring: "{color.cobalt.700}";
         };
         readonly control: {
             /** Switch thumb, slider thumb. */
             readonly thumb: "{color.white}";
-            /** Selected segment in a segmented track: one step lighter than the track. */
-            readonly selected: "{color.gray.0}";
         };
+        /**
+         * The tooltip is an inverse chip: everything inside it (a Kbd, a secondary line) reads its
+         * colors from here, through the context the chip sets (`--prime-color-text-*`, fills).
+         */
         readonly tooltip: {
             readonly bg: "{color.gray.925}";
             readonly text: "{color.gray.0}";
+            /** Secondary text on the chip (a shortcut, a second line). */
+            readonly muted: "{color.gray.300}";
+            /** A key cap or chip on the chip: a light wash over the dark fill. */
+            readonly fill: "rgba(255, 255, 255, 0.14)";
         };
         readonly palette: Record<string, {
             soft: string;
@@ -317,6 +300,8 @@ export declare const semanticTokens: {
         };
         /** Step between items of a staggered first render. */
         readonly stagger: "{duration.80}";
+        /** Blur that hides a change of shape while two states swap in place (icon → check, letters). */
+        readonly blur: "2px";
         /** `:active` scale of pressable controls; `compact` for icon-only and small targets. */
         readonly press: {
             readonly scale: "0.98";
@@ -430,6 +415,13 @@ export declare const semanticTokens: {
             readonly choice: "{icon.24}";
             readonly track: "0.5rem";
         };
+        /**
+         * Coarse pointers (`@media (pointer: coarse)`): the hit area of a control below this size grows
+         * to it (WCAG 2.5.5); the visual size stays the tier's.
+         */
+        readonly touchTarget: "2.75rem";
+        /** Touch screens and narrow viewports: the least text size of an editable value (iOS zoom). */
+        readonly touchTextSize: "{font.size.16}";
     };
     /** Badge / Kbd tiers. Inside a control of tier T use the badge tier one step down. */
     readonly badge: {
@@ -545,8 +537,6 @@ export declare const semanticTokens: {
         readonly minWidth: "12rem";
     };
     readonly card: {
-        /** Context: surfaces set it to `none` together with `--prime-color-card-bg` (see color.card). */
-        readonly shadow: "{shadow.raised}";
         readonly radius: "{radius.12}";
         readonly paddingS: "{space.4}";
         readonly paddingM: "{space.5}";
@@ -569,10 +559,86 @@ export declare const semanticTokens: {
         readonly widthL: "40rem";
         readonly widthXl: "50rem";
     };
-    readonly tooltip: {
-        readonly radius: "{radius.6}";
+    /** Bottom sheets: Drawer `side="bottom"`, Modal and floating layers on a narrow viewport. */
+    readonly sheet: {
+        readonly radius: "{radius.16}";
+        /** The grab bar at the top edge and the strip that holds it. */
+        readonly handleWidth: "2.25rem";
+        readonly handleHeight: "{space.1}";
+        readonly handleArea: "{space.5}";
+        /** Room kept above a sheet so the page behind stays visible. */
+        readonly topGap: "{space.10}";
+        /** A bottom sheet on a tablet or desktop is never narrower than this (= Modal m). */
+        readonly minWidth: "35rem";
+    };
+    readonly bottomNav: {
+        /** Bar height without the safe-area inset: icon 20 + gap 4 + label 12 and air around them. */
+        readonly height: "3.25rem";
+        /** An icon-only flat bar: no label row, so it is lower. */
+        readonly iconOnlyHeight: "{space.12}";
+        /**
+         * Floating capsule (iOS 26 tab bar): items 44 high — icon-only items are 44 squares, the touch
+         * size — inset 4 inside the capsule, so the selection capsule sits clear of its edge (52 in all).
+         */
+        readonly floatingItemSize: "2.75rem";
+        readonly floatingPadding: "{space.1}";
         readonly paddingX: "{space.2}";
-        readonly paddingY: "{space.1}";
+        /** Between the icon and the label. */
+        readonly itemGap: "{space.1}";
+        /** The box that holds the icon and anchors the count. */
+        readonly indicatorWidth: "{space.7}";
+        readonly indicatorHeight: "{space.5}";
+        /** A light icon (20) over a small label (10, as the iOS tab bar): the bar stays quiet. */
+        readonly iconSize: "{icon.20}";
+        readonly labelSize: "{font.size.10}";
+        readonly labelLineHeight: "{font.lineHeight.12}";
+        /**
+         * Floating: the capsule's gap from the screen edges and the blur behind it — light, as Liquid
+         * Glass: the content stays recognisable under the glass, only softened.
+         */
+        readonly floatingInset: "{space.3}";
+        readonly blur: "0.5rem";
+    };
+    /**
+     * Tooltip tiers: a chip of tier T is as tall as a menu item of tier T (24 · 28 · 32 · 36 · 40),
+     * and text, padding and radius grow together, one step per tier.
+     */
+    readonly tooltip: {
+        readonly xs: {
+            readonly textSize: "{font.size.12}";
+            readonly lineHeight: "{font.lineHeight.16}";
+            readonly paddingX: "0.375rem";
+            readonly paddingY: "{space.1}";
+            readonly radius: "{radius.4}";
+        };
+        readonly s: {
+            readonly textSize: "{font.size.12}";
+            readonly lineHeight: "{font.lineHeight.16}";
+            readonly paddingX: "{space.2}";
+            readonly paddingY: "0.375rem";
+            readonly radius: "{radius.6}";
+        };
+        readonly m: {
+            readonly textSize: "{font.size.13}";
+            readonly lineHeight: "{font.lineHeight.20}";
+            readonly paddingX: "0.625rem";
+            readonly paddingY: "0.375rem";
+            readonly radius: "{radius.6}";
+        };
+        readonly l: {
+            readonly textSize: "{font.size.14}";
+            readonly lineHeight: "{font.lineHeight.20}";
+            readonly paddingX: "{space.3}";
+            readonly paddingY: "{space.2}";
+            readonly radius: "{radius.8}";
+        };
+        readonly xl: {
+            readonly textSize: "{font.size.16}";
+            readonly lineHeight: "{font.lineHeight.24}";
+            readonly paddingX: "{space.4}";
+            readonly paddingY: "{space.2}";
+            readonly radius: "{radius.8}";
+        };
         readonly maxWidth: "17.5rem";
         /** Arrow base and depth; the arrow points at the trigger's centre. */
         readonly arrowWidth: "0.625rem";

package/dist/tokens/themes/dark.d.ts

@@ -1,20 +1,18 @@
 export declare const darkThemeOverrides: {
     readonly color: {
+        readonly layer: Record<string, import("../layers").LayerColors>;
         readonly bg: {
-            readonly canvas: "{color.gray.950}";
-            readonly surface: "{color.gray.900}";
-            readonly raised: "{color.gray.875}";
-            /** = canvas: nested tiles on the 900 surface need a clear step (925 read as 1.03:1). */
-            readonly sunken: "{color.gray.950}";
             readonly inverse: "{color.gray.100}";
             readonly scrim: "rgba(0, 0, 0, 0.6)";
+            /** Darker than the scrim's share: a shade on a 900 surface needs more ink to read. */
+            readonly edgeShadow: "rgba(0, 0, 0, 0.5)";
+            readonly glass: "color-mix(in srgb, var(--prime-ref-color-gray-875) 56%, transparent)";
+            readonly glassEdge: "rgba(255, 255, 255, 0.16)";
         };
         readonly fill: {
             readonly subtle: "rgba(233, 235, 240, 0.05)";
             readonly subtleActive: "rgba(233, 235, 240, 0.09)";
             readonly faint: "rgba(233, 235, 240, 0.02)";
-            readonly muted: "color-mix(in srgb, var(--prime-ref-color-gray-100) 7%, transparent)";
-            readonly mutedHover: "color-mix(in srgb, var(--prime-ref-color-gray-100) 10%, transparent)";
             readonly strong: "color-mix(in srgb, var(--prime-ref-color-gray-100) 16%, transparent)";
             readonly strongHover: "color-mix(in srgb, var(--prime-ref-color-gray-100) 22%, transparent)";
         };
@@ -68,10 +66,6 @@ export declare const darkThemeOverrides: {
             readonly text: "{color.sky.300}";
         };
         readonly field: {
-            readonly bg: "color-mix(in srgb, var(--prime-ref-color-gray-100) 6%, transparent)";
-            readonly bgSurface: "color-mix(in srgb, var(--prime-ref-color-gray-100) 6%, transparent)";
-            readonly bgHover: "color-mix(in srgb, var(--prime-ref-color-gray-100) 12%, transparent)";
-            readonly bgFocus: "{color.gray.925}";
             readonly bgDisabled: "color-mix(in srgb, var(--prime-ref-color-gray-100) 4%, transparent)";
         };
         readonly focus: {
@@ -79,11 +73,13 @@ export declare const darkThemeOverrides: {
         };
         readonly control: {
             readonly thumb: "{color.gray.100}";
-            readonly selected: "{color.gray.750}";
         };
+        /** A light chip over the dark UI: inverse like in light, so it reads over any layer. */
         readonly tooltip: {
-            readonly bg: "{color.gray.750}";
-            readonly text: "{color.gray.100}";
+            readonly bg: "{color.gray.100}";
+            readonly text: "{color.gray.925}";
+            readonly muted: "{color.gray.600}";
+            readonly fill: "rgba(17, 19, 24, 0.08)";
         };
         readonly palette: Record<string, {
             soft: string;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.9.1",
-  "description": "React 19 UI kit for product interfaces: 57 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y. Ships COMPONENT.md docs and copyable examples.",
+  "version": "0.9.3",
+  "packageManager": "bun@1.3.13",
+  "description": "React 19 UI kit for product interfaces: 61 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y. Ships COMPONENT.md docs and copyable examples.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/components/accordion/COMPONENT.md

@@ -1,6 +1,6 @@
 # Accordion
 
-**Category:** layout
+**Category:** data-display
 **Kind:** navigation
 
 > Collapsible sections: FAQ, settings groups, checkout steps.
@@ -96,8 +96,8 @@ Accordion.Root                frame (grouped) or column of cards (separate)
 ### layout
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `grouped` | One `card-bg` surface with card radius, `border-subtle` hairlines between items, no shadow of its own | FAQ, short settings lists | yes |
-| `separate` | Each item is a separate card (`card-bg`, card radius, `card-shadow`) with `--prime-space-2` between them | Heavier sections, checkout steps | |
+| `grouped` | One surface — a layer of the ladder (`layer-current`) — with card radius, `border-subtle` hairlines between items, no shadow of its own | FAQ, short settings lists | yes |
+| `separate` | Each item is a separate card (`layer-current`, card radius, the raised whisper on the page) with `--prime-space-2` between them | Heavier sections, checkout steps | |
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -122,7 +122,7 @@ Accordion.Root                frame (grouped) or column of cards (separate)
 |---|---|---|
 | open / closed | `value` / `defaultValue` + `onValueChange` | `data-state="open" \| "closed"` on Item, Trigger and Content; `aria-expanded` on Trigger; `inert` on a closed Content |
 | disabled | `disabled` on Item | `data-disabled` on Item and Trigger, native `disabled`, `text-disabled`, `cursor: not-allowed` |
-| hover / active | pointer | trigger `fill-subtle` / `fill-subtle-active` |
+| hover / active | pointer | trigger `fill-muted-hover` (two ladder steps off the accordion's layer, so it never lands on the host's color at the edges) / `fill-strong` |
 | focus-visible | keyboard | inset focus ring inside the trigger |
 
 Root: `data-size`, `data-layout`. The panel height transitions through `grid-template-rows: 0fr → 1fr` (no JS measuring, follows content that resizes while open) and the body fades in while settling by `--prime-space-1`; open uses `base` + `enter`, close `fast` + `exit`. The chevron rotates over `base`. Instant under `prefers-reduced-motion`.
@@ -130,7 +130,7 @@ Root: `data-size`, `data-layout`. The panel height transitions through `grid-tem
 ## Layout & spacing
 - Takes the full width of its parent (`width: 100%`); the parent sets the measure.
 - Panel content is a flex column with `--prime-space-3` gap; it reserves `--prime-focus-space` at the top so focus rings of fields inside are not clipped.
-- Fields inside panels get the surface field fill automatically.
+- The root is a layer of the surface ladder (`data-depth`): fields inside panels take that layer's fill automatically.
 - Stack several accordions or an accordion and other blocks with the page gap (`--prime-space-8` between groups).
 
 ## Accessibility

package/src/components/avatar/COMPONENT.md

@@ -156,7 +156,7 @@ No keyboard interaction.
 - `alt="Анна Климова"` while the name is printed next to it → `alt=""`.
 - A random `color` on every render → derive it from the user id.
 - A custom presence dot → use `Avatar.Status`.
-- A group on a custom filled block with a canvas-colored ring → set `--avatar-ring` to that fill.
+- A group on a custom filled block with a ring in the wrong color → set `--avatar-ring` to that fill (by default the ring is the current layer, `--prime-color-layer-current`).
 - `size` on every avatar in a group → set it once on `Avatar.Group`.
 
 ## Related

package/src/components/badge/COMPONENT.md

@@ -30,7 +30,7 @@ Badge.Root          <span>: fill, tier dimensions
 ├─ [start segment]  Badge.Icon or Badge.Dot at the start edge: full height, mark centred
 ├─ body             text, Badge.Dot, inline Badge.Icon
 │                   (a <button> with onPress; a <span> with a trailing segment; none when read-only)
-├─ Badge.Action     optional end segment revealed on hover / focus
+├─ Badge.Action     optional end segment revealed on hover / focus (always shown on touch screens)
 └─ remove segment   with onRemove: full height, the whole end is the hit area (Icon action.close)
 ```
 
@@ -70,7 +70,7 @@ Badge.Root          <span>: fill, tier dimensions
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
 
 ### Badge.Action
-`ref` → `HTMLButtonElement`. A `<button>` segment at the end, revealed on hover and focus; the badge reserves its room, so the width never changes. One per badge, not together with `onRemove`.
+`ref` → `HTMLButtonElement`. A `<button>` segment at the end, revealed on hover and focus, always shown on touch screens; the badge reserves its room, so the width never changes. One per badge, not together with `onRemove`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|

package/src/components/banner/COMPONENT.md

@@ -1,6 +1,6 @@
 # Banner
 
-**Category:** feedback
+**Category:** status
 **Kind:** primitive
 
 > Full-width in-flow message for a page, section or card: status icon, title, description, actions and dismiss.

package/src/components/button/COMPONENT.md

@@ -7,7 +7,9 @@
 
 ## When to use
 - Primary, secondary and destructive actions in forms, toolbars, dialogs, cards and empty states.
-- Async actions: `loading` shows a spinner, blocks clicks and keeps the width.
+- Async actions: `loading` shows a spinner, blocks clicks and keeps the width; when it ends, a new label («Сохранено») flows in.
+- Long actions with known progress (downloads, exports): `progress` fills the button itself.
+- Destructive actions without a dialog: `holdToConfirm` needs a held press.
 - Compact toolbars: icon-only buttons (only `Button.Icon` inside) are square.
 - Action-styled navigation: `asChild` with an `<a>` or a router link.
 
@@ -26,8 +28,11 @@ import { Button } from "prime-ui-kit";
 ## Anatomy
 ```
 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
 ├─ (Spinner)       rendered by Root while loading, 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
 ```
 
 ## API
@@ -44,10 +49,14 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | `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. |
+| `progress` | `number` | — | Progress of a long action started by the button, `0…1`: a wash of the text color grows inside from the start edge, `aria-busy` is set and the button stays pressable (to cancel). Put the number in the label («Скачивание 42%»); remove the prop when done and the fill fades out. |
+| `holdToConfirm` | `boolean` | `false` | The action needs a held press: the fill runs for 1.2 s (a gesture clock, kept under reduced motion) and `onConfirm` fires at its end. Releasing, leaving or losing focus earlier rolls it back. Space and Enter hold too; the gesture is described to assistive tech by `labels.holdHint`. |
+| `onConfirm` | `() => void` | — | Fires when a `holdToConfirm` press completes; the action goes here, not in `onClick`. |
+| `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 → square icon-only button; give it `aria-label`. |
+| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → square icon-only button; give it `aria-label`. A changed text label flows into the new one letter by letter while the width glides; a change of digits only («58 с» → «57 с», «42%» → «43%») stays in place. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size">` | — | `onClick`, `className`, `aria-*`, `data-*` and the other button attributes. |
 
 ### Button.Icon
@@ -109,6 +118,9 @@ A Button lines up exactly with Input, Select, Datepicker trigger, SegmentedContr
 | focus-visible | keyboard | outer focus ring with `--prime-focus-offset`; `tone="inherit"` draws it in `currentColor` |
 | disabled | `disabled` | native `disabled`, `data-disabled="true"`, `fill-muted` + `text-disabled`, `cursor: not-allowed`; ghost stays transparent |
 | loading | `loading` (native `<button>`) | `data-loading="true"`, native `disabled`, `aria-busy="true"`, colors kept (busy, not unavailable), no hover or press; a `Spinner` (`aria-hidden`) replaces the leading (or only) icon, otherwise it is centered over the hidden label (`data-loading-overlay="true"`) |
+| 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 |
+| 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 earlier → `data-hold="cancel"`, the fill rolls back (`fast` · exit) |
+| 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 |
 | asChild disabled / loading | `asChild` + `disabled`/`loading` | `aria-disabled="true"`, `pointer-events: none`, click `preventDefault`; no native `disabled`, no automatic spinner |
 
 Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-full-width`, `data-icon-only`, `data-leading-icon`, `data-trailing-icon`.
@@ -123,19 +135,23 @@ Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-full-widt
 ### Keyboard
 | Key | Action |
 |---|---|
-| `Enter` · `Space` | Presses the button (native `<button>`). |
+| `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`. |
 
 ### ARIA
 - Native `<button>`, `type="button"` by default, so it never submits a form by accident.
 - Icon-only buttons need `aria-label`; `Button.Icon` is `aria-hidden`.
-- `loading` sets `aria-busy="true"` and blocks the press.
+- `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`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-No `labels`.
+| Key | Default | Used for |
+|---|---|---|
+| `holdHint` | `"Удерживайте, чтобы подтвердить"` | Description of a `holdToConfirm` button for assistive tech (`aria-describedby`). |
 
 ## Examples
 | Example | Shows |
@@ -145,6 +161,9 @@ No `labels`.
 | [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`. |
+| [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`. |
+| [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 — `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 — `children`, `loading`. |
 | [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`. |
@@ -156,6 +175,8 @@ No `labels`.
 - 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.
+- A destructive `holdToConfirm` action in `onClick` → it fires on any click; put it in `onConfirm`.
+- 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)

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

@@ -0,0 +1,45 @@
+/** A long download inside the button: the fill shows how far it got, the label counts and then offers the file — `progress`. */
+import { Button, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+/** Share of the file received at each network tick. */
+const TICKS = [0.06, 0.15, 0.27, 0.34, 0.48, 0.61, 0.66, 0.79, 0.88, 0.97, 1];
+
+export default function ButtonDownloadExample() {
+  const [tick, setTick] = React.useState<number | null>(null);
+  const [ready, setReady] = React.useState(false);
+
+  React.useEffect(() => {
+    if (tick === null) return;
+    const timer = window.setTimeout(() => {
+      if (tick + 1 < TICKS.length) setTick(tick + 1);
+      else {
+        setTick(null);
+        setReady(true);
+      }
+    }, 220);
+    return () => window.clearTimeout(timer);
+  }, [tick]);
+
+  const progress = tick === null ? undefined : TICKS[tick];
+
+  return (
+    <Button.Root
+      variant={ready ? "soft" : "solid"}
+      progress={progress}
+      onClick={() => {
+        if (ready) setReady(false);
+        else if (tick === null) setTick(0);
+      }}
+    >
+      <Button.Icon>
+        <Icon name={ready ? "action.externalLink" : "action.download"} />
+      </Button.Icon>
+      {progress !== undefined
+        ? `Скачивание ${Math.round(progress * 100)}%`
+        : ready
+          ? "Открыть отчёт"
+          : "Скачать отчёт за октябрь"}
+    </Button.Root>
+  );
+}

package/src/components/button/examples/hold-to-confirm.tsx

@@ -0,0 +1,23 @@
+/** A destructive action that needs a held press; letting go early rolls the fill back and does nothing — `holdToConfirm`, `onConfirm`. */
+import { Button, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+export default function ButtonHoldToConfirmExample() {
+  const [deleted, setDeleted] = React.useState(false);
+
+  return deleted ? (
+    <Button.Root variant="ghost" tone="neutral" onClick={() => setDeleted(false)}>
+      <Button.Icon>
+        <Icon name="action.refresh" />
+      </Button.Icon>
+      Восстановить проект
+    </Button.Root>
+  ) : (
+    <Button.Root variant="soft" tone="danger" holdToConfirm onConfirm={() => setDeleted(true)}>
+      <Button.Icon>
+        <Icon name="action.delete" />
+      </Button.Icon>
+      Удерживайте, чтобы удалить проект
+    </Button.Root>
+  );
+}

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

@@ -0,0 +1,33 @@
+/** A new label flows into the button letter by letter while the width glides: save, then saved; a step flow — `children`, `loading`. */
+import { Button } from "prime-ui-kit";
+import * as React from "react";
+
+const STEPS = ["Продолжить", "Подтвердить оплату", "Оплачено"];
+
+export default function ButtonLabelMorphExample() {
+  const [save, setSave] = React.useState<"idle" | "saving" | "saved">("idle");
+  const [step, setStep] = React.useState(0);
+
+  React.useEffect(() => {
+    if (save === "idle") return;
+    const timer = window.setTimeout(
+      () => setSave(save === "saving" ? "saved" : "idle"),
+      save === "saving" ? 1200 : 2000,
+    );
+    return () => window.clearTimeout(timer);
+  }, [save]);
+
+  return (
+    <>
+      <Button.Root
+        variant="soft"
+        tone="neutral"
+        loading={save === "saving"}
+        onClick={() => setSave("saving")}
+      >
+        {save === "saved" ? "Изменения сохранены" : "Сохранить изменения"}
+      </Button.Root>
+      <Button.Root onClick={() => setStep((step + 1) % STEPS.length)}>{STEPS[step]}</Button.Root>
+    </>
+  );
+}

package/src/components/card/COMPONENT.md

@@ -39,7 +39,7 @@ Card.Root variant="cover"        Media · Body(Title, Description) · Footer
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Card.Root
-`ref` → `HTMLDivElement`. The filled surface (card fill, radius 12, raised shadow, no border) and a size container; `variant` picks the template layout of its parts.
+`ref` → `HTMLDivElement`. A layer of the surface ladder (`data-depth` one above the surface around it: white on the light page, the next layer when nested; radius 12, the raised whisper only on the page, no border) and a size container; `variant` picks the template layout of its parts.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -143,13 +143,15 @@ Card.Root variant="cover"        Media · Body(Title, Description) · Footer
 |---|---|---|
 | template | `variant` | `data-variant` |
 | flat | `flat` | `data-flat` |
+| depth | nesting: one above the nearest surface (the page and the AppShell panel are 0) | `data-depth` (`1`–`4`, `floating-1`/`floating-2` inside a floating layer); the fill is `--prime-color-layer-current`, the shadow only at depth 1 |
 | card width | container queries | `split` stacks below 22rem, `Header` wraps below 22rem, the `stat-trend` value changes at 20rem / 36rem |
 
 Card is static: no hover, focus or press of its own.
 
 ## Layout & spacing
 - Grid of cards: `repeat(auto-fit, minmax(min(100%, 14rem), 1fr))`, gap `--prime-space-4`.
-- Padding `--prime-card-padding-m` (20); `Body` gap `--prime-card-gap` (16); fields inside `Body` 20 apart, on the surface field fill.
+- Padding `--prime-card-padding-m` (20); `Body` gap `--prime-card-gap` (16); fields inside `Body` 20 apart, one ladder step off the card.
+- Depth comes from nesting (foundation §4): on the page — the AppShell panel is the page — a card is layer 1 (white in light) with the raised whisper; inside another card it is the next layer, a flat tile. The ladder stops at layer 4.
 - Long values wrap, labels truncate; a chart SVG needs a CSS height.
 - In a `Header` the title takes the free width; a control or a caption after it sits at the end without a wrapper.
 

package/src/components/card/examples/narrow.tsx

@@ -28,7 +28,7 @@ export default function CardNarrowExample() {
                     <Icon name="object.wallet" />
                   </Card.Icon>
                   <Card.Label>Средний чек</Card.Label>
-                  <Card.Value>₽ 2 450</Card.Value>
+                  <Card.Value>2 450 ₽</Card.Value>
                 </div>
               </Card.Body>
             </Card.Root>
@@ -36,7 +36,7 @@ export default function CardNarrowExample() {
           <div className={width.className}>
             <Card.Root variant="stat-trend">
               <Card.Label>Выручка</Card.Label>
-              <Card.Value>₽ 4,2 млн</Card.Value>
+              <Card.Value>4,2 млн ₽</Card.Value>
               <Card.Delta tone="success">+18% к прошлому месяцу</Card.Delta>
             </Card.Root>
           </div>

package/src/components/card/examples/panel-chart.tsx

@@ -23,7 +23,7 @@ export default function CardPanelChartExample() {
         </Card.Header>
         <Card.Body>
           <Typography variant="body-s" tone="secondary">
-            С начала квартала: ₽ 12,6 млн, план выполнен на 84%.
+            С начала квартала: 12,6 млн ₽, план выполнен на 84%.
           </Typography>
         </Card.Body>
         <Card.Media>