prime-ui-kit 0.7.11 → 0.9.0

package/src/components/checkbox/COMPONENT.md

@@ -1,139 +1,164 @@
 # Checkbox
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** selection
 
-## Canonical
+> A checkbox for an independent yes/no choice that submits with a form: checked, indeterminate, groups.
 
-- **Export:** `Checkbox` namespace — **`Checkbox.Root`**, **`Checkbox.Label`**, **`Checkbox.Hint`**, **`Checkbox.Error`**.
-- **Pattern:** compound field — native **`input type="checkbox"`** (visually hidden) + decorative box; **`Checkbox.Label`** is required for the interactive row and wires **`htmlFor`** to the input id.
-- **State:** **controlled** (`checked` + `onChange`) or **uncontrolled** (`defaultChecked`); internal checked state updates before consumer **`onChange`** runs.
-- **`indeterminate`:** boolean on **`Root`** — sets DOM **`input.indeterminate`** and mixed visual; not a third form value — clear or resync in your **`onChange`** when the user toggles.
-- **Sizing:** **`size`** `s` | `m` | `l` | `xl` on **`Root`** (default **`m`**); propagates via **`ControlSizeProvider`** to label/hint typography.
-- **Validation chrome:** **`variant="error"`** on **`Root`** and/or mounted **`Checkbox.Error`** → **`aria-invalid`**, error styling; **`Checkbox.Hint`** contributes to **`aria-describedby`** when mounted.
-- **Forwarding:** **`Root`** accepts **`Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size">`** spread onto the real input — use **`name`**, **`value`**, **`required`**, **`form`**, etc. Ref on **`Root`** targets the **input** element.
-- **Not supported:** **`asChild`**, loading state, or custom checkbox markup.
+## When to use
+- Independent on/off options that are saved together with a form (consents, sets of options).
+- Multi-select in lists and table rows, with a parent «select all» that becomes `indeterminate` on a partial selection.
+- Accepting terms with a required validation message.
 
