prime-ui-kit 0.9.2 → 0.10.0

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
@@ -40,14 +45,18 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `variant` | `"solid" \| "soft" \| "outline" \| "ghost"` | `"solid"` | Visual treatment. |
-| `tone` | `"accent" \| "neutral" \| "danger" \| "inherit"` | `"accent"` | Meaning of the action; `danger` for destructive actions. `inherit` takes the host's text color for an action on a colored host (a solid Banner); it needs `variant` `ghost`, `soft` or `outline`. |
+| `tone` | `"accent" \| "neutral" \| "success" \| "danger" \| "inherit"` | `"accent"` | Meaning of the action; `danger` for destructive actions; `success` for an action that is done (a payment went through). `inherit` takes the host's text color for an action on a colored host (a solid Banner); it needs `variant` `ghost`, `soft` or `outline`. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier: height 28 · 32 · 36 · 40 · 48, padding, text, icon, radius. Without it the button takes the tier of its host (LoginForm, Popover, a field, a panel with a size), else `m`. |
 | `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
@@ -66,9 +75,11 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | `solid` + `accent` | accent fill, accent-fg text, hover `accent-hover` | the one primary action of an area (Save, Publish) | yes |
 | `solid` + `neutral` | `fill-muted` fill, primary text | a neutral filled action next to fields | |
 | `solid` + `danger` | danger fill, danger-fg text | confirming a destructive action in a dialog | |
+| `solid` + `success` | success fill, success-fg text; a button turning success glides its fill over `fast` | an action that is done: «Оплачено», «Отправлено» | |
 | `soft` + `accent` | `accent-soft` fill, accent text | secondary but highlighted action | |
 | `soft` + `neutral` | translucent `fill-subtle` wash, primary text | secondary actions (Cancel, Filters) | |
 | `soft` + `danger` | `danger-soft` fill, danger text | secondary destructive action | |
+| `soft` / `outline` / `ghost` + `success` | `success-soft` fill or wash, success text | a quieter done state next to other actions | |
 | `outline` + `accent` | transparent, 1px `border-default` inset line, accent text | rare; accent action lighter than solid | |
 | `outline` + `neutral` | transparent, 1px inset line, primary text | secondary action that needs an edge (Draft, Back) | |
 | `outline` + `danger` | 1px inset line, danger text, `danger-soft` on hover | destructive trigger that opens a confirm | |
@@ -109,6 +120,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 +137,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,9 +163,12 @@ 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 that turns green once paid — `children`, `loading`, `tone`. |
 | [on-colored-host.tsx](examples/on-colored-host.tsx) | Actions on a colored strip take its text color: a ghost icon close and a soft action — `tone="inherit"`. |
 | [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`. |
+| [in-form.tsx](examples/in-form.tsx) | A full-width submit button that shows the request in progress after the email passes validation — `type`, `loading`, `fullWidth`. |
 
 ## Mistakes
 - `<Button.Root><Icon name="action.copy" /></Button.Root>` → wrap in `Button.Icon` so the button becomes square and the icon is sized.
@@ -156,6 +177,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/in-form.tsx

@@ -1,27 +1,39 @@
-/** A full-width submit button that shows the request in progress — `type`, `loading`, `fullWidth`. */
+/** A full-width submit button that shows the request in progress after the email passes validation — `type`, `loading`, `fullWidth`. */
 import { Button, Input } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
+/** The email error, or nothing when the address is valid. */
+function emailError(value: string) {
+  if (!value.trim()) return "Введите рабочую почту";
+  if (!/^\S+@\S+\.\S+$/.test(value.trim())) return "Проверьте адрес: нужен вид name@company.ru";
+  return undefined;
+}
+
 export default function ButtonInFormExample() {
   const [sending, setSending] = React.useState(false);
+  const [error, setError] = React.useState<string>();
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
+    const next = emailError(String(new FormData(event.currentTarget).get("email") ?? ""));
+    setError(next);
+    if (next) return;
     setSending(true);
     window.setTimeout(() => setSending(false), 1500);
   };
 
   return (
-    <form className={styles.form} onSubmit={submit}>
-      <Input.Root label="Рабочая почта" required>
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Input.Root label="Рабочая почта" required error={error} reserveSupportRow>
         <Input.Wrapper>
           <Input.Field
             type="email"
             name="email"
             placeholder="name@company.ru"
             autoComplete="email"
+            onValueChange={() => setError(undefined)}
           />
         </Input.Wrapper>
       </Input.Root>

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

@@ -0,0 +1,38 @@
+/** A new label flows into the button letter by letter while the width glides: save, then saved; a step flow that turns green once paid — `children`, `loading`, `tone`. */
+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
+        tone={step === STEPS.length - 1 ? "success" : "accent"}
+        onClick={() => setStep((step + 1) % STEPS.length)}
+      >
+        {STEPS[step]}
+      </Button.Root>
+    </>
+  );
+}

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

