prime-ui-kit 0.14.0 → 0.16.0

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**
@@ -92,7 +99,7 @@ No `variant` / `tone` / `color`.
 | 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` |
 | 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>

package/src/components/tabs/COMPONENT.md

@@ -27,8 +27,8 @@ import { Tabs } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItemWidth; no surface
-├─ Tabs.List              role="tablist" on a ScrollContainer, sliding folder; collapses, then scrolls
+Tabs.Root                 value, size (else the host tier), orientation, tone, fullWidth, min/maxItemWidth
+├─ Tabs.List              role="tablist" on the switcher row, sliding folder; collapses, then scrolls
 │  ├─ Tabs.Item           one tab (role="tab") in an item wrapper; onRemove adds a close button; parts:
 │  │  ├─ Tabs.Icon        decorative icon; hidden first, kept last
 │  │  ├─ Tabs.Label       title; keeps its width when it turns medium weight
@@ -51,17 +51,17 @@ Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItem
 | `defaultValue` | `string` | `""` | Initial active tab (uncontrolled). With `""` no tab is selected. |
 | `onValueChange` | `(value: string) => void` | — | Called with the new active value. |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | List direction and arrow keys. Vertical: a column of sections beside the panel, which becomes a horizontal strip in a container below 600px. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier: text, icon, spacing, folder radius and the gap between the strip and the panel; a tab is at least the control height. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Control tier: text, icon, spacing, folder radius and the gap between the strip and the panel; a tab is at least the control height. Without it the tier of the host. |
 | `fullWidth` | `boolean` | `true` | Horizontal tabs fill the list and tend to equal widths within `minItemWidth` … `maxItemWidth`; `false` sizes each tab to its content within the same bounds. |
 | `tone` | `"neutral" \| "accent"` | `"neutral"` | Colour of the active tab: `neutral` is primary text with an accent icon, `accent` puts text and icon in accent. |
-| `minItemWidth` | `number \| string` | `2.5 × control height` | Narrowest a horizontal tab with a label gets, px or a CSS length; a tab is also never narrower than its content (up to `maxItemWidth`). |
-| `maxItemWidth` | `number \| string` | `7 × control height` | Widest a horizontal tab gets, px or a CSS length (`"none"` lifts the cap); a longer label ends with an ellipsis. |
+| `minItemWidth` | `number \| string` | 2.5 × control height | Narrowest a horizontal tab with a label gets, px or a CSS length; a tab is also never narrower than its content (up to `maxItemWidth`). |
+| `maxItemWidth` | `number \| string` | 7 × control height | Widest a horizontal tab gets, px or a CSS length (`"none"` lifts the cap); a longer label ends with an ellipsis. |
 | `labels` | `Partial<TabsLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | `Tabs.List` and `Tabs.Panel`s. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">` | — | `className` and the other div attributes. |
 
 ### Tabs.List
-`ref` → `HTMLDivElement`. `role="tablist"` on a `ScrollContainer` with the sliding folder. When tabs do not fit it hides icons and descriptions, then labels (only when every tab has an icon), then scrolls; the active tab stays in view.
+`ref` → `HTMLDivElement`. `role="tablist"` on the switcher row (a sideways `ScrollContainer`) with the sliding folder. When tabs do not fit it hides icons and descriptions, then labels (only when every tab has an icon), then scrolls; the active tab stays in view.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -173,7 +173,7 @@ A tab is at least the control height of the tier, so a one-line list lines up wi
 | `Tabs.Icon` + `Tabs.Label` | muted icon before the label; the active tab's leading icon turns accent | sections with recognizable icons | |
 | `Tabs.Count` | soft badge after the label, tabular numbers | showing how many items a section has | |
 | `Tabs.Description` (two-line) | label (+ count) on line 1, `body-s` muted text on line 2; `<strong>` is primary / medium | dashboards with a summary per section | |
