prime-ui-kit 0.14.0 → 0.16.0

package/src/components/smart-filter/examples/ranges.tsx

@@ -1,5 +1,8 @@
-/** Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip — `kind`, `formatValue`, `matchesSmartFilter`. */
+/** Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `matchesSmartFilter`, `isSmartFilterRange`. */
 import {
+  Card,
+  formatDateValue,
+  isSmartFilterRange,
   matchesSmartFilter,
   SmartFilter,
   type SmartFilterField,
@@ -59,6 +62,23 @@ const DEALS = [
 
 const INITIAL: SmartFilterValue = { amount: { from: 50_000, to: 500_000 } };
 
+const asParam = (bound: number | Date) =>
+  bound instanceof Date ? formatDateValue(bound) : String(bound);
+
+/** The query a server gets: a range becomes `key_from` / `key_to`, a selection its included values. */
+function toQuery(value: SmartFilterValue) {
+  const params = new URLSearchParams();
+  for (const [key, entry] of Object.entries(value)) {
+    if (isSmartFilterRange(entry)) {
+      if (entry.from !== null) params.set(`${key}_from`, asParam(entry.from));
+      if (entry.to !== null) params.set(`${key}_to`, asParam(entry.to));
+    } else if (entry.include.length > 0) {
+      params.set(key, entry.include.join(","));
+    }
+  }
+  return params.toString();
+}
+
 export default function SmartFilterRangesExample() {
   const [value, setValue] = React.useState<SmartFilterValue>(INITIAL);
   const rows = DEALS.filter(
@@ -74,16 +94,31 @@ export default function SmartFilterRangesExample() {
         <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)}
+      <Card.Root variant="list">
+        <Card.Header>
+          <Card.Title>Сделки</Card.Title>
+          <Typography as="span" variant="caption" tone="muted">
+            {rows.length} из {DEALS.length}
           </Typography>
-        </div>
-      ))}
+        </Card.Header>
+        <Card.List>
+          {rows.map((deal) => (
+            <Card.ListItem key={deal.id}>
+              <span 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>
+              </span>
+            </Card.ListItem>
+          ))}
+        </Card.List>
+      </Card.Root>
+      <Typography as="span" variant="code" tone="secondary">
+        {`GET /deals?${toQuery(value)}`}
+      </Typography>
     </div>
   );
 }

package/src/components/smart-filter/examples/sizes.tsx

