prime-ui-kit 0.0.1

package/src/components/stepper/examples/low-level-api.tsx

@@ -0,0 +1,58 @@
+import { HorizontalStepper, VerticalStepper } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** `HorizontalStepper` / `VerticalStepper`: you own each row `state`; no semantic `<ol>`. */
+export default function StepperLowLevelApiExample() {
+  const [horizontalActive, setHorizontalActive] = React.useState(0);
+  const [verticalActive, setVerticalActive] = React.useState(0);
+
+  const steps = [
+    { label: "Profile", indicator: "1" },
+    { label: "Role", indicator: "2" },
+    { label: "Access", indicator: "3" },
+  ] as const;
+
+  const getState = (idx: number): "completed" | "active" | "default" => {
+    if (idx < horizontalActive) return "completed";
+    if (idx === horizontalActive) return "active";
+    return "default";
+  };
+
+  const getStateV = (idx: number): "completed" | "active" | "default" => {
+    if (idx < verticalActive) return "completed";
+    if (idx === verticalActive) return "active";
+    return "default";
+  };
+
+  return (
+    <div className={styles.stackLoose}>
+      <HorizontalStepper.Root className={styles.horizontalRailMd}>
+        {steps.map((step, idx) => (
+          <React.Fragment key={step.label}>
+            {idx > 0 ? <HorizontalStepper.SeparatorIcon /> : null}
+            <HorizontalStepper.Item state={getState(idx)} onClick={() => setHorizontalActive(idx)}>
+              <HorizontalStepper.ItemIndicator>{step.indicator}</HorizontalStepper.ItemIndicator>
+              {step.label}
+            </HorizontalStepper.Item>
+          </React.Fragment>
+        ))}
+      </HorizontalStepper.Root>
+
+      <VerticalStepper.Root className={styles.verticalRail}>
+        {steps.map((step, idx) => (
+          <VerticalStepper.Item
+            key={step.label}
+            state={getStateV(idx)}
+            onClick={() => setVerticalActive(idx)}
+          >
+            <VerticalStepper.ItemIndicator>{step.indicator}</VerticalStepper.ItemIndicator>
+            {step.label}
+            {getStateV(idx) === "active" ? <VerticalStepper.Arrow /> : null}
+          </VerticalStepper.Item>
+        ))}
+      </VerticalStepper.Root>
+    </div>
+  );
+}

package/src/components/stepper/examples/orientation.tsx

