prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/reference/components/smart-filter/examples/ranges.tsx

@@ -0,0 +1,89 @@
+/** Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip — `kind`, `formatValue`, `matchesSmartFilter`. */
+import {
+  matchesSmartFilter,
+  SmartFilter,
+  type SmartFilterField,
+  type SmartFilterValue,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+const FIELDS: SmartFilterField[] = [
+  { key: "amount", label: "Сумма", kind: "range", formatValue: formatRubles },
+  { key: "closed", label: "Период", kind: "date-range" },
+  {
+    key: "stage",
+    label: "Этап",
+    options: [
+      { value: "proposal", label: "Предложение" },
+      { value: "contract", label: "Договор" },
+      { value: "won", label: "Выиграна" },
+    ],
+  },
+];
+
+const DEALS = [
+  {
+    id: "d-118",
+    client: "ООО «Гранит»",
+    amount: 94_750,
+    closed: new Date(2026, 2, 3),
+    stage: "won",
+  },
+  {
+    id: "d-121",
+    client: "АО «Альфа Медиа»",
+    amount: 380_000,
+    closed: new Date(2026, 2, 12),
+    stage: "contract",
+  },
+  {
+    id: "d-124",
+    client: "ИП Орлов Д. С.",
+    amount: 18_000,
+    closed: new Date(2026, 2, 20),
+    stage: "proposal",
+  },
+  {
+    id: "d-130",
+    client: "ООО «Север»",
+    amount: 1_250_000,
+    closed: new Date(2026, 3, 2),
+    stage: "won",
+  },
+];
+
+const INITIAL: SmartFilterValue = { amount: { from: 50_000, to: 500_000 } };
+
+export default function SmartFilterRangesExample() {
+  const [value, setValue] = React.useState<SmartFilterValue>(INITIAL);
+  const rows = DEALS.filter(
+    (deal) =>
+      matchesSmartFilter(value.amount, deal.amount) &&
+      matchesSmartFilter(value.closed, deal.closed) &&
+      matchesSmartFilter(value.stage, deal.stage),
+  );
+
+  return (
+    <div className={styles.stack}>
+      <SmartFilter.Root fields={FIELDS} value={value} onValueChange={setValue}>
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+      {rows.map((deal) => (
+        <div key={deal.id} className={styles.request}>
+          <Typography as="span" variant="body-m" truncate className={styles.route}>
+            {deal.client}
+          </Typography>
+          <Typography as="span" variant="body-m" tone="secondary">
+            {formatRubles(deal.amount)}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/smart-filter/examples/single-value.tsx

@@ -0,0 +1,41 @@
+/** For an API that takes one value per field: the filter button without a search, a press picks only that value and nothing can be hidden — `searchable`, `multiple`. */
+import { SmartFilter, type SmartFilterField } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "pipeline",
+    label: "Воронка",
+    multiple: false,
+    options: [
+      { value: "b2b", label: "Корпоративные продажи" },
+      { value: "retail", label: "Розница" },
+      { value: "partners", label: "Партнёры" },
+    ],
+  },
+  {
+    key: "period",
+    label: "Срок",
+    multiple: false,
+    options: [
+      { value: "overdue", label: "Просрочены" },
+      { value: "today", label: "Сегодня" },
+      { value: "week", label: "На этой неделе" },
+    ],
+  },
+];
+
+export default function SmartFilterSingleValueExample() {
+  return (
+    <div className={styles.stack}>
+      <SmartFilter.Root
+        fields={FIELDS}
+        defaultValue={{ pipeline: { include: ["b2b"], exclude: [] } }}
+      >
+        <SmartFilter.Toolbar searchable={false} />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/smart-filter/examples/sizes.tsx

@@ -0,0 +1,33 @@
+/** Every size tier: the filter button, the search, the tags and the panel follow one tier — `size`. */
+import { SmartFilter, type SmartFilterField, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const FIELDS: SmartFilterField[] = [
+  {
+    key: "method",
+    label: "Метод",
+    options: ["GET", "POST", "PUT", "DELETE"].map((v) => ({ value: v, label: v })),
+  },
+];
+
+const ONLY_GET = { method: { include: ["GET"], exclude: [] } };
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function SmartFilterSizesExample() {
+  return (
+    <div className={styles.sizes}>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.size}>
+          <SmartFilter.Root fields={FIELDS} size={size} defaultValue={ONLY_GET}>
+            <SmartFilter.Toolbar />
+            <SmartFilter.Chips />
+          </SmartFilter.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,127 @@
+# Sparkline
+
+**Category:** data-display
+**Kind:** primitive
+
+> A small line or bar chart with its headline — the value at rest, its change against the point before and its date — where any point can be scrubbed.
+
+## When to use
+- A metric card on a dashboard: revenue, orders, sign-ups over the last days or weeks.
+- A trend next to a number where the shape matters more than exact axes.
+- Values with a sign by period — profit, net new customers (`variant="bars"`: up when positive, down when negative), with the current period highlighted (`highlight`).
+- A detail page header that shows how a value moved.
+
+## When not to use
+- Exact values on axes, several series, or a legend → a full chart library on the kit's chart palette (`chartColors`); Sparkline has no axes.
+- Progress toward a goal → [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- Shares of categories or a ranking → [ProgressBar](../progress-bar/COMPONENT.md) with `segments` or `layout="rows"`.
+- A list of values to compare → [DataTable](../data-table/COMPONENT.md).
+
+## Import
+```tsx
+import { Sparkline, type SparklinePoint } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Sparkline              <div>; the headline and the chart; aria-busy while loading
+├─ head                title (label) · date of the shown point
+├─ value row           value (rolling digits when settled) · change Badge with the trend arrow
+└─ plot                role="slider" over the chart
+   ├─ line:            svg line and area + cursor (guide line and dot, aria-hidden)
+   └─ bars:            zero line (chart axis) + a slot per point with its bar (aria-hidden)
+loading:               Skeletons of the date, the value line and the plot
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Sparkline
+`ref` → `HTMLDivElement` (the root). A headline (title · date, value · change) over a line or bar chart; the chart is a `role="slider"` that picks a point. The change hides when a percentage means nothing (the previous value is 0 or the sign flips).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `SparklinePoint[]` | — (required) | Points oldest first, `{ label, value }`; `label` names the point («8 окт»). Two or more draw a line. A new array cross-fades the line in. |
+| `label` | `string` | — (required) | Visible title above the value and the accessible name of the chart. |
+| `variant` | `"line" \| "bars"` | `"line"` | `line` — a line over a soft area; `bars` — a bar per point standing on a zero line: up when positive, down (danger) when negative, the value end rounded. |
+| `highlight` | `number` | `the latest point` | Index of the point at rest (the current month): the headline shows it when nobody scrubs and leaving the chart returns to it; `bars` draw the other bars quieter. |
+| `loading` | `boolean` | `false` | The series is on its way: Skeletons of the date, the value and the plot that cross-fade into the data; the title stays, the root is `aria-busy` and the chart is not focusable yet. |
+| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a value in the headline and the spoken point («312 400 ₽»). |
+| `labels` | `Partial<SparklineLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root. |
+
+## Variants
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `line` | an accent line over a soft area, a dot on the shown point | a continuous trend (daily revenue) | yes |
+| `bars` | a bar per point from a zero line (`--prime-color-chart-axis`): accent up, danger down, value end rounded | values by period, especially with a sign (monthly profit) | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `highlight` | the headline rests on that point; in `bars` the other bars are quieter | the current period is not the last point (a year with empty months ahead) | the latest point |
+| `loading` | Skeletons of the date, the value and the plot | the series is on its way | `false` |
+
+Put it in a `Card` for a dashboard tile.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| at rest | — | the latest point or `highlight`; the value rolls its digits when `data` changes |
+| scrubbing | pointer, touch or the arrow keys | `data-scrubbing` on the root; the cursor (or the bar under the pointer) and the headline follow with no easing (direct manipulation), digits change in place |
+| keyboard | arrows, Home, End on the focused plot | `aria-valuenow` / `aria-valuetext`, `data-scrubbing`; the cursor moves to the point at once (keyboard steps are high-frequency); in `bars` the current bar keeps its fill, the others go quiet (`fast` opacity) |
+| settle | pointer leaves, touch ends, focus leaves | back to the point at rest |
+| change hidden | the first point, the previous value is 0, or the sign flips | no change Badge: a percentage would mean nothing |
+| new series | a new `data` array | the chart cross-fades in (swap motion); the trend arrow turns half a turn between up and down |
+| loading | `loading` | `aria-busy` on the root; Skeletons in place of the date, the value and the plot; no slider until the data comes; the data cross-fades in |
+
+## Layout & spacing
+- Takes the width of its container; the plot is 80 px high and inset by the dot radius so the cursor is never clipped.
+- Bars share the width equally, 4 px apart; the zero line sits where 0 falls on the scale (the bottom when every value is positive).
+- In a dashboard, wrap it in `Card.Root` + `Card.Body`; several cards go in a grid.
+- When the value row does not fit (a narrow card), the change badge wraps under the value.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `←` · `→` · `↓` · `↑` | Previous or next point: `←` / `↓` back, `→` / `↑` forward, as on a slider. |
+| `Home` · `End` | First or last point. |
+| `Tab` | Focuses the chart; leaving focus returns to the point at rest (the latest or `highlight`). |
+
+### ARIA
+- The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`). The headline is the tooltip of the chart: the value of the point under the pointer or the arrows, in text.
+- The headline with the value and change reads as plain text.
+- The change carries a sign and an arrow, never color alone; a negative bar goes down, not only red.
+- While `loading` the root is `aria-busy` and the chart is not in the tab order yet.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `point` | `"{label}: {value}"` | Spoken value of the chosen point (`aria-valuetext`); `{label}` and `{value}` are replaced. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. |
+| [variants.tsx](examples/variants.tsx) | The same week as a line and as bars from zero — `variant`. |
+| [states.tsx](examples/states.tsx) | While the series loads the date, the value and the plot are Skeletons in their own places; the title stays — `loading`. |
+| [signed-bars.tsx](examples/signed-bars.tsx) | Monthly profit with a sign: losses go below the zero line, the current month rests highlighted and any bar shows its value under the pointer or the arrows — `variant`, `highlight`. |
+| [period.tsx](examples/period.tsx) | Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. |
+
+## Mistakes
+- A new array on every render (`data={rows.map(...)}` inline) → the line cross-fades on every render; memoize the series.
+- Formatting inside `label` of a point («312 400 ₽») → the point label is its name («8 окт»); format values with `formatValue`.
+- A Sparkline without a container width (inside an inline flex row) → give it a width or put it in a `Card`.
+- A separate tooltip over the bars → the headline already shows the scrubbed point; a floating tooltip would cover the next bar.
+- A grey box while the series loads → `loading`.
+
+## Related
+- **Built from:** [Badge](../badge/COMPONENT.md) (change), [Skeleton](../skeleton/COMPONENT.md) (loading), `Icon` (trend arrow)
+- **See also:** [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/dist/skill/reference/components/sparkline/examples/examples.module.css

@@ -0,0 +1,13 @@
+/* Layout of the Sparkline scenarios: semantic tokens only. */
+
+/* A dashboard card's width: the chart takes the card width. */
+.card {
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* The period switch above the chart inside the card body. */
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
+}

package/dist/skill/reference/components/sparkline/examples/overview.tsx

@@ -0,0 +1,27 @@
+/** Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. */
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const MONTHS = ["янв", "фев", "мар", "апр", "мая", "июн", "июл", "авг", "сен", "окт", "ноя", "дек"];
+
+/** Daily revenue, 9 September — 8 October 2026. */
+const REVENUE: SparklinePoint[] = Array.from({ length: 30 }, (_, i) => {
+  const day = new Date(2026, 8, 9 + i);
+  return {
+    label: `${day.getDate()} ${MONTHS[day.getMonth()]}`,
+    value: Math.round(260 + 40 * Math.sin(i / 3.2) + 28 * Math.sin(i / 1.4 + 1) + i * 2.6) * 1000,
+  };
+});
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+export default function SparklineOverviewExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <Sparkline data={REVENUE} label="Выручка за 30 дней" formatValue={formatRubles} />
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/sparkline/examples/period.tsx

@@ -0,0 +1,46 @@
+/** Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. */
+import { Card, SegmentedControl, Sparkline, type SparklinePoint } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Period = "week" | "month" | "quarter";
+
+const series = (labels: string[], base: number, swing: number): SparklinePoint[] =>
+  labels.map((label, i) => ({
+    label,
+    value: Math.round((base + swing * Math.sin(i / 1.7) + (swing / 4) * i) / 100) * 100,
+  }));
+
+const SERIES: Record<Period, SparklinePoint[]> = {
+  week: series(["2 окт", "3 окт", "4 окт", "5 окт", "6 окт", "7 окт", "8 окт"], 41_000, 6_000),
+  month: series(
+    ["сен, 1 нед.", "сен, 2 нед.", "сен, 3 нед.", "сен, 4 нед.", "окт, 1 нед."],
+    286_000,
+    32_000,
+  ),
+  quarter: series(["авг", "сен", "окт"], 1_240_000, 160_000),
+};
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+export default function SparklinePeriodExample() {
+  const [period, setPeriod] = React.useState<Period>("month");
+
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body className={styles.body}>
+        <SegmentedControl.Root
+          value={period}
+          onValueChange={(value) => setPeriod(value as Period)}
+          aria-label="Период"
+        >
+          <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
+          <SegmentedControl.Item value="quarter">Квартал</SegmentedControl.Item>
+        </SegmentedControl.Root>
+        <Sparkline data={SERIES[period]} label="Новые заказы" formatValue={formatRubles} />
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/sparkline/examples/signed-bars.tsx

@@ -0,0 +1,41 @@
+/** Monthly profit with a sign: losses go below the zero line, the current month rests highlighted and any bar shows its value under the pointer or the arrows — `variant`, `highlight`. */
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const PROFIT: SparklinePoint[] = [
+  { label: "янв", value: 420_000 },
+  { label: "фев", value: 310_000 },
+  { label: "мар", value: -120_000 },
+  { label: "апр", value: 180_000 },
+  { label: "мая", value: 540_000 },
+  { label: "июн", value: 610_000 },
+  { label: "июл", value: -60_000 },
+  { label: "авг", value: 280_000 },
+  { label: "сен", value: 470_000 },
+  { label: "окт", value: 390_000 },
+  { label: "ноя", value: 0 },
+  { label: "дек", value: 0 },
+];
+
+/** October is the current month: November and December are still empty. */
+const CURRENT_MONTH = 9;
+
+const formatRubles = (value: number) =>
+  `${value < 0 ? "−" : ""}${Math.abs(value).toLocaleString("ru-RU")} ₽`;
+
+export default function SparklineSignedBarsExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <Sparkline
+          data={PROFIT}
+          label="Прибыль по месяцам, 2026"
+          variant="bars"
+          highlight={CURRENT_MONTH}
+          formatValue={formatRubles}
+        />
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/sparkline/examples/states.tsx

@@ -0,0 +1,30 @@
+/** While the series loads the date, the value and the plot are Skeletons in their own places; the title stays — `loading`. */
+import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+
+const REVENUE: SparklinePoint[] = [
+  { label: "июл", value: 2_840_000 },
+  { label: "авг", value: 3_120_000 },
+  { label: "сен", value: 2_960_000 },
+  { label: "окт", value: 3_410_000 },
+];
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+export default function SparklineStatesExample() {
+  return (
+    <div>
+      <div>
+        <Sparkline data={REVENUE} label="Выручка" formatValue={formatRubles} />
+        <Typography as="span" variant="caption" tone="muted">
+          data
+        </Typography>
+      </div>
+      <div>
+        <Sparkline data={[]} label="Выручка" loading />
+        <Typography as="span" variant="caption" tone="muted">
+          loading
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/dist/skill/reference/components/sparkline/examples/variants.tsx

@@ -0,0 +1,29 @@
+/** The same week as a line and as bars from zero — `variant`. */
+import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+
+const ORDERS: SparklinePoint[] = [
+  { label: "2 окт", value: 38 },
+  { label: "3 окт", value: 44 },
+  { label: "4 окт", value: 41 },
+  { label: "5 окт", value: 29 },
+  { label: "6 окт", value: 33 },
+  { label: "7 окт", value: 47 },
+  { label: "8 окт", value: 52 },
+];
+
+const VARIANTS = ["line", "bars"] as const;
+
+export default function SparklineVariantsExample() {
+  return (
+    <div>
+      {VARIANTS.map((variant) => (
+        <div key={variant}>
+          <Sparkline data={ORDERS} label="Заказы за неделю" variant={variant} />
+          <Typography as="span" variant="caption" tone="muted">
+            {variant}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,114 @@
+# Spinner
+
+**Category:** status
+**Kind:** primitive
+
+> An indeterminate loading indicator: the kit ring with the share unknown — a quarter arc turning on a faint track while a request runs.
+
+## When to use
+- A region is busy and has no content shape to hold (a running job, a request with no layout yet).
+- A status line next to text («Загружаем счета…»).
+- Inside a kit component that shows loading (it is the kit's one spinner).
+
+## When not to use
+- The progress is known (upload, steps, quota) → use [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- A named process on the data scale whose share is not known yet (an import card) → [ProgressCircle](../progress-circle/COMPONENT.md) `value={null}`: a `progressbar` with your name that can show the share once it arrives.
+- A button waiting for its request → set `loading` on [Button](../button/COMPONENT.md); it places the spinner itself.
+- Content of a known shape is loading (a list, a card, a form) → [Skeleton](../skeleton/COMPONENT.md) of that shape inside [Crossfade](../crossfade/COMPONENT.md).
+- A table loading its rows → `loading` on [DataTable](../data-table/COMPONENT.md) (skeleton rows keep the layout).
+- A whole page failed to load → [EmptyPage](../empty-page/COMPONENT.md) with a retry action.
+
+## Import
+```tsx
+import { Spinner } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Spinner          <span role="status">; size and tone
+├─ ring          the kit ring (internal/ring, value null): a quarter arc on a faint track (aria-hidden)
+└─ label         visually hidden labels.loading
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Spinner
+`ref` → `HTMLSpanElement`. The kit ring with the share unknown — a quarter arc turning on a faint track, at the line weight — inside a `role="status"` region with text for screen readers.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | — | Explicit size on the icon scale: 14 · 16 · 20 · 24 · 32. Without it the spinner follows its host like `Icon`: the host's `--prime-icon-size`, else the nearest control tier, else 16. |
+| `tone` | `"default" \| "secondary" \| "muted" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Ring color; `default` inherits `currentColor`. |
+| `labels` | `Partial<SpinnerLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className`, `aria-hidden`, `data-*` and the other span attributes. |
+
+## Variants
+
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `default` | the color of the surrounding text | inside text, buttons, rows | yes |
+| `secondary` | `text-secondary` | a status line in secondary text | |
+| `muted` | `text-muted` | a loading region on a card | |
+| `accent` | `accent-text` | the one loading spot that should draw the eye | |
+| `success` · `warning` · `danger` | the status `*-text` color | loading inside a status block of that tone | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 14px | dense rows, inside `xs` controls | |
+| `s` | 16px | next to `body-s` text | |
+| `m` | 20px | standalone next to `body-m` text | |
+| `l` | 24px | a loading card or panel | |
+| `xl` | 32px | a loading page region | |
+| — (omitted) | the host's icon size, else the control tier (16 on `m`) | inside a kit control or next to its text | yes |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| spinning | mounted | the ring turns at a constant speed (`--prime-motion-loop × 3` per turn, linear) |
+| reduced motion | `prefers-reduced-motion` | the ring keeps turning, twice as slow (`--prime-motion-loop × 6` per turn) and linear: a loading cue is information, so the token is not zeroed |
+| size / tone | `size`, `tone` | `data-size` (the explicit size, else the host control tier, else `m`), `data-tone` (only for a non-default tone) |
+
+## Layout & spacing
+- The ring fills the icon box: a stroke of two border widths (the line weight, an icon's stroke) — a round-capped quarter arc in the tone color over an 18% track of it; `inline-flex`, `vertical-align: middle`. The svg turns as a whole (a compositor transform).
+- Next to text: one row, `align-items: center`, gap = the tier gap (`--prime-control-m-gap`).
+- In a loading region: centered in the region with its explanation under it, gap `--prime-space-3`.
+- Render the real layout around it; never a full-screen overlay of spinners.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- `role="status"` with a visually hidden `labels.loading`, so screen readers learn that something is loading.
+- When the host already announces it is busy (`aria-busy` on a button or a region), pass `aria-hidden="true"`.
+- Under `prefers-reduced-motion` the ring keeps turning, slower and linear, so the loading cue stays readable.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `loading` | `"Загрузка"` | Visually hidden text inside `role="status"`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A loading status next to a short explanation; the spinner takes the text color. |
+| [variants.tsx](examples/variants.tsx) | Every ring color; `default` follows the surrounding text — `tone`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size on the icon scale, 14 to 32 px — `size`. |
+| [loading-region.tsx](examples/loading-region.tsx) | A card that loads its content: the region says it is busy and the spinner stays hidden from screen readers — `aria-hidden`. |
+
+## Mistakes
+- A hand-made spinner (`@keyframes spin` on a bordered circle) → use `Spinner`.
+- A `Spinner` next to a `loading` Button → the button already shows one.
+- Both `aria-busy` on the region and a spoken spinner inside → add `aria-hidden="true"` to the spinner.
+- A spinner for a known progress → ProgressBar / ProgressCircle.
+
+## Related
+- **Built from:** `internal/ring` (the ring drawing, shared with ProgressCircle and the circle Button)
+- **See also:** [Skeleton](../skeleton/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [ProgressCircle](../progress-circle/COMPONENT.md), [Button](../button/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)

package/dist/skill/reference/components/spinner/examples/examples.module.css

@@ -0,0 +1,20 @@
+/* Layout of the Spinner scenarios: semantic tokens only. */
+
+/* overview.tsx: spinner and text in one line, icon → text gap of the m tier. */
+.status {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--prime-control-m-gap);
+}
+
+/* loading-region.tsx: the Card's size and its centered body. */
+.region {
+  width: min(100%, var(--prime-modal-width-s));
+  min-height: calc(var(--prime-space-24) * 2);
+}
+
+.loading {
+  align-items: center;
+  justify-content: center;
+  gap: var(--prime-space-3);
+}

package/dist/skill/reference/components/spinner/examples/loading-region.tsx

@@ -0,0 +1,22 @@
+/** A card that loads its content: the region says it is busy and the spinner stays hidden from screen readers — `aria-hidden`. */
+import { Card, Spinner, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function SpinnerLoadingRegionExample() {
+  return (
+    <Card.Root
+      role="region"
+      aria-busy="true"
+      aria-label="Выручка за неделю"
+      className={styles.region}
+    >
+      <Card.Body className={styles.loading}>
+        <Spinner size="l" tone="muted" aria-hidden="true" />
+        <Typography as="p" variant="body-s" tone="secondary">
+          Считаем выручку за неделю
+        </Typography>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/spinner/examples/overview.tsx

@@ -0,0 +1,15 @@
+/** A loading status next to a short explanation; the spinner takes the text color. */
+import { Spinner, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function SpinnerOverviewExample() {
+  return (
+    <div className={styles.status}>
+      <Spinner labels={{ loading: "Загружаем счета" }} />
+      <Typography as="span" variant="body-m" tone="secondary">
+        Загружаем счета за октябрь…
+      </Typography>
+    </div>
+  );
+}