prime-ui-kit 0.15.0 → 0.17.0

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>
   );
 }

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

@@ -1,49 +1,50 @@
-/** Statuses that come from the server, a failed step with its own indicator and a locked step — `status`, `disabled`. */
-import { Icon, Stepper } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** Statuses that come from the server, a failed step marked by a glyph and a locked step — `status`, `disabled`. */
+import { Stepper, Typography } from "prime-ui-kit";
 
 export default function StepperStatesExample() {
   return (
-    <div className={styles.column}>
-      <Stepper.Root>
-        <Stepper.Item status="completed">
-          <Stepper.Indicator />
-          <Stepper.Content>
-            <Stepper.Title>Оплата прошла</Stepper.Title>
-            <Stepper.Description>12 400 ₽ списано с карты</Stepper.Description>
-          </Stepper.Content>
-        </Stepper.Item>
-        <Stepper.Item status="danger">
-          <Stepper.Indicator>
-            <Icon name="status.danger" />
-          </Stepper.Indicator>
-          <Stepper.Content>
-            <Stepper.Title>Ошибка доставки</Stepper.Title>
-            <Stepper.Description>Проверьте адрес получателя</Stepper.Description>
-          </Stepper.Content>
-        </Stepper.Item>
-        <Stepper.Item status="active">
-          <Stepper.Indicator />
-          <Stepper.Content>
-            <Stepper.Title>Подтверждение</Stepper.Title>
-            <Stepper.Description>Ждём ответа склада</Stepper.Description>
-          </Stepper.Content>
-        </Stepper.Item>
-        <Stepper.Item status="pending">
-          <Stepper.Indicator />
-          <Stepper.Content>
-            <Stepper.Title>Получение</Stepper.Title>
-          </Stepper.Content>
-        </Stepper.Item>
-        <Stepper.Item status="pending" disabled>
-          <Stepper.Indicator />
-          <Stepper.Content>
-            <Stepper.Title>Отзыв</Stepper.Title>
-            <Stepper.Description>Откроется после получения</Stepper.Description>
-          </Stepper.Content>
-        </Stepper.Item>
-      </Stepper.Root>
+    <div>
+      <div>
+        <Stepper.Root>
+          <Stepper.Item status="completed">
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>Оплата прошла</Stepper.Title>
+              <Stepper.Description>12 400 ₽ списано с карты</Stepper.Description>
+            </Stepper.Content>
+          </Stepper.Item>
+          <Stepper.Item status="danger">
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>Ошибка доставки</Stepper.Title>
+              <Stepper.Description>Проверьте адрес получателя</Stepper.Description>
+            </Stepper.Content>
+          </Stepper.Item>
+          <Stepper.Item status="current">
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>Подтверждение</Stepper.Title>
+              <Stepper.Description>Ждём ответа склада</Stepper.Description>
+            </Stepper.Content>
+          </Stepper.Item>
+          <Stepper.Item status="pending">
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>Получение</Stepper.Title>
+            </Stepper.Content>
+          </Stepper.Item>
+          <Stepper.Item status="pending" disabled>
+            <Stepper.Indicator />
+            <Stepper.Content>
+              <Stepper.Title>Отзыв</Stepper.Title>
+              <Stepper.Description>Откроется после получения</Stepper.Description>
+            </Stepper.Content>
+          </Stepper.Item>
+        </Stepper.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          completed · danger · current · pending · disabled
+        </Typography>
+      </div>
     </div>
   );
 }

package/src/components/stepper/examples/with-icon.tsx