-## Extended
-
-### About
-
-A compound checkbox: a visually hidden native `input type="checkbox"`, a decorative box with check or indeterminate mark, and optional label, hint, and error text wired to `aria-describedby` and invalid state.
-
-- **When to use** — explicit consent, terms, or other “yes/no” fields that submit with the form (`name`, `value`, `required`); row or “select all” patterns where the parent shows **indeterminate** when only some children are checked; independent toggles (feature flags, optional features, settings) rather than one-of-many choices; hint text or inline validation aligned under the label column.
-- **When not to use** — exactly one option from a set of alternatives (prefer [Radio](../radio/COMPONENT.md)); a single binary setting where a switch fits the product language (prefer [Switch](../switch/COMPONENT.md)); you need `asChild` or fully custom markup; the control is a fixed [Label](../label/COMPONENT.md) row with a hidden input and SVG.
-
-### Playground snippets
-
-Demos match **`playground/sections/CheckboxSection.tsx`** (order and intent). Sources use `@/` imports under **`playground/snippets/checkbox/`**:
-
-| Block | File | What it shows |
-|-------|------|----------------|
-| **Sizes** | [`sizes.tsx`](../../../playground/snippets/checkbox/sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`** — box, gap, and label scale from control tokens. |
-| **Variants** | [`variants.tsx`](../../../playground/snippets/checkbox/variants.tsx) | **`variant="default"`** vs **`variant="error"`**; mounting **`Checkbox.Error`** also drives invalid (see **Composition** + recipes). |
-| **States** | [`states.tsx`](../../../playground/snippets/checkbox/states.tsx) | Unchecked, **`defaultChecked`**, **`indeterminate`**, native **`required`**, **`disabled`** (off and on). |
-| **Controlled** | [`controlled.tsx`](../../../playground/snippets/checkbox/controlled.tsx) | **`checked`** + **`onChange`**; **`indeterminate`** from parent state cleared on user change (table “select all” pattern). |
-| **Composition** | [`composition.tsx`](../../../playground/snippets/checkbox/composition.tsx) | **`Hint`** only; **`Error`** without **`variant="error"`** on root; full **`Hint`** + **`Error`** with **`variant="error"`**. |
-| **Full width** | [`full-width.tsx`](../../../playground/snippets/checkbox/full-width.tsx) (+ [`full-width.module.css`](../../../playground/snippets/checkbox/full-width.module.css)) | Narrow container: field root is **`width: 100%`**; long label wraps in the text column; hint aligned under label. |
-| **Specific** | [`specific.tsx`](../../../playground/snippets/checkbox/specific.tsx) | Empty **`Checkbox.Label`** with **`aria-label`** on **`Root`**; **`name`** / **`value`** / **`defaultChecked`** for form submit. |
-
-### Scenarios (recipes)
-
-| Scenario | Approach |
-|----------|----------|
-| **Terms acceptance** | **`required`** on **`Root`**; optional **`Checkbox.Hint`** for legal context; show **`Checkbox.Error`** or **`variant="error"`** after validation when unchecked. → [`examples/terms-acceptance.tsx`](examples/terms-acceptance.tsx) |
-| **Feature flags list** | One **`Checkbox.Root` per flag**; independent **controlled** booleans or a small state map; no indeterminate unless a parent “enable all” exists. → [`examples/feature-flags-list.tsx`](examples/feature-flags-list.tsx) |
-| **Bulk select (row / table)** | **Header** checkbox: **`checked`** when all rows selected, **`indeterminate`** when some; **`onChange`** selects or clears all row ids. **Row** checkboxes toggle one id each. → [`examples/bulk-select-rows.tsx`](examples/bulk-select-rows.tsx) |
-| **Settings panel** | Stack of **`Root` → `Label` → optional `Hint`** rows; same **`size`** across the panel for rhythm; **`disabled`** for plan-gated options. → [`examples/settings-panel.tsx`](examples/settings-panel.tsx) |
-| **Empty label + form attrs** | Icon-only / compact cell: **`aria-label`** (or **`aria-labelledby`**) on **`Root`**; optional **`name`** / **`value`** for submission. → [`examples/empty-label-form.tsx`](examples/empty-label-form.tsx) |
-
-Runnable recipe examples use **`prime-ui-kit`** imports under **`examples/`**. Snippet-level demos (internal imports) are listed in **Playground snippets** above.
-
-### Composition
-
-- **`Checkbox.Root`** — wraps the field in a `div` with `data-size`, `data-variant`, `data-disabled`, `data-invalid`, `data-checked`, `data-indeterminate`; provides context and `ControlSizeProvider` for child parts.
-- **`Checkbox.Label`** — required for the control: hosts the native checkbox and decorative SVG, then optional text in a trailing column; sets `htmlFor` to the input id.
-- **`Checkbox.Hint`** — optional; registers hint text and contributes its id to the input’s `aria-describedby`.
-- **`Checkbox.Error`** — optional; error-styled [Hint](../hint/COMPONENT.md) and registers invalid state when mounted (with `variant="error"` on the root when you want error chrome without the slot).
-- **Order:** `Root` → `Label` (always) → `Hint` / `Error` below when needed.
-
-### Minimal example
+## When not to use
+- One choice out of several mutually exclusive options → use [Radio](../radio/COMPONENT.md) or [SegmentedControl](../segmented-control/COMPONENT.md) instead.
+- A setting that applies immediately, without a submit → use [Switch](../switch/COMPONENT.md) instead.
+- Picking several values from a long list in a compact field → use [TagSelect](../tag-select/COMPONENT.md) or [Select](../select/COMPONENT.md) with `multiple` instead.
 
+## Import
 ```tsx
 import { Checkbox } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <Checkbox.Root name="terms" value="yes">
-      <Checkbox.Label>Accept terms</Checkbox.Label>
-    </Checkbox.Root>
-  );
-}
 ```
 
-### Rules
-
-- Vertical rhythm between **label and hint** is owned by the component; avoid inserting extra [Typography](../typography/Typography.tsx) between them unless the design explicitly requires a different reading role.
-- **`indeterminate`** only affects visuals and the DOM `indeterminate` property; it is not a separate submitted value—clear or sync it in your handler when the user clicks.
-- Set **`aria-label`** or **`aria-labelledby`** on **`Checkbox.Root`** (forwarded to the input via rest props) when **`Checkbox.Label`** has no visible text (icon-only or compact “select all” cell).
-- **`aria-describedby`** on **`Root`** is merged with hint and error ids when those slots are mounted; include your own ids in `aria-describedby` if you need extra descriptors.
-- **`variant="error"`** or a mounted **`Checkbox.Error`** sets `aria-invalid` and error styling; **`disabled`** disables the input and dims hint styling.
-- Focus and keyboard activation use the native checkbox; the visible focus ring targets the decorative control via `focus-visible`.
-- There is no loading or `asChild` API; **`size`** on the root does not forward as a DOM attribute on the wrapper (layout/visual token axis only).
+## Anatomy
+```
+Checkbox.Root          wrapper grid + context; ref and input props go to the hidden native input
+├─ Checkbox.Label      clickable row: renders the native input, the box and the text
+├─ Checkbox.Hint       description under the text column (optional)
+└─ Checkbox.Error      error message under the text column (optional, makes the field invalid)
+```
+The native `input type="checkbox"` is rendered inside `Checkbox.Label`, so `Checkbox.Label` is required even without visible text.
 
 ## API
 
 ### Checkbox.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| variant | `"default" \| "error"` | `"default"` | no | Error-colored outline for `error`; `invalid` is also true when `Checkbox.Error` is mounted. |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Box and typography scale. |
-| indeterminate | `boolean` | `false` | no | Indeterminate visuals; syncs `input.indeterminate`. |
-| id | `string` | auto (`useId`) | no | Stable input id; paired with `Checkbox.Label` via `htmlFor`. |
-| className | `string` | — | no | Class on the field wrapper `div`. |
-| checked | `boolean` | — | no | Controlled checked state. |
-| defaultChecked | `boolean` | `false` | no | Initial checked state when uncontrolled. |
-| onChange | `React.ChangeEventHandler<HTMLInputElement>` | — | no | Fired on toggle; internal checked state updates before this runs. |
-| disabled | `boolean` | — | no | Disables the input and label row. |
-| aria-describedby | `string` | — | no | Combined with hint and error ids when those slots exist. |
-| children | `React.ReactNode` | — | no | Typically `Label`, optional `Hint` / `Error`. |
-| ref | `React.Ref<HTMLInputElement>` | — | no | Ref to the native checkbox input. |
-| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | — | no | Other native attributes forwarded to the hidden `input` (e.g. `name`, `value`, `required`, `readOnly`, `form`). `type` is always `checkbox`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` | — | Controlled checked state; use with `onCheckedChange`. |
+| `defaultChecked` | `boolean` | `false` | Initial state in uncontrolled mode. |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state on click or Space. |
+| `indeterminate` | `boolean` | `false` | Mixed state (partial «select all»); wins over `checked` visually and is synced to `input.indeterminate`. |
+| `invalid` | `boolean` | `false` | Invalid look and `aria-invalid`; also set automatically while `Checkbox.Error` is mounted. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Size tier of the box, gap and label text. |
+| `fullWidth` | `boolean` | `false` | Stretch to the container width; by default the field is as wide as its content. |
+| `disabled` | `boolean` | `false` | Disables the input; dims box, label and hint. |
+| `id` | `string` | auto (`useId`) | Id of the native input; hint/error ids derive from it. |
+| `aria-describedby` | `string` | — | Extra description ids; merged with the mounted hint and error ids. |
+| `className` | `string` | — | Class on the wrapper `div`. |
+| `children` | `ReactNode` | — | `Checkbox.Label`, `Checkbox.Hint`, `Checkbox.Error`. |
+
++ native `<input>` props except `type`, `size`, `checked`, `defaultChecked`, `onChange`, `children` (`name`, `value`, `required`, `aria-label`, `onBlur`, `style`, …) — they are applied to the hidden native input, not to the wrapper.
+Ref: `forwardRef` → `HTMLInputElement`. No `asChild`.
 
 ### Checkbox.Label
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Label text. Empty → only the box is rendered; then set `aria-label` on `Checkbox.Root`. |
+| `className` | `string` | — | Class on the `<label>` row. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | no | Label text beside the box; omit for a box-only control and set an accessible name on `Root`. |
-| className | `string` | — | no | Class on the label row. |
-| …rest | `Omit<React.HTMLAttributes<HTMLLabelElement>, "htmlFor" \| "size">` | — | no | Other label attributes; `htmlFor` is managed internally. |
++ native `<label>` HTML attributes except `htmlFor` and `size` (wired from context).
+Ref: `forwardRef` → `HTMLLabelElement`.
 
 ### Checkbox.Hint
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Description text, aligned with the text column; added to `aria-describedby`. |
+| `className` | `string` | — | Class on the `<p>`. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Supplementary text below the label. |
-| className | `string` | — | no | Additional class on the hint. |
-| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally. |
++ native `<p>` props except `id` (fixed to `<inputId>-hint`). No ref.
 
 ### Checkbox.Error
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Error text in `danger-text`; while mounted the field is invalid. |
+| `className` | `string` | — | Class on the `<p>`. |
+
++ native `<p>` props except `id` (fixed to `<inputId>-error`). No ref.
+
+## Variants
+Checkbox has no `variant`/`tone`/`color`. Axes: `size`, `fullWidth`.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 14px box, 4px gap, 12/16 text | dense tables, filters in a 28px toolbar | |
+| `s` | 16px box, 8px gap, 13/20 text | compact forms and side panels | |
+| `m` | 18px box, 8px gap, 14/20 text | regular forms and settings | yes |
+| `l` | 20px box, 8px gap, 16/24 text | spacious forms, onboarding | |
+| `xl` | 24px box (radius 6), 12px gap, 16/24 text | touch-first screens | |
+
+### fullWidth
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `false` | field shrinks to its content, text wraps inside the container | choices placed side by side or in a list | yes |
+| `true` | field stretches to 100% of the container | the label row must fill a grid cell or a card row | |
+
+**Combinations**
+- Match the checkbox `size` to the fields and buttons of the same form (`m` with `m`).
+- `indeterminate` only on a parent checkbox that controls a group; leaf options never use it.
+- `invalid` together with a `Checkbox.Error` text is redundant — the error already sets it. Use bare `invalid` only when the message is shown elsewhere.
+
+**Sizes** — the box is optically centred on the first text line; label text follows the tier text size (12 · 13 · 14 · 16 · 16).
+
+**Hierarchy** — a parent checkbox sits above its children; nested options are indented by the box width plus the gap so they align with the parent text (see [settings-card.tsx](examples/settings-card.tsx)).
+
+## States
+| State | Driven by | DOM | Looks like |
+|---|---|---|---|
+| unchecked | `checked={false}` / default | `data-state="unchecked"` | box `fill-strong`, hover `fill-strong-hover` |
+| checked | `checked` / `defaultChecked` | `data-state="checked"` | box `accent-default` (hover `accent-hover`), check mark in `accent-fg` drawn in with a stroke reveal |
+| indeterminate | `indeterminate` | `data-state="indeterminate"`, `input.indeterminate` | accent box with a horizontal bar |
+| invalid | `invalid` or mounted `Checkbox.Error` | `data-invalid="true"`, `aria-invalid` on input | unchecked box gets a `danger-border` inset ring; focus ring turns `danger-border` |
+| disabled | `disabled` | `data-disabled="true"` on root and label | box `fill-muted`, mark `text-disabled`, `cursor: not-allowed`, hint dimmed |
+| active | pointer press | — | box scales to 92% |
+| focus-visible | keyboard focus | — | outer focus ring around the box |
+
+Root also carries `data-size` and `data-full-width="true"` when `fullWidth`.
+Controlled: `checked` + `onCheckedChange`. Uncontrolled: `defaultChecked` (+ optional `onCheckedChange`). There is no native `onChange` prop.
+
+## Layout & spacing
+- Grid `[box][text]`; `Checkbox.Hint` / `Checkbox.Error` sit under the text column, not under the box.
+- Checkboxes in a vertical list: gap `--prime-space-3` (12px); separate fields/groups: `--prime-space-5` (20px); group → group `--prime-space-8`.
+- Group several checkboxes in a `role="group"` container named by a `Typography.Root` heading via `aria-labelledby` (gap on the container, no margins); nested options indent by `calc(var(--prime-control-m-choice) + var(--prime-control-m-gap))`.
+- Long labels wrap (`overflow-wrap: anywhere`); the field is `max-width: 100%` and works from 320px.
+
+## Accessibility
+- Native `<input type="checkbox">` (visually hidden, still in the box for validation bubbles), associated with the `<label>` via `htmlFor`.
+- Keyboard: Tab focuses, Space toggles.
+- `aria-invalid` is set when invalid; `aria-describedby` = your ids + hint id + error id (only mounted parts).
+- Without visible text, pass `aria-label` on `Checkbox.Root` (it lands on the input).
+- `required` goes to the native input; no visual asterisk is drawn — state it in the label text or a hint.
+- No `labels` keys.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | All size tiers | Choosing the tier next to other controls |
+| [states.tsx](examples/states.tsx) | Unchecked, checked, indeterminate, invalid, disabled | Reference for every state |
+| [hint-error.tsx](examples/hint-error.tsx) | `Checkbox.Hint` and `Checkbox.Error` | Consents and options that need an explanation or validation |
+| [select-all.tsx](examples/select-all.tsx) | Controlled «select all» with `indeterminate` | Bulk selection in lists |
+| [settings-card.tsx](examples/settings-card.tsx) | Named group with parent and nested options, disabled option with hint, inside a Card with `Card.Actions` (primary last) | Grouped preferences in a settings form |
+| [without-label.tsx](examples/without-label.tsx) | Empty `Checkbox.Label` + `aria-label`, `name`/`value` | Row selection in tables |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Error message text. |
-| className | `string` | — | no | Additional class on the message. |
-| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` is managed internally. |
-
-## Related
+```tsx
+import { Checkbox } from "prime-ui-kit";
 
