prime-ui-kit 0.9.3 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.9.3",
+  "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/button/COMPONENT.md

@@ -45,7 +45,7 @@ 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. |
@@ -75,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 | |
@@ -163,10 +165,10 @@ Other data attributes: `data-variant`, `data-tone`, `data-size`, `data-full-widt
 | [with-icon.tsx](examples/with-icon.tsx) | An icon before or after the label, and a square icon-only button — `Button.Icon`, `aria-label`. |
 | [download.tsx](examples/download.tsx) | A long download inside the button: the fill shows how far it got, the label counts and then offers the file — `progress`. |
 | [hold-to-confirm.tsx](examples/hold-to-confirm.tsx) | A destructive action that needs a held press; letting go early rolls the fill back and does nothing — `holdToConfirm`, `onConfirm`. |
-| [label-morph.tsx](examples/label-morph.tsx) | A new label flows into the button letter by letter while the width glides: save, then saved; a step flow — `children`, `loading`. |
+| [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.

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

@@ -1,4 +1,4 @@
-/** A new label flows into the button letter by letter while the width glides: save, then saved; a step flow — `children`, `loading`. */
+/** 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";
 
@@ -27,7 +27,12 @@ export default function ButtonLabelMorphExample() {
       >
         {save === "saved" ? "Изменения сохранены" : "Сохранить изменения"}
       </Button.Root>
-      <Button.Root onClick={() => setStep((step + 1) % STEPS.length)}>{STEPS[step]}</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/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/color-picker/COMPONENT.md

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

@@ -90,7 +90,7 @@ ColorSwatches                 field frame: label → swatches → hint | error
 | 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 inner edge of every swatch 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`.
@@ -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/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

@@ -98,7 +98,7 @@ No `variant` or `tone`.
 | 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 |
 
@@ -141,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 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/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/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="Только латиница, цифры и дефис">