@@ -1,8 +1,6 @@
 /** 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",
@@ -16,9 +14,9 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function SmartFilterSizesExample() {
   return (
-    <div className={styles.sizes}>
+    <div>
       {SIZES.map((size) => (
-        <div key={size} className={styles.size}>
+        <div key={size}>
           <SmartFilter.Root fields={FIELDS} size={size} defaultValue={ONLY_GET}>
             <SmartFilter.Toolbar />
             <SmartFilter.Chips />

package/src/components/sparkline/COMPONENT.md

@@ -57,13 +57,13 @@ compact:               the plot alone (no head, no value row); loading — the p
 | `layout` | `"default" \| "compact"` | `"default"` | `default` — the headline over an 80 px plot; `compact` — the plot alone at an `xs` control height with the dot at rest, for a DataTable cell; the scrubbed point shows in the tooltip and `aria-valuetext`. |
 | `change` | `"previous" \| "first" \| "none"` | `"previous"` | What the change badge of a shown point compares it with: `previous` — the point before it; `first` — the first point with a value (the change over the period); `none` — no badge. |
 | `summary` | `"latest" \| "sum" \| "average"` | `"latest"` | What the headline shows at rest: `latest` — the latest point (or `highlight`), for a level (MRR, conversion); `sum` — the period total, for a flow (revenue per day); `average` — the period mean. |
-| `highlight` | `number` | `the latest point with a value` | Index of the point at rest with `summary="latest"` (the current month): the headline returns to it; `bars` draw the other bars quieter. Not allowed with `sum` / `average`. |
+| `highlight` | `number` | the latest point with a value | Index of the point at rest with `summary="latest"` (the current month): the headline returns to it; `bars` draw the other bars quieter. Not allowed with `sum` / `average`. |
 | `compareTo` | `number` | — | The same summary for the previous period («прошлые 30 дней»): the badge at rest compares the headline with it. Without it a `sum` / `average` headline shows no change at rest. |
 | `min` | `number` | — | The value axis reaches down to at least this value: a floor of zero, or one scale for several sparklines (a table column). Data below widens the scale, never gets cut. |
 | `max` | `number` | — | The value axis reaches up to at least this value; data above widens the scale. |
 | `reference` | `number` | — | A dashed horizontal line at this value — a plan, a target, an average; the scale holds it and the chart is described by `labels.reference`. |
 | `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, the tooltip, the reference description and the spoken point («312 400 ₽»). |
+| `formatValue` | `(value: number) => string` | Russian digit groups | Display of a value in the headline, the tooltip, the reference description 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. |
 
@@ -139,6 +139,8 @@ Put it in a `Card` for a dashboard tile.
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `←` · `→` · `↓` · `↑` | Previous or next point: `←` / `↓` back, `→` / `↑` forward, as on a slider. |
@@ -147,6 +149,8 @@ Put it in a `Card` for a dashboard tile.
 | `Escape` | Hides the tooltip and returns the headline to rest. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The plot is `role="slider"` named by `label`; `aria-valuetext` speaks the point («8 окт: 312 400 ₽», `labels.point`); a point with no data speaks `labels.empty` («8 окт: Нет данных»). At rest with `sum` / `average` it speaks the period and the summary («9 сен – 8 окт: 8 914 000 ₽»). With `reference` the slider is described by `labels.reference` («Ориентир: 3%», `aria-describedby`). The headline follows 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.
@@ -173,7 +177,7 @@ Put it in a `Card` for a dashboard tile.
 | [compact.tsx](examples/compact.tsx) | Revenue by month per client in a list: the plot alone at a row's height with the dot on the current month, scrubbing shows the month in a tooltip, the label is the chart's accessible name — `layout`, `label`. |
 | [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`. |
 | [curve.tsx](examples/curve.tsx) | The same month of active users as a smooth curve, straight segments and steps — `curve`. |
-| [reference.tsx](examples/reference.tsx) | Checkout conversion against its plan: a dashed reference line, the scale from zero and the change over the whole period — `reference`, `min`, `change`. |
+| [reference.tsx](examples/reference.tsx) | Checkout conversion against its plan: a dashed reference line, the scale from zero to 5% and the change over the whole period — `reference`, `min`, `max`, `change`. |
 | [gaps.tsx](examples/gaps.tsx) | Daily API requests with days the collector was down: the line breaks over a missing day and the headline says there is no data — `data`, `labels`. |
 | [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`, `summary`. |
 
@@ -190,5 +194,5 @@ Put it in a `Card` for a dashboard tile.
 - A full Sparkline squeezed into a table cell, or its headline hidden with CSS → `layout="compact"`.
 
 ## Related
-- **Built from:** [Badge](../badge/COMPONENT.md) (change), [Skeleton](../skeleton/COMPONENT.md) (loading), `Icon` (trend arrow), `ChartTooltip` (the chart tooltip shared with ChartFrame)
+- **Built from:** [Badge](../badge/COMPONENT.md) (change), [Skeleton](../skeleton/COMPONENT.md) (loading), `Icon` (trend arrow), `ChartTooltip` (the chart tooltip shared with ChartFrame), [ScrollContainer](../scroll-container/COMPONENT.md) (the tooltip's floating panel)
 - **See also:** [ChartFrame](../chart-frame/COMPONENT.md), [DataTable](../data-table/COMPONENT.md) (a compact Sparkline per row), [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -2,7 +2,7 @@
 
 /* A dashboard card's width: the chart takes the card width. */
 .card {
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 /* compact: a client list, the name and its trend on one line per client. */

package/src/components/sparkline/examples/reference.tsx

@@ -1,4 +1,4 @@
-/** Checkout conversion against its plan: a dashed reference line, the scale from zero and the change over the whole period — `reference`, `min`, `change`. */
+/** Checkout conversion against its plan: a dashed reference line, the scale from zero to 5% and the change over the whole period — `reference`, `min`, `max`, `change`. */
 import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -27,6 +27,7 @@ export default function SparklineReferenceExample() {
           label="Конверсия оформления заказа"
           reference={PLAN}
           min={0}
+          max={5}
           change="first"
           formatValue={formatPercent}
           labels={{ reference: "План: {value}" }}

package/src/components/sparkline/examples/signed-bars.tsx

@@ -14,8 +14,8 @@ const PROFIT: SparklinePoint[] = [
   { label: "авг", value: 280_000 },
   { label: "сен", value: 470_000 },
   { label: "окт", value: 390_000 },
-  { label: "ноя", value: 0 },
-  { label: "дек", value: 0 },
+  { label: "ноя", value: null },
+  { label: "дек", value: null },
 ];
 
 /** October is the current month: November and December are still empty. */

package/src/components/spinner/COMPONENT.md

@@ -6,7 +6,7 @@
 > 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).
+- Something is busy and has no content shape to hold (a running job on a status line, 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).
 
@@ -51,7 +51,7 @@ Spinner          <span role="status">; size and tone
 |---|---|---|---|
 | `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 | |
+| `muted` | `text-muted` | a quiet status line under content | |
 | `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 | |
 
@@ -61,29 +61,34 @@ Spinner          <span role="status">; size and tone
 | `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 | |
+| `l` | 24px | next to `body-l` or a title | |
+| `xl` | 32px | a running job with nothing to show yet, next to its explanation | |
 | — (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 |
 |---|---|---|
+| appearing | mounted | fades in over `fast` (`internal/enterMotion`), so a spinner that comes and goes never blinks |
 | 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`.
+- Next to text: one row, `align-items: center`, 8px apart (the `m` tier gap).
+- A region whose content has a shape (a card, a list) shows a `Skeleton` of that shape, not a spinner.
 - Render the real layout around it; never a full-screen overlay of spinners.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `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.
@@ -98,17 +103,18 @@ No keyboard interaction.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | A loading status next to a short explanation; the spinner takes the text color. |
+| [overview.tsx](examples/overview.tsx) | A loading status next to a short explanation; the spinner takes the text color and names the wait — `labels`. |
 | [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.
+- A spinner in a card or a list while its content loads → a `Skeleton` in the content's shape.
+- Fading a conditional spinner in by hand → the spinner fades itself in.
 
 ## Related
-- **Built from:** `internal/ring` (the ring drawing, shared with ProgressCircle and the circle Button)
+- **Built from:** `internal/ring` (the ring drawing, shared with ProgressCircle and the circle Button), `internal/enterMotion` (the fade-in), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **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/src/components/spinner/examples/examples.module.css

@@ -1,20 +1,8 @@
 /* Layout of the Spinner scenarios: semantic tokens only. */
 
-/* overview.tsx: spinner and text in one line, icon → text gap of the m tier. */
+/* overview.tsx: spinner and text in one line, 8px apart (the m tier gap). */
 .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);
+  gap: var(--prime-space-2);
 }

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

@@ -1,4 +1,4 @@
-/** A loading status next to a short explanation; the spinner takes the text color. */
+/** A loading status next to a short explanation; the spinner takes the text color and names the wait — `labels`. */
 import { Spinner, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/src/components/stepper/COMPONENT.md

@@ -3,7 +3,7 @@
 **Category:** navigation
 **Kind:** navigation
 
-> Steps of a multi-step process with pending, active, completed and danger statuses.
+> Steps of a multi-step process with pending, current, completed and danger statuses.
 
 ## When to use
 - Checkout, onboarding and setup wizards where the user moves through ordered steps.
@@ -23,13 +23,12 @@ import { Stepper } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Stepper.Root                 <ol>; current step; chevrons between horizontal items
+Stepper.Root                 <ol>; current step; chevrons between horizontal items, at the end of vertical rows with `arrows`
 └─ Stepper.Item              <li> with a <button>; a direct child of Root (index = order)
-   ├─ Stepper.Indicator      circle: number, check when completed, or custom content
-   ├─ Stepper.Content        text column
-   │  ├─ Stepper.Title       step name
-   │  └─ Stepper.Description muted support text
-   └─ Stepper.Arrow          trailing chevron for vertical rows that open a page or panel
+   ├─ Stepper.Indicator      circle: number, check when completed, danger mark, or custom content
+   └─ Stepper.Content        text column
+      ├─ Stepper.Title       step name
+      └─ Stepper.Description muted support text
 ```
 
 ## API
@@ -37,34 +36,36 @@ Stepper.Root                 <ol>; current step; chevrons between horizontal ite
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Stepper.Root
-`ref` → `HTMLOListElement`. `<ol>` of items; owns the current step, numbers the items and adds chevrons between horizontal ones.
+`ref` → `HTMLOListElement`. `<ol>` of items; owns the current step, numbers the items and draws the chevrons between horizontal ones and, with `arrows`, at the end of vertical rows.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `number` | — | Current step, 0-based (controlled). |
 | `defaultValue` | `number` | `0` | Initial step (uncontrolled). |
 | `onValueChange` | `(index: number) => void` | — | Called with the index of the clicked item. |
-| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Column of rows, or a row with chevrons that stacks below a 480px container. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Indicator 20 · 24 · 28 · 32 · 36, title in the control text of the tier. |
+| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Column of rows, or one row with chevrons (steps shrink and wrap their titles) that stacks below a 480px container. |
+| `arrows` | `boolean` | `false` | Every vertical row ends with a chevron: each step opens a page or panel. Horizontal steps already have their chevrons. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Indicator 20 · 24 · 28 · 32 · 36, title in the control text of the tier. Without it the tier of its host, else `m`. |
+| `labels` | `Partial<StepperLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | `Stepper.Item`s as direct children (an array from `map` is fine). |
 | `…rest` | `Omit<OlHTMLAttributes<HTMLOListElement>, "defaultValue" \| "onChange">` | — | `aria-label`, `className` and the other list attributes. |
 
 ### Stepper.Item
-`ref` → `HTMLButtonElement`. One step: an `<li>` with a `<button>` (and, between horizontal steps, the decorative chevron in front of it); `aria-current="step"` when active.
+`ref` → `HTMLButtonElement`. One step: an `<li>` with a `<button>` (and, between horizontal steps, the decorative chevron in front of it); `aria-current="step"` on the current one; a completed or danger step adds its status to its name.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `status` | `"pending" \| "active" \| "completed" \| "danger"` | — | Overrides the status derived from `value` (before → `completed`, equal → `active`, after → `pending`). |
+| `status` | `"pending" \| "current" \| "completed" \| "danger"` | — | Overrides the status derived from `value` (before → `completed`, equal → `current`, after → `pending`). |
 | `disabled` | `boolean` | — | The item cannot be selected. |
-| `children` | `ReactNode` | — | `Stepper.Indicator`, `Stepper.Content`, optional `Stepper.Arrow`. |
+| `children` | `ReactNode` | — | `Stepper.Indicator` and `Stepper.Content`. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">` | — | `onClick` (runs first; `preventDefault()` stops the selection), `className` and the other button attributes. |
 
 ### Stepper.Indicator
-`ref` → `HTMLSpanElement`. The circle (`aria-hidden`): the item number, or a check when completed.
+`ref` → `HTMLSpanElement`. The circle (`aria-hidden`): the item number, a check when completed, the danger mark on a danger step; a status change cross-fades the glyph.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — | Replaces the default content, e.g. `<Icon name="status.danger" />`. |
+| `children` | `ReactNode` | — | Replaces the default content, e.g. `<Icon name="status.info" />`. |
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
 
 ### Stepper.Content
@@ -81,20 +82,18 @@ Stepper.Root                 <ol>; current step; chevrons between horizontal ite
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
 
-### Stepper.Arrow
-`ref` → `SVGSVGElement`. Trailing chevron (`aria-hidden`) for vertical items that open a page or panel.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `…rest` | `Omit<SVGAttributes<SVGSVGElement>, "children">` | — | `className` and the other svg attributes. |
-
 ## Variants
 
 ### orientation
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `vertical` | full-width rows (indicator · text · optional arrow); hover `fill-subtle`, active row on `fill-subtle`, danger row on `danger-soft` | side columns of wizards, step lists with descriptions | yes |
-| `horizontal` | items in a row with placeholder-colored chevrons between them; hover → primary text; below a 30rem container the items stack one per row and chevrons hide | checkout headers with short step names | |
+| `vertical` | full-width rows (indicator · text · the chevron with `arrows`); hover `fill-subtle`, the current row on `fill-subtle`, danger row on `danger-soft` | side columns of wizards, step lists with descriptions | yes |
+| `horizontal` | one row of items with placeholder-colored chevrons between them; a cramped step wraps its title, the row never wraps; hover → primary text; below a 30rem container the items stack one per row and chevrons hide | checkout headers with short step names | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `arrows` | every vertical row ends with a placeholder-colored chevron (`aria-hidden`); horizontal steps keep their separators only | each vertical step opens a page or panel | off |
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -111,66 +110,76 @@ Title uses the control text of the tier, Description the hint text of the tier.
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `pending` | `fill-muted` circle with secondary number, secondary text | steps after the current one | derived |
-| `active` | accent circle with a `space-1` `accent-soft` halo, primary text | the current step | derived |
-| `completed` | `accent-soft` circle with an accent check (`Icon action.check`), primary text | finished steps | derived |
-| `danger` | horizontal: `danger-soft` circle; vertical: solid danger circle on a `danger-soft` row; danger text | a step that needs attention | |
+| `current` | accent circle with a `space-1` `accent-soft` halo, primary text | the current step | derived |
+| `completed` | `accent-soft` circle with an accent check (`Icon action.check`), primary text; `labels.completed` added to the name | finished steps | derived |
+| `danger` | the danger mark (`Icon status.danger`) — horizontal: on a `danger-soft` circle; vertical: on a solid danger circle in a `danger-soft` row; danger text; `labels.danger` added to the name | a step that needs attention | |
 
-Derive statuses from `value`; set `status="danger"` only on the failing step with an indicator that is not a number (`<Icon name="status.danger" />`); disable steps the user cannot reach yet. Avoid `Stepper.Arrow` in horizontal mode (the root adds chevrons) and several `active` steps.
+Derive statuses from `value`; set `status="danger"` only on the failing step; disable steps the user cannot reach yet. Never mark several steps `current`.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| status | `value` or `status` | `data-status` on the button and the indicator; `aria-current="step"` on the active item |
+| status | `value` or `status` | `data-status` on the button and the indicator; `aria-current="step"` on the current item; a visually hidden status after the name of a completed or danger step |
 | disabled | `disabled` | native `disabled`, `data-disabled="true"`, `text-disabled`, muted indicator without halo |
-| hover / active | pointer | vertical `fill-subtle` / `fill-subtle-active`; horizontal text → primary; press scale |
+| hover / press | pointer | vertical `fill-subtle` / `fill-subtle-active`; horizontal text → primary; press scale |
 | focus-visible | keyboard | outer focus ring |
 
 Root attributes: `data-orientation`, `data-size`. Uncontrolled (`defaultValue`) clicks still select items.
 
-Motion: a status change moves the indicator's fill, color and halo over `base`; the row fill and text color change over `fast`; press scales the step to `--prime-motion-press-scale`. Under reduced motion the indicator changes at once.
+Motion: a status change fades the indicator's fill, color and halo over `base` and cross-fades its glyph (number ⇄ check ⇄ danger mark); the row fill and text color change over `fast`; press scales the step to `--prime-motion-press-scale` (the kit press). Under reduced motion the press does not scale and the glyph only fades.
 
 ## Layout & spacing
 - The root is a size container (`inline-size: 100%`): give it a definite width, a shrink-wrapped parent collapses it.
-- Wizard: stepper column and form side by side with `gap: var(--prime-space-8)`, stacking on narrow widths.
-- Vertical rows are separated by `var(--prime-space-1)` (`var(--prime-space-2)` at `size="xl"`); the same value is the row gap of a wrapping horizontal stepper.
+- Wizard: stepper column and form side by side with the page gap between groups, stacking on narrow widths.
+- Vertical rows are separated by `var(--prime-space-1)` (`var(--prime-space-2)` at `size="xl"`); the same value is the row gap of a horizontal stepper stacked in a narrow container.
+- On a coarse pointer a step is at least the touch target high.
 - Horizontal steps and their chevrons sit 8 · 12 · 16 · 20 · 24 apart (xs → xl); below a 30rem (480px) container each step takes its own full-width row with the vertical row padding.
 - Indicator → text gap 8 (xs, s) · 12 (m, l) · 16 (xl); titles are medium weight and wrap long words.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus between items; a disabled one is skipped. |
 | `Enter` · `Space` | Selects the item. |
 
 ### ARIA
-- Semantic `<ol>`; each item is a `<button>` inside an `<li>`; the active one has `aria-current="step"`.
-- Separators, indicator and arrow are `aria-hidden`; the name comes from Title (and Description).
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- Semantic `<ol>`; each item is a `<button>` inside an `<li>`; the current one has `aria-current="step"`.
+- Separators, indicator and arrows are `aria-hidden`; the name comes from Title and Description, and a completed or danger step adds `labels.completed` or `labels.danger` to it.
 - Give the `<ol>` an `aria-label` when there are several steppers on a page.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-No `labels`.
+| Key | Default | Used for |
+|---|---|---|
+| `completed` | `"пройден"` | Spoken after the name of a completed step; the check is only seen. |
+| `danger` | `"требует внимания"` | Spoken after the name of a step that needs attention; its colour and glyph are only seen. |
 
 ## Examples
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Steps of a process: done ones get a check, the current one is highlighted — `defaultValue`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: indicator 20 to 36 px, title in the control text of the tier — `size`. |
-| [states.tsx](examples/states.tsx) | Statuses that come from the server, a failed step with its own indicator and a locked step — `status`, `disabled`. |
-| [with-icon.tsx](examples/with-icon.tsx) | Vertical rows that open a page or panel end with a chevron — `Stepper.Arrow`. |
+| [states.tsx](examples/states.tsx) | Statuses that come from the server, a failed step marked by a glyph and a locked step — `status`, `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | Vertical rows that open a page or panel end with a chevron — `arrows`. |
 | [orientation.tsx](examples/orientation.tsx) | A row of steps with chevrons between them above the content, and a column for a side panel — `orientation`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the current step: Back and Next move it, far steps stay locked until reached — `value`, `onValueChange`. |
-| [narrow.tsx](examples/narrow.tsx) | A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons. |
+| [narrow.tsx](examples/narrow.tsx) | A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons — `orientation`. |
 
 ## Mistakes
 - Wrapping `Stepper.Item` in another component or element → it must be a direct child of Root (it throws otherwise).
 - 1-based `value` → steps are 0-based.
 - Adding separators by hand in horizontal mode → every step already draws its chevron.
-- `status="error"` → the status is `danger`; give it an indicator that is not a number so it does not read by color only.
+- `status="error"` → the status is `danger`; its indicator shows the danger mark and its name says it, so it never reads by color only.
+- A chevron added by hand at the end of a vertical row → set `arrows` on the root.
+- `status="active"` → the step a person is on is `current`.
 
 ## Related
-- **Built from:** Icon (`action.check`, `nav.chevronRight`)
+- **Built from:** Icon (`action.check`, `status.danger`, `nav.chevronRight`), `internal/glyphSwap` (the indicator glyph), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Tabs](../tabs/COMPONENT.md), [Pagination](../pagination/COMPONENT.md), [Timeline](../timeline/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md)

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

@@ -1,10 +1,5 @@
 /* Layout of the Stepper scenarios: semantic tokens only. */
 
-/* The stepper measures its own width (container query), so its wrapper needs one. */
-.wide {
-  width: 100%;
-}
-
 /* A side column for a vertical stepper (288px), with anything under it a group gap away. */
 .column {
   display: grid;
@@ -14,7 +9,7 @@
 
 /* A phone-width container (320px). */
 .narrow {
-  width: min(100%, calc(var(--prime-drawer-width-s) - var(--prime-space-10)));
+  width: min(100%, var(--prime-layout-min-width));
 }
 
 /* Back / Next under the stepper. */

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

@@ -1,4 +1,4 @@
-/** A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons. */
+/** A horizontal stepper in a phone-width container stacks one step per row and hides the chevrons — `orientation`. */
 import { Stepper } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

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

@@ -1,19 +1,14 @@
 /** Every size tier: indicator 20 to 36 px, title in the control text of the tier — `size`. */
 import { Stepper, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 const STEPS = ["Аккаунт", "Команда", "Готово"];
 
 export default function StepperSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <div key={size} className={styles.wide}>
-          <Typography as="span" variant="caption" tone="muted">
-            {size}
-          </Typography>
+        <div key={size}>
           <Stepper.Root orientation="horizontal" size={size} defaultValue={1}>
             {STEPS.map((title) => (
               <Stepper.Item key={title}>
@@ -24,8 +19,11 @@ export default function StepperSizesExample() {
               </Stepper.Item>
             ))}
           </Stepper.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
         </div>
       ))}
-    </>
+    </div>
   );
 }