-- [Radio](../radio/COMPONENT.md) — one-of-many choice with the same validation variants.
-- [Switch](../switch/COMPONENT.md) — binary setting with a different control pattern.
-- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — primitives used inside the checkbox; pair with [Input](../input/COMPONENT.md) in larger forms.
+export function TermsCheckbox() {
+  return (
+    <Checkbox.Root name="terms" required>
+      <Checkbox.Label>Принимаю условия оферты</Checkbox.Label>
+      <Checkbox.Hint>Без этого мы не сможем оформить заказ.</Checkbox.Hint>
+    </Checkbox.Root>
+  );
+}
+```
 
-## LLM note
+## Mistakes
+- `<Checkbox.Root onChange={…}>` → use `onCheckedChange={(checked) => …}`.
+- `<Checkbox.Root>Текст</Checkbox.Root>` → wrap the text in `Checkbox.Label`; without it no input is rendered.
+- `invalid` plus `Checkbox.Error` → just mount `Checkbox.Error`.
+- Several checkboxes for one-of-many → use `Radio.Root` with items.
+- Checkbox that saves instantly («Тёмная тема») → use `Switch`.
+- `style` on `Checkbox.Root` expecting to style the wrapper → it goes to the hidden input; use `className`.
 
-- Prefer **`Checkbox.Label`** with visible text; if the label slot is empty or icon-only, set **`aria-label`** (or **`aria-labelledby`**) via **`Checkbox.Root`** rest props so the native input has a name.
-- **`indeterminate`** is purely visual + DOM hinting — parent “select all” logic must derive **`checked`** / **`indeterminate`** from child selection state and normalize **`onChange`** (e.g. indeterminate click → select all).
-- Use **`Checkbox.Error`** or **`variant="error"`** for validation feedback; mounting **`Checkbox.Error`** registers invalid state even without **`variant`** on **`Root`**.
-- Do not substitute **Radio** or **Switch** based on “sounds nicer” — **Radio** is for mutually exclusive options; **Switch** for settings that read as on/off system toggles.
-- Keep composition order **`Root` → `Label` → `Hint`/`Error`**; refs on **`Root`** attach to the **`<input>`**, not the wrapper `div`.
+## Related
+[Radio](../radio/COMPONENT.md) · [Switch](../switch/COMPONENT.md) · [SegmentedControl](../segmented-control/COMPONENT.md) · [Label](../label/COMPONENT.md) · [Hint](../hint/COMPONENT.md)

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

@@ -0,0 +1,65 @@
+.sizes {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  justify-content: center;
+  gap: var(--prime-space-8);
+}
+
+.sizeCell {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--prime-space-2);
+}
+
+.stack {
+  display: grid;
+  gap: var(--prime-space-4);
+  width: 100%;
+  max-width: 100%;
+  min-width: 0;
+}
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-3);
+  justify-content: center;
+}
+
+.column {
+  display: grid;
+  gap: var(--prime-space-5);
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+}
+
+.list {
+  display: grid;
+  gap: var(--prime-space-3);
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+}
+
+.card {
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+}
+
+.group {
+  display: grid;
+  gap: var(--prime-space-3);
+  min-width: 0;
+  /* Native fieldset reset. */
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+
+/* Child options sit under the parent's text column. */
+.nested {
+  display: grid;
+  gap: var(--prime-space-3);
+  padding-inline-start: calc(var(--prime-control-m-choice) + var(--prime-control-m-gap));
+}

package/src/components/checkbox/examples/hint-error.tsx

@@ -0,0 +1,22 @@
+/** A description under the label and a validation error that marks the field invalid. Use it for consents and options that need an explanation. */
+import { Checkbox } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function CheckboxHintErrorExample() {
+  return (
+    <div className={styles.column}>
+      <Checkbox.Root name="marketing">
+        <Checkbox.Label>Получать новости продукта</Checkbox.Label>
+        <Checkbox.Hint>
+          Не чаще одного письма в неделю, отписаться можно в любой момент.
+        </Checkbox.Hint>
+      </Checkbox.Root>
+      <Checkbox.Root name="terms" required>
+        <Checkbox.Label>Принимаю условия оферты</Checkbox.Label>
+        <Checkbox.Hint>Без этого мы не сможем оформить заказ.</Checkbox.Hint>
+        <Checkbox.Error>Отметьте пункт, чтобы продолжить.</Checkbox.Error>
+      </Checkbox.Root>
+    </div>
+  );
+}

package/src/components/checkbox/examples/select-all.tsx

@@ -0,0 +1,40 @@
+/** A controlled «select all» checkbox that turns indeterminate on a partial selection. Use it above lists and table rows with bulk actions. */
+
+import { Checkbox } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const FILES = ["Договор.pdf", "Счёт-фактура.pdf", "Акт сверки.xlsx"];
+
+export default function CheckboxSelectAllExample() {
+  const [selected, setSelected] = React.useState<string[]>([FILES[0]]);
+
+  const all = selected.length === FILES.length;
+  const some = selected.length > 0 && !all;
+
+  return (
+    <div className={styles.list}>
+      <Checkbox.Root
+        onCheckedChange={(checked) => setSelected(checked ? FILES : [])}
+        checked={all}
+        indeterminate={some}
+      >
+        <Checkbox.Label>
+          Выбрать все ({selected.length} из {FILES.length})
+        </Checkbox.Label>
+      </Checkbox.Root>
+      {FILES.map((file) => (
+        <Checkbox.Root
+          onCheckedChange={(checked) =>
+            setSelected((prev) => (checked ? [...prev, file] : prev.filter((f) => f !== file)))
+          }
+          key={file}
+          checked={selected.includes(file)}
+        >
+          <Checkbox.Label>{file}</Checkbox.Label>
+        </Checkbox.Root>
+      ))}
+    </div>
+  );
+}

package/src/components/checkbox/examples/settings-card.tsx

@@ -0,0 +1,76 @@
+/** A settings card with a parent «all channels» checkbox, nested options, a disabled option with a hint and a standalone setting. Use it for grouped preferences inside a form. */
+import { Button, Card, Checkbox, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const CHANNELS = [
+  { id: "email", label: "Почта" },
+  { id: "push", label: "Push в браузере" },
+  { id: "telegram", label: "Telegram" },
+];
+
+export default function CheckboxSettingsCardExample() {
+  const [channels, setChannels] = React.useState<string[]>(["email"]);
+  const [digest, setDigest] = React.useState(true);
+
+  const headingId = React.useId();
+  const all = channels.length === CHANNELS.length;
+
+  return (
+    <Card.Root variant="panel" className={styles.card}>
+      <Card.SectionHeader>
+        <Card.SectionTitle>Уведомления</Card.SectionTitle>
+      </Card.SectionHeader>
+      <Card.Body>
+        <fieldset aria-labelledby={headingId} className={styles.group}>
+          <Typography.Root id={headingId} variant="body-s" weight="medium" tone="secondary">
+            Куда присылать
+          </Typography.Root>
+          <Checkbox.Root
+            onCheckedChange={(checked) => setChannels(checked ? CHANNELS.map((c) => c.id) : [])}
+            checked={all}
+            indeterminate={channels.length > 0 && !all}
+          >
+            <Checkbox.Label>Все каналы</Checkbox.Label>
+          </Checkbox.Root>
+          <div className={styles.nested}>
+            {CHANNELS.map((channel) => (
+              <Checkbox.Root
+                onCheckedChange={(checked) =>
+                  setChannels((prev) =>
+                    checked ? [...prev, channel.id] : prev.filter((id) => id !== channel.id),
+                  )
+                }
+                key={channel.id}
+                name="channels"
+                value={channel.id}
+                checked={channels.includes(channel.id)}
+              >
+                <Checkbox.Label>{channel.label}</Checkbox.Label>
+              </Checkbox.Root>
+            ))}
+            <Checkbox.Root name="channels" value="sms" disabled>
+              <Checkbox.Label>SMS</Checkbox.Label>
+              <Checkbox.Hint>Доступно на тарифе «Бизнес».</Checkbox.Hint>
+            </Checkbox.Root>
+          </div>
+        </fieldset>
+        <Checkbox.Root
+          onCheckedChange={(checked) => setDigest(checked)}
+          name="digest"
+          checked={digest}
+        >
+          <Checkbox.Label>Еженедельная сводка</Checkbox.Label>
+          <Checkbox.Hint>Упоминания, задачи и комментарии за неделю одним письмом.</Checkbox.Hint>
+        </Checkbox.Root>
+      </Card.Body>
+      <Card.Actions>
+        <Button.Root variant="ghost" tone="neutral">
+          Отмена
+        </Button.Root>
+        <Button.Root>Сохранить</Button.Root>
+      </Card.Actions>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,23 @@
+/** All five size tiers of a checked checkbox side by side. Use it to pick the tier that matches the neighbouring controls. */
+import { Checkbox, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function CheckboxSizesExample() {
+  return (
+    <div className={styles.sizes}>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.sizeCell}>
+          <Checkbox.Root size={size} defaultChecked>
+            <Checkbox.Label>Подпись</Checkbox.Label>
+          </Checkbox.Root>
+          <Typography.Root as="span" variant="caption" tone="muted">
+            {size}
+          </Typography.Root>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,29 @@
+/** Unchecked, checked, indeterminate, invalid and disabled checkboxes. Use it as a reference for every visual state. */
+import { Checkbox } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function CheckboxStatesExample() {
+  return (
+    <div className={styles.stack}>
+      <Checkbox.Root>
+        <Checkbox.Label>Не отмечен</Checkbox.Label>
+      </Checkbox.Root>
+      <Checkbox.Root defaultChecked>
+        <Checkbox.Label>Отмечен</Checkbox.Label>
+      </Checkbox.Root>
+      <Checkbox.Root indeterminate>
+        <Checkbox.Label>Частично (indeterminate)</Checkbox.Label>
+      </Checkbox.Root>
+      <Checkbox.Root invalid>
+        <Checkbox.Label>Ошибка</Checkbox.Label>
+      </Checkbox.Root>
+      <Checkbox.Root disabled>
+        <Checkbox.Label>Недоступен</Checkbox.Label>
+      </Checkbox.Root>
+      <Checkbox.Root disabled defaultChecked>
+        <Checkbox.Label>Недоступен, отмечен</Checkbox.Label>
+      </Checkbox.Root>
+    </div>
+  );
+}

package/src/components/checkbox/examples/without-label.tsx

@@ -0,0 +1,17 @@
+/** Checkboxes with no visible text, named via aria-label and submitted with name/value. Use it in table rows where the row itself explains the choice. */
+import { Checkbox } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function CheckboxWithoutLabelExample() {
+  return (
+    <div className={styles.row}>
+      <Checkbox.Root aria-label="Выбрать заказ №1042" name="orders" value="1042">
+        <Checkbox.Label />
+      </Checkbox.Root>
+      <Checkbox.Root aria-label="Выбрать заказ №1043" name="orders" value="1043" defaultChecked>
+        <Checkbox.Label />
+      </Checkbox.Root>
+    </div>
+  );
+}