prime-ui-kit 0.3.1 → 0.4.0

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

@@ -1,17 +1,17 @@
 # Switch
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**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.
 
-- **When to use** — binary settings (notifications, feature flags, consent) where the UI should read as on/off rather than a small checkbox in a list.
-- **When to use** — forms that need `name`, `value`, or `required` on the underlying input together with hint or error copy under the label column.
-- **When to use** — a single independent toggle per row; state is obvious from the thumb position and `aria-checked`.
-- **When not to use** — picking exactly one option from mutually exclusive alternatives (prefer [Radio](../radio/COMPONENT.md)).
-- **When not to use** — lists with partial selection or an **indeterminate** state (prefer [Checkbox](../checkbox/COMPONENT.md)).
-- **When not to use** — you need `asChild` or fully custom markup; the structure is fixed to `Switch.*` parts and [Label](../label/COMPONENT.md) / [Hint](../hint/COMPONENT.md) primitives.
+- **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
 
@@ -35,16 +35,74 @@ export function Example() {
 }
 ```
 
+### 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 size="m" 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:** pass **`checked`** with **`onCheckedChange`**. **Uncontrolled:** use **`defaultChecked`** (defaults to **`false`**). User toggles run through the internal change handler; **`onChange`** on **`Root`** is not the switch API—use **`onCheckedChange`** only.
-- **`readOnly`** calls **`preventDefault`** in the change handler so the value does not change on click; **`aria-readonly`** is set on the input.
-- **`variant="error"`** or a mounted **`Switch.Error`** sets **`invalid`** in context, **`aria-invalid`** on the input, and error styling; **`disabled`** disables the input and adjusts hint styling.
-- **`aria-describedby`** on **`Root`** is merged with hint and error ids when those slots are mounted; add your own ids in **`aria-describedby`** if you need extra descriptors.
-- **`Switch.Label`** with no visible **`children`** leaves only the track; set an accessible name with **`aria-label`** or **`aria-labelledby`** on **`Root`** (or ensure context from nearby text).
-- The public props type includes **`label?: React.ReactNode`**, but **`Root`** does not render it as **`Switch.Label`**—always compose **`Switch.Label`** (and optional **`Hint`** / **`Error`**) as **`children`**.
-- Keyboard and role follow the native checkbox pattern with **`role="switch"`** and **`aria-checked`**; focus visibility uses **`focus-visible`** on the track.
-- There is no **indeterminate** or **loading** state; **`size`** on **`Root`** drives layout tokens, not a DOM **`size`** attribute on the input.
+- **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
 

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 size="m" 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,24 @@
+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
+        size="m"
+        defaultChecked
+        aria-label="Включено: имя для скринридеров без видимого текста у трека"
+      >
+        <Switch.Label />
+      </Switch.Root>
+      <Switch.Root size="m">
+        <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 size="m" 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 size="m" 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 size="m" 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>
+  );
+}

package/src/components/switch/examples/scenario-feature-flag.tsx

@@ -0,0 +1,30 @@
+import { Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Controlled feature flag: parent owns state; hint explains rollout scope.
+ */
+export default function SwitchScenarioFeatureFlag() {
+  const [enabled, setEnabled] = React.useState(true);
+
+  return (
+    <div className={styles.stackDense}>
+      <Switch.Root
+        size="m"
+        checked={enabled}
+        onCheckedChange={setEnabled}
+        name="flag_new_dashboard"
+      >
+        <Switch.Label>New dashboard experience</Switch.Label>
+        <Switch.Hint>
+          Applies to this workspace only. Users may need to refresh after toggling.
+        </Switch.Hint>
+      </Switch.Root>
+      <p className={styles.muted} aria-live="polite">
+        Flag is <strong>{enabled ? "on" : "off"}</strong> for members on the next session.
+      </p>
+    </div>
+  );
+}

package/src/components/switch/examples/scenario-form-consent.tsx

@@ -0,0 +1,34 @@
+import { Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/**
+ * Form submit: native `name` / `value` with FormData; required consent switch.
+ */
+export default function SwitchScenarioFormConsent() {
+  const [message, setMessage] = React.useState<string | null>(null);
+
+  return (
+    <form
+      className={styles.form}
+      onSubmit={(e) => {
+        e.preventDefault();
+        const data = new FormData(e.currentTarget);
+        const terms = data.get("terms") === "on";
+        setMessage(
+          terms ? "Terms accepted — you can continue checkout." : "Please accept the terms.",
+        );
+      }}
+    >
+      <Switch.Root name="terms" required>
+        <Switch.Label>I agree to the Terms of Service and Privacy Policy</Switch.Label>
+        <Switch.Hint>Required to place an order.</Switch.Hint>
+      </Switch.Root>
+      <button type="submit" className={styles.formSubmit}>
+        Continue to payment
+      </button>
+      {message != null ? <p className={styles.formMessage}>{message}</p> : null}
+    </form>
+  );
+}

package/src/components/switch/examples/scenario-settings-toggle.tsx

@@ -0,0 +1,26 @@
+import { Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Settings screen: independent notification toggles with short hints.
+ */
+export default function SwitchScenarioSettingsToggle() {
+  return (
+    <fieldset className={styles.settingsGroup}>
+      <legend className={styles.legend}>Notification preferences</legend>
+      <Switch.Root size="m" defaultChecked name="notify_email">
+        <Switch.Label>Email notifications</Switch.Label>
+        <Switch.Hint>Order status, receipts, and security alerts.</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root size="m" name="notify_push">
+        <Switch.Label>Push notifications</Switch.Label>
+        <Switch.Hint>Mobile alerts for time-sensitive updates only.</Switch.Hint>
+      </Switch.Root>
+      <Switch.Root size="m" name="notify_marketing">
+        <Switch.Label>Tips and offers</Switch.Label>
+        <Switch.Hint>Optional product news; never required for core service.</Switch.Hint>
+      </Switch.Root>
+    </fieldset>
+  );
+}