@@ -0,0 +1,52 @@
+import { Stepper } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** Horizontal flow with `SeparatorIcon`; vertical default with `Arrow` on active rows. */
+export default function StepperOrientationExample() {
+  const [horizontalStep, setHorizontalStep] = React.useState(1);
+  const [verticalStep, setVerticalStep] = React.useState(1);
+
+  return (
+    <div className={styles.stackLoose}>
+      <Stepper.Root
+        orientation="horizontal"
+        currentStep={horizontalStep}
+        className={styles.horizontalRailXl}
+      >
+        <Stepper.Step type="button" onClick={() => setHorizontalStep(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Cart" />
+        </Stepper.Step>
+        <Stepper.SeparatorIcon />
+        <Stepper.Step type="button" onClick={() => setHorizontalStep(1)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Shipping" />
+        </Stepper.Step>
+        <Stepper.SeparatorIcon />
+        <Stepper.Step type="button" onClick={() => setHorizontalStep(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Payment" />
+        </Stepper.Step>
+      </Stepper.Root>
+
+      <Stepper.Root currentStep={verticalStep}>
+        <Stepper.Step type="button" onClick={() => setVerticalStep(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Draft" />
+          <Stepper.Arrow />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setVerticalStep(1)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Edits" description="Edit body copy" />
+          <Stepper.Arrow />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setVerticalStep(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Publish" />
+        </Stepper.Step>
+      </Stepper.Root>
+    </div>
+  );
+}

package/src/components/stepper/examples/polymorphic-as.tsx

@@ -0,0 +1,51 @@
+import { HorizontalStepper, IconHouse, IconMail, VerticalStepper } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** `as` on `HorizontalStepper.SeparatorIcon` and `VerticalStepper.Arrow` for custom icons. */
+export default function StepperPolymorphicAsExample() {
+  const [horizontalActive, setHorizontalActive] = React.useState(1);
+  const [verticalActive, setVerticalActive] = React.useState(0);
+
+  return (
+    <div className={styles.stackLoose}>
+      <HorizontalStepper.Root className={styles.horizontalRailMd}>
+        <HorizontalStepper.Item
+          state={horizontalActive > 0 ? "completed" : horizontalActive === 0 ? "active" : "default"}
+          onClick={() => setHorizontalActive(0)}
+        >
+          <HorizontalStepper.ItemIndicator>1</HorizontalStepper.ItemIndicator>
+          Start
+        </HorizontalStepper.Item>
+        <HorizontalStepper.SeparatorIcon as={IconHouse} />
+        <HorizontalStepper.Item
+          state={horizontalActive > 1 ? "completed" : horizontalActive === 1 ? "active" : "default"}
+          onClick={() => setHorizontalActive(1)}
+        >
+          <HorizontalStepper.ItemIndicator>2</HorizontalStepper.ItemIndicator>
+          Home
+        </HorizontalStepper.Item>
+      </HorizontalStepper.Root>
+
+      <VerticalStepper.Root className={styles.verticalRailNarrow}>
+        <VerticalStepper.Item
+          state={verticalActive > 0 ? "completed" : verticalActive === 0 ? "active" : "default"}
+          onClick={() => setVerticalActive(0)}
+        >
+          <VerticalStepper.ItemIndicator>1</VerticalStepper.ItemIndicator>
+          Notifications
+          {verticalActive === 0 ? <VerticalStepper.Arrow as={IconMail} /> : null}
+        </VerticalStepper.Item>
+        <VerticalStepper.Item
+          state={verticalActive > 1 ? "completed" : verticalActive === 1 ? "active" : "default"}
+          onClick={() => setVerticalActive(1)}
+        >
+          <VerticalStepper.ItemIndicator>2</VerticalStepper.ItemIndicator>
+          Cadence
+          {verticalActive === 1 ? <VerticalStepper.Arrow as={IconMail} /> : null}
+        </VerticalStepper.Item>
+      </VerticalStepper.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,71 @@
+import { Stepper } from "prime-ui-kit";
+import * as React from "react";
+
+/** Four `size` tiers on `Stepper.Root` — one row per size (`s`–`xl`). */
+export default function StepperSizesExample() {
+  const [stepS, setStepS] = React.useState(1);
+  const [stepM, setStepM] = React.useState(1);
+  const [stepL, setStepL] = React.useState(1);
+  const [stepXL, setStepXL] = React.useState(1);
+
+  return (
+    <>
+      <Stepper.Root size="s" currentStep={stepS}>
+        <Stepper.Step type="button" onClick={() => setStepS(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Account" description="Create or link account" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStepS(1)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Details" description="Fill profile details" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStepS(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Review" description="Confirm and submit" />
+        </Stepper.Step>
+      </Stepper.Root>
+      <Stepper.Root size="m" currentStep={stepM}>
+        <Stepper.Step type="button" onClick={() => setStepM(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Account" description="Create or link account" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStepM(1)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Details" description="Fill profile details" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStepM(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Review" description="Confirm and submit" />
+        </Stepper.Step>
+      </Stepper.Root>
+      <Stepper.Root size="l" currentStep={stepL}>
+        <Stepper.Step type="button" onClick={() => setStepL(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Account" description="Create or link account" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStepL(1)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Details" description="Fill profile details" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStepL(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Review" description="Confirm and submit" />
+        </Stepper.Step>
+      </Stepper.Root>
+      <Stepper.Root size="xl" currentStep={stepXL}>
+        <Stepper.Step type="button" onClick={() => setStepXL(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Account" description="Create or link account" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStepXL(1)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Details" description="Fill profile details" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setStepXL(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Review" description="Confirm and submit" />
+        </Stepper.Step>
+      </Stepper.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,44 @@
+import { Stepper } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** Disabled step and `status="error"` with custom `Indicator` content. */
+export default function StepperStatesExample() {
+  const [disabledStep, setDisabledStep] = React.useState(1);
+  const [errorStep, setErrorStep] = React.useState(1);
+
+  return (
+    <div className={styles.stackLoose}>
+      <Stepper.Root currentStep={disabledStep}>
+        <Stepper.Step type="button" onClick={() => setDisabledStep(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Done" />
+        </Stepper.Step>
+        <Stepper.Step type="button" disabled>
+          <Stepper.Indicator />
+          <Stepper.Content title="Unavailable" description="Opens after verification" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setDisabledStep(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Finish" />
+        </Stepper.Step>
+      </Stepper.Root>
+
+      <Stepper.Root currentStep={errorStep}>
+        <Stepper.Step type="button" onClick={() => setErrorStep(0)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Payment OK" />
+        </Stepper.Step>
+        <Stepper.Step type="button" status="error" onClick={() => setErrorStep(1)}>
+          <Stepper.Indicator>!</Stepper.Indicator>
+          <Stepper.Content title="Delivery error" description="Check address and slot" />
+        </Stepper.Step>
+        <Stepper.Step type="button" onClick={() => setErrorStep(2)}>
+          <Stepper.Indicator />
+          <Stepper.Content title="Confirm" />
+        </Stepper.Step>
+      </Stepper.Root>
+    </div>
+  );
+}

package/src/components/switch/COMPONENT.md

@@ -0,0 +1,156 @@
+# Switch
+
+**Default `size`:** `m` on the size axis unless the scenario explicitly needs another value.
+
+## About
+
+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.
+
+- **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
+
+```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>
+  );
+}
+```
+
+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`**.
+
+## API
+
+### Switch.Root
+
+| 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.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. |
+
+## 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.

package/src/components/switch/examples/canonical-maximal.tsx

@@ -0,0 +1,19 @@
+import { Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Full composition: label column, hint under the text, default size `m`.
+ */
+export default function SwitchCanonicalMaximal() {
+  return (
+    <div className={styles.stackDense}>
+      <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>
+    </div>
+  );
+}

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

@@ -0,0 +1,23 @@
+import { Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Пустой `Switch.Label` + `aria-label`; колонка текста + hint; mirrors `playground/snippets/switch/composition.tsx`. */
+export default function SwitchCompositionExample() {
+  return (
+    <div className={styles.stack}>
+      <Switch.Root
+        defaultChecked
+        aria-label="Включено: имя для скринридеров без видимого текста у трека"
+      >
+        <Switch.Label />
+      </Switch.Root>
+      <Switch.Root>
+        <Switch.Label>Разметка через Switch.Label и подсказка ниже</Switch.Label>
+        <Switch.Hint>
+          Hint выровнен под колонку текста; для ошибки используйте Switch.Error рядом с тем же Root.
+        </Switch.Hint>
+      </Switch.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,18 @@
+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);
+
+  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>
+  );
+}

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

@@ -0,0 +1,65 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.stackDense {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+}
+
+.settingsGroup {
+  margin: 0;
+  padding: 0;
+  border: none;
+  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);
+}
+
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+  max-width: 24rem;
+}
+
+.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);
+}

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

@@ -0,0 +1,31 @@
+import { Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** `name`, `defaultChecked`, `required` и submit; mirrors `playground/snippets/switch/form-features.tsx`. */
+export default function SwitchFormFeaturesExample() {
+  const [message, setMessage] = React.useState<string | null>(null);
+
+  return (
+    <form
+      className={styles.form}
+      onSubmit={(e) => {
+        e.preventDefault();
+        const data = new FormData(e.currentTarget);
+        setMessage(data.get("newsletter") === "on" ? "Подписка включена" : "Флажок не отмечен");
+      }}
+    >
+      <Switch.Root name="newsletter" defaultChecked>
+        <Switch.Label>Новости продукта</Switch.Label>
+      </Switch.Root>
+      <Switch.Root name="digest" required>
+        <Switch.Label>Еженедельный дайджест (обязательно)</Switch.Label>
+      </Switch.Root>
+      <button type="submit" className={styles.formSubmit}>
+        Отправить
+      </button>
+      {message != null ? <p className={styles.formMessage}>{message}</p> : null}
+    </form>
+  );
+}

package/src/components/switch/examples/full-width.tsx

@@ -0,0 +1,15 @@
+import { Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Root на всю ширину контейнера; mirrors `playground/snippets/switch/full-width.tsx`. */
+export default function SwitchFullWidthExample() {
+  return (
+    <div className={styles.fullWidthCard}>
+      <Switch.Root defaultChecked>
+        <Switch.Label>Растягивается на ширину карточки</Switch.Label>
+        <Switch.Hint>Корень поля занимает 100% ширины контейнера</Switch.Hint>
+      </Switch.Root>
+    </div>
+  );
+}

package/src/components/switch/examples/scenario-billing-annual.tsx

@@ -0,0 +1,27 @@
+import { Switch, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Billing: annual plan as a single on/off switch with savings context.
+ */
+export default function SwitchScenarioBillingAnnual() {
+  const [annual, setAnnual] = React.useState(false);
+
+  return (
+    <div className={styles.stack}>
+      <Typography.Root as="p" variant="body-default" className={styles.muted}>
+        Choose how you are billed. Annual includes two months free on the Pro plan.
+      </Typography.Root>
+      <Switch.Root checked={annual} onCheckedChange={setAnnual} name="billing_cycle">
+        <Switch.Label>Bill annually</Switch.Label>
+        <Switch.Hint>
+          {annual
+            ? "You will be charged once per year at the discounted rate."
+            : "Switch on to save compared to twelve monthly charges."}
+        </Switch.Hint>
+      </Switch.Root>
+    </div>
+  );
+}