prime-ui-kit 0.7.13 → 0.9.1

package/src/components/card/examples/flat.tsx

@@ -0,0 +1,25 @@
+/** A flat tile without the raised shadow next to the default one, for dense grids — `flat`. */
+import { Card, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function CardFlatExample() {
+  return (
+    <div className={styles.grid}>
+      <Card.Root variant="mini">
+        <Card.Icon>
+          <Icon name="field.email" strokeWidth={2} />
+        </Card.Icon>
+        <Card.Label>С тенью (по умолчанию)</Card.Label>
+        <Card.Value>42</Card.Value>
+      </Card.Root>
+      <Card.Root variant="mini" flat>
+        <Card.Icon>
+          <Icon name="field.email" strokeWidth={2} />
+        </Card.Icon>
+        <Card.Label>flat</Card.Label>
+        <Card.Value>42</Card.Value>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/card/examples/kpi-media.tsx

@@ -0,0 +1,42 @@
+/** A KPI with a sparkline or a fill level in the bottom slot of `mini` — `Card.Media`. */
+import { Card, Icon, ProgressBar } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SPARKLINE = "M0 32 L15 28 L30 30 L45 18 L60 22 L75 12 L90 16 L105 8 L120 4";
+
+export default function CardKpiMediaExample() {
+  return (
+    <div className={styles.grid}>
+      <Card.Root variant="mini">
+        <Card.Icon>
+          <Icon name="object.activity" />
+        </Card.Icon>
+        <Card.Label>Запросы в минуту</Card.Label>
+        <Card.Value>12 840</Card.Value>
+        <Card.Media>
+          {/* The SVG stretches to the card width; CSS sets its height, not the viewBox. */}
+          <svg
+            className={styles.spark}
+            viewBox="0 0 120 40"
+            preserveAspectRatio="none"
+            aria-hidden="true"
+          >
+            <path d={SPARKLINE} className={styles.chartLine} />
+          </svg>
+        </Card.Media>
+      </Card.Root>
+
+      <Card.Root variant="mini">
+        <Card.Icon>
+          <Icon name="object.storage" />
+        </Card.Icon>
+        <Card.Label>Хранилище</Card.Label>
+        <Card.Value>72 из 100 ГБ</Card.Value>
+        <Card.Media>
+          <ProgressBar value={72} size="s" label="Занято" showValue />
+        </Card.Media>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/card/examples/narrow.tsx

@@ -0,0 +1,47 @@
+/** The card is a size container: the split template stacks its cells below 22rem and the trend value shrinks below 20rem. */
+import { Card, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const WIDTHS = [
+  { id: "narrow", className: styles.w18 },
+  { id: "wide", className: styles.w40 },
+];
+
+export default function CardNarrowExample() {
+  return (
+    <div className={styles.stack}>
+      {WIDTHS.map((width) => (
+        <div key={width.id} className={styles.stack}>
+          <div className={width.className}>
+            <Card.Root variant="split">
+              <Card.Body>
+                <div>
+                  <Card.Icon>
+                    <Icon name="object.cart" />
+                  </Card.Icon>
+                  <Card.Label>Конверсия</Card.Label>
+                  <Card.Value>3,8%</Card.Value>
+                </div>
+                <div>
+                  <Card.Icon>
+                    <Icon name="object.wallet" />
+                  </Card.Icon>
+                  <Card.Label>Средний чек</Card.Label>
+                  <Card.Value>₽ 2 450</Card.Value>
+                </div>
+              </Card.Body>
+            </Card.Root>
+          </div>
+          <div className={width.className}>
+            <Card.Root variant="stat-trend">
+              <Card.Label>Выручка</Card.Label>
+              <Card.Value>₽ 4,2 млн</Card.Value>
+              <Card.Delta tone="success">+18% к прошлому месяцу</Card.Delta>
+            </Card.Root>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,39 @@
+/** A company settings panel: a header, fields on the surface fill and buttons in the footer — `Card.Header`, `Card.Body`, `Card.Footer`. */
+import { Button, Card, Input, Switch } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function CardOverviewExample() {
+  return (
+    <div className={styles.panel}>
+      <Card.Root variant="panel">
+        <Card.Header>
+          <Card.Title>Профиль компании</Card.Title>
+        </Card.Header>
+        <Card.Body>
+          <div className={styles.form}>
+            <Input.Root label="Название" required>
+              <Input.Wrapper>
+                <Input.Field defaultValue="ООО «Прайм»" />
+              </Input.Wrapper>
+            </Input.Root>
+            <Input.Root label="Сайт" optional hint="Покажем в счетах и письмах">
+              <Input.Wrapper>
+                <Input.Field placeholder="https://" />
+              </Input.Wrapper>
+            </Input.Root>
+            <Switch.Root defaultChecked>
+              <Switch.Label>Отправлять ежемесячный отчёт</Switch.Label>
+            </Switch.Root>
+          </div>
+        </Card.Body>
+        <Card.Footer>
+          <Button.Root variant="ghost" tone="neutral">
+            Отмена
+          </Button.Root>
+          <Button.Root>Сохранить</Button.Root>
+        </Card.Footer>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/card/examples/panel-chart.tsx

@@ -0,0 +1,43 @@
+/** A chart widget: a header with a period switch, a summary line and an edge-to-edge chart — `Card.Header`, `Card.Media`. */
+import { Card, SegmentedControl, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const POINTS = [42, 48, 45, 60, 58, 72, 66, 80, 76, 88, 84, 96];
+
+/** An area chart path in a 100 × 100 box; the SVG stretches over the whole `Card.Media`. */
+const LINE = POINTS.map(
+  (value, i) => `${i === 0 ? "M" : "L"}${(i * 100) / (POINTS.length - 1)} ${100 - value}`,
+).join(" ");
+
+export default function CardPanelChartExample() {
+  return (
+    <div className={styles.panel}>
+      <Card.Root variant="panel">
+        <Card.Header>
+          <Card.Title>Выручка</Card.Title>
+          <SegmentedControl.Root size="xs" defaultValue="month" aria-label="Период">
+            <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
+            <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
+          </SegmentedControl.Root>
+        </Card.Header>
+        <Card.Body>
+          <Typography variant="body-s" tone="secondary">
+            С начала квартала: ₽ 12,6 млн, план выполнен на 84%.
+          </Typography>
+        </Card.Body>
+        <Card.Media>
+          <svg
+            className={styles.chart}
+            viewBox="0 0 100 100"
+            preserveAspectRatio="none"
+            aria-hidden="true"
+          >
+            <path className={styles.chartFill} d={`${LINE} L100 100 L0 100 Z`} />
+            <path className={styles.chartLine} d={LINE} />
+          </svg>
+        </Card.Media>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/card/examples/variants.tsx

@@ -0,0 +1,38 @@
+/** KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change — `variant`, `Card.Delta`. */
+import { Badge, Card, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function CardVariantsExample() {
+  return (
+    <div className={styles.grid}>
+      <Card.Root variant="mini">
+        <Card.Icon>
+          <Icon name="object.users" />
+        </Card.Icon>
+        <Card.Label>Активные сессии</Card.Label>
+        <Card.Value>1 248</Card.Value>
+      </Card.Root>
+
+      <Card.Root variant="stat-trend">
+        <Card.Header>
+          <Badge.Root color="green">SLA</Badge.Root>
+          <Card.Value>99,95%</Card.Value>
+        </Card.Header>
+        <Card.Description>Доступность API за 30 дней</Card.Description>
+      </Card.Root>
+
+      <Card.Root variant="stat-trend">
+        <Card.Label>Выручка за месяц</Card.Label>
+        <Card.Value>₽ 4,2 млн</Card.Value>
+        <Card.Delta tone="success">+18% к сентябрю</Card.Delta>
+      </Card.Root>
+
+      <Card.Root variant="stat-trend">
+        <Card.Label>Отток</Card.Label>
+        <Card.Value>3,1%</Card.Value>
+        <Card.Delta tone="danger">+0,6 п. п. за неделю</Card.Delta>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/checkbox/COMPONENT.md

@@ -1,139 +1,160 @@
 # Checkbox
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** selection
+**Kind:** control
 
-## Canonical
+> A checkbox for an independent yes/no choice that submits with a form: checked, indeterminate, with a hint or an error.
 
-- **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.
+- A checkbox look inside an option or menu row that carries `aria-selected` itself → `Checkbox.Indicator`, never a nested `Checkbox.Root`.
 
+## 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
+## Anatomy
+```
+Checkbox.Root          field grid; ref and input props go to the native input
+├─ <label> row         the native input, the box and the text (rendered by Root)
+│  └─ Checkbox.Label   the visible text (optional)
+└─ hint | error        support text under the text column (`hint`, `error`)
 
-- 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).
+Checkbox.Indicator     the box alone, no input — a mark inside option / menu rows (used without Root)
+```
+`<Checkbox.Root aria-label="…" />` without `Checkbox.Label` is a valid bare control (table rows).
 
 ## API
 
-### Checkbox.Root
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-| 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`. |
+### Checkbox.Root
+`ref` → `HTMLInputElement` (the native checkbox). Renders the field `<div>`, the `<label>` row with the input and the box, 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 checked state. |
+| `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state on every toggle (not while `readOnly`). |
+| `indeterminate` | `boolean` | `false` | Mixed state (a partial «select all»): a bar instead of the check; wins over `checked` visually and sets the native `indeterminate`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the box, the text and the gap. Without it the tier of its host (a form, a panel, a table), 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 unchecked box and `aria-invalid`. A non-empty `error` implies it. |
+| `disabled` | `boolean` | `false` | Disabled fill, dimmed label and hint, no toggling. |
+| `readOnly` | `boolean` | `false` | The state is shown and focusable but does not change (`aria-readonly`); no hover or press. The native checkbox ignores `readOnly`, so the root guards the toggle. |
+| `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` | — | `Checkbox.Label`. Without it only the box renders — give the root an `aria-label`. |
+| `className` | `string` | — | Class on the field `<div>`. |
+| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange">` | — | `name`, `value`, `required`, `aria-label`, `onBlur`… on the native input. |
 
 ### Checkbox.Label
-
-| 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. |
-
-### Checkbox.Hint
-
-| 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. |
-
-### Checkbox.Error
-
-| 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. |
+`ref` → `HTMLSpanElement`. The visible text in the text column of the label row. Native `<span>` props.
+
+### Checkbox.Indicator
+`ref` → `HTMLSpanElement`. The box alone, without an input (`aria-hidden`, no focus or clicks) for rows that carry the state themselves: `role="option"` + `aria-selected`, `role="menuitemcheckbox"` + `aria-checked`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean` | `false` | Shows the check. |
+| `indeterminate` | `boolean` | `false` | Shows the bar; wins over `checked`. |
+| `disabled` | `boolean` | `false` | Disabled fill. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | — | Box tier; without it the nearest control size (the Select or menu it sits in), else `m`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className`, `data-*` and the other span attributes. |
+
+## Variants
+Checkbox has no `variant` / `tone` / `color`.
+
+### 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 | |
+
+**Sizes:** the box is optically centred on the first text line; the text follows the tier text size (12 · 13 · 14 · 16 · 16). Match the checkbox `size` to the fields and buttons of the same form.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `indeterminate` | accent box with a horizontal bar | a parent checkbox over a partially selected group | `false` |
+| `invalid` | danger ring on the unchecked box | the message is shown elsewhere; otherwise pass `error` | `false` |
+| `disabled` | muted box, dimmed text and hint | the option is unavailable | `false` |
+
+**Combinations**
+- `indeterminate` only on a parent checkbox that controls a group; leaf options never use it.
+- `invalid` together with `error` is redundant — the error already sets it.
+- Nested options are indented by the box width plus the gap so they align with the parent text.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| unchecked | `checked={false}` / default | `data-state="unchecked"`; box `fill-strong`, hover `fill-strong-hover` |
+| checked | `checked` / `defaultChecked` | `data-state="checked"`; accent box, the check draws in |
+| indeterminate | `indeterminate` | `data-state="indeterminate"`, `input.indeterminate`; accent box with a bar |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid` on the input; danger ring on the unchecked box and on focus |
+| disabled | `disabled` | `data-disabled="true"` on the root; `fill-muted` box, disabled text, `cursor: not-allowed` |
+| read-only | `readOnly` | `aria-readonly="true"` on the input, `data-readonly="true"` on the root; the state stays, no hover or press, default cursor |
+| pressed | pointer press | the box scales to the compact press scale |
+| focus-visible | keyboard focus | outer focus ring around the box |
+
+Root also carries `data-size`. Controlled: `checked` + `onCheckedChange`. Uncontrolled: `defaultChecked` (+ optional `onCheckedChange`). There is no native `onChange` prop.
+
+## Layout & spacing
+- Grid `[box][text]`; the hint or error sits under the text column, not under the box.
+- Checkboxes in a vertical list: gap `--prime-space-3`; separate fields: `--prime-space-5`; group → actions `--prime-space-8`.
+- Long labels wrap (`overflow-wrap: anywhere`); the field shrinks to its content with `max-width: 100%`.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the checkbox. |
+| `Space` | Toggles it. |
+
+### ARIA
+- A native `<input type="checkbox">` (visually hidden over the box, so validation bubbles point at it), wrapped by the `<label>` row.
+- `aria-invalid` is set when invalid; `aria-describedby` = your ids + the hint or the error id.
+- Without visible text, pass `aria-label` on `Checkbox.Root` (it lands on the input).
+- `required` goes to the native input; no asterisk is drawn — state it in the text or the hint.
+- `Checkbox.Indicator` is `aria-hidden`; the host row carries `aria-selected` / `aria-checked`.
+
+### 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 checkbox with its label; a click anywhere on the row toggles it. |
+| [sizes.tsx](examples/sizes.tsx) | Every size; the box and the text follow the control tier — `size`. |
+| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `indeterminate`, `invalid`, `disabled`. |
+| [without-label.tsx](examples/without-label.tsx) | Bare boxes in table rows, named by `aria-label` and submitted with `name` and `value`. |
+| [indicator.tsx](examples/indicator.tsx) | The box alone in a multi-select list: the option row carries `aria-selected`, the box only shows it — `Checkbox.Indicator`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the selection; «select all» turns indeterminate on a partial one — `checked`, `onCheckedChange`, `indeterminate`. |
+| [in-form.tsx](examples/in-form.tsx) | Consent in a sign-up form: a hint under the text, an error after a submit without the tick — `required`, `hint`, `error`. |
+
+## Mistakes
+- `<Checkbox.Root onChange={…}>` → use `onCheckedChange={(checked) => …}`.
+- `<Checkbox.Root>Текст</Checkbox.Root>` → wrap the text in `Checkbox.Label`, so it sits in the text column.
+- `invalid` plus `error` → just pass `error`.
+- Several checkboxes for one-of-many → use `Radio.Group`.
+- A checkbox that saves instantly («Тёмная тема») → use `Switch`.
+- `style` on `Checkbox.Root` expecting to style the field → it goes to the hidden input; use `className`.
 
 ## Related
-
-- [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.
-
-## LLM note
-
-- 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`.
+- **Built from:** [Label](../label/COMPONENT.md) (the row), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **See also:** [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -0,0 +1,41 @@
+/** The parent owns the selection; «select all» turns indeterminate on a partial one — `checked`, `onCheckedChange`, `indeterminate`. */
+import { Checkbox } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const DOCUMENTS = ["Договор поставки.pdf", "Счёт-фактура №418.pdf", "Акт сверки.xlsx"];
+
+export default function CheckboxControlledExample() {
+  const [selected, setSelected] = React.useState<string[]>([DOCUMENTS[0]]);
+  const all = selected.length === DOCUMENTS.length;
+
+  return (
+    <div className={styles.list}>
+      <Checkbox.Root
+        checked={all}
+        indeterminate={selected.length > 0 && !all}
+        onCheckedChange={(checked) => setSelected(checked ? DOCUMENTS : [])}
+      >
+        <Checkbox.Label>
+          Выбрать все ({selected.length} из {DOCUMENTS.length})
+        </Checkbox.Label>
+      </Checkbox.Root>
+      <div className={styles.nested}>
+        {DOCUMENTS.map((document) => (
+          <Checkbox.Root
+            key={document}
+            checked={selected.includes(document)}
+            onCheckedChange={(checked) =>
+              setSelected((current) =>
+                checked ? [...current, document] : current.filter((item) => item !== document),
+              )
+            }
+          >
+            <Checkbox.Label>{document}</Checkbox.Label>
+          </Checkbox.Root>
+        ))}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,67 @@
+/* Layout of the Checkbox scenarios: semantic tokens only. */
+
+/* without-label.tsx: boxes in one row. */
+.row {
+  display: flex;
+  gap: var(--prime-space-3);
+}
+
+/* controlled.tsx: «select all» above its options. */
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+}
+
+/* Child options sit under the parent's text column. */
+.nested {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+  padding-inline-start: calc(var(--prime-control-m-choice) + var(--prime-control-m-gap));
+}
+
+/* in-form.tsx: choices, then actions (group → actions 32). */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.formActions {
+  display: flex;
+  margin-top: var(--prime-space-4);
+}
+
+/* indicator.tsx: a listbox panel with full-width option rows (panel tokens, row hover wash). */
+.optionList {
+  box-sizing: border-box;
+  display: grid;
+  width: min(100%, var(--prime-panel-min-width));
+  padding: var(--prime-panel-padding);
+  border-radius: var(--prime-panel-radius);
+  background: var(--prime-color-bg-raised);
+  box-shadow: var(--prime-shadow-overlay);
+}
+
+.option {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-control-m-gap);
+  min-height: var(--prime-control-m-item-height);
+  padding-inline: var(--prime-control-m-field-padding-x);
+  border-radius: var(--prime-panel-item-radius);
+  cursor: pointer;
+  transition: background-color var(--prime-motion-duration-xfast)
+    var(--prime-motion-easing-standard);
+}
+
+.option:hover {
+  background: var(--prime-color-fill-subtle);
+}
+
+.option:focus-visible {
+  outline: var(--prime-focus-width) solid var(--prime-color-focus-ring);
+  outline-offset: var(--prime-focus-offset-inset);
+}