prime-ui-kit 0.9.2 → 0.10.0

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,19 +62,19 @@ import {
   suspendTransitions,
   useNotifications,
   useSidebar
-} from "./chunks/chunk-LXGRKN34.js";
+} from "./chunks/chunk-K4FACFQ2.js";
 import {
   Button,
   COLOR_PRESETS,
   Checkbox,
   ColorSwatches,
-  ControlSizeProvider,
   Divider,
   EmptyPage,
   Hint,
   Icon,
   Input,
   Label,
+  ProgressBar,
   ScrollContainer,
   Select,
   Spinner,
@@ -81,13 +82,17 @@ import {
   controlSizes,
   createIcon,
   dataStates,
+  getPasswordStrength,
   paletteColors,
   stepDown,
   textTones,
   tones,
-  useOptionalControlSize,
   variants
-} from "./chunks/chunk-ZEFCDEEQ.js";
+} from "./chunks/chunk-4TRNUP45.js";
+import {
+  ControlSizeProvider,
+  useOptionalControlSize
+} from "./chunks/chunk-GFKDZFQR.js";
 export {
   Accordion,
   AppHeader,
@@ -145,6 +150,7 @@ export {
   Skeleton,
   Slider,
   SmartFilter,
+  Sparkline,
   Spinner,
   Stepper,
   Switch,
@@ -158,11 +164,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/ChoiceField.d.ts

@@ -1,5 +1,5 @@
 import type * as React from "react";
-import type { FieldIds } from "@/internal/FieldFrame";
+import { type FieldIds } from "@/internal/FieldFrame";
 import type { ControlSize, DataState } from "@/internal/states";
 /** Class of the visually hidden native input that sits on top of the visual control. */
 export declare const choiceInputClass: string;

package/dist/internal/FieldFrame.d.ts

@@ -48,6 +48,23 @@ export declare function useFieldFrame(explicitId: string | undefined, { label, h
     error?: React.ReactNode;
     invalid?: boolean;
 }, ariaDescribedBy?: string): FieldIds;
+/**
+ * `data-shake` of a field root: the control shakes once when the field turns invalid or its error
+ * message changes (foundation §7, rule 14) — never for an error it mounts with. The value
+ * alternates between `odd` and `even` so a new error restarts the keyframes.
+ */
+export declare function useErrorShake(invalid: boolean, error: React.ReactNode): "odd" | "even" | undefined;
+/**
+ * The error that has just been fixed, kept on screen while it fades out (`fast`, `exit`) so the
+ * message leaves as smoothly as it arrived; the hint takes the slot after it. `null` when nothing
+ * is leaving. Reduced motion drops it at once.
+ */
+export declare function useLeavingError(showError: boolean, error: React.ReactNode): {
+    node: React.ReactNode;
+    onExitEnd: (event: React.SyntheticEvent<Element>) => void;
+} | null;
+/** Class of the leaving error message (`useLeavingError`), for frames that render their own row. */
+export declare const leavingErrorClass: string;
 type FieldFrameRenderProps = Omit<FieldFrameProps, "focusRing"> & {
     size: ControlSize;
     ids: FieldIds;

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/primitives.d.ts

@@ -68,6 +68,7 @@ export declare const primitiveTokens: {
             readonly 400: "#4ade80";
             readonly 500: "#22c55e";
             readonly 700: "#15803d";
+            readonly 800: "#166534";
         };
         readonly teal: {
             readonly 100: "#ccfbf1";

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)";
         };
@@ -88,6 +72,7 @@ export declare const semanticTokens: {
         };
         readonly success: {
             readonly default: "{color.green.700}";
+            readonly hover: "{color.green.800}";
             readonly fg: "{color.white}";
             readonly soft: "{color.green.100}";
             readonly text: "{color.green.700}";
@@ -105,39 +90,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 +301,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 +538,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 +600,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)";
         };
@@ -55,6 +49,7 @@ export declare const darkThemeOverrides: {
         };
         readonly success: {
             readonly default: "{color.green.400}";
+            readonly hover: "{color.green.300}";
             readonly fg: "{color.gray.950}";
             readonly soft: "color-mix(in srgb, var(--prime-ref-color-green-500) 16%, transparent)";
             readonly text: "{color.green.300}";
@@ -72,10 +67,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 +74,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.10.0",
   "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",
@@ -60,7 +60,8 @@
     "src/layout/**/COMPONENT.md",
     "src/components/**/examples/**",
     "src/layout/**/examples/**",
-    "LICENSE"
+    "LICENSE",
+    "THIRD_PARTY_NOTICES"
   ],
   "publishConfig": {
     "access": "public"
@@ -105,6 +106,10 @@
       "types": "./dist/color-picker.d.ts",
       "default": "./dist/color-picker.js"
     },
+    "./icons": {
+      "types": "./dist/icon-set.d.ts",
+      "default": "./dist/icons.js"
+    },
     "./bundle.css": "./dist/index.css",
     "./fonts.css": "./src/styles/fonts.css",
     "./reset.css": "./src/styles/reset.css",
@@ -113,9 +118,11 @@
     "./theme-dark.css": "./src/styles/theme-dark.css"
   },
   "scripts": {
-    "clean": "rm -rf dist .dts-stage playground/dist",
+    "clean": "rm -rf dist dist-skill .dts-stage playground/dist",
     "tokens:build": "bun run scripts/build-tokens.ts",
     "docs:build": "bun run scripts/build-docs.ts",
+    "icons:add": "bun run scripts/add-glyph.ts",
+    "skill:build": "bun run scripts/build-skill.ts",
     "build": "bun run tokens:build && bun run scripts/bundle-lib.ts",
     "prepublishOnly": "bun run clean && bun run build",
     "playground:dev": "vite playground --config playground/vite.config.ts",
@@ -125,7 +132,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "verify": "bun run check:ci && bun run typecheck && bun run test && bun run verify:tokens && bun run build",
+    "verify": "bun run check:ci && bun run typecheck && bun run test && bun run verify:tokens && bun run build && bun run skill:build",
     "verify:tokens": "bun run tokens:build && git diff --exit-code -- src/styles/tokens.css src/styles/theme-light.css src/styles/theme-dark.css"
   },
   "sideEffects": [

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