-| `onRemove` on Item | a ghost close button (`action.close`, two tiers below) at the end of the tab: on the active tab, on hover and focus, always on touch screens; the tab also closes by `Delete` / `Backspace` and a middle click, and closing the active tab selects its neighbour | open documents the user closes, like browser tabs | |
+| `onRemove` on Item | a ghost close button (`action.close`, `xs`; `s` in `l` and `xl` tabs) at the end of the tab: on the active tab, on hover and focus, always on touch screens; the tab also closes by `Delete` / `Backspace` and a middle click, and closing the active tab selects its neighbour | open documents the user closes, like browser tabs | |
 
 Avoid icons or descriptions on only some tabs (uneven rows; without an icon on every tab the list cannot collapse to icons) and Tabs used as a filter — use SegmentedControl.
 
@@ -182,18 +182,18 @@ Avoid icons or descriptions on only some tabs (uneven rows; without an icon on e
 |---|---|---|
 | active | `value` / `defaultValue` | item `aria-selected="true"`, `data-state="active"`, `tabIndex=0`; others `data-state="inactive"`, `tabIndex=-1` |
 | hover | pointer | text → primary; the folder shape in `fill-faint`, under the folder |
-| pressed | pointer down | the tab content scales to `--prime-motion-press-scale-compact` |
-| focus-visible | keyboard | focus ring inside the tab, above the folder; the panel shows an inset ring |
+| pressed | pointer down | the tab content scales to `--prime-motion-press-scale-compact` (`internal/press`) |
+| focus-visible | keyboard | the tab draws an inset ring in its own shape, above the folder; the focused panel draws the outer ring |
 | disabled | `disabled` on Item | native `disabled`, `data-disabled="true"`, `text-disabled`; a removable tab loses its close button |
 | removable | `onRemove` on Item | item wrapper `data-removable="true"`, close button, tab `aria-keyshortcuts="Delete"` |
 | closing, confirm pending | `onRemove` returned a promise that has not settled | the close button is `loading` (`aria-busy`); the tab, its selection and focus stay; resolved → the neighbour takes over, rejected → nothing changes |
 | two-line | `Tabs.Description` child | `data-two-line="true"` |
-| collapsed | tabs wider than the list, or a label that would be cut (horizontal) | list `data-collapse="full" \| "compact" \| "icon"`: `compact` hides icons and descriptions; `icon` hides labels (sr-only, shown in a `Tooltip`), counts and close buttons, only when every tab has an icon |
-| overflow | tabs at their narrowest (content width, `minItemWidth` or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (ScrollContainer), faded edges as deep as the hidden part at most (they grow and melt with the scroll, never switch); the active tab is kept in view and clear of the fades on mount and on every value change, the first and the last tab scroll all the way to the end — only the list scrolls, never the page |
+| collapsed | tabs wider than the list, or a label that would be cut (horizontal) | list `data-collapse="full" \| "compact" \| "icon"`: `compact` hides icons and descriptions; `icon` takes labels, counts and close buttons out of the row — a `VisuallyHidden` copy of the label names the tab and a `Tooltip` shows it — only when every tab has an icon |
+| overflow | tabs at their narrowest (content width, `minItemWidth` or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (the switcher row, a ScrollContainer), faded edges as deep as the hidden part at most (they grow and melt with the scroll, never switch); the active tab is kept in view and clear of the fades on mount and on every value change, the first and the last tab scroll all the way to the end — only the list scrolls, never the page. A column (a wide vertical list) has plain edges |
 
 The indicator glides (`emphasized` + `base`, `data-animate="true"`) only into a choice by click, arrow keys or closing the active tab; on mount, a value set from outside, a resize, font loading, tabs added or removed and collapse it is placed without motion, and it stays still under `prefers-reduced-motion`. The list scrolls smoothly to the active tab only after such a choice too.
 
-Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; List `data-indicator="folder"`, its indicator `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted; a panel's content enters each time it opens.
+Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; the folder (the list's first child, `data-indicator`) `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted, and a tab points at its panel (`aria-controls`) only while the panel is in the document; a panel's content enters each time it opens.
 
 ## Layout & spacing
 - Tabs are a bar, not a surface: the root has no fill, padding, radius or `data-depth`. On a page or in a `Card.Body`, put it straight into the host's padded region and the panel content straight into `Tabs.Panel`. The strip's edges and the panel content share the host's content edge; the panel stands one tier gap below the strip (`--prime-space-3` … `--prime-space-8`).
@@ -214,13 +214,16 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 ```
 - The folder paints the host's `layer-current`, so the active tab is always the colour of the surface it stands on; controls in a panel read the host's field and fill tokens.
 - Vertical: the column is as wide as its widest section (at least four control heights, at most 40% of the root) and as tall as its sections; the panel sits beside it, one gap away.
-- The list never wraps: it collapses, then scrolls horizontally with faded edges (hidden scrollbar, `overscroll-behavior: contain`). Give the list's container a width (`min-width: 0` on flex children).
+- The list is a switcher (foundation §9): it never wraps — it collapses, then scrolls horizontally with faded edges (hidden scrollbar, `overscroll-behavior: contain`). Give the list's container a width (`min-width: 0` on flex children).
+- Without `size` the tabs take the tier of their host (a Card, a Drawer, a form), else `m`.
 - A horizontal tab is never narrower than its content (`min-width: max-content`; the tab bounds that content between `minItemWidth` and `maxItemWidth`), so a label is never cut to make room. Full width, tabs tend to equal widths, not widths in proportion to their labels (`flex: 1 1 0`): a long label keeps its width, the short ones share the rest.
 - A vertical Tabs.Root is a size container: give it a width (it measures itself to switch to a row).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `ArrowLeft` · `ArrowRight` | Select the neighbouring tab, wrapping and skipping disabled ones; also work in a vertical list. |
@@ -230,11 +233,13 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 | `Tab` | Enters the active tab (roving tabindex), then moves to the panel. |
 
 ### ARIA
-- WAI-ARIA tabs pattern: `tablist` / `tab` / `tabpanel` with `aria-controls` / `aria-labelledby` wired automatically; give `Tabs.List` an `aria-label`.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- WAI-ARIA tabs pattern: `tablist` / `tab` / `tabpanel` with `aria-controls` / `aria-labelledby` wired automatically; a tab names its panel in `aria-controls` only while the panel is in the document. Give `Tabs.List` an `aria-label`.
 - Selection follows focus; the panel is focusable (`tabIndex=0`).
 - In a two-line tab the accessible name is label (+ count); `Tabs.Description` becomes `aria-describedby`.
 - `Tabs.Icon` and `Tabs.Separator` are `aria-hidden`.
-- When only icons are left, the label stays for screen readers (sr-only) and shows in a `Tooltip` on hover and focus.
+- When only icons are left, a `VisuallyHidden` copy of the label names the tab and the label shows in a `Tooltip` on hover and focus.
 - The close button of a removable tab is named after it (`labels.remove`) and stays out of the Tab order; the tab announces `aria-keyshortcuts="Delete"`.
 
 ### Labels
@@ -249,7 +254,7 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Sections of one screen; the active tab rises into the strip and glides to the next one — `defaultValue`. |
 | [variants.tsx](examples/variants.tsx) | The active tab in primary text with an accent icon, or all in accent — `tone`. |
-| [sizes.tsx](examples/sizes.tsx) | Every size tier: text, icon, folder radius and spacing grow together — `size`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier: text, icon, folder radius and spacing grow together; tabs sized to their content — `size`, `fullWidth`. |
 | [states.tsx](examples/states.tsx) | A disabled tab that clicks and arrow keys skip — `disabled`. |
 | [with-icon.tsx](examples/with-icon.tsx) | A muted icon before the label and a hairline before the service section — `Tabs.Icon`, `Tabs.Label`, `Tabs.Separator`. |
 | [orientation.tsx](examples/orientation.tsx) | Account settings with a side list of sections: the active section reaches out of the panel, and below 600px the list moves above it — `orientation`. |
@@ -272,5 +277,5 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 - Tabs inside `Drawer.Body` / `Modal.Body` under the header → a floating strip under the header's hairline; wrap the header and the body in `Tabs.Root` and put `Tabs.List` into the header.
 
 ## Related
-- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Button](../button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), Icon (`action.close`)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (`internal/SwitcherScroller`, the list), [Badge](../badge/COMPONENT.md), [Button](../button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [VisuallyHidden](../visually-hidden/COMPONENT.md) (the label of an icon-only tab), Icon (`action.close`); `internal/selectionIndicator` (the folder), `internal/press`
 - **See also:** [SegmentedControl](../segmented-control/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Accordion](../accordion/COMPONENT.md)

package/src/components/tabs/examples/in-drawer.tsx

@@ -41,7 +41,7 @@ export default function TabsInDrawerExample() {
               <DescriptionList.Root>
                 <DescriptionList.Item label="Клиент">Анна Смирнова</DescriptionList.Item>
                 <DescriptionList.Item label="Статус">
-                  <Badge.Root color="orange">Собирается на складе</Badge.Root>
+                  <Badge.Root tone="info">Собирается на складе</Badge.Root>
                 </DescriptionList.Item>
                 <DescriptionList.Item label="Оплата">Картой, 3 октября</DescriptionList.Item>
                 <DescriptionList.Item label="Менеджер">Илья Соколов</DescriptionList.Item>

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

@@ -1,30 +1,25 @@
-/** Every size tier: text, icon, folder radius and spacing grow together — `size`. */
+/** Every size tier: text, icon, folder radius and spacing grow together; tabs sized to their content — `size`, `fullWidth`. */
 import { Tabs, Typography } from "prime-ui-kit";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function TabsSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
         <div key={size}>
-          <Typography as="span" variant="caption" tone="muted">
-            {size}
-          </Typography>
           <Tabs.Root size={size} defaultValue="all" fullWidth={false}>
             <Tabs.List aria-label="Заявки">
               <Tabs.Item value="all">Все</Tabs.Item>
               <Tabs.Item value="active">Активные</Tabs.Item>
               <Tabs.Item value="archive">Архив</Tabs.Item>
             </Tabs.List>
-            <Tabs.Panel value="all">
-              <Typography variant="body-m" tone="secondary">
-                12 заявок за неделю.
-              </Typography>
-            </Tabs.Panel>
           </Tabs.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
         </div>
       ))}
-    </>
+    </div>
   );
 }

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

@@ -11,30 +11,26 @@ const SECTIONS = [
 
 export default function TabsVariantsExample() {
   return (
-    <>
+    <div>
       {TONES.map((tone) => (
-        <Tabs.Root key={tone} tone={tone} defaultValue="orders">
-          <Tabs.List aria-label="Продажи">
-            {SECTIONS.map((section) => (
-              <Tabs.Item key={section.value} value={section.value}>
-                <Tabs.Icon>
-                  <Icon name={section.icon} />
-                </Tabs.Icon>
-                <Tabs.Label>{section.label}</Tabs.Label>
-              </Tabs.Item>
-            ))}
-          </Tabs.List>
-          {SECTIONS.map((section) => (
-            <Tabs.Panel key={section.value} value={section.value}>
-              <Typography variant="body-m" tone="secondary">
-                {tone === "neutral"
-                  ? "Спокойный акцент: цвет только у иконки."
-                  : "Активная вкладка целиком в акцентном цвете."}
-              </Typography>
-            </Tabs.Panel>
-          ))}
-        </Tabs.Root>
+        <div key={tone}>
+          <Tabs.Root tone={tone} defaultValue="orders">
+            <Tabs.List aria-label="Продажи">
+              {SECTIONS.map((section) => (
+                <Tabs.Item key={section.value} value={section.value}>
+                  <Tabs.Icon>
+                    <Icon name={section.icon} />
+                  </Tabs.Icon>
+                  <Tabs.Label>{section.label}</Tabs.Label>
+                </Tabs.Item>
+              ))}
+            </Tabs.List>
+          </Tabs.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {tone}
+          </Typography>
+        </div>
       ))}
-    </>
+    </div>
   );
 }

package/src/components/tag-select/COMPONENT.md

@@ -51,9 +51,11 @@ TagSelect                       field frame: label · control · hint/error (sin
 | `open` | `boolean` | — | Controlled open state of the list. |
 | `defaultOpen` | `boolean` | `false` | Initial open state, uncontrolled. |
 | `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: focus, a field click, typing, arrows, Escape, an outside press; typing closes it when nothing matches. |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the list; focus stays in the input. |
+| `closeOnOutsideClick` | `boolean` | `true` | A press outside the field and the list closes the list. |
 | `creatable` | `boolean` | `false` | A typed text that is not an option can be added (the Create row or Enter). |
 | `onCreate` | `(value: string) => void \| Promise<void>` | — | A new value was created, not picked from `options`; it joins the selection at once. Return the save's promise: the chip waits busy; on reject it leaves again (say why with `error`). |
-| `defaultColor` | `PaletteColor` | `"gray"` | Chip color of values without an option color, created ones included. |
+| `fallbackColor` | `PaletteColor` | `"gray"` | Chip color of values without an option color, created ones included. |
 | `onOptionUpdate` | `(value: string, updates: { label?: string; color?: PaletteColor }) => void \| Promise<void>` | — | Enables the row «⋯» menu to rename and recolor a tag; `value` never changes. Return the save's promise and apply the change to `options` before it resolves; on reject the option goes back. |
 | `onOptionDelete` | `(value: string) => void \| Promise<void>` | — | Enables «Удалить» in the row menu; the value also leaves the selection. A returned Promise defers it: resolve deletes, reject keeps everything (e.g. after a confirmation). |
 | `label` | `ReactNode` | — | Field label above; names the input. |
@@ -65,15 +67,16 @@ TagSelect                       field frame: label · control · hint/error (sin
 | `disabled` | `boolean` | `false` | Disabled field and chips; the list never opens. |
 | `name` | `string` | — | Form field name: one hidden input per selected value (read with `formData.getAll(name)`). |
 | `placeholder` | `string` | `""` | Text in the input while no tag is picked. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Field tier; the list uses the same tier, chips one tier down. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Field tier; the list uses the same tier, chips one tier down. Without it the tier of its host (a form, a panel with a size), else `m`. |
 | `focusRing` | `boolean` | `true` | `false` hides the visual focus ring (`data-focus-ring="false"`), never focus or the error ring. |
 | `id` | `string` | — | Id of the input; generated when omitted. |
 | `labels` | `Partial<TagSelectLabels>` | — | Built-in strings, see Labels (`colorNames` merges by key). |
 | `aria-label · aria-labelledby` | `string` | — | Name of the input and the list when there is no `label`. |
+| `className` | `string` | — | Class on the field frame `<div>`. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
 
 ## Variants
-No `variant` or `tone`. The control is the field look; chips are soft Badges on the field's wash (neutral chips a stronger wash, hue chips a wash of their hue); the list is the shared floating panel.
+No `variant` or `tone`. The control is the field look; chips are the kit's soft Badges, the palette's soft steps that read on any field fill; the list is the shared floating panel.
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -90,13 +93,17 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | `creatable` | a «Создать» row with the preview chip while the typed text is new | The dictionary is open | `false` |
 | `onOptionUpdate` / `onOptionDelete` | a «⋯» button on the highlighted row (always shown on touch screens) opening a rename / color / delete menu | Users keep their own tags | |
 | `disabled` | disabled fill, muted chips, no list | The value is read-only in this context | `false` |
+| `closeOnOutsideClick` | `false`: the list stays open on a press beside the field; Escape and Tab still close it | The person reads the page while tagging | `true` |
+| `closeOnEscape` | `false`: Escape leaves the list open | The list must close only by Tab or a press outside | `true` |
 | `invalid` / `error` | danger inset ring (+ the message) | Validation failed | |
+| `required` / `optional` | red `*` / muted «необязательно» after the label | Mark the minority of the form | `false` / — |
+| `focusRing` | `false`: no focus ring; the field keeps its focus fill | Only where focus shows otherwise; never on a form field (WCAG 2.4.7) | `true` |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | collapsed / expanded | focus inside or the list open | `data-expanded="true"` on the control: every chip on up to three rows (then scroll with edge fades); the height animates. Focus leaving the field collapses it and clears the typed query |
-| open | focus, typing, arrows | `data-state="open"` on the control; list `data-state`, `data-side` |
+| open | `open` / `defaultOpen`, focus, typing, arrows | `data-state="open"` on the control; list `data-state`, `data-side` |
 | overflow | more chips than fit at rest | a «+N» Badge button with `labels.more` and the hidden labels in `title` |
 | invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the input; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | `data-disabled="true"`, native `disabled` on the input and the hidden `name` inputs; never expands |
@@ -115,6 +122,8 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `ArrowDown` · `ArrowUp` | Open the list (when it has something to show) and move the highlight over the options. |
@@ -123,9 +132,12 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | `Backspace` | In an empty input removes the last tag; on a tag removes it and focuses the previous tag. |
 | `ArrowLeft` · `ArrowRight` | From the start of the input move focus over the tags and back to the input. |
 | `Delete` | On a tag removes it; focus moves to the next tag, or to the input when none is left. |
+| `Shift+F10` · `ContextMenu` | With `onOptionUpdate` or `onOptionDelete`: opens the «⋯» menu of the highlighted row; Escape closes it. |
 | `Escape` | Closes the row «⋯» menu if it is open, otherwise the list. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The input is `role="combobox"` with `aria-expanded` and `aria-controls`; the list is `role="listbox"` with `aria-multiselectable`, options are `role="option"` with `aria-selected`.
 - The highlight goes through `aria-activedescendant`; the checkbox in a row is decorative.
 - A removal is announced with `labels.removed` in a live region; the remove button is named by `labels.remove`.
@@ -148,7 +160,7 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | `name` | `"Название тега"` | Accessible name of the tag name field in the menu. |
 | `delete` | `"Удалить"` | Delete button in the menu. |
 | `colors` | `"Цвета"` | Heading of the color list in the menu. |
-| `colorNames` | `"По умолчанию · Красный · Оранжевый · …"` | Names of the palette colors in the menu, by `PaletteColor` key. |
+| `colorNames` | `"По умолчанию · Красный · Оранжевый · Жёлтый · Зелёный · Синий · Фиолетовый · Розовый · Голубой · Бирюзовый"` | Names of the palette colors in the menu, by `PaletteColor` key. |
 | `optional` | `"необязательно"` | Muted marker after the label when `optional`. |
 
 ## Examples
@@ -156,12 +168,13 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A labelled tag field: focus opens the list, typing filters it, picked tags become chips — `label`, `options`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier with two picked tags; chips sit one tier below the field — `size`. |
-| [states.tsx](examples/states.tsx) | A default field next to a disabled and an invalid one, with a disabled option in the list — `disabled`, `invalid`. |
+| [states.tsx](examples/states.tsx) | A default field next to a disabled and an invalid one and one whose focus shows without the ring, with a disabled option in the list — `disabled`, `invalid`, `focusRing`. |
 | [validation.tsx](examples/validation.tsx) | Live validation: removing the last region shakes the field and drops the error in, adding one clears it; required and optional markers and a hint — `required`, `optional`, `hint`, `error`. |
-| [creatable.tsx](examples/creatable.tsx) | A typed text that is not in the list becomes a new tag from the Create row or Enter and is saved on the server: the chip waits busy, and a tag the server refuses leaves again — `creatable`, `onCreate`, `defaultColor`. |
+| [creatable.tsx](examples/creatable.tsx) | A typed text that is not in the list becomes a new tag from the Create row or Enter and is saved on the server: the chip waits busy, and a tag the server refuses leaves again — `creatable`, `onCreate`, `fallbackColor`. |
 | [many-tags.tsx](examples/many-tags.tsx) | More tags than fit: at rest one row with «+N», focused every tag on up to three wrapped rows that scroll — `defaultValue`. |
 | [manage-tags.tsx](examples/manage-tags.tsx) | Users keep their own tag dictionary on the server: the row «⋯» menu renames, recolors or deletes an option, and «⋯» spins while a change is saved — `onOptionUpdate`, `onOptionDelete`. |
 | [confirm-delete.tsx](examples/confirm-delete.tsx) | Deleting a shared tag asks first: the row waits with a spinner while the dialog is open, cancelling keeps the tag and the selection — `onOptionDelete`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A tag list that stays open while the person reads the task beside it: Escape or Tab close it — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value: a preset button replaces the tags and the count follows them — `value`, `onValueChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the list: a button opens it from code, Escape or an outside press closes it — `open`, `onOpenChange`. |
 | [in-form.tsx](examples/in-form.tsx) | A new task form: the required labels field is checked on submit, its error shakes the field and leaves once a label is added, a calm note confirms the task; the tags go with the form — `required`, `error`, `creatable`, `name`. |