@@ -4,6 +4,7 @@ import { Button, Typography } from "prime-ui-kit";
 const TONES = [
   { tone: "accent", label: "Сохранить" },
   { tone: "neutral", label: "Отмена" },
+  { tone: "success", label: "Оплачено" },
   { tone: "danger", label: "Удалить" },
 ] as const;
 

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>

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

@@ -24,7 +24,7 @@ export default function CardVariantsExample() {
 
       <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>
 

package/src/components/checkbox/COMPONENT.md

@@ -103,7 +103,7 @@ Checkbox has no `variant` / `tone` / `color`.
 | unchecked | `checked={false}` / default | `data-state="unchecked"`; box `fill-strong`, hover `fill-strong-hover` |
 | checked | `checked` / `defaultChecked` | `data-state="checked"`; accent box, the check draws in |
 | indeterminate | `indeterminate` | `data-state="indeterminate"`, `input.indeterminate`; accent box with a bar |
-| invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid` on the input; danger ring on the unchecked box and on focus |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid` on the input; danger ring on the unchecked box and on focus; the row shakes once when an error arrives (`data-shake`) |
 | disabled | `disabled` | `data-disabled="true"` on the root; `fill-muted` box, disabled text, `cursor: not-allowed` |
 | read-only | `readOnly` | `aria-readonly="true"` on the input, `data-readonly="true"` on the root; the state stays, no hover or press, default cursor |
 | pressed | pointer press | the box scales to the compact press scale |

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

@@ -41,7 +41,7 @@
   width: min(100%, var(--prime-panel-min-width));
   padding: var(--prime-panel-padding);
   border-radius: var(--prime-panel-radius);
-  background: var(--prime-color-bg-raised);
+  background: var(--prime-color-layer-floating-bg);
   box-shadow: var(--prime-shadow-overlay);
 }
 

package/src/components/code-block/COMPONENT.md

@@ -3,7 +3,7 @@
 **Category:** data-display
 **Kind:** primitive
 
-> A static TypeScript / TSX snippet with syntax highlighting, on a sunken panel or bare inside a host.
+> A static TypeScript / TSX snippet with syntax highlighting, on a filled panel or bare inside a host.
 
 ## When to use
 - Code samples in docs, settings («API key usage») and onboarding.
@@ -37,7 +37,7 @@ CodeBlock        <pre>; variant, colorScheme (data-theme)
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `code` | `string` | — (required) | TS / TSX source; trailing whitespace is trimmed, then highlighted. |
-| `variant` | `"soft" \| "ghost"` | `"soft"` | `soft` — sunken panel with padding and the `code` text role; `ghost` — bare `pre` that inherits type and background from its host. |
+| `variant` | `"soft" \| "ghost"` | `"soft"` | `soft` — a filled panel (one ladder step off its host) with padding and the `code` text role; `ghost` — bare `pre` that inherits type and background from its host. |
 | `colorScheme` | `"light" \| "dark"` | — | Fixes the theme for this block only (`data-theme`). Omit to follow the page theme. |
 | `tabIndex` | `number` | — | Default `0` for `soft` (a scrolling block stays reachable from the keyboard), none for `ghost`; pass `-1` when it never overflows. |
 | `…rest` | `Omit<HTMLAttributes<HTMLPreElement>, "children" \| "dangerouslySetInnerHTML">` | — | `className`, `aria-label` and the other `<pre>` attributes. |
@@ -54,8 +54,8 @@ CodeBlock        <pre>; variant, colorScheme (data-theme)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | — (omitted) | token colors and fill follow the page theme | normal case | yes |
-| `light` | light palette; the soft fill becomes that scheme's `bg-raised` | a light sample inside a dark page | |
-| `dark` | dark palette; the soft fill becomes that scheme's `bg-raised` | a terminal-like sample inside a light page | |
+| `light` | light palette; the soft fill becomes that scheme's floating layer (`layer-floating-bg`) | a light sample inside a dark page | |
+| `dark` | dark palette; the soft fill becomes that scheme's floating layer (`layer-floating-bg`) | a terminal-like sample inside a light page | |
 
 Syntax tokens: keywords purple (weight 500), strings teal, numbers orange, JSX tags blue, comments muted italic — palette text tokens, readable in both themes.
 