@@ -1,7 +1,5 @@
-/** Vertical rows that open a page or panel end with a chevron — `Stepper.Arrow`. */
-import { Stepper } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** Vertical rows that open a page or panel end with a chevron — `arrows`. */
+import { Stepper, Typography } from "prime-ui-kit";
 
 const STEPS = [
   { title: "Корзина", description: "3 товара" },
@@ -11,19 +9,23 @@ const STEPS = [
 
 export default function StepperWithIconExample() {
   return (
-    <div className={styles.column}>
-      <Stepper.Root defaultValue={1}>
-        {STEPS.map((step) => (
-          <Stepper.Item key={step.title}>
-            <Stepper.Indicator />
-            <Stepper.Content>
-              <Stepper.Title>{step.title}</Stepper.Title>
-              <Stepper.Description>{step.description}</Stepper.Description>
-            </Stepper.Content>
-            <Stepper.Arrow />
-          </Stepper.Item>
-        ))}
-      </Stepper.Root>
+    <div>
+      <div>
+        <Stepper.Root defaultValue={1} arrows>
+          {STEPS.map((step) => (
+            <Stepper.Item key={step.title}>
+              <Stepper.Indicator />
+              <Stepper.Content>
+                <Stepper.Title>{step.title}</Stepper.Title>
+                <Stepper.Description>{step.description}</Stepper.Description>
+              </Stepper.Content>
+            </Stepper.Item>
+          ))}
+        </Stepper.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          arrows
+        </Typography>
+      </div>
     </div>
   );
 }

package/src/components/switch/COMPONENT.md

@@ -42,7 +42,9 @@ Switch.Root          field grid; ref and input props go to the native input (rol
 | `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
 | `onCheckedChange` | `(checked: boolean) => void \| Promise<void>` | — | Called with the new state on every toggle. Return the save's promise: the thumb waits with a spinner; a controlled owner sets `checked` before resolving; on reject the thumb goes back (say why with `error`). |
 | `loading` | `boolean` | `false` | Saving, for an owner that tracks the request itself: a spinner in the thumb, `aria-busy` on the input, presses do nothing. A promise from `onCheckedChange` does the same on its own. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the track (24×16 … 44×24), the text and the gap. Without it the tier of its host (a form, a panel), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the track (24×16 … 44×24), the text and the gap. Without it the tier of its host (a form, a panel), else `m`. |
+| `optional` | `boolean` | `false` | Muted `labels.optional` after the label text; the field may stay off. |
+| `labels` | `Partial<SwitchLabels>` | — | Built-in strings, see Labels. |
 | `hint` | `ReactNode` | — | Help text under the label text. Hidden while `error` is shown. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger ring on the off track and `aria-invalid`. A non-empty `error` implies it. |
@@ -52,11 +54,15 @@ Switch.Root          field grid; ref and input props go to the native input (rol
 | `aria-describedby` | `string` | — | Merged before the hint/error ids. |
 | `children` | `ReactNode` | — | `Switch.Label`. Without it only the track renders — name it with `aria-label` or `aria-labelledby`. |
 | `className` | `string` | — | Class on the field `<div>`. |
-| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange">` | — | `name`, `value`, `required`, `aria-label`, `aria-labelledby`… on the native input. |
+| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange">` | — | `name`, `value`, `required` (also a red `*` after the text), `aria-label`, `aria-labelledby`… on the native input. |
 
 ### Switch.Label
 `ref` → `HTMLSpanElement`. The visible text in the text column of the label row. Native `<span>` props.
 
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
 ## Variants
 No `variant` / `tone` / `color`.
 
@@ -77,6 +83,7 @@ No `variant` / `tone` / `color`.
 | `readOnly` | normal colours, no hover or press, clicks ignored | the value is meaningful but someone else controls it | `false` |
 | `disabled` | muted track (on = `accent-soft`), dimmed text | the setting is unavailable | `false` |
 | `invalid` | danger ring on the off track | the message is shown elsewhere; otherwise pass `error` | `false` |
+| `optional` | muted `labels.optional` after the text | a form where most fields are required | `false` |
 | `loading` | a spinner turns inside the thumb, presses do nothing | the owner tracks the save itself; with a promise from `onCheckedChange` it comes on its own | `false` |
 
 **Combinations**
@@ -90,9 +97,9 @@ No `variant` / `tone` / `color`.
 | off | `checked={false}` / default | `data-state="unchecked"`; track `fill-strong` (hover `fill-strong-hover`), thumb at the start |
 | on | `checked` / `defaultChecked` | `data-state="checked"`; accent track, the thumb glides to the end |
 | invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid`; danger ring on the off track and on focus; the row shakes once when an error arrives (`data-shake`) |
-| disabled | `disabled` | `data-disabled="true"`; off track `fill-muted`, on track `accent-soft`, `cursor: not-allowed` |
+| disabled | `disabled` | `data-disabled="true"`; off track `fill-muted`, on track `accent-soft`, thumb `control-thumb-disabled` without shadow, `cursor: not-allowed` |
 | read-only | `readOnly` | `aria-readonly="true"` on the input, `data-readonly="true"` on the field; no hover or press, default cursor |
-| saving | `loading`, or `onCheckedChange` returned a pending promise | the thumb stands in the new position with a `Spinner` inside (accent when on, muted when off; it enters with `enterMotion`), `aria-busy` on the input, `data-loading` on the track, presses ignored; a rejection glides the thumb back (`base`, emphasized) |
+| saving | `loading`, or `onCheckedChange` returned a pending promise | the thumb stands in the new position with a `Spinner` inside (accent when on, muted when off; it fades in by itself), `aria-busy` on the input, `data-loading` on the track, presses ignored; a rejection glides the thumb back (`base`, emphasized) |
 | pressed | pointer press | the track scales to the compact press scale (not when disabled or read-only) |
 | focus-visible | keyboard | outer focus ring around the track |
 
@@ -100,19 +107,23 @@ Root also carries `data-size`. Controlled: `checked` + `onCheckedChange`. Uncont
 
 ## Layout & spacing
 - Grid `[track][text]`; hint and error sit under the text column.
-- Switches in a settings list: gap `--prime-space-4`–`--prime-space-5` between fields.
-- Settings row (text left, switch right): flex row with `justify-content: space-between`, gap `--prime-space-4`; a bare `Switch.Root` with `aria-labelledby` / `aria-describedby` pointing at the row text.
+- Switches in a settings list: a label-less [Fieldset](../fieldset/COMPONENT.md), the field column of a form, sets their rhythm.
+- Settings row (text left, switch right): flex row with `justify-content: space-between`; a bare `Switch.Root` with `aria-labelledby` / `aria-describedby` pointing at the row text.
 - In a form, a `name`d switch submits `"on"` when checked (native checkbox semantics).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus to the switch. |
 | `Space` | Toggles it (not while `readOnly` or saving). |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - A native `<input type="checkbox" role="switch">` (its native checked state is the switch state), visually hidden over the track and wrapped by the `<label>` row.
 - `aria-invalid`, `aria-readonly` and `aria-describedby` (your ids + the hint or the error) are set on the input.
 - Without visible text, name it with `aria-label` or `aria-labelledby` on `Switch.Root`.
@@ -121,14 +132,16 @@ Root also carries `data-size`. Controlled: `checked` + `onCheckedChange`. Uncont
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-No `labels`.
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
 
 ## Examples
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A setting that applies at once, with a hint under its text — `hint`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size, track 24×16 to 44×24; the text follows the control tier — `size`. |
-| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `readOnly`, `invalid`, `loading`, `disabled`. |
+| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `defaultChecked`, `readOnly`, `invalid`, `loading`, `disabled`. |
 | [settings-row.tsx](examples/settings-row.tsx) | A settings row with text on the left and a bare track on the right — `aria-labelledby`, `aria-describedby`. |
 | [saving.tsx](examples/saving.tsx) | A setting that applies on the server at once: the thumb waits in its new place with a spinner, and a refused save glides it back and says why — `onCheckedChange`, `error`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the state and rewrites the hint to match it — `checked`, `onCheckedChange`. |
@@ -143,5 +156,5 @@ No `labels`.
 - Setting `checked` in `onCheckedChange` and flipping it back when the request fails, or a separate «saving» flag → return the request's promise; set `checked` only after it succeeds.
 
 ## Related
-- **Built from:** [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Spinner](../spinner/COMPONENT.md) (saving); the row is a native `<label>`
+- **Built from:** [Label](../label/COMPONENT.md) (the `optional` and `required` marks), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Spinner](../spinner/COMPONENT.md) (saving), [VisuallyHidden](../visually-hidden/COMPONENT.md); the row is a native `<label>`
 - **See also:** [Checkbox](../checkbox/COMPONENT.md), [Radio](../radio/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -6,7 +6,7 @@
   align-items: center;
   justify-content: space-between;
   gap: var(--prime-space-4);
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 .rowText {
@@ -21,7 +21,7 @@
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-4);
-  width: min(100%, var(--prime-modal-width-s));
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 .formActions {

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

@@ -1,4 +1,4 @@
-/** Every state side by side, each labelled by its prop — `checked`, `readOnly`, `invalid`, `loading`, `disabled`. */
+/** Every state side by side, each labelled by its prop — `defaultChecked`, `readOnly`, `invalid`, `loading`, `disabled`. */
 import { Switch } from "prime-ui-kit";
 
 export default function SwitchStatesExample() {
@@ -12,7 +12,7 @@ export default function SwitchStatesExample() {
         </div>
         <div>
           <Switch.Root defaultChecked>
-            <Switch.Label>checked</Switch.Label>
+            <Switch.Label>defaultChecked</Switch.Label>
           </Switch.Root>
         </div>
         <div>
@@ -39,7 +39,7 @@ export default function SwitchStatesExample() {
         </div>
         <div>
           <Switch.Root disabled defaultChecked>
-            <Switch.Label>disabled · checked</Switch.Label>
+            <Switch.Label>disabled · defaultChecked</Switch.Label>
           </Switch.Root>
         </div>
       </div>