prime-ui-kit 0.9.2 → 0.9.3

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./components";
 export * from "./icons";
 export * from "./internal/states";
+export * from "./motion/celebrate";
 export * from "./theme/applyTheme";

package/dist/index.js

@@ -34,7 +34,6 @@ import {
   PageToolbar,
   Pagination,
   Popover,
-  ProgressBar,
   ProgressCircle,
   Radio,
   SegmentedControl,
@@ -42,6 +41,7 @@ import {
   Skeleton,
   Slider,
   SmartFilter,
+  Sparkline,
   Stepper,
   Switch,
   THEME_SWITCHING_ATTRIBUTE,
@@ -53,6 +53,7 @@ import {
   Typography,
   YEARLESS_YEAR,
   applyTheme,
+  celebrate,
   datepickerPresets,
   formatDatepickerValue,
   matchesSmartFilter,
@@ -61,7 +62,7 @@ import {
   suspendTransitions,
   useNotifications,
   useSidebar
-} from "./chunks/chunk-LXGRKN34.js";
+} from "./chunks/chunk-OAE4IQX2.js";
 import {
   Button,
   COLOR_PRESETS,
@@ -74,6 +75,7 @@ import {
   Icon,
   Input,
   Label,
+  ProgressBar,
   ScrollContainer,
   Select,
   Spinner,
@@ -81,13 +83,14 @@ import {
   controlSizes,
   createIcon,
   dataStates,
+  getPasswordStrength,
   paletteColors,
   stepDown,
   textTones,
   tones,
   useOptionalControlSize,
   variants
-} from "./chunks/chunk-ZEFCDEEQ.js";
+} from "./chunks/chunk-6JTZOA5I.js";
 export {
   Accordion,
   AppHeader,
@@ -145,6 +148,7 @@ export {
   Skeleton,
   Slider,
   SmartFilter,
+  Sparkline,
   Spinner,
   Stepper,
   Switch,
@@ -158,11 +162,13 @@ export {
   Typography,
   YEARLESS_YEAR,
   applyTheme,
+  celebrate,
   controlSizes,
   createIcon,
   dataStates,
   datepickerPresets,
   formatDatepickerValue,
+  getPasswordStrength,
   matchesSmartFilter,
   moveBefore,
   paletteColors,

package/dist/internal/CheckMark.d.ts

@@ -0,0 +1,12 @@
+export type CheckMarkState = "checked" | "unchecked" | "indeterminate";
+/**
+ * The kit's check and indeterminate bar, drawn in with a stroke reveal (foundation §7 rule 8: a
+ * check draws in, it does not pop). Both paths stay in the DOM so the mark animates both ways;
+ * `state` picks the one that shows. Color is `currentColor`; size comes from the host box.
+ * Shared by Checkbox and the color swatches. Own SVG instead of `Icon`: the motion needs
+ * `pathLength` on the paths.
+ */
+export declare function CheckMark({ state, className }: {
+    state: CheckMarkState;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/internal/MorphText.d.ts

@@ -0,0 +1,12 @@
+export type MorphTextProps = {
+    children: string;
+    className?: string;
+};
+/**
+ * A label that changes in place (foundation §7 rule 8): the old letters leave upward, the new ones
+ * come from below one short step apart, and the box glides between the two widths. At rest it is
+ * one plain text span; the letter layers exist only while a change plays. Still on the first
+ * render, under reduced motion, and when only digits change (a counter or a percentage in a label
+ * updates in place).
+ */
+export declare function MorphText({ children: text, className }: MorphTextProps): import("react/jsx-runtime").JSX.Element;

package/dist/internal/RollingNumber.d.ts

@@ -0,0 +1,14 @@
+export type RollingNumberProps = {
+    /** The formatted value («4 812 350 ₽», «12», «−3,4%»); digits roll, other characters stay put. */
+    children: string | number;
+    className?: string;
+};
+/**
+ * A number whose digits roll to their new values column by column, like an odometer (foundation §7
+ * rule 8: counters ease, they do not flip). The DOM holds the real digits (text, copy, assistive
+ * tech and a page without CSS read the value); each digit column draws the 0–9 strip in a
+ * pseudo-element. Columns are keyed from the right, so an unchanged digit stays still and a new
+ * leading digit appears without rolling. A value that changes by itself every frame (a running
+ * percentage) stays plain tabular text: rolling there is noise.
+ */
+export declare function RollingNumber({ children, className }: RollingNumberProps): import("react/jsx-runtime").JSX.Element;

package/dist/internal/surfaceDepth.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+/**
+ * Depth of a surface on the ladder (foundation §4): `0` the page … `4` the deepest nested layer,
+ * `floating` for menus, popovers, modals and drawers, `floating-1`/`floating-2` for layers nested in
+ * one, `tinted` for a host off the ladder (a tinted banner, an accent wash). A surface renders
+ * `data-depth` with it; `globals.css` maps each depth to the context variables
+ * (`--prime-color-layer-current`, `--prime-color-field-bg`…).
+ */
+export type SurfaceDepth = 0 | 1 | 2 | 3 | 4 | "floating" | "floating-1" | "floating-2" | "tinted";
+/**
+ * The depth of a surface nested in `depth`; the deepest layer and `floating-2` repeat, a card on a
+ * tinted host is a card on the page.
+ */
+export declare function nextSurfaceDepth(depth: SurfaceDepth): SurfaceDepth;
+/** Depth of the surface the caller renders: one above the nearest surface around it. */
+export declare function useNestedSurfaceDepth(): SurfaceDepth;
+/** Surfaces inside `children` count their depth from `value`. */
+export declare const SurfaceDepthProvider: React.Provider<SurfaceDepth>;
+/**
+ * The layer an ExampleFrame stage stands for (the docs' "preview background"). The stage element
+ * itself takes it as `data-depth`: no wrapper may sit between the stage and the example, because
+ * the stage lays out its children with child selectors (`> *`).
+ */
+export declare const StageDepthProvider: React.Provider<SurfaceDepth>;
+export declare function useStageDepth(): SurfaceDepth;

package/dist/internal/swatch.d.ts

@@ -31,7 +31,10 @@ export declare const swatchTierClass: string;
 export declare function SwatchFill({ value }: {
     value: string | null;
 }): import("react/jsx-runtime").JSX.Element;
-/** Inside a selectable swatch: the color layer and, when selected, the contrasting check. */
+/**
+ * Inside a selectable swatch: the color layer and the contrasting check, which draws in when the
+ * swatch is selected and retracts when it is not (`CheckMark`, the same mark as Checkbox).
+ */
 export declare function SwatchContent({ value, selected }: {
     value: string | null;
     selected: boolean;

package/dist/layout/app-shell/AppShell.d.ts

@@ -7,14 +7,14 @@ export type AppShellRootProps = React.HTMLAttributes<HTMLDivElement> & {
 export type AppShellNavProps = React.HTMLAttributes<HTMLDivElement> & {
     ref?: React.Ref<HTMLDivElement>;
 };
-/** Navigation column (usually `Sidebar.Root`); sits on the canvas. */
+/** Navigation column (usually `Sidebar.Root`, a surface one layer above the page). */
 declare function AppShellNav({ className, ...rest }: AppShellNavProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppShellNav {
     var displayName: string;
 }
 /**
  * Grid: navigation column | content panel. Everything that is not `AppShell.Nav` goes into the
- * content panel (`bg-surface`, inset from the window on wide screens).
+ * content panel, which is the page itself (the layer around the shell): cards on it are the next layer.
  */
 declare function AppShellRoot({ fillViewport, className, children, ...rest }: AppShellRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppShellRoot {

package/dist/motion/celebrate.d.ts

@@ -0,0 +1,18 @@
+export type CelebrateOptions = {
+    /**
+     * Where the burst starts: an element (from its center) or a point in the viewport. Default: the
+     * middle of the screen, a third from the top.
+     */
+    origin?: Element | {
+        x: number;
+        y: number;
+    };
+};
+/**
+ * A short confetti burst for a rare milestone: a quarter closed, the first invoice paid, an
+ * onboarding finished (foundation §7 rule 1 — only rare moments carry delight; never for routine
+ * success, that is a Notification). Draws on a canvas above every layer, ignores the pointer and
+ * assistive tech, and removes itself after 1.4 s. Under reduced motion it draws nothing. Say the
+ * achievement in words too: the burst is decoration. Resolves when the canvas is gone.
+ */
+export declare function celebrate(options?: CelebrateOptions): Promise<void>;

package/dist/tokens/layers.d.ts

@@ -0,0 +1,37 @@
+/** ΔL in OKLab between neighbouring layers. */
+export declare const LAYER_STEP = 0.03;
+/** Layers 0…4: the page and four nested surfaces. */
+export declare const LAYER_DEPTH = 4;
+export type LayerTheme = {
+    /** The page color (layer 0). */
+    page: string;
+    /** Lightness window: no color goes outside it. */
+    lo: number;
+    hi: number;
+    /** Direction of control fills from their host: −1 darker, +1 lighter. */
+    control: 1 | -1;
+};
+export declare const LIGHT_LAYERS: LayerTheme;
+export declare const DARK_LAYERS: LayerTheme;
+export declare const lightnessOf: (hex: string) => number;
+/**
+ * `steps` steps from L towards `dir`. Reflects when less than half a step of room is left (unless
+ * `reflect` is off), snaps to the edge when less than half a step would remain after the move.
+ */
+export declare function move(theme: LayerTheme, L: number, dir: 1 | -1, steps?: number, reflect?: boolean): number;
+export type LayerColors = {
+    /** The layer itself. */
+    bg: string;
+    /** Fields, chips, segmented tracks, neutral buttons on this layer. */
+    fill: string;
+    /** Hover of that fill. */
+    fillHover: string;
+    /** The selected segment (thumb) on a track of this layer. */
+    selected: string;
+};
+/** Layers 0…LAYER_DEPTH of a theme, each one step from its parent. */
+export declare function layerLadder(theme: LayerTheme): LayerColors[];
+/** Floating layers (popovers, menus, modals, drawers) sit one step above a card and never reflect. */
+export declare function floatingLayer(theme: LayerTheme): LayerColors;
+/** Token tree for `color.layer`: `0`…`4` plus `floating` and the two layers nested in it. */
+export declare function layerTokens(theme: LayerTheme): Record<string, LayerColors>;

package/dist/tokens/naming.d.ts

@@ -2,5 +2,5 @@
 export declare const REF_PREFIX = "--prime-ref";
 /** Semantic variables: `--prime-*`. */
 export declare const SYS_PREFIX = "--prime";
-/** Token path → CSS variable: `color.bg.canvas` → `--prime-color-bg-canvas`, camelCase → kebab-case. */
+/** Token path → CSS variable: `color.text.primary` → `--prime-color-text-primary`, camelCase → kebab-case. */
 export declare function toVarName(path: string, prefix?: string): string;

package/dist/tokens/semantic.d.ts

@@ -1,25 +1,13 @@
-/**
- * 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). */
@@ -32,22 +20,18 @@ export declare const semanticTokens: {
             /** 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)";
         };
@@ -105,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;
@@ -326,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";
@@ -561,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}";
@@ -625,10 +599,46 @@ export declare const semanticTokens: {
         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 radius: "{radius.6}";
-        readonly paddingX: "{space.2}";
-        readonly paddingY: "{space.1}";
+        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,11 +1,7 @@
 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. */
@@ -17,8 +13,6 @@ export declare const darkThemeOverrides: {
             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)";
         };
@@ -72,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: {
@@ -83,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,6 +1,6 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.9.2",
+  "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",

package/src/components/accordion/COMPONENT.md

@@ -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/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)