prime-ui-kit 0.7.13 → 0.9.1

package/src/components/switch/COMPONENT.md

@@ -1,156 +1,141 @@
 # Switch
 
-**Default `size`:** `m` on the size axis unless the scenario explicitly needs another value.
+**Category:** selection
+**Kind:** control
 
-## About
+> An on/off switch for a setting that takes effect immediately.
 
-A compound on/off control: a native `input type="checkbox"` with `role="switch"`, a visual track and thumb, and optional slots for label text, hint, and error wired through `aria-describedby` and invalid state.
+## 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.
 
-- **Use** for binary settings (notifications, feature flags, billing options, consent) where the UI should read as on/off rather than a small checkbox in a list.
-- **Use** when forms need `name`, `value`, or `required` on the underlying input together with hint or error copy under the label column.
-- **Use** for a single independent toggle per row; state is obvious from the thumb position and `aria-checked`.
-- **Do not use** for picking exactly one option from mutually exclusive alternatives (prefer [Radio](../radio/COMPONENT.md)).
-- **Do not use** for lists with partial selection or an **indeterminate** state (prefer [Checkbox](../checkbox/COMPONENT.md)).
-- **Do not use** when you need `asChild` or fully custom markup; the structure is fixed to `Switch.*` parts and [Label](../label/COMPONENT.md) / [Hint](../hint/COMPONENT.md) primitives.
-
-## Composition
-
-- **`Switch.Root`** — field wrapper `div` with `data-size`, `data-variant`, `data-disabled`, `data-invalid`, `data-checked`, `data-readonly`; provides context and **`ControlSizeProvider`** for child parts. Renders **`children` only** (no shortcut that replaces **`Switch.Label`**).
-- **`Switch.Label`** — **`Label.Root`** row: the native switch **`input`**, the decorative **`track`**, and optional label copy; **`htmlFor`** / **`size`** come from context; **`ref`** on **`Root`** is forwarded to this **`input`**.
-- **`Switch.Hint`** — optional; registers hint text and contributes its id to **`aria-describedby`**; uses a dimmed hint variant when the field is **`disabled`**.
-- **`Switch.Error`** — optional; error-styled **[Hint](../hint/COMPONENT.md)** and registers invalid state when mounted (with **`variant="error"`** on **`Root`** when you want error chrome without the slot).
-- **Order:** **`Root`** → **`Label`** (required for the control to exist) → **`Hint`** / **`Error`** below when needed. Public API: **`Switch`** with **`Root`**, **`Label`**, **`Hint`**, **`Error`**.
-
-### Minimal example
+## 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";
-
-export function Example() {
-  return (
-    <Switch.Root defaultChecked name="reminders">
-      <Switch.Label>Deadline reminders</Switch.Label>
-    </Switch.Root>
-  );
-}
 ```
 
-### Canonical example (full shell)
-
-Use this when you want label text, a hint under the text column, and default **`size="m"`**. Always compose **`Switch.Label`** (and optional **`Switch.Hint`**) as **`children`** of **`Switch.Root`** — the **`label`** prop on **`Root`** is not rendered.
-
-```tsx
-import { Switch } from "prime-ui-kit";
-
-export function ProductUpdatesSwitch() {
-  return (
-    <Switch.Root defaultChecked name="product_updates">
-      <Switch.Label>Product updates</Switch.Label>
-      <Switch.Hint>
-        At most one email per week. You can change this anytime in notification settings.
-      </Switch.Hint>
-    </Switch.Root>
-  );
-}
+## Anatomy
 ```
-
-Source of truth (stays in sync with the snippet above): `examples/canonical-maximal.tsx`.
-
-### Scenarios (`playground/snippets/switch/` + `examples/`)
-
-Playground UI: **`playground/sections/SwitchSection.tsx`** — blocks **Размеры** and **Состояния** with `sizes.tsx` and `states.tsx` (`?raw` source tabs). Every snippet under **`playground/snippets/switch/`** has a package-oriented twin next to this file (import **`prime-ui-kit`**, same structure and copy unless noted). Workspace snippets use `@/components/switch/Switch`.
-
-| Snippet | Package example |
-|---------|-----------------|
-| [`sizes.tsx`](../../../playground/snippets/switch/sizes.tsx) | [`examples/sizes.tsx`](examples/sizes.tsx) — **`s`–`xl`**, **`defaultChecked`** |
-| [`states.tsx`](../../../playground/snippets/switch/states.tsx) | [`examples/states.tsx`](examples/states.tsx) — off/on, **`disabled`**, **`readOnly`**, **`variant="error"`** + **`Switch.Error`** |
-| [`variants.tsx`](../../../playground/snippets/switch/variants.tsx) | [`examples/variants.tsx`](examples/variants.tsx) — **`default`** vs **`error`** |
-| [`controlled.tsx`](../../../playground/snippets/switch/controlled.tsx) | [`examples/controlled.tsx`](examples/controlled.tsx) — **`checked`** / **`onCheckedChange`** |
-| [`composition.tsx`](../../../playground/snippets/switch/composition.tsx) | [`examples/composition.tsx`](examples/composition.tsx) — пустой **`Switch.Label`** + **`aria-label`** на **`Root`**; второй ряд — **`Label`** + **`Hint`** |
-| [`full-width.tsx`](../../../playground/snippets/switch/full-width.tsx) | [`examples/full-width.tsx`](examples/full-width.tsx) — обёртка-карточка **`width: 100%`** (`examples.module.css` → **`fullWidthCard`**) |
-| [`form-features.tsx`](../../../playground/snippets/switch/form-features.tsx) | [`examples/form-features.tsx`](examples/form-features.tsx) — **`name`**, **`defaultChecked`**, **`required`**, **`FormData`** on submit |
-
-Shared layout tokens for **`full-width`** / **`form-features`** in the playground: `playground/snippets/switch/snippets.module.css`.
-
-### Additional examples (narratives)
-
-| File | Intent |
-|------|--------|
-| `examples/canonical-maximal.tsx` | Full shell: **`Switch.Label`** + **`Switch.Hint`**, **`size="m"`** (English) |
-| `examples/scenario-settings-toggle.tsx` | Settings: several independent toggles in a **`fieldset`** |
-| `examples/scenario-feature-flag.tsx` | Controlled flag: **`checked`** / **`onCheckedChange`** + rollout copy |
-| `examples/scenario-billing-annual.tsx` | Billing: annual vs monthly as one switch with dynamic hint |
-| `examples/scenario-form-consent.tsx` | Form: **`name`**, **`required`**, **`FormData`** on submit |
-
-### Extended usage
-
-- **Controlled:** pass **`checked`** with **`onCheckedChange`**. **Uncontrolled:** use **`defaultChecked`** (defaults to **`false`**). Do not rely on **`onChange`** on **`Root`** for the boolean API — use **`onCheckedChange`**.
-- **`readOnly`** blocks toggling via **`preventDefault`** in the internal handler; **`aria-readonly`** is set on the input.
-- **Invalid / error:** mount **`Switch.Error`** and/or set **`variant="error"`** on **`Root`**; **`aria-invalid`** and error styling follow context.
-- **`aria-describedby`** on **`Root`** merges with hint and error ids when those slots are mounted; append your own ids on **`Root`** if you need extra descriptors.
-- **`Switch.Label`** with no visible **`children`** leaves only the track — supply **`aria-label`** / **`aria-labelledby`** on **`Root`** (or nearby visible text) for an accessible name.
-- **Grouping settings:** prefer a **`fieldset`** + **`legend`** over **`role="group"`** when several switches belong to one preference block.
-- There is no **indeterminate** or **loading** state; keyboard and focus use the native switch pattern with **`focus-visible`** on the track.
-
-### Note for LLMs
-
-When generating **Switch** markup for this library: (1) Always include **`Switch.Label`** as a **child** of **`Switch.Root`** — the **`label?: React.ReactNode`** prop on **`Root`** is **not** rendered and must not replace **`Switch.Label`** (it may end up forwarded to the native **`input`** if passed). (2) Use **`onCheckedChange`**, not **`onChange`**, for controlled on/off updates. (3) For controlled mode, pair **`checked`** with **`onCheckedChange`**; for forms, forward **`name`**, **`required`**, and other input attributes on **`Root`** (they go to the native **`input`**). (4) Order parts **`Root`** → **`Label`** → optional **`Hint`** / **`Error`**. (5) Do not wrap kit parts to restyle them; use **`size`**, **`variant`**, and documented props only. (6) Start from **`examples/canonical-maximal.tsx`** or the **`sizes`** / **`states`** snippet twins; use **`scenario-*.tsx`** for longer narratives.
-
-## Rules
-
-- **Controlled:** **`checked`** + **`onCheckedChange`**. **Uncontrolled:** **`defaultChecked`**.
-- **`readOnly`** prevents value changes on user interaction; **`aria-readonly`** is set.
-- **`variant="error"`** or mounted **`Switch.Error`** sets **`invalid`**, **`aria-invalid`**, and error styling; **`disabled`** disables the input and adjusts hint styling.
-- The public props type includes **`label?: React.ReactNode`**, but **`Root`** does not render it — compose **`Switch.Label`** as **`children`**.
-- **`size`** on **`Root`** drives layout tokens only; it is not a DOM **`size`** attribute on the **`input`**.
+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
 
-### Switch.Root
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Track and thumb scale from switch tokens. |
-| variant | `"default" \| "error"` | `"default"` | no | Error styling; **`invalid`** is also true when **`Switch.Error`** is mounted. |
-| checked | `boolean` | — | no | Controlled on state. |
-| defaultChecked | `boolean` | `false` | no | Initial on state when uncontrolled. |
-| onCheckedChange | `(checked: boolean) => void` | — | no | Called after the checked value changes from user input. |
-| disabled | `boolean` | — | no | Disables the input; **`data-disabled`** on the field root. |
-| readOnly | `boolean` | — | no | Prevents toggling; **`data-readonly`** and **`aria-readonly`**. |
-| label | `React.ReactNode` | — | no | Present on the type only; not used to render **`Switch.Label`**—compose **`Switch.Label`** as a child instead. |
-| id | `string` | auto (`useId`) | no | Stable input id; paired with **`Switch.Label`** via **`htmlFor`**. |
-| className | `string` | — | no | Class on the field wrapper **`div`**. |
-| aria-describedby | `string` | — | no | Combined with hint and error ids when those slots exist. |
-| children | `React.ReactNode` | — | no | Typically **`Switch.Label`** and optional **`Switch.Hint`** / **`Switch.Error`**. |
-| ref | `React.Ref<HTMLInputElement>` | — | no | Ref to the native **`input`**. |
-| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange">` | — | no | Other native attributes forwarded to the **`input`** (e.g. **`name`**, **`value`**, **`required`**, **`autoFocus`**, **`aria-*`**). **`type`** is always **`checkbox`**. |
+### 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. Field-root rule for a leaf: `className` goes to the field `<div>`; `id`, `ref` and 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` | — | Called with the new state on every toggle (not while `readOnly`). |
+| `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
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | no | Text beside the switch; omit only when an accessible name is provided elsewhere. |
-| className | `string` | — | no | Class on the label row. |
-| …rest | `Omit<React.HTMLAttributes<HTMLLabelElement>, "htmlFor" \| "size">` | — | no | Other label attributes; **`htmlFor`** and **`size`** are managed internally. |
-
-### Switch.Hint
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Supplementary text below the label. |
-| className | `string` | — | no | Class on the hint slot. |
-| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; **`id`** is managed internally. |
-
-### Switch.Error
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Error message text. |
-| className | `string` | — | no | Class on the error block. |
-| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; **`id`** is managed internally. |
+`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` |
+
+**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 |
+| 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 |
+| 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`). |
+
+### 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`.
+
+### 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`, `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`. |
+| [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`.
 
 ## Related
-
-- [Checkbox](../checkbox/COMPONENT.md) — groups, **indeterminate**, and checkbox semantics.
-- [Radio](../radio/COMPONENT.md) — one selected option from a set.
-- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — primitives inside the switch; pair with [Input](../input/COMPONENT.md) in larger forms.
+- **Built from:** [Label](../label/COMPONENT.md) (the row), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **See also:** [Checkbox](../checkbox/COMPONENT.md), [Radio](../radio/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/switch/examples/controlled.tsx

@@ -1,18 +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";
 
-import styles from "./examples.module.css";
-
-/** Controlled `checked` / `onCheckedChange`; mirrors `playground/snippets/switch/controlled.tsx`. */
 export default function SwitchControlledExample() {
-  const [on, setOn] = React.useState(false);
+  const [digest, setDigest] = React.useState(false);
 
   return (
-    <div className={styles.stackDense}>
-      <Switch.Root checked={on} onCheckedChange={setOn}>
-        <Switch.Label>Рассылка: {on ? "включена" : "выключена"}</Switch.Label>
-        <Switch.Hint>Состояние задаётся снаружи через checked и onCheckedChange</Switch.Hint>
-      </Switch.Root>
-    </div>
+    <Switch.Root
+      checked={digest}
+      onCheckedChange={setDigest}
+      hint={digest ? "Пришлём сводку в понедельник в 09:00" : "Сводка не приходит"}
+    >
+      <Switch.Label>Еженедельная сводка по продажам</Switch.Label>
+    </Switch.Root>
   );
 }

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

@@ -1,65 +1,30 @@
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
-}
+/* Layout of the Switch scenarios: semantic tokens only. */
 
-.stackDense {
+/* settings-row.tsx: text on the left, the track on the right. */
+.row {
   display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-s);
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+  width: min(100%, var(--prime-modal-width-s));
 }
 
-.settingsGroup {
-  margin: 0;
-  padding: 0;
-  border: none;
+.rowText {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-l);
-  max-width: 28rem;
-}
-
-.legend {
-  padding: 0;
-  margin: 0 0 var(--prime-sys-spacing-s);
-  font-size: var(--prime-sys-typography-sizeScale-m);
-  line-height: var(--prime-sys-typography-lineHeightScale-m);
-  font-weight: var(--prime-sys-typography-weight-medium);
-  color: var(--prime-sys-color-content-primary);
-}
-
-.muted {
-  margin: 0;
-  color: var(--prime-sys-color-content-secondary);
-  font-size: var(--prime-sys-typography-sizeScale-s);
-  line-height: var(--prime-sys-typography-lineHeightScale-s);
-}
-
-.fullWidthCard {
-  box-sizing: border-box;
-  width: 100%;
-  max-width: 22rem;
-  padding: var(--prime-sys-spacing-m);
-  border: 1px solid var(--prime-sys-color-border-subtle);
-  border-radius: var(--prime-sys-shape-radius-m);
+  gap: var(--prime-space-1);
+  min-width: 0;
 }
 
+/* in-form.tsx: switches, then actions (group → actions 32). */
 .form {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
-  max-width: 24rem;
+  gap: var(--prime-space-4);
+  width: min(100%, var(--prime-modal-width-s));
 }
 
-.formSubmit {
-  align-self: flex-start;
-  padding: var(--prime-sys-spacing-s) var(--prime-sys-spacing-m);
-  border-radius: var(--prime-sys-shape-radius-m);
-}
-
-.formMessage {
-  margin: 0;
-  font-size: var(--prime-sys-typography-sizeScale-s);
-  line-height: var(--prime-sys-typography-lineHeightScale-s);
+.formActions {
+  display: flex;
+  margin-top: var(--prime-space-4);
 }

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

@@ -0,0 +1,34 @@
+/** Switches submitted with a form: the value goes to FormData by `name`, a required one shows an error — `name`, `required`, `error`. */
+import { Button, Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SwitchInFormExample() {
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const accepted = new FormData(event.currentTarget).get("processing") === "on";
+    setError(accepted ? undefined : "Без согласия аккаунт не создать");
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Switch.Root name="news" defaultChecked>
+        <Switch.Label>Новости продукта</Switch.Label>
+      </Switch.Root>
+      <Switch.Root
+        name="processing"
+        required
+        error={error}
+        onCheckedChange={(checked) => checked && setError(undefined)}
+      >
+        <Switch.Label>Согласие на обработку данных</Switch.Label>
+      </Switch.Root>
+      <div className={styles.formActions}>
+        <Button.Root type="submit">Создать аккаунт</Button.Root>
+      </div>
+    </form>
+  );
+}

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

@@ -0,0 +1,10 @@
+/** A setting that applies at once, with a hint under its text — `hint`. */
+import { Switch } from "prime-ui-kit";
+
+export default function SwitchOverviewExample() {
+  return (
+    <Switch.Root defaultChecked hint="Каждую ночь в 03:00 по Москве">
+      <Switch.Label>Резервное копирование</Switch.Label>
+    </Switch.Root>
+  );
+}

package/src/components/switch/examples/settings-row.tsx

@@ -0,0 +1,24 @@
+/** A settings row with text on the left and a bare track on the right — `aria-labelledby`, `aria-describedby`. */
+import { Switch, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function SwitchSettingsRowExample() {
+  return (
+    <div className={styles.row}>
+      <div className={styles.rowText}>
+        <Typography id="two-factor-title" variant="title-s">
+          Двухфакторная защита
+        </Typography>
+        <Typography id="two-factor-description" variant="body-s" tone="secondary">
+          Код из приложения при каждом входе
+        </Typography>
+      </div>
+      <Switch.Root
+        defaultChecked
+        aria-labelledby="two-factor-title"
+        aria-describedby="two-factor-description"
+      />
+    </div>
+  );
+}

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

@@ -1,23 +1,18 @@
+/** Every size, track 24×16 to 44×24; the text follows the control tier — `size`. */
 import { Switch } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
-/** Ladder `s`–`xl`; mirrors `playground/snippets/switch/sizes.tsx`. */
 export default function SwitchSizesExample() {
   return (
-    <div className={styles.stack}>
-      <Switch.Root size="s" defaultChecked>
-        <Switch.Label>Switch s</Switch.Label>
-      </Switch.Root>
-      <Switch.Root size="m" defaultChecked>
-        <Switch.Label>Switch m</Switch.Label>
-      </Switch.Root>
-      <Switch.Root size="l" defaultChecked>
-        <Switch.Label>Switch l</Switch.Label>
-      </Switch.Root>
-      <Switch.Root size="xl" defaultChecked>
-        <Switch.Label>Switch xl</Switch.Label>
-      </Switch.Root>
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Switch.Root size={size} defaultChecked>
+            <Switch.Label>{size}</Switch.Label>
+          </Switch.Root>
+        </div>
+      ))}
     </div>
   );
 }

package/src/components/switch/examples/states.tsx

@@ -1,32 +1,43 @@
+/** Every state side by side, each labelled by its prop — `checked`, `readOnly`, `invalid`, `disabled`. */
 import { Switch } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
-/** Off, on, disabled, read-only, error; mirrors `playground/snippets/switch/states.tsx`. */
 export default function SwitchStatesExample() {
   return (
-    <div className={styles.stack}>
-      <Switch.Root>
-        <Switch.Label>Switch off</Switch.Label>
-        <Switch.Hint>Switch hint</Switch.Hint>
-      </Switch.Root>
-      <Switch.Root defaultChecked>
-        <Switch.Label>Switch on</Switch.Label>
-        <Switch.Hint>Switch hint</Switch.Hint>
-      </Switch.Root>
-      <Switch.Root disabled>
-        <Switch.Label>Switch disabled off</Switch.Label>
-      </Switch.Root>
-      <Switch.Root defaultChecked disabled>
-        <Switch.Label>Switch disabled on</Switch.Label>
-      </Switch.Root>
-      <Switch.Root defaultChecked readOnly>
-        <Switch.Label>Switch readonly on</Switch.Label>
-      </Switch.Root>
-      <Switch.Root variant="error">
-        <Switch.Label>Switch error</Switch.Label>
-        <Switch.Error>Switch error message</Switch.Error>
-      </Switch.Root>
-    </div>
+    <>
+      <div>
+        <div>
+          <Switch.Root>
+            <Switch.Label>unchecked</Switch.Label>
+          </Switch.Root>
+        </div>
+        <div>
+          <Switch.Root defaultChecked>
+            <Switch.Label>checked</Switch.Label>
+          </Switch.Root>
+        </div>
+        <div>
+          <Switch.Root defaultChecked readOnly>
+            <Switch.Label>readOnly</Switch.Label>
+          </Switch.Root>
+        </div>
+        <div>
+          <Switch.Root invalid>
+            <Switch.Label>invalid</Switch.Label>
+          </Switch.Root>
+        </div>
+      </div>
+      <div>
+        <div>
+          <Switch.Root disabled>
+            <Switch.Label>disabled</Switch.Label>
+          </Switch.Root>
+        </div>
+        <div>
+          <Switch.Root disabled defaultChecked>
+            <Switch.Label>disabled · checked</Switch.Label>
+          </Switch.Root>
+        </div>
+      </div>
+    </>
   );
 }