@@ -92,8 +92,8 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | An API response sample on a sunken panel, named for screen readers — `code`, `aria-label`. |
-| [variants.tsx](examples/variants.tsx) | A sunken panel and a bare block that takes type and background from its host — `variant`. |
+| [overview.tsx](examples/overview.tsx) | An API response sample on a filled panel, named for screen readers — `code`, `aria-label`. |
+| [variants.tsx](examples/variants.tsx) | A filled panel and a bare block that takes type and background from its host — `variant`. |
 | [color-scheme.tsx](examples/color-scheme.tsx) | A block fixed to one scheme looks the same in both page themes — `colorScheme`. |
 | [narrow.tsx](examples/narrow.tsx) | In a narrow column a long line scrolls inside the block and never wraps; Tab, then arrow keys. |
 

package/src/components/code-block/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** An API response sample on a sunken panel, named for screen readers — `code`, `aria-label`. */
+/** An API response sample on a filled panel, named for screen readers — `code`, `aria-label`. */
 import { CodeBlock } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/src/components/code-block/examples/variants.tsx

@@ -1,4 +1,4 @@
-/** A sunken panel and a bare block that takes type and background from its host — `variant`. */
+/** A filled panel and a bare block that takes type and background from its host — `variant`. */
 import { CodeBlock, Typography } from "prime-ui-kit";
 
 const SAMPLE = `const total = formatPrice(14990);`;

package/src/components/color-picker/COMPONENT.md

@@ -211,7 +211,7 @@ No `variant` / `tone` / `color`.
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `none` | parts stacked with a 12px gap, no own background | inside a Popover or a Card | yes |
-| `raised` | `bg-raised`, panel radius and padding, `shadow-overlay`; fields switch to `field-bg-surface` | a standalone panel on the page | |
+| `raised` | the floating layer of the ladder (`data-depth="floating"`), panel radius and padding, `shadow-overlay`; fields take that layer's fill | a standalone panel on the page | |
 
 ### defaultFormat (ColorPicker.Root)
 | Value | Looks like | Use when | Default |
@@ -307,13 +307,13 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 | [overview.tsx](examples/overview.tsx) | A color field: a hex value and a swatch button that opens the picker panel — `ColorPicker.HexInput`, `ColorPicker.TriggerSwatch`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size of the hex field with a swatch button of the same tier — `size`. |
 | [states.tsx](examples/states.tsx) | A disabled area and hue slider keep showing the color but take no input — `disabled`. |
-| [validation.tsx](examples/validation.tsx) | A hint under the hex field and an error that replaces it; invalid text reverts on blur — `hint`, `error`. |
+| [validation.tsx](examples/validation.tsx) | A button color checked live: a too light color shakes in an error that leaves once the color is darker; a hint under the other field, invalid text reverts on blur — `hint`, `error`. |
 | [panel.tsx](examples/panel.tsx) | The full raised panel and its part order: format, area, hue and alpha sliders, channels, brand swatches — `ColorPicker.Panel`, `surface`, `ColorPicker.Swatches`. |
 | [formats.tsx](examples/formats.tsx) | The channel strip in each value format; three pickers edit one color — `defaultFormat`, `ColorPicker.ChannelStrip`. |
 | [presets.tsx](examples/presets.tsx) | A quick color from the palette: a square trigger next to a field and a Button trigger; «no color» allowed — `ColorPresets`, `allowEmpty`, `asChild`. |
 | [presets-sizes.tsx](examples/presets-sizes.tsx) | The preset trigger in every size, a square of the control height next to an input of the same tier — `ColorPresets`, `size`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the color: brand swatches and the hex field edit it, a button resets it — `value`, `onValueChange`. |
-| [in-form.tsx](examples/in-form.tsx) | Theme settings: the color goes with the form and a too light color fails on save — `value`, `error`. |
+| [in-form.tsx](examples/in-form.tsx) | Theme settings: the color goes with the form, a too light color shakes in an error on save that leaves once the color changes — `value`, `error`. |
 
 ## Mistakes
 - Trigger in one `ColorPicker.Root` and panel in another → they will not share the color; wrap both in one Root.

package/src/components/color-picker/examples/in-form.tsx

@@ -1,5 +1,5 @@
-/** Theme settings: the color goes with the form and a too light color fails on save — `value`, `error`. */
-import { Button, Input } from "prime-ui-kit";
+/** Theme settings: the color goes with the form, a too light color shakes in an error on save that leaves once the color changes — `value`, `error`. */
+import { Button, Input, Typography } from "prime-ui-kit";
 import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
 import * as React from "react";
 
