prime-ui-kit 0.9.0 → 0.9.2

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

@@ -0,0 +1,41 @@
+/** Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. */
+import { Select } from "prime-ui-kit";
+
+export default function SelectValidationExample() {
+  return (
+    <>
+      <Select.Root label="Страна" required hint="Определяет валюту счетов" defaultValue="ru">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="ru">Россия</Select.Item>
+          <Select.Item value="kz">Казахстан</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Select.Root
+        label="Ответственный"
+        required
+        error="Назначьте ответственного"
+        placeholder="Не выбран"
+      >
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="anna">Анна Петрова</Select.Item>
+          <Select.Item value="ivan">Иван Смирнов</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Select.Root label="Отдел" optional placeholder="Не указан">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="sales">Продажи</Select.Item>
+          <Select.Item value="support">Поддержка</Select.Item>
+        </Select.Content>
+      </Select.Root>
+    </>
+  );
+}

package/src/components/select/examples/with-icon.tsx

@@ -0,0 +1,35 @@
+/** A leading icon in the trigger and an icon before every option label — `Select.TriggerIcon`, `Select.ItemIcon`. */
+import { Icon, Select } from "prime-ui-kit";
+import * as React from "react";
+
+const ACCESS = [
+  { value: "public", label: "Виден в поиске", icon: "action.search" },
+  { value: "invite", label: "Только по приглашению", icon: "field.email" },
+  { value: "private", label: "Только участники", icon: "status.locked" },
+] as const;
+
+export default function SelectWithIconExample() {
+  const [access, setAccess] = React.useState<string>("invite");
+  const selected = ACCESS.find((option) => option.value === access) ?? ACCESS[1];
+
+  return (
+    <Select.Root label="Доступ к проекту" value={access} onValueChange={setAccess}>
+      <Select.Trigger>
+        <Select.TriggerIcon>
+          <Icon name={selected.icon} />
+        </Select.TriggerIcon>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        {ACCESS.map((option) => (
+          <Select.Item key={option.value} value={option.value}>
+            <Select.ItemIcon>
+              <Icon name={option.icon} />
+            </Select.ItemIcon>
+            {option.label}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/src/components/skeleton/COMPONENT.md

@@ -0,0 +1,104 @@
+# Skeleton
+
+**Category:** status
+**Kind:** primitive
+
+> A placeholder in the shape of the content that is loading — text lines, a control, an avatar, a block — so the layout is in place before the data arrives.
+
+## When to use
+- A region whose content has a known shape is loading: a list, a card, a profile, a form with saved values.
+- The loading state inside [Crossfade](../crossfade/COMPONENT.md): the skeleton holds the data's geometry and cross-fades into it.
+- First load of a page section, when the structure is known before the values.
+
+## When not to use
+- Loading with no shape to hold (a button waiting for its request, a status line) → [Spinner](../spinner/COMPONENT.md), or `loading` on [Button](../button/COMPONENT.md).
+- A known progress (upload, steps) → [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- A table loading its rows → `loading` on [DataTable](../data-table/COMPONENT.md); it renders skeleton rows of its columns itself.
+- Data already on screen being refreshed → keep it and set `aria-busy`; do not swap it back to a skeleton.
+
+## Import
+```tsx
+import { Skeleton } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Skeleton           <span aria-hidden="true">; data-shape, data-size
+└─ line × lines    shape="text" only: one line box per line, a rounded bar in its middle
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Skeleton
+`ref` → `HTMLSpanElement`. A pulsing placeholder in the shape of loading content; `aria-hidden="true"`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `shape` | `"text" \| "control" \| "circle" \| "block"` | `"text"` | `text` — lines of the tier's text; `control` — a field or button of the tier; `circle` — an avatar of the tier; `block` — a box that fills its container (image, chart, card). |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the text line (control text size and line height), the control height or the avatar size. |
+| `lines` | `number` | `1` | `text` only: number of lines; the last of several is 60% wide. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` (width, height of a `block`), `data-*` and the other span attributes. |
+
+## Variants
+
+### shape
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `text` | rounded bars on the tier's text line boxes; the last of several lines is 60% wide | titles, names, descriptions, cells | yes |
+| `control` | a block of the tier's control height and radius, full width | fields, buttons, selects of a form | |
+| `circle` | a circle of the tier's avatar size | avatars, round icons | |
+| `block` | a radius-l block that fills its container (at least 64px high) | images, covers, charts, whole cards | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` · `s` · `m` · `l` · `xl` | text: the control text size and line height of the tier; control: the control height; circle: the avatar size | the tier of the content it stands for | host tier, else `m` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| pulsing | mounted | opacity eases 1 → 0.4 and back (`slow × 5`, `standard`, alternate) |
+| reduced motion | `prefers-reduced-motion: reduce` | no pulse: the placeholder stands still and stays visible |
+| shape / size | `shape`, `size` | `data-shape`, `data-size` |
+
+## Layout & spacing
+- Put skeletons in the real layout of the content: the same grid, gaps and paddings, so the swap to data moves nothing.
+- Width: a text line and a control fill their container; narrow them with a `className` (a label is shorter than its field, an amount shorter than a name). Shape defaults have zero specificity, so a `className` always wins.
+- Height: text and control come from the tier; a `block` fills its container or takes a height from `className`.
+- Inside a sized host (a DataTable, a Popover, a field tier) `size` follows the host tier.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Decorative: `aria-hidden="true"`, screen readers skip it.
+- The loading region announces itself: `aria-busy` on it (Crossfade, a card, a form) and, when the wait matters, a `role="status"` text.
+- Under `prefers-reduced-motion` the placeholder does not pulse.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A project card while it loads: the cover, the author and two lines of text take the room of the real content — `shape`, `lines`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier of a text line, a control and an avatar circle: the placeholder matches the content of that tier — `size`, `shape`. |
+| [form.tsx](examples/form.tsx) | A settings form while its values load: labels are short text lines, fields and the button are controls of the same tier — `shape`. |
+| [with-crossfade.tsx](examples/with-crossfade.tsx) | A list that reloads: placeholder rows of the same geometry cross-fade into the data, nothing jumps — `Crossfade`, `state`. |
+
+## Mistakes
+- A hand-drawn grey box with its own `@keyframes` → use `Skeleton`.
+- A spinner in the middle of an empty card while its list loads → skeleton rows of that list.
+- Skeletons of a different geometry than the data (one tall block for three rows) → the swap jumps; mirror the rows.
+- Swapping a skeleton for data without `Crossfade` → wrap the region: `Crossfade state={loading ? "loading" : "ready"}`.
+- Returning to a skeleton on every refresh of data already shown → keep the data, set `aria-busy`.
+
+## Related
+- **Built from:** —
+- **See also:** [Crossfade](../crossfade/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)

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

@@ -0,0 +1,89 @@
+/* Layout of the Skeleton scenarios: semantic tokens only. */
+
+.card {
+  width: min(100%, calc(var(--prime-space-24) * 3.5));
+}
+
+.content {
+  display: grid;
+  gap: var(--prime-space-4);
+}
+
+.cover {
+  height: calc(var(--prime-space-24) + var(--prime-space-12));
+}
+
+.author {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-3);
+}
+
+.form {
+  display: grid;
+  gap: var(--prime-space-5);
+  width: min(100%, calc(var(--prime-space-24) * 4));
+}
+
+.field {
+  display: grid;
+  gap: var(--prime-space-2);
+}
+
+/* A label is shorter than its field. */
+.label {
+  width: 40%;
+}
+
+/* The placeholder of the submit button: a button, not a full-width field. */
+.button {
+  width: calc(var(--prime-space-24) + var(--prime-space-8));
+}
+
+.stack {
+  display: grid;
+  justify-items: start;
+  gap: var(--prime-space-4);
+  width: min(100%, calc(var(--prime-space-24) * 5));
+}
+
+.stack > * {
+  justify-self: stretch;
+}
+
+.stack > :first-child {
+  justify-self: start;
+}
+
+.list {
+  display: grid;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* Data rows and their placeholders share one row geometry, so the swap does not move anything. */
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+  padding-block: var(--prime-space-3);
+  border-bottom: var(--prime-border-width) solid var(--prime-color-border-subtle);
+}
+
+.row:last-child {
+  border-bottom: 0;
+}
+
+.payer {
+  width: 55%;
+}
+
+.amount {
+  width: 20%;
+}
+
+.sum {
+  font-variant-numeric: tabular-nums;
+}

package/src/components/skeleton/examples/form.tsx

@@ -0,0 +1,20 @@
+/** A settings form while its values load: labels are short text lines, fields and the button are controls of the same tier — `shape`. */
+import { Skeleton } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const FIELDS = ["company", "inn", "email"];
+
+export default function SkeletonFormExample() {
+  return (
+    <div className={styles.form} aria-busy="true">
+      {FIELDS.map((field) => (
+        <div key={field} className={styles.field}>
+          <Skeleton size="s" className={styles.label} />
+          <Skeleton shape="control" />
+        </div>
+      ))}
+      <Skeleton shape="control" className={styles.button} />
+    </div>
+  );
+}

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

@@ -0,0 +1,21 @@
+/** A project card while it loads: the cover, the author and two lines of text take the room of the real content — `shape`, `lines`. */
+import { Card, Skeleton } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function SkeletonOverviewExample() {
+  return (
+    <Card.Root variant="panel" className={styles.card} aria-busy="true">
+      <Card.Body>
+        <div className={styles.content}>
+          <Skeleton shape="block" className={styles.cover} />
+          <div className={styles.author}>
+            <Skeleton shape="circle" />
+            <Skeleton />
+          </div>
+          <Skeleton lines={2} />
+        </div>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/skeleton/examples/sizes.tsx

@@ -0,0 +1,24 @@
+/** Every tier of a text line, a control and an avatar circle: the placeholder matches the content of that tier — `size`, `shape`. */
+import { Skeleton, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+const SHAPES = ["text", "control", "circle"] as const;
+
+export default function SkeletonSizesExample() {
+  return (
+    <>
+      {SHAPES.map((shape) => (
+        <div key={shape}>
+          {SIZES.map((size) => (
+            <div key={size}>
+              <Skeleton shape={shape} size={size} />
+              <Typography as="span" variant="caption" tone="muted">
+                {`${shape} · ${size}`}
+              </Typography>
+            </div>
+          ))}
+        </div>
+      ))}
+    </>
+  );
+}

package/src/components/skeleton/examples/with-crossfade.tsx

@@ -0,0 +1,68 @@
+/** A list that reloads: placeholder rows of the same geometry cross-fade into the data, nothing jumps — `Crossfade`, `state`. */
+import { Button, Card, Crossfade, Icon, Skeleton, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PAYMENTS = [
+  { id: "p1", payer: "ООО «Гранит»", amount: "₽ 94 750" },
+  { id: "p2", payer: "ИП Орлов Д. С.", amount: "₽ 18 000" },
+  { id: "p3", payer: "АО «Альфа Медиа»", amount: "₽ 380 000" },
+];
+
+const LOAD_MS = 1500;
+
+export default function SkeletonWithCrossfadeExample() {
+  const [loading, setLoading] = React.useState(true);
+
+  React.useEffect(() => {
+    if (!loading) return;
+    const id = window.setTimeout(() => setLoading(false), LOAD_MS);
+    return () => window.clearTimeout(id);
+  }, [loading]);
+
+  return (
+    <div className={styles.stack}>
+      <Button.Root
+        variant="soft"
+        tone="neutral"
+        disabled={loading}
+        onClick={() => setLoading(true)}
+      >
+        <Button.Icon>
+          <Icon name="action.refresh" />
+        </Button.Icon>
+        Обновить
+      </Button.Root>
+
+      <Card.Root variant="panel">
+        <Card.Header>
+          <Card.Title as="h3">Поступления за сегодня</Card.Title>
+        </Card.Header>
+        <Card.Body>
+          <Crossfade state={loading ? "loading" : "ready"} aria-busy={loading}>
+            <ul className={styles.list}>
+              {PAYMENTS.map((payment) =>
+                loading ? (
+                  <li key={payment.id} className={styles.row}>
+                    <Skeleton className={styles.payer} />
+                    <Skeleton className={styles.amount} />
+                  </li>
+                ) : (
+                  <li key={payment.id} className={styles.row}>
+                    <Typography as="span" variant="body-m">
+                      {payment.payer}
+                    </Typography>
+                    <Typography as="span" variant="body-m" className={styles.sum}>
+                      {payment.amount}
+                    </Typography>
+                  </li>
+                ),
+              )}
+            </ul>
+          </Crossfade>
+        </Card.Body>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/slider/COMPONENT.md

@@ -1,6 +1,7 @@
 # Slider
 
 **Category:** selection
+**Kind:** control
 
 > A slider for picking an approximate numeric value within a range, with an optional label and value readout.
 
@@ -22,111 +23,147 @@ import { Slider } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Slider.Root
-├─ header row (only with `label` or `showValue`)
-│  ├─ Label            from `label`, linked to the input
+Slider                 field frame (FieldFrame): className, ref, rest
+├─ label row (only with `label` or `showValue`)
+│  ├─ Label            from `label`, linked to the input; `required` / `optional` markers
 │  └─ <output>         from `showValue`, formatted value
-└─ <input type="range">
+├─ control
+│  ├─ <input type="range">   transparent, on top: pointer, keyboard, a11y; `id`, `aria-label`
+│  ├─ track · fill            visual, aria-hidden
+│  └─ thumb                   visual, aria-hidden
+└─ support row         `hint` | `error` (same slot)
 ```
-Single part: everything is configured by `Slider.Root` props.
 
 ## API
 
-### Slider.Root
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Slider
+`ref` → `HTMLDivElement` (the field frame). A framed field like every other: the label row with the value, a native `<input type="range">` (transparent, on top) over the visual track, fill and thumb, then the hint or the error. Field-root rule: `className`, `ref` and the rest go to the frame; `id` and `aria-label` to the range input.
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `number` | — | Controlled value (clamped to `[min, max]`); use with `onValueChange`. |
-| `defaultValue` | `number` | `min` | Initial value in uncontrolled mode (clamped). |
-| `onValueChange` | `(value: number) => void` | — | Called on every thumb move. |
+| `value` | `number` | — | Controlled value; clamped to `min`…`max`. |
+| `defaultValue` | `number` | `min` | Initial value when uncontrolled. |
+| `onValueChange` | `(value: number) => void` | — | Called with the new number while dragging and on every key step. |
 | `min` | `number` | `0` | Lower bound. |
 | `max` | `number` | `100` | Upper bound. |
-| `step` | `number` | `1` | Step of the native range; fractional steps work. |
-| `label` | `ReactNode` | — | Visible label (`Label`), linked to the input via `htmlFor`. Without it, pass `aria-label`. |
-| `showValue` | `boolean` | `false` | Shows the current value at the end of the label row (tabular numbers). |
-| `formatValue` | `(value: number) => string` | — | Formats the shown value and sets `aria-valuetext` (e.g. `` (v) => `${v} °C` ``). |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Size tier of the thumb and the label row. |
-| `disabled` | `boolean` | — | Disables the input; mutes track, fill and value. |
+| `step` | `number` | `1` | Step of the keyboard and of the snapping; fractions allowed. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the track thickness T (thumb 4.5T × 3T), the label, the value and the hint. Without it the tier of its host (a form, a panel), else `m`. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Color of the filled part of the track. |
+| `disabled` | `boolean` | — | Muted track and thumb, dimmed label and value, no interaction. |
+| `label` | `ReactNode` | — | Visible label linked to the range input (`<label htmlFor>`). Without it, set `aria-label`. |
+| `required` | `boolean` | — | Red `*` after the label (`aria-hidden`); a range always has a value, so there is no native `required`. |
+| `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the track (`aria-describedby`). Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | — | `aria-invalid` on the range input and a danger focus ring on the thumb. A non-empty `error` implies it. |
+| `showValue` | `boolean` | `false` | Shows the current value at the end of the label row (tabular numbers, `aria-hidden` — the input announces it). |
+| `formatValue` | `(value: number) => string` | — | Formats the shown value and `aria-valuetext` (units, currency). |
+| `id` | `string` | — | Id of the range input (generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
 | `aria-label` | `string` | — | Accessible name when there is no visible `label`. |
-| `className` | `string` | — | Class on the root `div`. |
-
-No other native props, no `name`, no ref forwarding.
+| `aria-describedby` | `string` | — | Merged before the hint / error ids on the range input. |
+| `labels` | `Partial<SliderLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `style` and the other attributes of the field frame `<div>`. |
 
 ## Variants
-No `variant`/`tone`/`color`. Axes: `size`, `showValue` (visual flag).
+No `variant` / `color`.
 
 ### size
+Everything derives from the tier track thickness T (`--prime-control-<tier>-track`, shared with ProgressBar): the thumb is a 4.5T × 3T capsule, so the control scales as one shape.
+
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | 14px thumb, 4px track, 12/16 label | dense filter panels | |
-| `s` | 16px thumb, 4px track, 12/16 label | compact side panels | |
-| `m` | 18px thumb, 4px track, 13/20 label | regular forms and settings | yes |
-| `l` | 20px thumb, 4px track, 14/20 label | spacious settings pages | |
-| `xl` | 24px thumb, 8px track, 14/20 label | touch-first screens | |
+| `xs` | 4px track, 18×12 thumb, 12/16 label | dense filter panels | |
+| `s` | 5px track, 22.5×15 thumb, 12/16 label | compact side panels | |
+| `m` | 6px track, 27×18 thumb, 13/20 label | regular forms and settings | yes |
+| `l` | 7px track, 31.5×21 thumb, 14/20 label | spacious settings pages | |
+| `xl` | 8px track, 36×24 thumb, 14/20 label | touch-first screens | |
+
+**Sizes:** the slider fills its container and never gets narrower than 192px (like a native range); the tier changes the track, the thumb and the label / value text. Use the same tier as the other fields of the form.
 
-### showValue
+### tone
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `false` | no readout; the header shows only the label | the position is self-explanatory (volume) or the value is shown elsewhere (a paired input) | yes |
-| `true` | value at the right end of the label row, `text-secondary`, tabular nums | the number matters (price, temperature, percent) | |
+| `accent` | `accent-default` fill | any regular setting | yes |
+| `neutral` | `text-secondary` fill | monochrome screens, editors, media controls | |
+| `success` | `success-default` fill | a value that means «safe / good» (minimum charge) | |
+| `warning` | `warning-default` fill | a warning threshold | |
+| `danger` | `danger-default` fill | a blocking or destructive threshold | |
+| `info` | `info-default` fill | informational settings next to info UI | |
+
+Tone never carries meaning alone: the label names what the value means.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `showValue` | the value at the right end of the label row, `text-secondary`, tabular nums | the number matters (price, temperature, percent) | `false` |
+| `disabled` | muted track, flat thumb, dimmed label and value | the setting is unavailable | — |
 
 **Combinations**
 - `showValue` + `formatValue` for any value with a unit; `formatValue` alone only changes `aria-valuetext`.
 - Neither `label` nor `aria-label` → forbidden (unnamed control).
 - A paired number input with `showValue` → redundant; drop `showValue`.
 
-**Sizes** — the root is always 100% wide; the tier changes only the thumb, label/value text and (at `xl`) the track thickness. Use the same tier as the other fields of the form.
-
-**Hierarchy** — sliders in a settings card are spaced `--prime-space-6`; a related switch can disable a slider (see [display-settings.tsx](examples/display-settings.tsx)).
-
 ## States
-| State | Driven by | DOM | Looks like |
-|---|---|---|---|
-| default | — | `data-size` | track `fill-strong`, fill `accent-default` up to the value, thumb `control-thumb` with a hairline edge and `shadow-overlay` |
-| hover | pointer | — | soft `accent-soft` halo (4px) around the thumb |
-| active | dragging | — | thumb scales to 110% |
-| focus-visible | keyboard | — | outer focus ring around the thumb |
-| disabled | `disabled` | `data-disabled="true"` on root, native `disabled` | track `fill-muted`, fill `text-disabled`, flat thumb `fill-strong`, value `text-disabled`, `cursor: not-allowed` |
+| State | Driven by | DOM |
+|---|---|---|
+| default | — | `data-size`, `data-tone`; track `fill-strong`, tone pill up to the thumb centre, opaque thumb |
+| hover | pointer (fine pointers only) | light liquid glass: the thumb grows to 110%, turns translucent and slightly frosted |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the root, `aria-invalid` on the input; the error replaces the hint, danger focus ring |
+| pressed | dragging | clear glass: the thumb grows to 125%, the rounded end of the fill shows through |
+| focus-visible | keyboard | outer focus ring around the thumb |
+| disabled | `disabled` | `data-disabled="true"` on the root, native `disabled`; muted track and fill, flat thumb, `cursor: not-allowed` |
 
 Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back to `min`).
 
 ## Layout & spacing
-- Always full width of its container; place it in a grid column to limit width.
-- Label row → track: tier `label-gap`; label and value are on one baseline, value pinned right.
-- Between sliders in a form: `--prime-space-5`; in a settings card: `--prime-space-6`.
-- With a paired input: grid `minmax(0, 1fr) auto-width column`, `align-items: end`, gap `--prime-space-4`.
+- Fills its container; place it in a grid column to limit the width.
+- Label row → track: tier `label-gap`; label and value share a baseline, the value is pinned right. Track → hint / error: tier `hint-gap` (FieldFrame, like every field).
+- Between sliders in a form: `--prime-space-5`.
+- With a paired input: grid `minmax(0, 1fr)` + a fixed column, `align-items: end`, gap `--prime-space-4`.
 
 ## Accessibility
-- Native `<input type="range">`: Arrow keys change by `step`, Page Up / Page Down by a larger step, Home / End jump to the ends.
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `ArrowRight` · `ArrowUp` | Increases the value by `step`. |
+| `ArrowLeft` · `ArrowDown` | Decreases the value by `step`. |
+| `PageUp` · `PageDown` | Changes the value by a larger step. |
+| `Home` · `End` | Jumps to `min` / `max`. |
+
+### ARIA
+- A native `<input type="range">` (`role="slider"`) on top of the visual layer.
 - `label` is a `<label htmlFor>`; otherwise `aria-label` is required.
-- `formatValue` sets `aria-valuetext`, so screen readers announce the unit.
-- The visual `<output>` is `aria-hidden` (the value is announced by the input).
-- No `labels` keys.
+- `formatValue` sets `aria-valuetext`, so screen readers announce the unit; the visual `<output>` is `aria-hidden`.
+- `aria-describedby` on the input: your ids + the hint or the error; `aria-invalid` when invalid.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | All size tiers with label and value | Matching the form tier |
-| [states.tsx](examples/states.tsx) | Minimum, middle, maximum, disabled | Reference for fill and disabled |
-| [value-format.tsx](examples/value-format.tsx) | `showValue` + `formatValue` (°C, ₽, %) | Values with units |
-| [basic.tsx](examples/basic.tsx) | One labelled slider with value | Checking contrast on any surface |
-| [controlled.tsx](examples/controlled.tsx) | `value` + `onValueChange` shared with a number Input | Drag plus exact entry |
-| [range-step.tsx](examples/range-step.tsx) | Custom `min`/`max`/`step`, fractional step, `aria-label` only | Bounded settings |
-| [display-settings.tsx](examples/display-settings.tsx) | Card with sliders and a Switch that disables one | Settings panels |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```tsx
-import { Slider } from "prime-ui-kit";
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
 
-export function VolumeSlider() {
-  return <Slider.Root label="Громкость" showValue defaultValue={60} />;
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A labelled slider with its current value — `label`, `showValue`. |
+| [variants.tsx](examples/variants.tsx) | Every fill color; accent by default, semantic tones when the value carries meaning — `tone`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size; the thumb, the label and the value grow with the tier — `size`. |
+| [states.tsx](examples/states.tsx) | The fill at both ends and a disabled slider — `disabled`. |
+| [value-format.tsx](examples/value-format.tsx) | Units in the shown value that are also read by screen readers — `formatValue`, `showValue`. |
+| [range-step.tsx](examples/range-step.tsx) | Own bounds and a coarse or fractional step; a slider without a visible label — `min`, `max`, `step`, `aria-label`. |
+| [hint-and-error.tsx](examples/hint-and-error.tsx) | A slider framed like every field: required marker, a hint, and an error in its place — `required`, `hint`, `error`, `optional`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the value and shares it with a number field for exact entry — `value`, `onValueChange`. |
 
 ## Mistakes
-- `<Slider.Root onChange={…}>` → use `onValueChange`.
-- `formatValue` without `showValue` expecting a visible unit → add `showValue`.
-- No `label` and no `aria-label` → add one.
-- `value={[20, 80]}` for a range → only a single number is supported.
-- Expecting it to submit in a form → there is no `name`; keep the value in state and submit it yourself.
+- `<Slider.Root>` → the slider is a single export: `<Slider />`.
+- A slider for an exact amount → use `Input type="number"`.
+- `tone="danger"` as the only signal of a dangerous value → say it in the label.
+- No `label` and no `aria-label` → the control has no name.
 
 ## Related
-[Input](../input/COMPONENT.md) · [SegmentedControl](../segmented-control/COMPONENT.md) · [Switch](../switch/COMPONENT.md) · [Label](../label/COMPONENT.md)
+- **Built from:** the field frame — [Label](../label/COMPONENT.md) (`label`) and [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **See also:** [ProgressBar](../progress-bar/COMPONENT.md) (the same track scale), [Input](../input/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)