prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/reference/components/progress-circle/COMPONENT.md

@@ -0,0 +1,189 @@
+# ProgressCircle
+
+**Category:** status
+**Kind:** primitive
+
+> Circular progress — the ring version of ProgressBar: one value or `segments` that split a whole, with status colors and optional content in the center.
+
+## When to use
+- Compact metrics and goals in cards and dashboards (84% of plan).
+- Progress where horizontal space is short: table cells, list rows.
+- A value on a custom scale shown as a ring («7/12»).
+- A compact breakdown of a whole: tasks by status, storage by type (`segments`); categories in their chart colors (`color`) with a `legend` beside the ring.
+- A named process whose share is not known yet (`value={null}`) or that turns while its share grows (`spin`), with an icon in the center that changes with its state.
+
+## When not to use
+- Progress with a label and width to spare (uploads, imports) → use [ProgressBar](../progress-bar/COMPONENT.md).
+- A breakdown with many parts or long labels → [ProgressBar](../progress-bar/COMPONENT.md) with `segments`.
+- An anonymous «busy» mark inside a control or a region (a button, a select, a list) → [Spinner](../spinner/COMPONENT.md): it sizes like an icon and is a `status`.
+- A ring you can press (cancel, retry, download) → [Button](../button/COMPONENT.md) `shape="circle"` with `progress`; ProgressCircle is never interactive.
+
+## Import
+```tsx
+import { ProgressCircle, type ProgressSegment } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+ProgressCircle           <div>; size, tone (value mode), children in the center, aria-busy while loading
+├─ svg                   the kit ring (internal/ring, data weight); role="progressbar" (value) or
+│                        role="group" (segments); track + arcs
+│                        (loading: a Skeleton ring of the same diameter and stroke)
+├─ description           visually hidden distribution (segments with aria-label, no legend)
+└─ inner                 children in the hole of the ring, a changed icon cross-fades
+                         (not on xs, text not on s, not while loading)
+
+with legend:             <div data-legend> — a row: the ring box + <ul> legend (swatch · name · value · share)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ProgressCircle
+`ref` → `HTMLDivElement` (the root). Props of both modes; pass either `value` (value mode) or `segments` (segments mode), never both.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Diameter 24 · 32 · 48 · 64 · 80 px; the stroke is 1/12 of it. |
+| `children` | `ReactNode` | — | Content in the center (number, percent, `Icon`): text from `m`, an icon from `s`, nothing on `xs`. A string or number also becomes `aria-valuetext`. |
+| `aria-label` | `string` | — | Accessible name of the ring (set on the svg). Always pass it. |
+| `loading` | `boolean` | `false` | The data is on its way: a Skeleton ring of the same diameter and stroke (and legend lines) that cross-fades into the data; the inner content waits, the root is `aria-busy`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root. |
+
+### ProgressCircle · value mode
+The svg is `role="progressbar"`: a track and one round-capped arc from 12 o'clock.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number \| null` | — (required) | The current value, clamped to `0…max`; it glides to a new value (`base`). `null` — under way, the share unknown: a quarter arc that always turns, no `aria-valuenow`. |
+| `spin` | `boolean` | `false` | The ring turns at any share (one turn = 3 × `--prime-motion-loop`; slower under reduced motion, never still) and the arc never drops under 8%: a sync whose share grows. `null` always turns. |
+| `max` | `number` | `100` | Top of the scale. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info" \| "inherit"` | `"accent"` | Arc color, telling the outcome. `inherit` — the arc in the host's text color over a 32% track of it, for a ring on a colored host or over media. |
+
+### ProgressCircle · segments mode
+The svg is `role="group"`: parts clockwise from the top, described by the legend or the distribution text.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `segments` | `ProgressSegment[]` | — (required) | Parts in order, `{ value, label?, tone? \| color? }`: `tone` names a meaning (default `accent`), `color` a category — its step of the chart palette. Each part's length is its share of `max`. |
+| `max` | `number` | — | Total capacity. Default: the sum of the parts (they close the ring); a larger `max` leaves the rest as track. |
+| `segmentGap` | `"none" \| "hairline"` | `"none"` | `none` — one continuous ring; `hairline` — every part and the rest are separate round arcs. |
+| `legend` | `boolean` | `false` | A legend beside the ring (below it when the row is narrow), one row per part: color · name · value · share; it becomes the group's description. The root turns into the row of ring and legend. |
+| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a part's value in the legend («38 ГБ»). |
+| `labels` | `Partial<ProgressCircleLabels>` | — | Built-in strings, see Labels. |
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 24 diameter, no inner content | inline in text or table cells | |
+| `s` | 32 diameter, an icon 16 in the center, no text | list rows, compact cards | |
+| `m` | 48 diameter, inner text 12/16, icon 20 | KPI tiles | yes |
+| `l` | 64 diameter, inner text 16/24, icon 24 | dashboard cards | |
+| `xl` | 80 diameter, inner text 18/24, icon 32 | hero metrics, breakdowns | |
+
+The stroke is always 1/12 of the diameter (the kit ring's `data` weight). These diameters are a data scale, separate from the control heights of a circle Button.
+
+### tone (value mode or each segment)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `accent` | accent arc on a `fill-strong` track | progress toward a goal, the main share | yes |
+| `neutral` | `text-secondary` arc | quiet background work, «other» share | |
+| `success` | success arc | goal reached, done share | |
+| `warning` | warning arc | at risk, quota almost used | |
+| `danger` | danger arc | failed, overdue share | |
+| `info` | info arc | informational processes (sync, indexing) | |
+| `inherit` (value mode) | the arc in the host's text color over a 32% track of it; the center text inherits it too | a ring on a colored host or over media | |
+
+### color (each segment, instead of tone)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `blue` · `orange` · `teal` · `yellow` · `pink` · `green` · `purple` · `red` | the hue's step of the chart palette (`--prime-color-chart-1…8`) | categories: channels, sources, regions — the color they have in charts | |
+| `gray` | `--prime-color-chart-other` | the «Прочее» share | |
+| `sky` | the palette's sky solid (no chart step) | only when the category is sky elsewhere | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `spin` (value mode) | the ring turns at any share, the arc never under 8% | a process whose share grows while it runs (a sync) | `false` |
+| `legend` | swatch · name · value · share rows beside the ring, below it when narrow | a breakdown read in numbers | `false` |
+| `loading` | a Skeleton ring (and legend lines) of the same geometry | the data is on its way | `false` |
+
+### segmentGap
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `none` | one continuous ring, flat joints; with free capacity the filled share has round caps | parts of a single process | yes |
+| `hairline` | every part and the free rest are separate round arcs; no track | distinct categories | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| size / tone | props | `data-size`, `data-tone` (value mode) on the root |
+| empty | `value` 0, or `segments` empty / all 0 | arc hidden, track only |
+| value | `value`, `max` | `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax`; `--ring-value` on the svg, the arc glides by `stroke-dashoffset` over `base` |
+| share unknown | `value={null}` | no `aria-valuenow`; `data-spin` on the svg: a quarter arc turning (one turn = 3 × `--prime-motion-loop`); a share that arrives glides out of the quarter |
+| spinning | `spin` | `data-spin` on the svg: the whole svg turns (a compositor transform) while the share glides on its own; the arc is at least 8% |
+| icon change | a new icon in `children` (another `name`) | the old one shrinks to 0.6 and fades, the new one grows in (`fast`) and plays its gesture once; a changing number updates in place |
+| segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the svg, `data-tone` or `data-color` on every arc and cap; arcs glide by dash, caps by `rotate` |
+| legend | `legend` | `data-legend` on the root, which becomes a wrapping row of the ring and the `<ul>` |
+| loading | `loading` | `aria-busy` on the root; a Skeleton ring (mask of the stroke) and legend lines; the data cross-fades in (`swapMotion`) |
+| reduced motion | `prefers-reduced-motion` | arcs and icons change instantly; a turning ring turns twice as slow and never stops |
+
+Always controlled: pass the current `value` or `segments`.
+
+## Layout & spacing
+- `display: inline-flex`, never shrinks (with `legend` the root is a block `flex` row); a caption sits next to it with `--prime-space-3` or under it with `--prime-space-2`.
+- Diameters sit on the 4px grid (`--prime-space-6…20`); the ring is placed in CSS (an svg without a viewBox), lengths along it are percent of the circle.
+- Inner content sits in the hole (5/6 of the diameter, clipped), primary, medium weight, tabular numbers.
+- With `legend` the root is a wrapping row: the ring and the legend `--prime-space-5` (20) apart; the legend takes the rest of the row (basis 192) and drops below the ring when that does not fit.
+- `hairline` arcs are ¾ of the stroke apart; arcs start at 12 o'clock and run clockwise.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Value mode: the svg is `role="progressbar"` with `aria-valuenow` / `-min` / `-max`; a string or number child becomes `aria-valuetext`. With `value={null}` there is no `aria-valuenow` — the share is unknown.
+- The turn never stops under reduced motion (twice as slow): it is the only sign the work goes on.
+- Segments mode: the svg is `role="group"`; with `aria-label` it is described by the distribution («Видео: 38%, Документы: 21%») or by the legend, without it the distribution is its name.
+- A category color always sits beside its name in the legend, so color is never the only cue.
+- While `loading` the root is `aria-busy` and the Skeletons are `aria-hidden`.
+- Always pass `aria-label`: a caption next to the ring is not linked to it.
+- The inner text is `aria-hidden` when it is already the `aria-valuetext`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `empty` | `"Нет сегментов"` | Accessible text when `segments` is empty. |
+| `allEmpty` | `"Все сегменты пусты"` | Accessible text when every segment is 0. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A plan ring with the percentage in the center, named for screen readers — `value`, `aria-label`. |
+| [variants.tsx](examples/variants.tsx) | Every arc color; the tone tells the outcome, not the progress — `tone`. |
+| [sizes.tsx](examples/sizes.tsx) | Diameters 24 to 80 px; the center text is not rendered on `xs` and `s` — `size`. |
+| [states.tsx](examples/states.tsx) | Loading is a Skeleton ring of the same diameter and stroke; the number in the centre waits for the data — `loading`. |
+| [inner-content.tsx](examples/inner-content.tsx) | The center holds a percentage, a count on its own scale or an icon — `children`, `max`. |
+| [under-way.tsx](examples/under-way.tsx) | An import whose share is not known yet turns a quarter arc, then fills and swaps its icon; a sync turns while its share grows — `value`, `spin`, `children`. |
+| [segments.tsx](examples/segments.tsx) | Parts of a whole clockwise from the top: a closed ring, free capacity up to `max`, separate arcs and an empty list — `segments`, `segmentGap`. |
+| [legend.tsx](examples/legend.tsx) | A ring of category shares with a legend beside it, in the categories' chart colors — `color`, `legend`, `formatValue`. |
+
+## Mistakes
+- No `aria-label` (even with a visible caption) → screen readers get an unnamed progressbar.
+- Text inside an `xs` / `s` ring → it is not rendered; show it outside (an icon shows from `s`).
+- A fake indeterminate ring (`value={25}` plus a CSS rotation) → `value={null}`.
+- `onClick` on the ring to cancel → a [Button](../button/COMPONENT.md) `shape="circle"` with `progress`.
+- `value` and `segments` together → a type error; pick one mode.
+- `tone` on the root with `segments` → set `tone` on each segment.
+- Long text inside the ring → it is clipped to the inner circle.
+- Categories painted with `tone` → use `color`; a hand-built legend beside the ring → `legend`.
+
+## Related
+- **Built from:** [Skeleton](../skeleton/COMPONENT.md), `internal/ring` (the ring drawing, shared with Spinner and the circle Button), `internal/glyphSwap` (the center cross-fade)
+- **See also:** [ProgressBar](../progress-bar/COMPONENT.md), [Card](../card/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), [Button](../button/COMPONENT.md)

package/dist/skill/reference/components/progress-circle/examples/examples.module.css

@@ -0,0 +1,22 @@
+/* Layout of the ProgressCircle scenarios: semantic tokens only. */
+
+/* Several rings in one line; captions of different rings share one baseline. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  justify-content: center;
+  gap: var(--prime-space-6);
+}
+
+/* A dashboard card as wide as a short form: the legend sits beside the ring or drops under it. */
+.card {
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--prime-space-2);
+}