@@ -10,13 +10,15 @@ const MAX_LIGHTNESS = 80;
 export default function ColorPickerInFormExample() {
   const [color, setColor] = React.useState(() => parseColor("#f2f2f2"));
   const [error, setError] = React.useState<string>();
+  const [saved, setSaved] = React.useState(false);
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
     const lightness = color.toFormat("hsl").getChannelValue("lightness");
-    setError(
-      lightness > MAX_LIGHTNESS ? "Слишком светлый: белый текст на нём не читается" : undefined,
-    );
+    const next =
+      lightness > MAX_LIGHTNESS ? "Слишком светлый: белый текст на нём не читается" : undefined;
+    setError(next);
+    setSaved(next === undefined);
   };
 
   return (
@@ -31,11 +33,17 @@ export default function ColorPickerInFormExample() {
         onValueChange={(next) => {
           setColor(next);
           setError(undefined);
+          setSaved(false);
         }}
       >
         <ColorPicker.HexInput label="Цвет кнопок" error={error} />
       </ColorPicker.Root>
       <input type="hidden" name="buttonColor" value={color.toString("hex")} />
+      {saved ? (
+        <Typography as="p" variant="body-s" tone="secondary" role="status">
+          Тема сохранена.
+        </Typography>
+      ) : null}
       <div className={styles.actions}>
         <Button.Root type="submit">Сохранить тему</Button.Root>
       </div>

package/src/components/color-picker/examples/validation.tsx

@@ -1,16 +1,22 @@
-/** A hint under the hex field and an error that replaces it; invalid text reverts on blur — `hint`, `error`. */
-import { ColorPicker } from "prime-ui-kit/color-picker";
+/** A button color checked live: a too light color shakes in an error that leaves once the color is darker; a hint under the other field, invalid text reverts on blur — `hint`, `error`. */
+import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
+import * as React from "react";
+
+const MAX_LIGHTNESS = 80;
 
 export default function ColorPickerValidationExample() {
+  const [color, setColor] = React.useState(() => parseColor("#f5f5f5"));
+  const tooLight = color.toFormat("hsl").getChannelValue("lightness") > MAX_LIGHTNESS;
+
   return (
     <>
       <ColorPicker.Root defaultValue="#0090ff">
         <ColorPicker.HexInput label="Цвет ссылок" hint="Формат #RRGGBB или #RRGGBBAA" />
       </ColorPicker.Root>
-      <ColorPicker.Root defaultValue="#f5f5f5">
+      <ColorPicker.Root value={color} onValueChange={setColor}>
         <ColorPicker.HexInput
           label="Цвет кнопок"
-          error="Слишком светлый: белый текст на нём не читается"
+          error={tooLight ? "Слишком светлый: белый текст на нём не читается" : undefined}
         />
       </ColorPicker.Root>
     </>

package/src/components/color-swatches/COMPONENT.md

@@ -48,7 +48,7 @@ ColorSwatches                 field frame: label → swatches → hint | error
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the swatches. Hidden while `error` is shown. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
-| `invalid` | `boolean` | — | Danger selection ring and `aria-invalid`. A non-empty `error` implies it. |
+| `invalid` | `boolean` | — | Danger inner edge on every swatch and `aria-invalid`. A non-empty `error` implies it. |
 | `disabled` | `boolean` | `false` | Disables every swatch (grey, half transparent). |
 | `allowEmpty` | `boolean` | `false` | Adds the «no color» checkerboard swatch after the presets (value `null`). |
 | `name` | `string` | — | Form field name: a hidden input submits the selected color (empty string for no color). |
@@ -76,7 +76,7 @@ ColorSwatches                 field frame: label → swatches → hint | error
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `allowEmpty` | an extra checkerboard swatch «Без цвета» at the end | the color is optional | `false` |
-| `invalid` | the selection ring turns danger | the message is shown elsewhere; otherwise pass `error` | — |
+| `invalid` | the inner edge of every swatch turns danger | the message is shown elsewhere; otherwise pass `error` | — |
 | `disabled` | every swatch grey at half opacity | the choice is unavailable | `false` |
 
 **Combinations**
@@ -87,17 +87,17 @@ ColorSwatches                 field frame: label → swatches → hint | error
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| selected | `value` / `defaultValue` | `aria-checked="true"`, `data-state="checked"` on the radio; 2px accent ring with a 2px gap and a check mark (light or dark by color contrast) |
+| selected | `value` / `defaultValue` | `aria-checked="true"`, `data-state="checked"` on the radio; the check mark (light or dark by color contrast) scales in from half size (`base` · emphasized) and leaves faster (`fast` · exit); no ring — the check is the selection |
 | hover | pointer | the swatch scales to 1.08 (fine pointers only) |
 | focus-visible | keyboard | focus ring outside the swatch |
-| invalid | `invalid` / `error` | `aria-invalid`, `data-invalid` on the group; the selected ring turns `danger-border` |
+| invalid | `invalid` / `error` | `aria-invalid`, `data-invalid` on the group; the inner edge of every swatch turns `danger-border`; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | native `disabled` on every radio, `aria-disabled` and `data-disabled` on the group |
 
 Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 
 ## Layout & spacing
 - The swatches take the container width and wrap to new rows by themselves; no column count to set. In a content-sized container they stay in one row.
-- The selection / focus rings sit outside the swatches; kit hosts (Modal / Drawer body, panels, cards) already keep `--prime-focus-space` padding, so the rings are never clipped. In your own `overflow` container, keep that padding.
+- The keyboard focus ring sits outside the swatches; kit hosts (Modal / Drawer body, panels, cards) already keep `--prime-focus-space` padding, so the ring is never clipped. In your own `overflow` container, keep that padding.
 - Label → swatches and swatches → hint use the tier `label-gap` / `hint-gap`; field → field 20.
 
 ## Accessibility
@@ -132,7 +132,7 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 | [states.tsx](examples/states.tsx) | A default palette next to an invalid and a disabled one — `invalid`, `disabled`. |
 | [wrapping.tsx](examples/wrapping.tsx) | In a narrow column the swatches wrap by themselves and the arrows move by the visual rows. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the color, «no color» included, and names it in the hint — `value`, `onValueChange`, `allowEmpty`. |
-| [in-form.tsx](examples/in-form.tsx) | A calendar event form: the color is submitted by `name` and required on save — `name`, `required`, `error`. |
+| [in-form.tsx](examples/in-form.tsx) | A calendar event form: the color is submitted by `name` and required on save: submitting an empty title or no color shakes the field, picking or typing clears the error — `name`, `required`, `error`. |
 
 ## Mistakes
 - `<ColorSwatches.Root>` → the component is a single export: `<ColorSwatches />`.

package/src/components/color-swatches/examples/in-form.tsx

@@ -1,23 +1,29 @@
-/** A calendar event form: the color is submitted by `name` and required on save — `name`, `required`, `error`. */
+/** A calendar event form: the color is submitted by `name` and required on save: submitting an empty title or no color shakes the field, picking or typing clears the error — `name`, `required`, `error`. */
 import { Button, ColorSwatches, Input } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 export default function ColorSwatchesInFormExample() {
+  const [titleError, setTitleError] = React.useState<string>();
   const [error, setError] = React.useState<string>();
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
-    const color = new FormData(event.currentTarget).get("color");
-    setError(color ? undefined : "Выберите цвет события");
+    const data = new FormData(event.currentTarget);
+    setTitleError(String(data.get("title") ?? "").trim() ? undefined : "Введите название события");
+    setError(data.get("color") ? undefined : "Выберите цвет события");
   };
 
   return (
     <form className={styles.form} noValidate onSubmit={submit}>
-      <Input.Root label="Название события" required>
+      <Input.Root label="Название события" required error={titleError} reserveSupportRow>
         <Input.Wrapper>
-          <Input.Field name="title" defaultValue="Встреча с поставщиком" />
+          <Input.Field
+            name="title"
+            defaultValue="Встреча с поставщиком"
+            onValueChange={() => setTitleError(undefined)}
+          />
         </Input.Wrapper>
       </Input.Root>
       <ColorSwatches

package/src/components/command-menu/COMPONENT.md

@@ -111,7 +111,7 @@ CommandMenu.Root                 Modal + top-aligned palette panel, query state
 | `keys` | `ReactNode[]` | — (required) | FooterHint: the keys (text or icons). |
 
 ## Variants
-One look: `bg-raised`, `--prime-modal-radius`, `shadow-modal`, `--prime-modal-width-l` wide, placed in the top part of the viewport so the search row never jumps while the list filters.
+One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radius`, `shadow-modal`, `--prime-modal-width-l` wide, placed in the top part of the viewport so the search row never jumps while the list filters.
 
 ### size (Root)
 | Value | Looks like | Use when | Default |