prime-ui-kit 0.10.0 → 0.11.1

package/dist/skill/reference/components/spinner/examples/sizes.tsx

@@ -0,0 +1,19 @@
+/** Every size on the icon scale, 14 to 32 px — `size`. */
+import { Spinner, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function SpinnerSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Spinner size={size} />
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/spinner/examples/variants.tsx

@@ -0,0 +1,19 @@
+/** Every ring color; `default` follows the surrounding text — `tone`. */
+import { Spinner, Typography } from "prime-ui-kit";
+
+const TONES = ["default", "secondary", "muted", "accent", "success", "warning", "danger"] as const;
+
+export default function SpinnerVariantsExample() {
+  return (
+    <div>
+      {TONES.map((tone) => (
+        <div key={tone}>
+          <Spinner tone={tone} />
+          <Typography as="span" variant="caption" tone="muted">
+            {tone}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/stepper/COMPONENT.md

@@ -0,0 +1,176 @@
+# Stepper
+
+**Category:** navigation
+**Kind:** navigation
+
+> Steps of a multi-step process with pending, active, completed and danger statuses.
+
+## When to use
+- Checkout, onboarding and setup wizards where the user moves through ordered steps.
+- Showing which steps are done, which is current and which failed.
+- A vertical step list next to the step form (`orientation="vertical"`, the default).
+
+## When not to use
+- Switching between independent sections → use [Tabs](../tabs/COMPONENT.md).
+- Paging through a list → use [Pagination](../pagination/COMPONENT.md).
+- A chronological history of events → use [Timeline](../timeline/COMPONENT.md).
+- Progress as a number or bar without step names → use [ProgressBar](../progress-bar/COMPONENT.md).
+
+## Import
+```tsx
+import { Stepper } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Stepper.Root                 <ol>; current step; chevrons between horizontal items
+└─ Stepper.Item              <li> with a <button>; a direct child of Root (index = order)
+   ├─ Stepper.Indicator      circle: number, check when completed, or custom content
+   ├─ Stepper.Content        text column
+   │  ├─ Stepper.Title       step name
+   │  └─ Stepper.Description muted support text
+   └─ Stepper.Arrow          trailing chevron for vertical rows that open a page or panel
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Stepper.Root
+`ref` → `HTMLOListElement`. `<ol>` of items; owns the current step, numbers the items and adds chevrons between horizontal ones.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | — | Current step, 0-based (controlled). |
+| `defaultValue` | `number` | `0` | Initial step (uncontrolled). |
+| `onValueChange` | `(index: number) => void` | — | Called with the index of the clicked item. |
+| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Column of rows, or a row with chevrons that stacks below a 480px container. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Indicator 20 · 24 · 28 · 32 · 36, title in the control text of the tier. |
+| `children` | `ReactNode` | — | `Stepper.Item`s as direct children (an array from `map` is fine). |
+| `…rest` | `Omit<OlHTMLAttributes<HTMLOListElement>, "defaultValue" \| "onChange">` | — | `aria-label`, `className` and the other list attributes. |
+
+### Stepper.Item
+`ref` → `HTMLButtonElement`. One step: an `<li>` with a `<button>` (and, between horizontal steps, the decorative chevron in front of it); `aria-current="step"` when active.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `status` | `"pending" \| "active" \| "completed" \| "danger"` | — | Overrides the status derived from `value` (before → `completed`, equal → `active`, after → `pending`). |
+| `disabled` | `boolean` | — | The item cannot be selected. |
+| `children` | `ReactNode` | — | `Stepper.Indicator`, `Stepper.Content`, optional `Stepper.Arrow`. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">` | — | `onClick` (runs first; `preventDefault()` stops the selection), `className` and the other button attributes. |
+
+### Stepper.Indicator
+`ref` → `HTMLSpanElement`. The circle (`aria-hidden`): the item number, or a check when completed.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Replaces the default content, e.g. `<Icon name="status.danger" />`. |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
+
+### Stepper.Content
+`ref` → `HTMLSpanElement`. Text column for the title and the description.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
+
+### Stepper.Title · Stepper.Description
+`ref` → `HTMLSpanElement`. Step title in the control text; muted secondary line in the hint text.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
+
+### Stepper.Arrow
+`ref` → `SVGSVGElement`. Trailing chevron (`aria-hidden`) for vertical items that open a page or panel.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<SVGAttributes<SVGSVGElement>, "children">` | — | `className` and the other svg attributes. |
+
+## Variants
+
+### orientation
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `vertical` | full-width rows (indicator · text · optional arrow); hover `fill-subtle`, active row on `fill-subtle`, danger row on `danger-soft` | side columns of wizards, step lists with descriptions | yes |
+| `horizontal` | items in a row with placeholder-colored chevrons between them; hover → primary text; below a 30rem container the items stack one per row and chevrons hide | checkout headers with short step names | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | indicator 20, 12/16 text, check 14 | dense panels | |
+| `s` | indicator 24, 13/20 text, check 14 | compact cards | |
+| `m` | indicator 28, 14/20 text, check 16 | default | yes |
+| `l` | indicator 32, 16/24 text, check 16 | large forms | |
+| `xl` | indicator 36, 16/24 text, check 20 | hero onboarding | |
+
+Title uses the control text of the tier, Description the hint text of the tier.
+
+### status
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `pending` | `fill-muted` circle with secondary number, secondary text | steps after the current one | derived |
+| `active` | accent circle with a `space-1` `accent-soft` halo, primary text | the current step | derived |
+| `completed` | `accent-soft` circle with an accent check (`Icon action.check`), primary text | finished steps | derived |
+| `danger` | horizontal: `danger-soft` circle; vertical: solid danger circle on a `danger-soft` row; danger text | a step that needs attention | |
+
+Derive statuses from `value`; set `status="danger"` only on the failing step with an indicator that is not a number (`<Icon name="status.danger" />`); disable steps the user cannot reach yet. Avoid `Stepper.Arrow` in horizontal mode (the root adds chevrons) and several `active` steps.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| status | `value` or `status` | `data-status` on the button and the indicator; `aria-current="step"` on the active item |
+| disabled | `disabled` | native `disabled`, `data-disabled="true"`, `text-disabled`, muted indicator without halo |
+| hover / active | pointer | vertical `fill-subtle` / `fill-subtle-active`; horizontal text → primary; press scale |
+| focus-visible | keyboard | outer focus ring |
+
+Root attributes: `data-orientation`, `data-size`. Uncontrolled (`defaultValue`) clicks still select items.
+
+Motion: a status change moves the indicator's fill, color and halo over `base`; the row fill and text color change over `fast`; press scales the step to `--prime-motion-press-scale`. Under reduced motion the indicator changes at once.
+
+## Layout & spacing
+- The root is a size container (`inline-size: 100%`): give it a definite width, a shrink-wrapped parent collapses it.
+- Wizard: stepper column and form side by side with `gap: var(--prime-space-8)`, stacking on narrow widths.
+- Vertical rows are separated by `var(--prime-space-1)` (`var(--prime-space-2)` at `size="xl"`); the same value is the row gap of a wrapping horizontal stepper.
+- Horizontal steps and their chevrons sit 8 · 12 · 16 · 20 · 24 apart (xs → xl); below a 30rem (480px) container each step takes its own full-width row with the vertical row padding.
+- Indicator → text gap 8 (xs, s) · 12 (m, l) · 16 (xl); titles are medium weight and wrap long words.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus between items; a disabled one is skipped. |
+| `Enter` · `Space` | Selects the item. |
+
+### ARIA
+- Semantic `<ol>`; each item is a `<button>` inside an `<li>`; the active one has `aria-current="step"`.
+- Separators, indicator and arrow are `aria-hidden`; the name comes from Title (and Description).
+- Give the `<ol>` an `aria-label` when there are several steppers on a page.
+
+### 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) | Steps of a process: done ones get a check, the current one is highlighted — `defaultValue`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier: indicator 20 to 36 px, title in the control text of the tier — `size`. |
+| [states.tsx](examples/states.tsx) | Statuses that come from the server, a failed step with its own indicator and a locked step — `status`, `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | Vertical rows that open a page or panel end with a chevron — `Stepper.Arrow`. |
+| [orientation.tsx](examples/orientation.tsx) | A row of steps with chevrons between them above the content, and a column for a side panel — `orientation`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the current step: Back and Next move it, far steps stay locked until reached — `value`, `onValueChange`. |
+| [narrow.tsx](examples/narrow.tsx) | A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons. |
+
+## Mistakes
+- Wrapping `Stepper.Item` in another component or element → it must be a direct child of Root (it throws otherwise).
+- 1-based `value` → steps are 0-based.
+- Adding separators by hand in horizontal mode → every step already draws its chevron.
+- `status="error"` → the status is `danger`; give it an indicator that is not a number so it does not read by color only.
+
+## Related
+- **Built from:** Icon (`action.check`, `nav.chevronRight`)
+- **See also:** [Tabs](../tabs/COMPONENT.md), [Pagination](../pagination/COMPONENT.md), [Timeline](../timeline/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md)

package/dist/skill/reference/components/stepper/examples/controlled.tsx

@@ -0,0 +1,46 @@
+/** The parent owns the current step: Back and Next move it, far steps stay locked until reached — `value`, `onValueChange`. */
+import { Button, Stepper } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const STEPS = [
+  { title: "Компания", description: "Название и ИНН" },
+  { title: "Контакты", description: "Кто будет администратором" },
+  { title: "Тариф", description: "Можно сменить позже" },
+];
+
+const LAST = STEPS.length - 1;
+
+export default function StepperControlledExample() {
+  const [step, setStep] = React.useState(0);
+
+  return (
+    <div className={styles.column}>
+      <Stepper.Root value={step} onValueChange={setStep}>
+        {STEPS.map((item, index) => (
+          <Stepper.Item key={item.title} disabled={index > step + 1}>
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>{item.title}</Stepper.Title>
+              <Stepper.Description>{item.description}</Stepper.Description>
+            </Stepper.Content>
+          </Stepper.Item>
+        ))}
+      </Stepper.Root>
+      <div className={styles.actions}>
+        <Button.Root
+          variant="outline"
+          tone="neutral"
+          disabled={step === 0}
+          onClick={() => setStep(step - 1)}
+        >
+          Назад
+        </Button.Root>
+        <Button.Root disabled={step === LAST} onClick={() => setStep(step + 1)}>
+          Далее
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/dist/skill/reference/components/stepper/examples/examples.module.css

@@ -0,0 +1,24 @@
+/* Layout of the Stepper scenarios: semantic tokens only. */
+
+/* The stepper measures its own width (container query), so its wrapper needs one. */
+.wide {
+  width: 100%;
+}
+
+/* A side column for a vertical stepper (288px), with anything under it a group gap away. */
+.column {
+  display: grid;
+  gap: var(--prime-space-4);
+  width: min(100%, calc(var(--prime-space-24) * 3));
+}
+
+/* A phone-width container (320px). */
+.narrow {
+  width: min(100%, calc(var(--prime-drawer-width-s) - var(--prime-space-10)));
+}
+
+/* Back / Next under the stepper. */
+.actions {
+  display: flex;
+  gap: var(--prime-space-2);
+}

package/dist/skill/reference/components/stepper/examples/narrow.tsx

@@ -0,0 +1,23 @@
+/** A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons. */
+import { Stepper } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const STEPS = ["Компания", "Реквизиты", "Договор"];
+
+export default function StepperNarrowExample() {
+  return (
+    <div className={styles.narrow}>
+      <Stepper.Root orientation="horizontal" defaultValue={1}>
+        {STEPS.map((title) => (
+          <Stepper.Item key={title}>
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>{title}</Stepper.Title>
+            </Stepper.Content>
+          </Stepper.Item>
+        ))}
+      </Stepper.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/stepper/examples/orientation.tsx

@@ -0,0 +1,35 @@
+/** A row of steps with chevrons between them above the content, and a column for a side panel — `orientation`. */
+import { Stepper } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const STEPS = ["Корзина", "Доставка", "Оплата"];
+
+export default function StepperOrientationExample() {
+  return (
+    <>
+      <Stepper.Root orientation="horizontal" defaultValue={1}>
+        {STEPS.map((title) => (
+          <Stepper.Item key={title}>
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>{title}</Stepper.Title>
+            </Stepper.Content>
+          </Stepper.Item>
+        ))}
+      </Stepper.Root>
+      <div className={styles.column}>
+        <Stepper.Root orientation="vertical" defaultValue={1}>
+          {STEPS.map((title) => (
+            <Stepper.Item key={title}>
+              <Stepper.Indicator />
+              <Stepper.Content>
+                <Stepper.Title>{title}</Stepper.Title>
+              </Stepper.Content>
+            </Stepper.Item>
+          ))}
+        </Stepper.Root>
+      </div>
+    </>
+  );
+}

package/dist/skill/reference/components/stepper/examples/overview.tsx

@@ -0,0 +1,28 @@
+/** Steps of a process: done ones get a check, the current one is highlighted — `defaultValue`. */
+import { Stepper } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const STEPS = [
+  { title: "Компания", description: "Название и ИНН" },
+  { title: "Реквизиты", description: "Банк и расчётный счёт" },
+  { title: "Договор", description: "Подпись и печать" },
+];
+
+export default function StepperOverviewExample() {
+  return (
+    <div className={styles.column}>
+      <Stepper.Root defaultValue={1}>
+        {STEPS.map((step) => (
+          <Stepper.Item key={step.title}>
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>{step.title}</Stepper.Title>
+              <Stepper.Description>{step.description}</Stepper.Description>
+            </Stepper.Content>
+          </Stepper.Item>
+        ))}
+      </Stepper.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/stepper/examples/sizes.tsx

@@ -0,0 +1,31 @@
+/** Every size tier: indicator 20 to 36 px, title in the control text of the tier — `size`. */
+import { Stepper, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+const STEPS = ["Аккаунт", "Команда", "Готово"];
+
+export default function StepperSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.wide}>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+          <Stepper.Root orientation="horizontal" size={size} defaultValue={1}>
+            {STEPS.map((title) => (
+              <Stepper.Item key={title}>
+                <Stepper.Indicator />
+                <Stepper.Content>
+                  <Stepper.Title>{title}</Stepper.Title>
+                </Stepper.Content>
+              </Stepper.Item>
+            ))}
+          </Stepper.Root>
+        </div>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/stepper/examples/states.tsx

@@ -0,0 +1,49 @@
+/** Statuses that come from the server, a failed step with its own indicator and a locked step — `status`, `disabled`. */
+import { Icon, Stepper } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function StepperStatesExample() {
+  return (
+    <div className={styles.column}>
+      <Stepper.Root>
+        <Stepper.Item status="completed">
+          <Stepper.Indicator />
+          <Stepper.Content>
+            <Stepper.Title>Оплата прошла</Stepper.Title>
+            <Stepper.Description>12 400 ₽ списано с карты</Stepper.Description>
+          </Stepper.Content>
+        </Stepper.Item>
+        <Stepper.Item status="danger">
+          <Stepper.Indicator>
+            <Icon name="status.danger" />
+          </Stepper.Indicator>
+          <Stepper.Content>
+            <Stepper.Title>Ошибка доставки</Stepper.Title>
+            <Stepper.Description>Проверьте адрес получателя</Stepper.Description>
+          </Stepper.Content>
+        </Stepper.Item>
+        <Stepper.Item status="active">
+          <Stepper.Indicator />
+          <Stepper.Content>
+            <Stepper.Title>Подтверждение</Stepper.Title>
+            <Stepper.Description>Ждём ответа склада</Stepper.Description>
+          </Stepper.Content>
+        </Stepper.Item>
+        <Stepper.Item status="pending">
+          <Stepper.Indicator />
+          <Stepper.Content>
+            <Stepper.Title>Получение</Stepper.Title>
+          </Stepper.Content>
+        </Stepper.Item>
+        <Stepper.Item status="pending" disabled>
+          <Stepper.Indicator />
+          <Stepper.Content>
+            <Stepper.Title>Отзыв</Stepper.Title>
+            <Stepper.Description>Откроется после получения</Stepper.Description>
+          </Stepper.Content>
+        </Stepper.Item>
+      </Stepper.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/stepper/examples/with-icon.tsx

@@ -0,0 +1,29 @@
+/** Vertical rows that open a page or panel end with a chevron — `Stepper.Arrow`. */
+import { Stepper } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const STEPS = [
+  { title: "Корзина", description: "3 товара" },
+  { title: "Доставка", description: "Адрес и интервал" },
+  { title: "Оплата", description: "Карта или СБП" },
+];
+
+export default function StepperWithIconExample() {
+  return (
+    <div className={styles.column}>
+      <Stepper.Root defaultValue={1}>
+        {STEPS.map((step) => (
+          <Stepper.Item key={step.title}>
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>{step.title}</Stepper.Title>
+              <Stepper.Description>{step.description}</Stepper.Description>
+            </Stepper.Content>
+            <Stepper.Arrow />
+          </Stepper.Item>
+        ))}
+      </Stepper.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/switch/COMPONENT.md

@@ -0,0 +1,147 @@
+# Switch
+
+**Category:** selection
+**Kind:** control
+
+> An on/off switch for a setting that takes effect immediately.
+
+## When to use
+- A single setting that applies at once, without a submit button: notifications, feature flags, preferences.
+- A master switch that enables or disables a group of dependent settings.
+- A settings row with the text on the left and the track on the right.
+
+## When not to use
+- The value only takes effect after the form is submitted (consent, options in a form) → use [Checkbox](../checkbox/COMPONENT.md) instead.
+- One choice out of several options → use [Radio](../radio/COMPONENT.md) or [SegmentedControl](../segmented-control/COMPONENT.md) instead.
+- A button that toggles a view mode inside a toolbar → use [SegmentedControl](../segmented-control/COMPONENT.md) instead.
+
+## Import
+```tsx
+import { Switch } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Switch.Root          field grid; ref and input props go to the native input (role="switch")
+├─ <label> row       the native input, the track and the text (rendered by Root)
+│  └─ Switch.Label   the visible text (optional)
+└─ hint | error      support text under the text column (`hint`, `error`)
+```
+`<Switch.Root aria-label="…" />` without `Switch.Label` is a valid bare control (settings rows, tables).
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Switch.Root
+`ref` → `HTMLInputElement` (the native `input type="checkbox" role="switch"`). Renders the field `<div>`, the `<label>` row with the input and the track, and the support row. `className` goes to the field `<div>`, native input props to the input.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` | — | Controlled state. |
+| `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
+| `onCheckedChange` | `(checked: boolean) => void \| Promise<void>` | — | Called with the new state on every toggle. Return the save's promise: the thumb waits with a spinner; a controlled owner sets `checked` before resolving; on reject the thumb goes back (say why with `error`). |
+| `loading` | `boolean` | `false` | Saving, for an owner that tracks the request itself: a spinner in the thumb, `aria-busy` on the input, presses do nothing. A promise from `onCheckedChange` does the same on its own. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the track (24×16 … 44×24), the text and the gap. Without it the tier of its host (a form, a panel), else `m`. |
+| `hint` | `ReactNode` | — | Help text under the label text. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | `false` | Danger ring on the off track and `aria-invalid`. A non-empty `error` implies it. |
+| `disabled` | `boolean` | `false` | No toggling; muted track (on = `accent-soft`), dimmed text and hint. |
+| `readOnly` | `boolean` | `false` | The state is shown and focusable but does not change (`aria-readonly`); no hover or press. |
+| `id` | `string` | — | Id of the input (auto-generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
+| `aria-describedby` | `string` | — | Merged before the hint/error ids. |
+| `children` | `ReactNode` | — | `Switch.Label`. Without it only the track renders — name it with `aria-label` or `aria-labelledby`. |
+| `className` | `string` | — | Class on the field `<div>`. |
+| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange">` | — | `name`, `value`, `required`, `aria-label`, `aria-labelledby`… on the native input. |
+
+### Switch.Label
+`ref` → `HTMLSpanElement`. The visible text in the text column of the label row. Native `<span>` props.
+
+## Variants
+No `variant` / `tone` / `color`.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | track 24×16, thumb 12, 4px gap, 12/16 text | dense tables and toolbars | |
+| `s` | track 28×16, thumb 12, 8px gap, 13/20 text | compact settings lists | |
+| `m` | track 32×20, thumb 16, 8px gap, 14/20 text | regular settings and forms | yes |
+| `l` | track 36×20, thumb 16, 8px gap, 16/24 text | spacious settings pages | |
+| `xl` | track 44×24, thumb 20, 12px gap, 16/24 text | touch-first screens | |
+
+**Sizes:** the track is centred on the first text line; the text follows the tier (12 · 13 · 14 · 16 · 16). Use the same tier as the neighbouring Checkbox / Radio / inputs.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `readOnly` | normal colours, no hover or press, clicks ignored | the value is meaningful but someone else controls it | `false` |
+| `disabled` | muted track (on = `accent-soft`), dimmed text | the setting is unavailable | `false` |
+| `invalid` | danger ring on the off track | the message is shown elsewhere; otherwise pass `error` | `false` |
+| `loading` | a spinner turns inside the thumb, presses do nothing | the owner tracks the save itself; with a promise from `onCheckedChange` it comes on its own | `false` |
+
+**Combinations**
+- `readOnly` and `disabled` together are pointless — pick one.
+- `invalid` together with `error` is redundant; pass `error` alone.
+- A master switch sits above its dependants and drives their `disabled`.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| off | `checked={false}` / default | `data-state="unchecked"`; track `fill-strong` (hover `fill-strong-hover`), thumb at the start |
+| on | `checked` / `defaultChecked` | `data-state="checked"`; accent track, the thumb glides to the end |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid`; danger ring on the off track and on focus; the row shakes once when an error arrives (`data-shake`) |
+| disabled | `disabled` | `data-disabled="true"`; off track `fill-muted`, on track `accent-soft`, `cursor: not-allowed` |
+| read-only | `readOnly` | `aria-readonly="true"` on the input, `data-readonly="true"` on the field; no hover or press, default cursor |
+| saving | `loading`, or `onCheckedChange` returned a pending promise | the thumb stands in the new position with a `Spinner` inside (accent when on, muted when off; it enters with `enterMotion`), `aria-busy` on the input, `data-loading` on the track, presses ignored; a rejection glides the thumb back (`base`, emphasized) |
+| pressed | pointer press | the track scales to the compact press scale (not when disabled or read-only) |
+| focus-visible | keyboard | outer focus ring around the track |
+
+Root also carries `data-size`. Controlled: `checked` + `onCheckedChange`. Uncontrolled: `defaultChecked`. No native `onChange` prop.
+
+## Layout & spacing
+- Grid `[track][text]`; hint and error sit under the text column.
+- Switches in a settings list: gap `--prime-space-4`–`--prime-space-5` between fields.
+- Settings row (text left, switch right): flex row with `justify-content: space-between`, gap `--prime-space-4`; a bare `Switch.Root` with `aria-labelledby` / `aria-describedby` pointing at the row text.
+- In a form, a `name`d switch submits `"on"` when checked (native checkbox semantics).
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the switch. |
+| `Space` | Toggles it (not while `readOnly` or saving). |
+
+### ARIA
+- A native `<input type="checkbox" role="switch">` (its native checked state is the switch state), visually hidden over the track and wrapped by the `<label>` row.
+- `aria-invalid`, `aria-readonly` and `aria-describedby` (your ids + the hint or the error) are set on the input.
+- Without visible text, name it with `aria-label` or `aria-labelledby` on `Switch.Root`.
+- While a change is saved (`loading` or a pending promise) the input has `aria-busy`; the thumb's spinner is hidden from assistive tech. A refused save puts the state back — say why with `error`.
+
+### 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 setting that applies at once, with a hint under its text — `hint`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size, track 24×16 to 44×24; the text follows the control tier — `size`. |
+| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `readOnly`, `invalid`, `loading`, `disabled`. |
+| [settings-row.tsx](examples/settings-row.tsx) | A settings row with text on the left and a bare track on the right — `aria-labelledby`, `aria-describedby`. |
+| [saving.tsx](examples/saving.tsx) | A setting that applies on the server at once: the thumb waits in its new place with a spinner, and a refused save glides it back and says why — `onCheckedChange`, `error`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the state and rewrites the hint to match it — `checked`, `onCheckedChange`. |
+| [in-form.tsx](examples/in-form.tsx) | Switches submitted with a form: the value goes to FormData by `name`, a required one shows an error — `name`, `required`, `error`. |
+
+## Mistakes
+- `<Switch.Root onChange={…}>` → use `onCheckedChange`.
+- A switch whose value only applies after «Сохранить» → use `Checkbox`.
+- `invalid` plus `error` → pass `error` alone.
+- A bare switch without `aria-label` / `aria-labelledby` → it has no accessible name.
+- `readOnly` used to block a setting that is unavailable → use `disabled`.
+- Setting `checked` in `onCheckedChange` and flipping it back when the request fails, or a separate «saving» flag → return the request's promise; set `checked` only after it succeeds.
+
+## Related
+- **Built from:** [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Spinner](../spinner/COMPONENT.md) (saving); the row is a native `<label>`
+- **See also:** [Checkbox](../checkbox/COMPONENT.md), [Radio](../radio/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/dist/skill/reference/components/switch/examples/controlled.tsx

@@ -0,0 +1,17 @@
+/** The parent owns the state and rewrites the hint to match it — `checked`, `onCheckedChange`. */
+import { Switch } from "prime-ui-kit";
+import * as React from "react";
+
+export default function SwitchControlledExample() {
+  const [digest, setDigest] = React.useState(false);
+
+  return (
+    <Switch.Root
+      checked={digest}
+      onCheckedChange={setDigest}
+      hint={digest ? "Пришлём сводку в понедельник в 09:00" : "Сводка не приходит"}
+    >
+      <Switch.Label>Еженедельная сводка по продажам</Switch.Label>
+    </Switch.Root>
+  );
+}