package/dist/skill/reference/components/progress-circle/examples/inner-content.tsx

@@ -0,0 +1,35 @@
+/** The center holds a percentage, a count on its own scale or an icon — `children`, `max`. */
+import { Icon, ProgressCircle, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ProgressCircleInnerContentExample() {
+  return (
+    <div className={styles.row}>
+      <div className={styles.item}>
+        <ProgressCircle size="l" value={45} aria-label="Загрузка отчёта">
+          45%
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Отчёт
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle size="l" value={7} max={12} aria-label="Оплачено месяцев">
+          7/12
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Подписка
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle size="l" value={100} tone="success" aria-label="Онбординг завершён">
+          <Icon name="action.check" />
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Онбординг
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/dist/skill/reference/components/progress-circle/examples/legend.tsx

@@ -0,0 +1,33 @@
+/** A ring of category shares with a legend beside it, in the categories' chart colors — `color`, `legend`, `formatValue`. */
+import { Card, ProgressCircle, type ProgressSegment } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TRAFFIC: ProgressSegment[] = [
+  { value: 18_420, label: "Поиск", color: "blue" },
+  { value: 9_310, label: "Реклама", color: "orange" },
+  { value: 6_050, label: "Соцсети", color: "pink" },
+  { value: 2_870, label: "Рассылки", color: "purple" },
+  { value: 1_240, label: "Прочее", color: "gray" },
+];
+
+const formatVisits = (value: number) => value.toLocaleString("ru-RU");
+
+export default function ProgressCircleLegendExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <ProgressCircle
+          size="xl"
+          segments={TRAFFIC}
+          segmentGap="hairline"
+          legend
+          formatValue={formatVisits}
+          aria-label="Визиты по каналам"
+        >
+          37,9 тыс.
+        </ProgressCircle>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/progress-circle/examples/overview.tsx

@@ -0,0 +1,10 @@
+/** A plan ring with the percentage in the center, named for screen readers — `value`, `aria-label`. */
+import { ProgressCircle } from "prime-ui-kit";
+
+export default function ProgressCircleOverviewExample() {
+  return (
+    <ProgressCircle value={84} aria-label="Выполнение плана">
+      84%
+    </ProgressCircle>
+  );
+}

package/dist/skill/reference/components/progress-circle/examples/segments.tsx

@@ -0,0 +1,64 @@
+/** Parts of a whole clockwise from the top: a closed ring, free capacity up to `max`, separate arcs and an empty list — `segments`, `segmentGap`. */
+import { ProgressCircle, type ProgressSegment, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const REVIEW: ProgressSegment[] = [
+  { value: 40, label: "Принято", tone: "success" },
+  { value: 35, label: "На проверке", tone: "warning" },
+  { value: 25, label: "Отклонено", tone: "danger" },
+];
+
+const SPRINT: ProgressSegment[] = [
+  { value: 12, label: "Готово", tone: "success" },
+  { value: 6, label: "В работе" },
+];
+
+const STORAGE: ProgressSegment[] = [
+  { value: 38, label: "Видео" },
+  { value: 21, label: "Документы", tone: "success" },
+  { value: 12, label: "Архивы", tone: "warning" },
+];
+
+export default function ProgressCircleSegmentsExample() {
+  return (
+    <div className={styles.row}>
+      <div className={styles.item}>
+        <ProgressCircle size="xl" segments={REVIEW} aria-label="Заявки">
+          100
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Заявки
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle size="xl" segments={SPRINT} max={30} aria-label="Спринт">
+          18/30
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Спринт
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle
+          size="xl"
+          segments={STORAGE}
+          max={100}
+          segmentGap="hairline"
+          aria-label="Хранилище"
+        >
+          71%
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Хранилище
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle size="xl" segments={[]} aria-label="Нет данных" />
+        <Typography as="span" variant="caption" tone="muted">
+          Нет данных
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/dist/skill/reference/components/progress-circle/examples/sizes.tsx

@@ -0,0 +1,21 @@
+/** Diameters 24 to 80 px; the center text is not rendered on `xs` and `s` — `size`. */
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ProgressCircleSizesExample() {
+  return (
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <ProgressCircle size={size} value={72} aria-label="Выполнено">
+            72%
+          </ProgressCircle>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/progress-circle/examples/states.tsx

@@ -0,0 +1,25 @@
+/** Loading is a Skeleton ring of the same diameter and stroke; the number in the centre waits for the data — `loading`. */
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+export default function ProgressCircleStatesExample() {
+  return (
+    <div>
+      <div>
+        <ProgressCircle value={72} size="l" aria-label="План продаж">
+          72%
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          value
+        </Typography>
+      </div>
+      <div>
+        <ProgressCircle value={0} size="l" aria-label="План продаж" loading>
+          0%
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          loading
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/dist/skill/reference/components/progress-circle/examples/under-way.tsx

@@ -0,0 +1,54 @@
+/** An import whose share is not known yet turns a quarter arc, then fills and swaps its icon; a sync turns while its share grows — `value`, `spin`, `children`. */
+import { Icon, ProgressCircle, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** Orders synced at each tick, out of `ORDERS`. */
+const SYNCED = [0, 18, 41, 57, 74, 96, 118, 131, 140];
+const ORDERS = 140;
+
+/** Steps of the invoice import: unknown while the file is read, then the share. */
+const IMPORT: (number | null)[] = [null, null, null, 24, 52, 81, 100];
+
+export default function ProgressCircleUnderWayExample() {
+  const [step, setStep] = React.useState(0);
+
+  React.useEffect(() => {
+    // Runs again from the start after a pause on the finished state.
+    const timer = window.setTimeout(() => setStep((step + 1) % (SYNCED.length + 4)), 700);
+    return () => window.clearTimeout(timer);
+  }, [step]);
+
+  const imported = IMPORT[Math.min(step, IMPORT.length - 1)];
+  const synced = SYNCED[Math.min(step, SYNCED.length - 1)];
+  const syncing = synced < ORDERS;
+
+  return (
+    <div className={styles.row}>
+      <div className={styles.item}>
+        <ProgressCircle size="l" value={imported} aria-label="Импорт счетов">
+          <Icon name={imported === 100 ? "action.check" : "action.download"} />
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Импорт счетов
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle
+          size="l"
+          value={synced}
+          max={ORDERS}
+          spin={syncing}
+          tone={syncing ? "accent" : "success"}
+          aria-label="Синхронизация заказов"
+        >
+          {`${synced}`}
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Заказы
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/dist/skill/reference/components/progress-circle/examples/variants.tsx

@@ -0,0 +1,28 @@
+/** Every arc color; the tone tells the outcome, not the progress — `tone`. */
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+const TONES = [
+  { tone: "accent", label: "Загрузка", value: 45 },
+  { tone: "success", label: "Готово", value: 100 },
+  { tone: "warning", label: "Квота", value: 88 },
+  { tone: "danger", label: "Сбой импорта", value: 20 },
+  { tone: "info", label: "Синхронизация", value: 30 },
+  { tone: "neutral", label: "Индексация", value: 55 },
+] as const;
+
+export default function ProgressCircleVariantsExample() {
+  return (
+    <div>
+      {TONES.map(({ tone, label, value }) => (
+        <div key={tone}>
+          <ProgressCircle value={value} tone={tone} aria-label={label}>
+            {`${value}%`}
+          </ProgressCircle>
+          <Typography as="span" variant="caption" tone="muted">
+            {tone}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/radio/COMPONENT.md

@@ -0,0 +1,165 @@
+# Radio
+
+**Category:** selection
+**Kind:** control
+
+> Radio buttons for choosing exactly one option out of a small visible set.
+
+## When to use
+- One choice out of 2–7 visible options where the user benefits from seeing all of them at once: plan, payment method, delivery slot.
+- Options that need a description under the text (`hint` on `Radio.Root`) or a reason why one is unavailable.
+- A required one-of-many question in a form.
+
+## When not to use
+- 2–4 short view modes or filters that apply instantly → use [SegmentedControl](../segmented-control/COMPONENT.md) instead.
+- A long list (8+ options) or limited space → use [Select](../select/COMPONENT.md) instead.
+- Independent yes/no options → use [Checkbox](../checkbox/COMPONENT.md) instead.
+- A single on/off setting → use [Switch](../switch/COMPONENT.md) instead.
+
+## Import
+```tsx
+import { Radio } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Radio.Group             field: group label → role="radiogroup" → hint | error; value, name, size, flags
+└─ Radio.Root           one option (value): the <label> row with the input and the circle, its hint
+   └─ Radio.Label       the visible text of the option
+```
+`className`, `ref` and the rest of `Radio.Group` go to the field frame; `id`, `aria-label`, `aria-labelledby` and `aria-describedby` to the `role="radiogroup"` element. `Radio.Root` must be inside `Radio.Group`. Without `Radio.Label` only the circle renders — give the option an `aria-label`.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Radio.Group
+`ref` → `HTMLDivElement` (the field frame). Owns the value, the shared `name` and size; renders the group label and the hint / error. `id` and the `aria-*` naming props go to the `role="radiogroup"` element.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Controlled value (the `value` of the chosen `Radio.Root`). |
+| `defaultValue` | `string` | — | Initial value when uncontrolled. |
+| `onValueChange` | `(value: string) => void` | — | Called with the value of the newly chosen option. |
+| `name` | `string` | — | Native `name` shared by the radios; generated when omitted. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of every circle, text, the label and the hint. Without it the group takes the tier of its host (LoginForm, Popover, a panel with a size), else `m`. |
+| `label` | `ReactNode` | — | Group heading above the options; names the radiogroup through `aria-labelledby`. Without it, pass `aria-label`. |
+| `required` | `boolean` | `false` | Red `*` after the label, native `required` on the radios and `aria-required` on the group. |
+| `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the options. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message under the options; implies `invalid`. |
+| `invalid` | `boolean` | `false` | Danger ring on the unchecked circles and `aria-invalid` on the group and the inputs. A non-empty `error` implies it. |
+| `disabled` | `boolean` | `false` | Disables every option. |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | `vertical` stacks the options; `horizontal` lays them out in a wrapping row. Sets `aria-orientation`. |
+| `labels` | `Partial<RadioGroupLabels>` | — | Built-in strings, see Labels. |
+| `id` | `string` | — | Id of the `role="radiogroup"` element (generated when omitted); also the default `name`. |
+| `aria-label / aria-labelledby / aria-describedby` | `string` | — | Name and description of the radiogroup (`aria-describedby` is merged before the hint / error ids). |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange" \| "dir">` | — | `className`, `data-*` and the other attributes of the field frame `<div>`. |
+
+### Radio.Root
+`ref` → `HTMLInputElement` (the native radio). One option inside `Radio.Group`: the `<label>` row with the input and the circle, and its hint; native input props go to the input.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Value reported to the group when this option is chosen. |
+| `hint` | `ReactNode` | — | Description under the option text, linked through `aria-describedby`. |
+| `disabled` | `boolean` | `false` | Disables this option only. |
+| `children` | `ReactNode` | — | `Radio.Label`. Without it only the circle renders — give the root an `aria-label`. |
+| `className` | `string` | — | Class on the option `<div>`. |
+| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange" \| "name" \| "value">` | — | `id`, `aria-label`, `aria-describedby`, `onBlur`… on the native input. |
+
+### Radio.Label
+`ref` → `HTMLSpanElement`. The visible text in the text column of the option row. Native `<span>` props.
+
+## Variants
+No `variant` / `tone` / `color`.
+
+### size (Radio.Group)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 14px circle, 4px gap, 12/16 text | dense filters and tables | |
+| `s` | 16px circle, 8px gap, 13/20 text | compact forms and side panels | |
+| `m` | 18px circle, 8px gap, 14/20 text | regular forms | yes |
+| `l` | 20px circle, 8px gap, 16/24 text | spacious forms, onboarding | |
+| `xl` | 24px circle, 12px gap, 16/24 text | touch-first screens | |
+
+**Sizes:** match the form — `m` radios next to `m` inputs and buttons. The circle is centred on the first text line; the group label and hint take the same tier.
+
+### orientation (Radio.Group)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `vertical` | options stacked, gap `--prime-space-2` | options with descriptions, more than 3 options | yes |
+| `horizontal` | options in a wrapping row, column gap `--prime-space-5`, row gap `--prime-space-2` | 2–4 short labels without hints | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `required` | red `*` after the group label | the question must be answered | `false` |
+| `optional` | muted «необязательно» after the group label | most questions are required | `false` |
+| `invalid` | danger ring on the unselected circles | the message is shown elsewhere; otherwise pass `error` | `false` |
+| `disabled` | muted circles and text | the whole question or one option is unavailable | `false` |
+
+**Combinations**
+- `orientation="horizontal"` with option hints → avoid: descriptions break the row; use vertical.
+- One error per question: `error` on `Radio.Group`, never per option.
+- `required` and `optional` together are pointless.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| unselected | group `value` ≠ option `value` | `data-state="unchecked"` on the option; circle `fill-strong`, hover `fill-strong-hover` |
+| selected | group `value` = option `value` | `data-state="checked"`; accent circle with a thumb-coloured dot that grows in |
+| invalid | `invalid` or a non-empty `error` on the group | `data-invalid="true"`, `aria-invalid` on the group and the inputs; danger ring on unselected circles; the control shakes once when an error arrives (`data-shake` on the frame) |
+| disabled | group or option `disabled` | `data-disabled="true"`, native `disabled` on every radio; `fill-muted` circle, `cursor: not-allowed` |
+| pressed | pointer press | the circle scales to the compact press scale |
+| focus-visible | keyboard | outer focus ring around the circle |
+
+The radiogroup carries `data-size`, `data-orientation`, `aria-orientation`, `aria-required`; options carry `data-size`, `data-state`, `data-invalid`, `data-disabled`. Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue`.
+
+## Layout & spacing
+- Group label → options: the tier `label-gap`; options → hint / error: the tier `hint-gap` (the same rhythm as fields).
+- Options inside a group: gap `--prime-space-2`; group → group: `--prime-space-8`.
+- An option hint aligns with the text column, not with the circle.
+- Long labels wrap; horizontal rows wrap at narrow widths.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focuses the selected option (or the first one when nothing is selected). |
+| `ArrowDown` · `ArrowRight` · `ArrowUp` · `ArrowLeft` | Selects the next or previous option of the group (native radio behaviour). |
+| `Space` | Selects the focused option. |
+
+### ARIA
+- `Radio.Group` is `role="radiogroup"`, named by its `label` through `aria-labelledby`, or by `aria-label`.
+- `aria-required`, `aria-invalid` and `aria-orientation` sit on the group; the group hint or error is in its `aria-describedby`.
+- Every option is a native `<input type="radio">` with the shared `name`; an option `hint` is linked through `aria-describedby`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the group label when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A labelled group of options with one chosen by default — `label`, `defaultValue`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size; the circle and the text follow the group tier — `size`. |
+| [states.tsx](examples/states.tsx) | Every state, each in its own group and labelled by its prop — `value`, `invalid`, `disabled`. |
+| [group.tsx](examples/group.tsx) | A required group with option descriptions and the group's error under the options — `label`, `required`, `hint`, `error`. |
+| [orientation.tsx](examples/orientation.tsx) | Options stacked in a column and laid out in a wrapping row — `orientation`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the chosen plan and shows it in the hint — `value`, `onValueChange`. |
+
+## Mistakes
+- `Radio.Root` outside `Radio.Group` → it throws; every option needs the group.
+- A heading made of `Typography` + `aria-labelledby` → pass `label` to `Radio.Group`.
+- An error under one option → pass `error` to `Radio.Group`.
+- Radios for an instant view switch → use `SegmentedControl`.
+- Eight or more options → use `Select`.
+
+## Related
+- **Built from:** [Label](../label/COMPONENT.md) (group label), [Hint](../hint/COMPONENT.md) (`hint`, `error`, option hints); option rows are native `<label>` elements
+- **See also:** [Checkbox](../checkbox/COMPONENT.md), [Switch](../switch/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Select](../select/COMPONENT.md)