prime-ui-kit 0.9.2 → 0.10.0

package/src/components/crossfade/examples/overview.tsx

@@ -16,9 +16,9 @@ import styles from "./examples.module.css";
 type Status = "loading" | "ready" | "empty" | "error";
 
 const PAYMENTS = [
-  { id: "p1", payer: "ООО «Гранит»", amount: "₽ 94 750" },
-  { id: "p2", payer: "ИП Орлов Д. С.", amount: "₽ 18 000" },
-  { id: "p3", payer: "АО «Альфа Медиа»", amount: "₽ 380 000" },
+  { id: "p1", payer: "ООО «Гранит»", amount: "94 750 ₽" },
+  { id: "p2", payer: "ИП Орлов Д. С.", amount: "18 000 ₽" },
+  { id: "p3", payer: "АО «Альфа Медиа»", amount: "380 000 ₽" },
 ];
 
 export default function CrossfadeOverviewExample() {

package/src/components/data-table/COMPONENT.md

@@ -150,8 +150,8 @@ Heads keep `start` whatever the cell alignment, with the sort icon at the end ed
 | `rowDividers` | hairlines between rows | default; off together with `striped` | `true` |
 | `columnDividers` | hairlines between content columns (none inside the lead columns) | default; off for 2–3 column key/value lists | `true` |
 | `striped` | every second row one opaque step off the fill | long numeric grids | `false` |
-| `highlightRowOnHover` | `fill-subtle` wash on the hovered row | interactive lists | `true` |
-| `highlightColumnOnHover` | `fill-subtle` wash on the hovered column | comparison tables | `false` |
+| `highlightRowOnHover` | `fill-subtle-active` wash on the hovered row (stronger than a zebra step, so a hovered row never takes a zebra row's color) | interactive lists | `true` |
+| `highlightColumnOnHover` | `fill-subtle-active` wash on the hovered column | comparison tables | `false` |
 | `stickyHeader` · `stickyFirstColumn` | opaque sticky head / first column with a hairline edge; on screens lower than 480px the head scrolls with the rows | long / wide tables in a `scrollHeight` window | `false` |
 | column `hideable` | `false`: the column stays even when listed in `hiddenColumns` | the key column that names the row | `true` |
 | `showHeader` | head row shown | off only for self-explanatory key/value tables | `true` |
@@ -169,7 +169,8 @@ Heads keep `start` whatever the cell alignment, with the sort icon at the end ed
 | sorted | `sort` / `defaultSort` | `aria-sort` and `data-sorted` on the head; the sort icon: unsorted `text-disabled`, hover `text-muted`, sorted `text-secondary` — never accent |
 | selected | `selected` / `defaultSelected` | `aria-selected` rows with `accent-soft` fill; polite `labels.selectedCount` |
 | expanded | `expanded` / `defaultExpanded` | `data-expanded` on the parent row (one step darker); toggle `aria-expanded`, chevron turns 90° |
-| new rows | rows mounted by an expand or new in `rows` (by `getRowKey`) | `data-animate`: cells drop in from above (`enterMotion`); detail panels open and close through `grid-template-rows` (`data-state` on the detail row; it unmounts after the close) |
+| new rows | rows new in `rows` (by `getRowKey`) | `data-animate`: top-level cells drop in from above (`enterMotion`) |
+| sub-rows and detail panels | an expand / a collapse | both fold open and shut through `grid-template-rows` (0fr ↔ 1fr) with the fade on the same `base` curve; the row height and padding live inside the track, so nothing is left to jump. Sub-rows: `data-fold` on the row (`opening` · `open` · `closed`); a collapsed row's sub-rows stay mounted until the fold ends. Detail row: `data-state`; it unmounts after the close |
 | overflowing sideways | the table is wider than its viewport | `data-overflow-start` (scrolled from the start) and `data-overflow-end` (more to the end) on the root: a soft shadow over that edge, from the end edge of the sticky first column for the start; fades in and out over `fast` |
 | hidden columns | `hiddenColumns` | the listed columns (except `hideable: false`) are not rendered in the head, rows, skeleton or state rows; widths are measured again |
 | state swap | the body moves between loading, rows, empty and error | the body fades in over `base` (opacity only, the same swap motion as [Crossfade](../crossfade/COMPONENT.md)); the head stays still; nothing moves on the first render |
@@ -177,7 +178,7 @@ Heads keep `start` whatever the cell alignment, with the sort icon at the end ed
 Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data-sticky-header`, `data-sticky-first-column`, `data-table-width` (`fill` · `auto` · `grow`), `data-highlight-row`, `data-highlight-column`, `data-striped`, `data-loading`, `data-selectable`, `data-expandable`, `data-dragging` (while drag-selecting), `data-overflow-start` · `data-overflow-end` (edges that hide columns). Sorting and paging swap rows instantly; everything is still under `prefers-reduced-motion`.
 
 ## Layout & spacing
-- The root fills its container on `--prime-color-card-bg`, radius 12, and clips full-bleed head and rows; on a card or a modal it becomes a sunken block — never wrap it in a Card.
+- The root is a layer of the surface ladder (`data-depth`, one above its host): it fills its container on `--prime-color-layer-current`, radius 12, and clips full-bleed head and rows; zebra rows and the sticky column are one ladder step off it, the head two. On a card or in a modal it is the next layer by itself — never wrap it in a Card.
 - Toolbar padding `--prime-space-3` × cell padding, items `gap: --prime-space-2`; below 30rem of table width toolbar and footer stack.
 - The footer has a hairline on top: range on the left, Pagination on the right. The range shows only with more than one page or with infinite scroll.
 - Columns scroll sideways inside the table, never the page; pin the identifying column with `stickyFirstColumn`. Works from 320 px.

package/src/components/datepicker/COMPONENT.md

@@ -140,7 +140,7 @@ Shared by `Datepicker.Root` and `Datepicker.Panel`.
 | empty | no value | `data-empty="true"`, `labels.placeholder` (or `placeholder`) in placeholder color |
 | open | click, `open` | `data-state="open"`, `field-bg-focus` fill, the chevron turns |
 | focus-visible | keyboard | inset focus ring; none with `focusRing={false}` (`data-focus-ring="false"`) |
-| invalid | `invalid`, `error` | `data-invalid`, `aria-invalid`, inset `danger-border` ring |
+| invalid | `invalid`, `error` | `data-invalid`, `aria-invalid`, inset `danger-border` ring; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | native `disabled`, `data-disabled`, `field-bg-disabled`, cannot open |
 | today | the current day | `data-today`, `aria-current="date"`, accent text |
 | selected / band | value | day `aria-pressed`, `data-edge`; cell `data-band="selected" \| "preview"`, `data-band-start` / `-end` |
@@ -201,13 +201,13 @@ Panel DOM: `data-size`, `data-embedded`, `data-compact`, `data-layout` (`aside`
 | [overview.tsx](examples/overview.tsx) | A shipping date field: a click opens one month, a picked day applies at once — `mode`, `label`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: the field is 28 to 48 px high, the day cell of the panel 24 to 40 px — `size`. |
 | [states.tsx](examples/states.tsx) | An empty field with the default placeholder, a filled one and a disabled one — `disabled`. |
-| [validation.tsx](examples/validation.tsx) | A required leave period with a hint, the same field with an error and an optional return date — `required`, `hint`, `error`, `optional`. |
+| [validation.tsx](examples/validation.tsx) | A leave period checked live: the error shakes in, names the broken rule and leaves once the period fits; an optional return date — `required`, `hint`, `error`, `optional`. |
 | [range-presets.tsx](examples/range-presets.tsx) | A report period: presets aside, two months, a step prompt, time fields with Reset / Apply, no future days — `presets`, `months`, `prompt`, `footer`, `withTime`, `disableFuture`. |
 | [inline-panel.tsx](examples/inline-panel.tsx) | A booking calendar embedded in the page: its own card, two months when the parent has room, the range applies at once — `Datepicker.Panel`, `months`, `prompt`. |
 | [yearless.tsx](examples/yearless.tsx) | An annual price change date: day and month without a year, a value prefix and taken days disabled — `yearless`, `valuePrefix`, `isDayDisabled`. |
 | [controlled.tsx](examples/controlled.tsx) | A report filter owns the period: quick buttons set it from outside, the field shows it — `value`, `onValueChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the panel: a reminder button opens the calendar from code, a picked day closes it — `open`, `onOpenChange`. |
-| [in-form.tsx](examples/in-form.tsx) | A leave request form: a required period that turns into an error after submit and an optional return date — `required`, `error`, `optional`. |
+| [in-form.tsx](examples/in-form.tsx) | A leave request form: submit checks the required period, the error shakes in and leaves once the period is fixed; an optional return date — `required`, `error`, `optional`. |
 | [narrow.tsx](examples/narrow.tsx) | An embedded panel in a 320 px column: one compact month instead of two, the footer fields wrap above the buttons — `months`, `footer`. |
 
 ## Mistakes

package/src/components/datepicker/examples/in-form.tsx

@@ -1,13 +1,15 @@
-/** A leave request form: a required period that turns into an error after submit and an optional return date — `required`, `error`, `optional`. */
-import { Button, Card, Datepicker, type DatepickerRange } from "prime-ui-kit";
+/** A leave request form: submit checks the required period, the error shakes in and leaves once the period is fixed; an optional return date — `required`, `error`, `optional`. */
+import { Button, Card, Datepicker, type DatepickerRange, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
+const EMPTY_PERIOD: DatepickerRange = { from: null, to: null };
+
 export default function DatepickerInFormExample() {
-  const [period, setPeriod] = React.useState<DatepickerRange>({ from: null, to: null });
-  const [submitted, setSubmitted] = React.useState(false);
-  const missing = submitted && (!period.from || !period.to);
+  const [period, setPeriod] = React.useState<DatepickerRange>(EMPTY_PERIOD);
+  const [error, setError] = React.useState<string>();
+  const [sent, setSent] = React.useState(false);
 
   return (
     <Card.Root className={styles.formCard}>
@@ -15,7 +17,9 @@ export default function DatepickerInFormExample() {
         className={styles.form}
         onSubmit={(event) => {
           event.preventDefault();
-          setSubmitted(true);
+          const complete = Boolean(period.from && period.to);
+          setError(complete ? undefined : "Укажите начало и конец отпуска");
+          setSent(complete);
         }}
       >
         <Datepicker.Root
@@ -23,17 +27,34 @@ export default function DatepickerInFormExample() {
           label="Период отпуска"
           required
           hint="Не больше 28 дней подряд"
-          error={missing ? "Укажите начало и конец отпуска" : undefined}
+          error={error}
           value={period}
-          onValueChange={setPeriod}
+          onValueChange={(next) => {
+            setPeriod(next);
+            setError(undefined);
+            setSent(false);
+          }}
           months={2}
           footer
           placeholder="Выбрать период"
           fullWidth
         />
         <Datepicker.Root mode="single" label="Выход на работу" optional fullWidth />
+        {sent ? (
+          <Typography as="p" variant="body-s" tone="secondary" role="status">
+            Заявка отправлена на согласование.
+          </Typography>
+        ) : null}
         <div className={styles.actions}>
-          <Button.Root variant="ghost" tone="neutral">
+          <Button.Root
+            variant="ghost"
+            tone="neutral"
+            onClick={() => {
+              setPeriod(EMPTY_PERIOD);
+              setError(undefined);
+              setSent(false);
+            }}
+          >
             Отмена
           </Button.Root>
           <Button.Root type="submit">Отправить заявку</Button.Root>

package/src/components/datepicker/examples/validation.tsx

@@ -1,7 +1,22 @@
-/** A required leave period with a hint, the same field with an error and an optional return date — `required`, `hint`, `error`, `optional`. */
-import { Datepicker } from "prime-ui-kit";
+/** A leave period checked live: the error shakes in, names the broken rule and leaves once the period fits; an optional return date — `required`, `hint`, `error`, `optional`. */
+import { Datepicker, type DatepickerRange } from "prime-ui-kit";
+import * as React from "react";
+
+const MAX_DAYS = 28;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const LONG_PERIOD: DatepickerRange = { from: new Date(2026, 6, 1), to: new Date(2026, 7, 4) };
+
+/** The period error, or nothing when both ends are set and the period fits the limit. */
+function periodError({ from, to }: DatepickerRange) {
+  if (!from || !to) return "Укажите начало и конец отпуска";
+  if ((to.getTime() - from.getTime()) / DAY_MS + 1 > MAX_DAYS)
+    return "Больше 28 дней подряд нельзя";
+  return undefined;
+}
 
 export default function DatepickerValidationExample() {
+  const [period, setPeriod] = React.useState<DatepickerRange>(LONG_PERIOD);
+
   return (
     <>
       <Datepicker.Root
@@ -10,14 +25,9 @@ export default function DatepickerValidationExample() {
         required
         hint="Не больше 28 дней подряд"
         placeholder="Выбрать период"
-        fullWidth
-      />
-      <Datepicker.Root
-        mode="range"
-        label="Период отпуска"
-        required
-        error="Укажите начало и конец отпуска"
-        placeholder="Выбрать период"
+        value={period}
+        onValueChange={setPeriod}
+        error={periodError(period)}
         fullWidth
       />
       <Datepicker.Root mode="single" label="Выход на работу" optional fullWidth />

package/src/components/digit-input/COMPONENT.md

@@ -44,6 +44,7 @@ DigitInput            field frame: label row → cells → support row (hint | e
 | `hint` | `ReactNode` | — | Help text under the cells. Hidden while `error` is shown. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | — | Danger ring and danger digits on every cell, `aria-invalid`. A non-empty `error` implies it. |
+| `success` | `boolean` | `false` | The code was accepted (after the server checked it): the cells turn success one after another. Ignored while invalid. Say it in words too (`hint`). |
 | `disabled` | `boolean` | — | Disables the fieldset and every cell. |
 | `value` | `string` | — | Controlled code; non-digits are dropped, extra digits cut to `length`. |
 | `defaultValue` | `string` | `""` | Initial code when uncontrolled. |
@@ -92,11 +93,12 @@ No `variant` or `tone`.
 | State | Driven by | DOM |
 |---|---|---|
 | hover | — | cell fill darkens (not on focused or disabled cells) |
-| focus | keyboard / click | focused cell: focus fill + inset focus ring; its content is selected so a new digit replaces it |
-| filled cell | a digit in the cell | `data-filled="true"` on the cell |
+| focus | keyboard / click | focused cell: focus fill and its content selected so a new digit replaces it; one inset ring for the row appears on the cell and glides to the next one (`fast` · emphasized) instead of each cell drawing its own |
+| filled cell | a digit in the cell | `data-filled="true"` on the cell; the digit fades in as it lands |
+| success | `success` (not while invalid) | `data-success="true"` on the fieldset; the cells turn `success-soft` one after another, half a stagger step apart |
 | full width | `fullWidth` | `data-full-width="true"` on the fieldset |
 | group start | `groupSize` | `data-group-start="true"` on the first cell of every group |
-| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the fieldset and the frame, `aria-invalid="true"` on cells |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the fieldset and the frame, `aria-invalid="true"` on cells; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | `data-disabled="true"` and native `disabled` on the fieldset, every cell disabled, label and hint dimmed |
 | no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the fieldset |
 
@@ -139,12 +141,12 @@ No `variant` or `tone`.
 | [overview.tsx](examples/overview.tsx) | A six-digit code from SMS with its label and a hint — `label`, `hint`, `length`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size; the cell is a square on its own scale, two steps above the control heights — `size`. |
 | [states.tsx](examples/states.tsx) | A default code next to a disabled one — `disabled`. |
-| [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint and an error that replaces it — `required`, `optional`, `hint`, `error`. |
+| [validation.tsx](examples/validation.tsx) | A confirmation code checked once it is complete: a wrong code shakes in with one message and leaves as soon as you type again; a hint and an optional code — `required`, `optional`, `hint`, `error`. |
 | [grouped.tsx](examples/grouped.tsx) | A long code read in chunks with a wider gap between groups — `groupSize`. |
 | [full-width.tsx](examples/full-width.tsx) | Cells that share the container width and keep the tier height, above a full-width button — `fullWidth`. |
-| [on-complete.tsx](examples/on-complete.tsx) | The code is checked as soon as the last cell is filled; a wrong code turns the hint into an error — `onComplete`, `error`. |
+| [on-complete.tsx](examples/on-complete.tsx) | The code is checked as soon as the last cell is filled: a right one turns the cells success, a wrong one turns the hint into an error — `onComplete`, `success`, `error`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the code and clears it with a button — `value`, `onValueChange`. |
-| [in-form.tsx](examples/in-form.tsx) | A masked card PIN submitted with a form; a short PIN shows an error — `name`, `mask`, `required`, `error`. |
+| [in-form.tsx](examples/in-form.tsx) | A masked card PIN submitted with a form; a short or wrong PIN shakes in an error that leaves when you type again — `name`, `mask`, `required`, `error`. |
 
 ## Mistakes
 - `<DigitInput.Root>` → the component is a single export: `<DigitInput />`.

package/src/components/digit-input/examples/in-form.tsx

@@ -1,18 +1,27 @@
-/** A masked card PIN submitted with a form; a short PIN shows an error — `name`, `mask`, `required`, `error`. */
-import { Button, DigitInput } from "prime-ui-kit";
+/** A masked card PIN submitted with a form; a short or wrong PIN shakes in an error that leaves when you type again — `name`, `mask`, `required`, `error`. */
+import { Button, DigitInput, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 const PIN_LENGTH = 4;
+const PIN = "4821";
 
 export default function DigitInputInFormExample() {
   const [error, setError] = React.useState<string>();
+  const [linked, setLinked] = React.useState(false);
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
     const pin = String(new FormData(event.currentTarget).get("pin") ?? "");
-    setError(pin.length === PIN_LENGTH ? undefined : "Введите все четыре цифры");
+    const next =
+      pin.length !== PIN_LENGTH
+        ? "Введите все четыре цифры"
+        : pin === PIN
+          ? undefined
+          : "Неверный PIN-код";
+    setError(next);
+    setLinked(next === undefined);
   };
 
   return (
@@ -23,9 +32,18 @@ export default function DigitInputInFormExample() {
         length={PIN_LENGTH}
         mask
         required
+        hint={`Для примера — ${PIN}`}
         error={error}
-        onValueChange={() => setError(undefined)}
+        onValueChange={() => {
+          setError(undefined);
+          setLinked(false);
+        }}
       />
+      {linked ? (
+        <Typography as="p" variant="body-s" tone="secondary" role="status">
+          Карта привязана.
+        </Typography>
+      ) : null}
       <Button.Root type="submit">Привязать карту</Button.Root>
     </form>
   );

package/src/components/digit-input/examples/on-complete.tsx

@@ -1,20 +1,21 @@
-/** The code is checked as soon as the last cell is filled; a wrong code turns the hint into an error — `onComplete`, `error`. */
+/** The code is checked as soon as the last cell is filled: a right one turns the cells success, a wrong one turns the hint into an error — `onComplete`, `success`, `error`. */
 import { DigitInput } from "prime-ui-kit";
 import * as React from "react";
 
 const VALID_CODE = "123456";
 
 export default function DigitInputOnCompleteExample() {
-  const [error, setError] = React.useState<string>();
+  const [result, setResult] = React.useState<"accepted" | "rejected">();
 
   return (
     <DigitInput
       label="Код подтверждения входа"
       length={6}
-      hint={`Для проверки подходит ${VALID_CODE}`}
-      error={error}
-      onValueChange={() => setError(undefined)}
-      onComplete={(code) => setError(code === VALID_CODE ? undefined : "Неверный код")}
+      hint={result === "accepted" ? "Код подтверждён" : `Для проверки подходит ${VALID_CODE}`}
+      error={result === "rejected" ? "Неверный код" : undefined}
+      success={result === "accepted"}
+      onValueChange={() => setResult(undefined)}
+      onComplete={(code) => setResult(code === VALID_CODE ? "accepted" : "rejected")}
     />
   );
 }

package/src/components/digit-input/examples/validation.tsx

@@ -1,15 +1,22 @@
-/** Required and optional markers, a hint and an error that replaces it — `required`, `optional`, `hint`, `error`. */
+/** A confirmation code checked once it is complete: a wrong code shakes in with one message and leaves as soon as you type again; a hint and an optional code — `required`, `optional`, `hint`, `error`. */
 import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+const CODE = "482916";
 
 export default function DigitInputValidationExample() {
+  const [error, setError] = React.useState<string>();
+
   return (
     <>
-      <DigitInput label="Код из письма" required hint="Проверьте папку «Спам»" length={6} />
       <DigitInput
-        label="Код подтверждения"
+        label="Код из письма"
         required
-        defaultValue="1111"
-        error="Неверный код, осталось 2 попытки"
+        hint={`Проверьте папку «Спам». Для примера — ${CODE}`}
+        length={6}
+        error={error}
+        onValueChange={() => setError(undefined)}
+        onComplete={(value) => setError(value === CODE ? undefined : "Неверный код")}
       />
       <DigitInput label="Код приглашения" optional />
     </>

package/src/components/dnd/COMPONENT.md

@@ -134,7 +134,7 @@ Generic `Dnd.DropZone<TData>`; `ref` → `HTMLElement`. Renders the `as` element
 | carried | a drag | the clone follows the pointer, lifted on `--prime-shadow-modal`, scale 1.02; a sortable source leaves the layout (`data-lifted`) and a dashed accent gap of its size and radius fades in and glides with the items as the landing spot moves; entering a connected list, it fades out in the list it left and in where it opens; crossing empty space (the gutter between lists) leaves the gap in the last list that takes the item; neighbours glide aside; a `Dnd.Draggable` stays at 0.4 opacity (`data-dragging`) |
 | over a zone | pointer over an accepting zone | `data-dnd-over`: `accent-soft` fill, dashed accent outline |
 | refused | `canDrop` returns `false` | `data-dnd-reject`: `danger-soft` fill; the clone gets a dashed `danger` outline |
-| dropped | release over a target, or over empty space while a list holds the gap | the clone glides to the item's new place and is swapped for the real element; `data-dnd-flash` with `flashOnDrop` |
+| dropped | release over a target, or over empty space while a list holds the gap | the clone glides to the item's new place and is swapped for the real element; `data-dnd-flash` with `flashOnDrop`; the clone sets down into the look the item will have in place — its resting shadow, or under the mouse its hover look: the item gets `data-dnd-hover` until the pointer leaves it or presses, so a host styles its hover lift on `:is(:hover, [data-dnd-hover])` and the card never dips to flat and lifts again |
 | cancelled | Escape, a system-cancelled pointer | the clone flies back, nothing changes |
 | disabled | `disabled` | `data-disabled`, no `aria-roledescription` |
 

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

@@ -14,8 +14,8 @@
   min-width: 0;
   padding: var(--prime-space-3) var(--prime-space-4);
   border-radius: var(--prime-radius-m);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
+  background: var(--prime-color-layer-nested);
+  box-shadow: var(--prime-shadow-raised);
 }
 
 /* The grip sits closer to the edge: it is a square button with its own inner room. */
@@ -45,7 +45,7 @@
   min-height: calc(var(--prime-space-24) * 2);
   padding: var(--prime-space-3);
   border-radius: var(--prime-radius-l);
-  background: var(--prime-color-bg-sunken);
+  background: var(--prime-color-fill-muted);
 }
 
 .columnHeader {
@@ -61,7 +61,7 @@
   gap: var(--prime-space-1);
   padding: var(--prime-space-3) var(--prime-space-4);
   border-radius: var(--prime-radius-m);
-  background: var(--prime-color-bg-surface);
+  background: var(--prime-color-layer-nested);
   box-shadow: var(--prime-shadow-raised);
 }
 

package/src/components/drawer/COMPONENT.md

@@ -182,7 +182,7 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 | [long-content.tsx](examples/long-content.tsx) | A long body scrolls on its own while the header and the footer stay in place — `Drawer.Body`. |
 | [dismiss.tsx](examples/dismiss.tsx) | An import closes only from its buttons, and not at all while it runs — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the state and opens the drawer from a link, without a trigger — `open`, `onOpenChange`. |
-| [in-form.tsx](examples/in-form.tsx) | A settings form in the panel: the footer button submits the form and an empty name keeps it open — `Drawer.Body`, `Drawer.Footer`, `error`. |
+| [in-form.tsx](examples/in-form.tsx) | A settings form in the panel: the footer button submits the form and an empty name shakes the field and keeps it open until it is filled — `Drawer.Body`, `Drawer.Footer`, `error`. |
 
 ## Mistakes
 - A delete confirmation in a Drawer → use Modal.

package/src/components/drawer/examples/in-form.tsx

@@ -1,4 +1,4 @@
-/** A settings form in the panel: the footer button submits the form and an empty name keeps it open — `Drawer.Body`, `Drawer.Footer`, `error`. */
+/** A settings form in the panel: the footer button submits the form and an empty name shakes the field and keeps it open until it is filled — `Drawer.Body`, `Drawer.Footer`, `error`. */
 import { Button, Drawer, Icon, Input, Select, Switch } from "prime-ui-kit";
 import * as React from "react";
 
@@ -44,7 +44,12 @@ export default function DrawerInFormExample() {
           <form id={formId} className={styles.form} noValidate onSubmit={submit}>
             <Input.Root label="Название" required error={error} reserveSupportRow>
               <Input.Wrapper>
-                <Input.Field name="name" defaultValue="Команда продукта" autoFocus />
+                <Input.Field
+                  name="name"
+                  defaultValue="Команда продукта"
+                  autoFocus
+                  onValueChange={() => setError(undefined)}
+                />
               </Input.Wrapper>
             </Input.Root>
             <Input.Root label="Адрес" hint="Только латиница, цифры и дефис">

package/src/components/dropdown/COMPONENT.md

@@ -115,7 +115,7 @@ No DOM: clones the single child, merges `ref` and `onClick` (toggles), sets `ari
 `ref` → `HTMLDivElement`. A non-interactive row at the top (who is signed in, the plan): an avatar, Title + Description stacked in one column, a trailing badge or button — in the written order / the medium heading line / the muted line under it; both truncate. + native `<div>` props.
 
 ## Variants
-The panel is the shared floating surface: `bg-raised`, `--prime-panel-radius` (12), padding 4, `shadow-overlay`; rows have radius 8 and the tier item height.
+The panel is the shared floating surface: the floating layer of the ladder (`data-depth="floating"`), `--prime-panel-radius` (12), padding 4, `shadow-overlay`; rows have radius 8 and the tier item height.
 
 ### size (Content)
 | Value | Looks like | Use when | Default |

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

@@ -18,5 +18,5 @@
   padding-block: var(--prime-space-1);
   padding-inline: var(--prime-space-4) var(--prime-space-1);
   border-radius: var(--prime-radius-l);
-  background: var(--prime-color-card-bg);
+  background: var(--prime-color-layer-nested);
 }

package/src/components/empty-page/examples/examples.module.css

@@ -27,7 +27,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/example-frame/COMPONENT.md

@@ -74,7 +74,7 @@ ExampleFrame               frame: toolbar + preview stage or code pane
 | `light` | stage and code pane in the light theme | default | yes |
 | `dark` | stage and code pane in the dark theme (`data-theme="dark"`), switched without color transitions | checking dark mode | |
 
-Frame look: `bg-sunken` chrome with a `border-subtle` hairline and `radius-xl`; the stage and code pane are `bg-canvas` wells with `radius-l` (16 − 4 padding = 12). The stage resets the card context (`--prime-color-card-bg: bg-surface`).
+Frame look: the chrome is a layer of the surface ladder (`data-depth`, one above its host) with a `border-subtle` hairline and `radius-xl`; the stage and code pane are wells with `radius-l` (16 − 4 padding = 12). Both wells carry `data-theme`, so each is a page of its own: layer 0 of its scheme, and surfaces in the example count from there.
 
 ## States
 | State | Driven by | DOM |

package/src/components/file-upload/COMPONENT.md

@@ -157,7 +157,7 @@ The built-in body (icon, `labels.title`, `labels.description` and a decorative s
 | hover | — | zone fill and dashed line darken |
 | focus | keyboard focus on the hidden input | inset focus ring on the zone (danger when invalid); Enter / Space opens the dialog |
 | drag-over | a file dragged over the zone | `data-state="active"` on the zone: accent line, accent soft fill, accent icon |
-| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the zone, `aria-invalid` on the input; `data-invalid="true"` on Item |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the zone, `aria-invalid` on the input; `data-invalid="true"` on Item; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | `data-disabled="true"`, disabled input, disabled fill and text, drops ignored |
 
 Also `data-size`, `data-variant` on the zone and `data-size` on Item. Files are not kept by the component: keep the list in your state and update it in `onFilesChange`.
@@ -197,11 +197,11 @@ Also `data-size`, `data-variant` on the zone and `data-size` on Item. Files are
 | [variants.tsx](examples/variants.tsx) | The dashed drop line next to a zone with only the fill, for cards and modals — `variant`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size of the zone and of a file row: padding, icon, button and text follow the tier — `size`. |
 | [states.tsx](examples/states.tsx) | A default zone, a disabled one and an invalid one without a message — `disabled`, `invalid`. |
-| [validation.tsx](examples/validation.tsx) | A required zone with a hint, a rejected file whose error replaces the hint and an optional zone — `required`, `hint`, `error`, `optional`. |
+| [validation.tsx](examples/validation.tsx) | A required scan checked as soon as it is picked: a wrong type or a large file shakes in an error that leaves when the file is removed; a hint and an optional zone — `required`, `hint`, `error`, `optional`. |
 | [custom-body.tsx](examples/custom-body.tsx) | A custom body: a muted title with a browse link and source buttons instead of the built-in one — `FileUpload.Body`, `FileUpload.Title`. |
 | [upload-progress.tsx](examples/upload-progress.tsx) | File rows while uploading, uploaded and failed with a retry — `FileUpload.ItemProgress`, `invalid`, `FileUpload.ItemActions`. |
 | [avatar-upload.tsx](examples/avatar-upload.tsx) | A round zone around an Avatar that takes images and shows a preview; buttons open the same input — `inputRef`, `accept`, `className`. |
-| [in-form.tsx](examples/in-form.tsx) | A contract upload form: the required scan is checked on submit and its error replaces the hint — `required`, `error`, `name`. |
+| [in-form.tsx](examples/in-form.tsx) | A contract upload form: submit checks the required scan, its error shakes in and leaves once a valid file is picked or removed — `required`, `error`, `name`. |
 | [narrow.tsx](examples/narrow.tsx) | In a phone-width column the zone text wraps and a long file name truncates. |
 
 ## Mistakes

package/src/components/file-upload/examples/in-form.tsx

@@ -1,18 +1,31 @@
-/** A contract upload form: the required scan is checked on submit and its error replaces the hint — `required`, `error`, `name`. */
+/** A contract upload form: submit checks the required scan, its error shakes in and leaves once a valid file is picked or removed — `required`, `error`, `name`. */
 import { Button, FileUpload, Icon, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 const HINT = "PDF до 20 МБ, все страницы";
+const MAX_SIZE = 20 * 1024 * 1024;
+
+/** The scan error on submit, or nothing when exactly a PDF within the limit is attached. */
+function scanError(files: File[]) {
+  if (files.length === 0) return "Приложите скан договора";
+  if (files.some((file) => !file.name.toLowerCase().endsWith(".pdf")))
+    return "Нужен файл в формате PDF";
+  if (files.some((file) => file.size > MAX_SIZE)) return "Файл больше 20 МБ";
+  return undefined;
+}
 
 export default function FileUploadInFormExample() {
   const [files, setFiles] = React.useState<File[]>([]);
   const [error, setError] = React.useState<string>();
+  const [sent, setSent] = React.useState(false);
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
-    setError(files.length === 0 ? "Приложите скан договора" : undefined);
+    const next = scanError(files);
+    setError(next);
+    setSent(next === undefined);
   };
 
   return (
@@ -36,18 +49,23 @@ export default function FileUploadInFormExample() {
           onFilesChange={(next) => {
             setFiles(next);
             setError(undefined);
+            setSent(false);
           }}
         />
         {files.map((file) => (
           <FileUpload.Item key={file.name}>
-            <FileUpload.FormatBadge format="pdf" color="red" />
+            <FileUpload.FormatBadge format={file.name.split(".").pop() ?? ""} color="red" />
             <FileUpload.ItemName>{file.name}</FileUpload.ItemName>
             <FileUpload.ItemActions>
               <Button.Root
                 variant="ghost"
                 tone="neutral"
                 aria-label={`Удалить ${file.name}`}
-                onClick={() => setFiles([])}
+                onClick={() => {
+                  setFiles([]);
+                  setError(undefined);
+                  setSent(false);
+                }}
               >
                 <Button.Icon>
                   <Icon name="action.close" />
@@ -57,6 +75,11 @@ export default function FileUploadInFormExample() {
           </FileUpload.Item>
         ))}
       </div>
+      {sent ? (
+        <Typography as="p" variant="body-s" tone="secondary" role="status">
+          Договор отправлен на проверку.
+        </Typography>
+      ) : null}
       <div className={styles.formActions}>
         <Button.Root
           variant="ghost"
@@ -65,6 +88,7 @@ export default function FileUploadInFormExample() {
           onClick={() => {
             setFiles([]);
             setError(undefined);
+            setSent(false);
           }}
         >
           Отменить

package/src/components/file-upload/examples/validation.tsx

@@ -1,18 +1,49 @@
-/** A required zone with a hint, a rejected file whose error replaces the hint and an optional zone — `required`, `hint`, `error`, `optional`. */
-import { FileUpload } from "prime-ui-kit";
+/** A required scan checked as soon as it is picked: a wrong type or a large file shakes in an error that leaves when the file is removed; a hint and an optional zone — `required`, `hint`, `error`, `optional`. */
+import { Button, FileUpload, Icon } from "prime-ui-kit";
+import * as React from "react";
 
 import styles from "./examples.module.css";
 
+const MAX_SIZE = 20 * 1024 * 1024;
+
+/** The scan error, or nothing when every picked file is a PDF within the limit. */
+function scanError(files: File[]) {
+  if (files.some((file) => !file.name.toLowerCase().endsWith(".pdf")))
+    return "Нужен файл в формате PDF";
+  if (files.some((file) => file.size > MAX_SIZE)) return "Файл больше 20 МБ";
+  return undefined;
+}
+
 export default function FileUploadValidationExample() {
+  const [files, setFiles] = React.useState<File[]>([]);
+
   return (
     <div className={styles.column}>
-      <FileUpload.Root label="Скан договора" required hint="PDF до 20 МБ, все страницы" />
       <FileUpload.Root
-        label="Счёт на оплату"
+        label="Скан договора"
         required
-        error="Файл не подошёл: нужен PDF до 20 МБ"
-        labels={{ title: "Выберите другой файл" }}
+        hint="PDF до 20 МБ, все страницы"
+        error={scanError(files)}
+        onFilesChange={setFiles}
       />
+      {files.map((file) => (
+        <FileUpload.Item key={file.name}>
+          <FileUpload.FormatBadge format={file.name.split(".").pop() ?? ""} color="red" />
+          <FileUpload.ItemName>{file.name}</FileUpload.ItemName>
+          <FileUpload.ItemActions>
+            <Button.Root
+              variant="ghost"
+              tone="neutral"
+              aria-label={`Удалить ${file.name}`}
+              onClick={() => setFiles([])}
+            >
+              <Button.Icon>
+                <Icon name="action.close" />
+              </Button.Icon>
+            </Button.Root>
+          </FileUpload.ItemActions>
+        </FileUpload.Item>
+      ))}
       <FileUpload.Root label="Доверенность" optional hint="Если подписывает не директор" />
     </div>
   );