prime-ui-kit 0.16.0 → 0.18.0

package/dist/skill/reference/components/message/examples/sticker.tsx

@@ -0,0 +1,35 @@
+/** Stickers in a conversation: a picture by its address and a video sticker in your own player, no bubble, the time on a pill over the corner — `Message.Sticker`, `src`, `loading`. */
+import { Message } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const THUMBS_UP = "https://fonts.gstatic.com/s/e/notoemoji/latest/1f44d/512.webp";
+const CLIP = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
+
+export default function MessageStickerExample() {
+  const [clipReady, setClipReady] = React.useState(false);
+
+  return (
+    <div className={styles.thread}>
+      <Message.Root value="sticker-text" time="10:42">
+        <Message.Text>Отгрузку подтвердили, машина выезжает в 14:00.</Message.Text>
+      </Message.Root>
+      <Message.Root value="sticker-image" direction="outgoing" time="10:43" status="read">
+        <Message.Sticker src={THUMBS_UP} aria-label="Стикер «Класс»" />
+      </Message.Root>
+      <Message.Root value="sticker-video" time="10:44">
+        <Message.Sticker aria-label="Видеостикер «Цветок»" loading={!clipReady}>
+          <video
+            src={CLIP}
+            autoPlay
+            loop
+            muted
+            playsInline
+            onLoadedData={() => setClipReady(true)}
+          />
+        </Message.Sticker>
+      </Message.Root>
+    </div>
+  );
+}

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

@@ -34,6 +34,7 @@ Modal.Root                    state and dismiss policy (no DOM)
     │   ├── Modal.Description <p>, describes the dialog
     │   └── Modal.Actions     row of tier-s controls before the close button
     ├── Modal.Body            the only scrolling zone
+    │   └── Modal.Section     <section>: <h3> label, description, Modal.Actions at the heading's end
     └── Modal.Footer          actions, primary last
         ├── Modal.Meta        <p>, muted status at the start
         ├── Modal.Close       clones its child; closes on click
@@ -83,7 +84,7 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other attributes of the `<header>`. |
 
 ### Modal.Actions
-`ref` → `HTMLDivElement`. A row of controls at the end of the header, before the close button: a status Badge, a ⋯ Dropdown, an icon button. Controls inside take tier `s`.
+`ref` → `HTMLDivElement`. A row of controls at the end of the header, before the close button: a status Badge, a ⋯ Dropdown, an icon button; or at the end of a `Modal.Section` heading. Controls inside take tier `s`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -112,6 +113,15 @@ No DOM, no ref. State and dismiss policy.
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `children` and the other attributes of the zone. |
 
+### Modal.Section
+`ref` → `HTMLElement`. A titled `<section>` of the body: an `<h3>` (title-s, under the `<h2>` title), an optional description, a `Modal.Actions` at the end of the heading row; the content 16 below, sections 32 apart. Fields group in a `Fieldset`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — (required) | The heading of the section; it names the `<section>`. |
+| `description` | `ReactNode` | — | One line of context under the heading (body-s). |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "title">` | — | `children` (the content and an optional `Modal.Actions`), `className` and the other attributes of the `<section>`. |
+
 ### Modal.Footer
 `ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last, and an optional `Meta` at the start.
 
@@ -168,7 +178,7 @@ Below 640px of viewport a centred dialog of every size becomes a full-width bott
 | `fill` | Equal-width buttons in one row, gap 12 | Narrow dialogs with two actions | for `xs`, `s`, `m` |
 | `end` | Auto-width buttons at the end, gap 8 | Wide dialogs | for `l`, `xl` |
 
-With a `Modal.Meta` the footer is a row in any layout: the status takes the free room at the start, the buttons keep their width at the end. On phones (viewport below 640px, where the dialog is a bottom sheet) and in a dialog narrower than 360px, actions stack full width in DOM order (primary last), the status above them.
+With a `Modal.Meta` the footer is a row in any layout: the status takes the free room at the start, the buttons keep their width at the end and stay one row — when the footer runs short the status goes above them first. On phones (viewport below 640px, where the dialog is a bottom sheet) and in a dialog narrower than 360px, actions stack full width in DOM order (primary last), the status above them.
 
 ### tone (Icon)
 | Value | Looks like | Use when | Default |
@@ -221,6 +231,7 @@ Motion (`overlayMotion`): the scrim fades in and out over `base`; the dialog fad
 - Max height = viewport minus `--prime-modal-viewport-padding` on both sides; only the body scrolls.
 - Tabs in the header: a `Tabs.List` inside `Modal.Header` (with `Tabs.Root` around the header and the body) spans the header's last row. The header becomes the tab strip, edge to edge and without the hairline; the active tab is the body rising into it, the panels sit in the body.
 - Fields inside take the floating layer's fill; a card inside is the next layer (`floating-1`), a flat tile. Group fields with a 20 gap.
+- Titled groups of a long body: `Modal.Section label` — an `<h3>` under the dialog's `<h2>` title, an optional `description`, a `Modal.Actions` at the end of its heading row; content 16 below, sections 32 apart. A group of fields is a `Fieldset`.
 - Narrow viewport (< 640px), `placement="center"`: the shared bottom-sheet surface (`src/internal/sheet.module.css`) — full width, rounded top, a grab handle strip on top while it swipes, up to the sheet top gap high, the bottom safe-area inset below the content.
 - `placement="top"`: the dialog hangs from a line 12% of the viewport down (between `--prime-modal-viewport-padding` and `--prime-space-24`) and grows downward.
 
@@ -262,7 +273,7 @@ Motion (`overlayMotion`): the scrim fades in and out over `base`; the dialog fad
 | [overview.tsx](examples/overview.tsx) | A trigger opens a dialog with a title, a field and two actions; Enter presses the confirm — `Modal.Trigger`, `Modal.Confirm`. |
 | [structure.tsx](examples/structure.tsx) | Optional parts: an icon tile with a header-only notice, and a header with a status before the close button and a footer with no body between them — `Modal.Icon`, `Modal.Actions`, `Modal.Footer`. |
 | [sizes.tsx](examples/sizes.tsx) | Every width; xs, s and m fill the footer with equal buttons, l and xl align them to the end — `size`. |
-| [long-content.tsx](examples/long-content.tsx) | A long body scrolls on its own while the header and the footer stay in place; the primary closes the dialog and is the Enter target — `Modal.Body`, `Modal.Confirm`. |
+| [long-content.tsx](examples/long-content.tsx) | A long body in titled sections scrolls on its own while the header and the footer stay in place; the primary closes the dialog and is the Enter target — `Modal.Body`, `Modal.Section`, `Modal.Confirm`. |
 | [custom-container.tsx](examples/custom-container.tsx) | The dialog portals into a given node instead of the document body — `container`. |
 | [guard.tsx](examples/guard.tsx) | An edit form that holds the dialog: changes make any dismiss ask first and show a note in the footer, the submit button saves the form, and while saving nothing closes it — `Modal.Guard`, `Modal.Meta`. |
 | [enter-key.tsx](examples/enter-key.tsx) | Enter in a dialog: handing a workspace over takes a click, never Enter in its field; in the tags dialog Enter adds the typed tag instead of closing — `confirmOnEnter`, `onEnterConfirm`. |
@@ -274,6 +285,7 @@ Motion (`overlayMotion`): the scrim fades in and out over `base`; the dialog fad
 - A destructive confirm built as a Modal → use ConfirmDialog. A destructive step that needs input (type the name to delete) stays a Modal with `closeOnOutsideClick={false}`.
 - Primary action not in `Modal.Confirm` → Enter does nothing; wrap it. In a form, the `type="submit"` button is the primary and stays outside `Modal.Confirm`: Enter in a field submits the form.
 - Primary action first in the footer → put it last (DOM order is the visual order).
+- A hand-made heading row (`Typography as="h3"` + buttons) over a group in the body → `Modal.Section label` with `Modal.Actions`.
 - Busy or unsaved state lifted out of the form into Root props → put `Modal.Guard` next to the form, inside Content.
 - `key` or a conditional around `Modal.Root` to reset a form → the dialog unmounts at once, without its exit; keep the Root mounted and drive `open`.
 - Scrolling wrapper inside Modal.Body → Body already scrolls.

package/dist/skill/reference/components/modal/examples/long-content.tsx

@@ -1,19 +1,34 @@
-/** A long body scrolls on its own while the header and the footer stay in place; the primary closes the dialog and is the Enter target — `Modal.Body`, `Modal.Confirm`. */
+/** A long body in titled sections scrolls on its own while the header and the footer stay in place; the primary closes the dialog and is the Enter target — `Modal.Body`, `Modal.Section`, `Modal.Confirm`. */
 import { Button, Modal, Typography } from "prime-ui-kit";
 
-const TERMS = [
-  "Исполнитель обрабатывает персональные данные только для оказания услуги.",
-  "Данные не передаются третьим лицам без письменного согласия заказчика.",
-  "Доступ к данным получают только сотрудники, которым он нужен для работы.",
-  "Резервные копии хранятся в зашифрованном виде в дата-центрах на территории РФ.",
-  "Заказчик может запросить выгрузку своих данных в течение 10 рабочих дней.",
-  "По запросу заказчика данные удаляются в течение 30 дней после расторжения договора.",
-  "О каждом инциденте безопасности исполнитель сообщает заказчику в течение 24 часов.",
-  "Журналы доступа хранятся не меньше одного года и выдаются по запросу.",
-  "Исполнитель ежегодно проходит внешний аудит защиты информации.",
-  "Субподрядчики допускаются только с согласия заказчика и на тех же условиях.",
-  "Изменения условий публикуются за 30 дней до вступления в силу.",
-  "Споры решаются в арбитражном суде по месту нахождения исполнителя.",
+const SECTIONS = [
+  {
+    title: "Обработка и хранение",
+    terms: [
+      "Исполнитель обрабатывает персональные данные только для оказания услуги.",
+      "Данные не передаются третьим лицам без письменного согласия заказчика.",
+      "Доступ к данным получают только сотрудники, которым он нужен для работы.",
+      "Резервные копии хранятся в зашифрованном виде в дата-центрах на территории РФ.",
+    ],
+  },
+  {
+    title: "Права заказчика",
+    terms: [
+      "Заказчик может запросить выгрузку своих данных в течение 10 рабочих дней.",
+      "По запросу заказчика данные удаляются в течение 30 дней после расторжения договора.",
+      "О каждом инциденте безопасности исполнитель сообщает заказчику в течение 24 часов.",
+      "Журналы доступа хранятся не меньше одного года и выдаются по запросу.",
+    ],
+  },
+  {
+    title: "Аудит и изменения",
+    terms: [
+      "Исполнитель ежегодно проходит внешний аудит защиты информации.",
+      "Субподрядчики допускаются только с согласия заказчика и на тех же условиях.",
+      "Изменения условий публикуются за 30 дней до вступления в силу.",
+      "Споры решаются в арбитражном суде по месту нахождения исполнителя.",
+    ],
+  },
 ];
 
 export default function ModalLongContentExample() {
@@ -30,10 +45,14 @@ export default function ModalLongContentExample() {
           <Modal.Description>Редакция от 1 октября 2026 года</Modal.Description>
         </Modal.Header>
         <Modal.Body>
-          {TERMS.map((line) => (
-            <Typography key={line} variant="body-m" tone="secondary">
-              {line}
-            </Typography>
+          {SECTIONS.map((section) => (
+            <Modal.Section key={section.title} label={section.title}>
+              {section.terms.map((line) => (
+                <Typography key={line} variant="body-m" tone="secondary">
+                  {line}
+                </Typography>
+              ))}
+            </Modal.Section>
           ))}
         </Modal.Body>
         <Modal.Footer>

package/dist/skill/reference/components/native-select/COMPONENT.md

@@ -41,6 +41,7 @@ NativeSelect          field frame: label row · control · support row
 |---|---|---|---|
 | `label` | `ReactNode` | — | Field label above; a `<label htmlFor>` of the select. |
 | `hint` | `ReactNode` | — | Support text under the field; linked by `aria-describedby`. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message; replaces the hint and implies `invalid`. |
 | `required` | `boolean` | `false` | Red `*` after the label and native `required`. |
 | `optional` | `boolean` | — | Muted `labels.optional` after the label. |

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

@@ -156,7 +156,7 @@ Collapsed stacks show up to 3 cards peeking behind each other. Hover or keyboard
 - Each stack is an `<ol>` named by the region label of its position; each card is an `<article>`: `role="status"` + `aria-live="polite"`, or `role="alert"` + `aria-live="assertive"` for `warning` / `danger`.
 - The icon and the countdown are `aria-hidden`; the close button is named by `labels.close`.
 - Focus never leaves with a toast: a card that goes while it holds focus hands it to the front card still open in its stack, else back to where focus came from.
-- A toast is a non-modal live region, not a layer of the overlay stack: Escape and a press elsewhere belong to the page and to the topmost open layer, so a toast takes no `closeOnEscape` / `closeOnOutsideClick` — it leaves by its timer, the close button, a swipe or `dismiss()`.
+- A toast is a non-modal live region, not a layer of the overlay stack: Escape and a press elsewhere belong to the page and to the topmost open layer, so a toast takes no `closeOnEscape` / `closeOnOutsideClick` — it leaves by its timer, the close button, a swipe or `dismiss()`. The toasts stay usable above an open Modal or Drawer, and a press on a toast is outside no layer: it never closes the dialog below.
 - Do not keep the only copy of important information in a toast with a timer — use `persistent` or a Banner.
 
 ### Labels

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

@@ -44,6 +44,7 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 | `siblingCount` | `number` | `1` | Pages on each side of the current one before an ellipsis (when `totalPages > 2·siblingCount+5`). |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Control tier of the buttons: height 28 · 32 · 36 · 40 · 48. Without it the tier of its host, else `m`. |
 | `compact` | `boolean` | `false` | Always arrows + «current / total» instead of numbers. Without it the nav fills its parent and shows that view only below 22rem of its width. |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Where the page numbers sit in the width the nav fills: centred under a list, `end` beside a range line (the DataTable footer). The compact view keeps its arrows at the edges. |
 | `labels` | `Partial<PaginationLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "defaultValue" \| "onChange">` | — | `className`, `data-*` and the other `<nav>` attributes; `aria-label` comes from `labels.nav`. |
 
@@ -52,9 +53,16 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 ### compact
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `false` | fills the parent: arrows around page numbers right-aligned, «…» for skipped ranges; below 22rem of its width the compact view with arrows at the edges | list and table footers, anywhere the width varies | yes |
+| `false` | fills the parent: arrows around page numbers placed by `align`, «…» for skipped ranges; below 22rem of its width the compact view with arrows at the edges | list and table footers, anywhere the width varies | yes |
 | `true` | arrows around «3 / 12» (current in primary medium, total muted, tabular figures) at any width | tight toolbars, a pager that must never show numbers | |
 
+### align
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `center` | the numbers centred in the width the nav fills | a pager under a list or a grid of cards | yes |
+| `start` | the numbers at the start | a pager under left-aligned content | |
+| `end` | the numbers at the end | beside a range line in a footer (the DataTable footer passes it) | |
+
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -78,7 +86,7 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 | hover / active | pointer | `fill-subtle` / `fill-subtle-active`, primary text, press scale |
 | focus-visible | keyboard | outer focus ring of the Button |
 | disabled arrow | first / last page | native `disabled`, `text-disabled` |
-| size / compact | `size` (else the host tier), `compact` | `data-size`, `data-compact` (`"auto"` · `"compact"`) |
+| size / compact / align | `size` (else the host tier), `compact`, `align` | `data-size`, `data-compact` (`"auto"` · `"compact"`), `data-align` |
 
 ## Layout & spacing
 - In a list footer: the range text on the left, rows-per-page Select and Pagination on the right (`justify-content: space-between`), the row wraps.
@@ -120,7 +128,7 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 | [overview.tsx](examples/overview.tsx) | Pages of an order list: arrows, page numbers and the current page — `totalPages`, `defaultValue`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; buttons are as high as Button and Input of the same tier, 28 to 48 px — `size`. |
 | [overflow.tsx](examples/overflow.tsx) | Up to 7 pages without an ellipsis, then a window around the current page; a wider window — `siblingCount`. |
-| [controlled.tsx](examples/controlled.tsx) | A list footer owns the page: changing rows per page returns it to page 1 — `value`, `onValueChange`. |
+| [controlled.tsx](examples/controlled.tsx) | A list footer owns the page: changing rows per page returns it to page 1, the pages at the end beside the range — `value`, `onValueChange`, `align`. |
 | [narrow.tsx](examples/narrow.tsx) | A 320 px card footer: by default the numbers give way to «current / total» on a narrow width, `compact` always shows it — `compact`. |
 
 ## Mistakes

package/dist/skill/reference/components/pagination/examples/controlled.tsx

@@ -1,4 +1,4 @@
-/** A list footer owns the page: changing rows per page returns it to page 1 — `value`, `onValueChange`. */
+/** A list footer owns the page: changing rows per page returns it to page 1, the pages at the end beside the range — `value`, `onValueChange`, `align`. */
 import { Card, Pagination, Select, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -39,6 +39,7 @@ export default function PaginationControlledExample() {
               </Select.Content>
             </Select.Root>
             <Pagination
+              align="end"
               value={page}
               onValueChange={setPage}
               totalPages={Math.ceil(TOTAL_INVOICES / pageSize)}

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

@@ -70,7 +70,7 @@ No DOM: clone the single child and merge `ref` and `onClick`. Trigger toggles th
 | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Preferred side; flips to the opposite side when there is no room. |
 | `align` | `"auto" \| "start" \| "center" \| "end"` | `"auto"` | Alignment along the trigger. `auto` lines the panel up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix the edge. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the text, padding and gap; also the size context of the controls inside. |
-| `width` | `"auto" \| "trigger" \| "content"` | `"auto"` | `auto`: by content, from the panel minimum to twice that. `trigger`: exactly the trigger's width, below the minimum too. `content`: what the content needs, within the viewport. A sheet is full width. |
+| `width` | `"auto" \| "trigger" \| "min-trigger" \| "content"` | `"auto"` | `auto`: by content, panel minimum to twice that. `trigger`: exactly the trigger. `min-trigger`: `auto`, never narrower than the trigger. `content`: what the content needs. A sheet is full width. |
 | `trapFocus` | `boolean` | `false` | Tab cycles inside the panel (forms). Without it Tab past the last (Shift+Tab before the first) stop closes the panel and returns focus to the trigger. |
 | `initialFocus` | `boolean` | `true` with `Popover.Trigger`, `false` with `Popover.Anchor` | Focus moves into the panel on open (`[data-autofocus]`, else the first tab stop, else the panel). Turn it on for an anchored panel opened by a command, such as a Dropdown item, so focus does not stay on the menu trigger. |
 | `flush` | `boolean` | `false` | No inner padding and no gap: rows and dividers reach the panel edges; the content lays out its own spacing. |
@@ -122,6 +122,7 @@ Title uses the tier text size with title weight; Description uses the tier label
 |---|---|---|---|
 | `auto` | As wide as the content, between `--prime-panel-min-width` and twice that | Most panels | yes |
 | `trigger` | Exactly as wide as the trigger, below the minimum too; text wraps | Full-width triggers in narrow columns | |
+| `min-trigger` | As `auto`, never narrower than the trigger | A panel under a wide anchor that must stay readable when the anchor is narrow ([SmartFilter](../smart-filter/COMPONENT.md)) | |
 | `content` | What the content needs, within the viewport | A wide calendar, a table of limits | |
 
 A bottom sheet is always full width, whatever `width` says.
@@ -185,7 +186,7 @@ No `labels`.
 | [structure.tsx](examples/structure.tsx) | Optional parts: a panel with plain text only, and a panel with a title, a description and actions — `Popover.Header`, `Popover.Actions`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier with a header and actions; the tier is the panel's own, set on `Popover.Content`, not taken from its trigger — `size`. |
 | [placement.tsx](examples/placement.tsx) | Every side and alignment relative to the trigger; near the viewport edge the panel flips and shifts — `side`, `align`. |
-| [width.tsx](examples/width.tsx) | In a narrow column the panel takes the exact width of a full-width trigger and its text wraps; a table of limits takes the width it needs — `width`. |
+| [width.tsx](examples/width.tsx) | In a narrow column the panel takes the exact width of a full-width trigger and its text wraps; a short trigger opens a panel at least as wide as itself; a table of limits takes the width it needs — `width`. |
 | [flush.tsx](examples/flush.tsx) | A notification list whose rows and dividers reach the panel edges; each row brings its own padding — `flush`. |
 | [from-menu.tsx](examples/from-menu.tsx) | A menu command opens a panel at the same button: the rename item shows a form anchored to the menu button and focus lands in its field, not back on that button — `Popover.Anchor`, `initialFocus`. |
 | [dismiss.tsx](examples/dismiss.tsx) | A note being typed is not lost to a stray click: the panel closes only from its buttons, and not at all while the note is saved — `closeOnOutsideClick`, `closeOnEscape`. |

package/dist/skill/reference/components/popover/examples/width.tsx

@@ -1,4 +1,4 @@
-/** In a narrow column the panel takes the exact width of a full-width trigger and its text wraps; a table of limits takes the width it needs — `width`. */
+/** In a narrow column the panel takes the exact width of a full-width trigger and its text wraps; a short trigger opens a panel at least as wide as itself; a table of limits takes the width it needs — `width`. */
 import { Button, DescriptionList, Popover, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -24,6 +24,18 @@ export default function PopoverWidthExample() {
           </Typography>
         </Popover.Content>
       </Popover.Root>
+      <Popover.Root>
+        <Popover.Trigger>
+          <Button.Root variant="soft" tone="neutral" fullWidth>
+            Что входит в поддержку
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content width="min-trigger">
+          <Typography variant="body-s" tone="secondary">
+            Ответ в течение 4 часов, персональный менеджер и разбор инцидентов.
+          </Typography>
+        </Popover.Content>
+      </Popover.Root>
       <Popover.Root>
         <Popover.Trigger>
           <Button.Root variant="ghost" tone="neutral" fullWidth>

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

@@ -47,6 +47,7 @@ Radio.Group             field: group label → role="radiogroup" → hint | erro
 | `required` | `boolean` | `false` | Red `*` after the label, native `required` on the radios and `aria-required` on the group. |
 | `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the options. Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message under the options; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger ring on the unchecked circles and `aria-invalid` on the group and the inputs. A non-empty `error` implies it. |
 | `disabled` | `boolean` | `false` | Disables every option. |
@@ -64,6 +65,7 @@ Radio.Group             field: group label → role="radiogroup" → hint | erro
 |---|---|---|---|
 | `value` | `string` | — (required) | Value reported to the group when this option is chosen. |
 | `hint` | `ReactNode` | — | Description under the option text, linked through `aria-describedby`. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `disabled` | `boolean` | `false` | Disables this option only. |
 | `children` | `ReactNode` | — | `Radio.Label`. Without it only the circle renders — give the root an `aria-label`. |
 | `className` | `string` | — | Class on the option `<div>`. |

package/dist/skill/reference/components/rich-text/COMPONENT.md

@@ -0,0 +1,93 @@
+# RichText
+
+**Category:** data-display
+**Kind:** primitive
+
+> Text in the chat's Markdown subset outside a message — a bot's welcome text, a template, a comment — rendered as elements, never as HTML.
+
+## When to use
+- A text written with the formatting toolbar of `Composer` or `Textarea formatting` is shown somewhere other than a chat: a bot's settings, a template list, a card.
+- Text from users or bots that may carry `**bold**`, links or a `||spoiler||` and must be rendered safely.
+
+## When not to use
+- The text of a chat message → [Message](../message/COMPONENT.md) `Message.Text` (it marks search matches and holds the meta's room).
+- A whole message shown outside a chat (a bot's welcome message with its keyboard) → `Message.Root preview`.
+- Plain text with a role → [Typography](../typography/COMPONENT.md).
+- Source code → [CodeBlock](../code-block/COMPONENT.md).
+
+## Import
+```tsx
+import { RichText } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+RichText         <div>; the source as children
+├─ <p>           a run of text, line breaks kept
+├─ <blockquote>  lines starting with "> "
+└─ <pre>         fenced code
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### RichText
+`ref` → `HTMLDivElement`. Text in the chat's Markdown subset outside a message, rendered as elements in the type of its host.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `string` | — (required) | The source: `**bold**`, `_italic_`, `~~strike~~`, `\|\|spoiler\|\|`, inline and fenced code, links (`[label]` then the address in parentheses), bare URLs, `> ` quotes; line breaks are kept. |
+| `labels` | `Partial<RichTextLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `id`, `data-*` and the other div attributes. |
+
+## Variants
+One look: the type of its host. Wrap it in `Typography as="div"` to pick a text role.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| masked spoiler | `\|\|text\|\|` in `children` | `role="button"`, `data-state="masked"`: a wash over transparent words |
+| revealed spoiler | a press, `Enter` or `Space` | `data-state="revealed"`: the wash and the words cross-fade on the fade clock; one way, like a chat |
+
+## Layout & spacing
+- Paragraphs, quotes and code blocks keep their line breaks and wrap anywhere, so a long address never widens the host; blocks stand 4px apart.
+- A quote is a wash with an accent bar on its start edge; code is the mono face on a wash.
+- No size of its own: the root takes the font and color of its host.
+
+## Accessibility
+
+### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves through the links and the masked spoilers. |
+| `Enter` · `Space` | On a masked spoiler: reveals it and moves the focus onto its text. |
+
+### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- A masked spoiler is a `role="button"` named `labels.spoiler`; its words are out of the accessibility tree until it is revealed.
+- Links take only http(s), `mailto:` and `tel:` addresses and open in a new tab (`rel="noopener noreferrer"`); markup is never parsed as HTML.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `spoiler` | `"Скрытый текст"` | The name of a masked spoiler until it is revealed. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | The welcome text of a support bot shown outside the chat: bold, a link, a quote, code and a spoiler from the chat's Markdown — `children`. |
+
+## Mistakes
+- `dangerouslySetInnerHTML` with a Markdown library for a chat text → `RichText`: the same subset as the chat, never HTML.
+- A `Message.Root` with no time and no author only to render formatted text → `RichText`.
+- Sizing the text with a class on `RichText` → put it inside the host that sets the type.
+
+## Related
+- **Built from:** `internal/richText` (the parser and the elements, shared with `Message.Text`)
+- **See also:** [Message](../message/COMPONENT.md), [Composer](../composer/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Typography](../typography/COMPONENT.md)

package/dist/skill/reference/components/rich-text/examples/overview.tsx

@@ -0,0 +1,19 @@
+/** The welcome text of a support bot shown outside the chat: bold, a link, a quote, code and a spoiler from the chat's Markdown — `children`. */
+import { Card, RichText } from "prime-ui-kit";
+
+const WELCOME = [
+  "**Здравствуйте!** Это бот поддержки «Прайм».",
+  "Счета и акты — в [личном кабинете](https://prime.app/billing), номер договора начинается с `PR-`.",
+  "> Отвечаем в рабочие дни с 9:00 до 19:00 по Москве.",
+  "Код для входа в приложение: ||4821||",
+].join("\n");
+
+export default function RichTextOverviewExample() {
+  return (
+    <Card.Root>
+      <Card.Body>
+        <RichText>{WELCOME}</RichText>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/scroll-container/COMPONENT.md

@@ -44,7 +44,7 @@ ScrollContainer   <div> (or the `as` tag); thin scrollbar, soft hidden edges
 | `edges` | `"fade" \| "shadow" \| "none"` | `"fade"` | Edges that hide content: `fade` dissolves them over any background; `shadow` — a soft shadow on the region's own fill (a floating panel, a code well); `none` — plain edges. |
 | `scrollbar` | `"thin" \| "hidden"` | `"thin"` | `thin` — the kit's quiet scrollbar; `hidden` — no scrollbar, keep `edges` on so the overflow stays visible. |
 | `lock` | `boolean` | `false` | The person cannot scroll the region (wheel, touch, keys, a drag's auto-scroll); code still can. Sets `data-lock`. |
-| `snap` | `boolean \| "mandatory"` | `false` | Scrolling comes to rest on the start of a child: `true` near one (strips of tiles and cards), `"mandatory"` always on one (board columns, a carousel). A Dnd drag inside turns it off; not with `anchor="end"`. |
+| `snap` | `boolean \| "mandatory"` | `false` | Once a scroll ends, the region glides to the start of a child: `true` near one (strips of tiles), `"mandatory"` always (board columns, a carousel). Native scrolling meanwhile; any input stops the glide. |
 | `anchor` | `"start" \| "end"` | `"start"` | `end` — a chat or a log: opens at the end and follows new content while the person is at the end; scrolled away, the view holds still. |
 | `onReachStart` | `() => void \| Promise<void>` | — | Fires within 120 px of the start, once per approach: load older content. A returned promise blocks repeats and sets `aria-busy`; content added above keeps the view. |
 | `onReachEnd` | `() => void \| Promise<void>` | — | The scroll position came within 120 px of the end: load the next page. Same once-per-approach and promise rules as `onReachStart`. |
@@ -93,11 +93,12 @@ Only the reader scrolling back unpins the end: content that keeps growing (an an
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `lock` | nothing the person does scrolls the region (wheel, touch, keys, a drag's edge auto-scroll); the position stays, and code may still set it | a list behind an open review, a gesture that must not move it | off |
-| `snap` | a scroll comes to rest on the start of a direct child near one (proximity); a host aligns deeper items itself | strips of tiles or cards | off |
-| `snap="mandatory"` | a scroll always comes to rest on the start of a child | board columns, a carousel of cards | off |
+| `snap` | once a scroll ends near the start of a direct child (within 30% of the view), the region glides there; a host marks deeper items with `scroll-snap-align` itself | strips of tiles or cards | off |
+| `snap="mandatory"` | once a scroll ends, the region always glides to the nearest start of a child | board columns on a phone, a carousel of cards | off |
 
 ### Wheel and auto-scroll
-- `axis="horizontal"`: a vertical mouse wheel scrolls the strip sideways while it can move, gliding to an accumulated target (instant under reduced motion). A trackpad's sideways swipe and Shift + wheel stay native; a wheel gesture that began outside the strip keeps scrolling the page; at the strip's edge the wheel chains to the page. There is no drag-to-scroll: a press-and-drag in a strip belongs to its items (reordering tiles, tabs); touch pans natively.
+- Snapping never takes over the scroll: the trackpad, touch, the scrollbar and the keys scroll natively with their momentum, and the browser does not snap (no `scroll-snap-type` — it damps a trackpad's momentum and pulls a scroll near the end back to merged rest points). Once the scroll ends — no movement for a moment, nothing held — the region glides to its rest point on the kit's own frames, and any wheel, touch, press or key stops that glide at once; it settles again when the input goes quiet. A Dnd drag inside never settles.
+- `axis="horizontal"`: a vertical mouse wheel (whole notches; a trackpad stays native) scrolls the strip sideways while it can move — by the wheel's distance, or a rest point per notch on a strip that snaps — on the kit's frames (instant under reduced motion), each notch from where the glide is heading, so a turn the other way goes back mid-glide. Shift + wheel stays native; a wheel gesture that began outside the strip keeps scrolling the page; at the strip's edge the wheel chains to the page. There is no drag-to-scroll: a press-and-drag in a strip belongs to its items (reordering tiles, tabs); touch pans natively.
 - A gesture held near an edge — a Dnd drag, a Gantt bar moved or drawn, a drag that paints a selection over table rows or messages — scrolls the region toward it, faster the closer the pointer (`src/internal/edgeAutoScroll`, one speed curve for the kit). A `lock`ed region or one whose content fits never moves.
 
 ### Edge events
@@ -116,7 +117,7 @@ Each fires once per approach — again after the position leaves the zone or the
 | edge treatment | `edges` | `data-edges="fade" \| "shadow"` (none for `none`) |
 | content hidden at an edge | scroll position (with `edges="fade"`), measured at most once per frame on scroll, on resize of the region or a child and when children are added; only the scroll axes; logical in RTL | `data-overflow-top`, `data-overflow-bottom`, `data-overflow-start`, `data-overflow-end` = `"true"`; `--edge-*` depths written only while they change (within the last fade depth of an edge, `--scroll-fade-depth`), on non-inherited properties |
 | locked | `lock` | `data-lock`, `overflow: hidden` |
-| snapping | `snap` | `data-snap="proximity" \| "mandatory"`, `scroll-snap-type: <axis> <strictness>`; `scroll-snap-align: start` on the children; off while a Dnd list inside carries an item (`data-dnd-carrying`) |
+| snapping | `snap` | `data-snap="proximity" \| "mandatory"`; `scroll-snap-align: start` on the children marks the rest points (no `scroll-snap-type`); no settling while a Dnd list inside carries an item (`data-dnd-carrying`) |
 | kit anchoring | `anchor="end"` or `onReachStart` | `data-anchor="end" \| "start"`, `overflow-anchor: none`: the kit keeps the visible entry in place (or the end, while pinned) before paint, the same in every browser |
 | pinned to the end | `anchor="end"` and the position within 4 px of the end | content changes scroll to the new end at once (high-frequency: no animation) |
 | loading at an edge | a pending promise from `onReachStart` / `onReachEnd` | `aria-busy="true"` |
@@ -176,6 +177,8 @@ No `labels`.
 - `edges="fade"` on a region that paints its own fill or shadow → the mask dissolves them; use `edges="shadow"`.
 - A hand-made edge auto-scroll loop for a drag → `createEdgeAutoScroll` from `src/internal/edgeAutoScroll`.
 - `snap` together with `anchor="end"` → snapping fights the pin to the end.
+- `scroll-snap-type` on a region or its host → `snap`: the browser's snapping damps a trackpad's momentum and pulls a scroll near the end back.
+- `snap="mandatory"` on a strip of children narrower than the view (a wide board) → their rest points merge at the end; snap only where each child fills most of the view, or use `snap`.
 - Wrapping a Modal body or Dropdown panel in another ScrollContainer → they already scroll.
 - `scrollTop = scrollHeight` in an effect after every message → `anchor="end"` (it also leaves a reader who scrolled up alone).
 - `flex-direction: column-reverse` to keep a chat at the bottom → it reverses the reading and Tab order; use `anchor="end"`.

package/dist/skill/reference/components/segmented-control/COMPONENT.md

@@ -53,6 +53,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the `radiogroup`. |
 | `optional` | `boolean` | `false` | Muted marker after the label (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the control (`aria-describedby`). Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger inset ring, `aria-invalid` and `data-invalid` on the `radiogroup`; the control shakes once when an error arrives. |
 | `reserveSupportRow` | `boolean` | `false` | Always render the support row, so an appearing error does not shift the layout. |

package/dist/skill/reference/components/segmented-control/examples/in-form.tsx

@@ -15,7 +15,7 @@ export default function SegmentedControlInFormExample() {
 
   return (
     <form className={styles.form} noValidate onSubmit={submit}>
-      <Input.Root label="Сумма, ₽" required>
+      <Input.Root label="Сумма" required>
         <Input.Wrapper>
           <Input.Field name="amount" inputMode="decimal" defaultValue="12 400" />
           <Input.InlineAffix side="end">₽</Input.InlineAffix>

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

@@ -11,12 +11,13 @@
 - A value out of thousands of records searched on the server (`search`, `onSearchChange`, `filter={false}`, `hasMore` + `onLoadMore`).
 - A few values from a short list shown as comma-separated text (`multiple`).
 - Options that need a picture, an avatar, a second line, a badge or a trailing value (rich options).
+- A pick that belongs to a text field (an icon before a name): put the Select inside `Input.Wrapper` — it becomes the box's start segment, named by its `aria-label`.
 
 ## When not to use
 - 2–5 options that should all be visible → use [Radio](../radio/COMPONENT.md) or [SegmentedControl](../segmented-control/COMPONENT.md).
 - The OS picker on a mobile-first form → use [NativeSelect](../native-select/COMPONENT.md).
 - Many values shown as removable tags, or creating new values → use [TagSelect](../tag-select/COMPONENT.md).
-- Free text → use [Input](../input/COMPONENT.md).
+- Free text, even with suggestions → use [Input](../input/COMPONENT.md) (`suggestions`).
 - A menu of actions (not a value) → use [Dropdown](../dropdown/COMPONENT.md).
 - Global search / command palette → use [CommandMenu](../command-menu/COMPONENT.md).
 - Dates → use [Datepicker](../datepicker/COMPONENT.md).
@@ -60,7 +61,7 @@ an icon) goes inside `Select.ItemMeta`.
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Select.Root
-`ref` → `HTMLDivElement`. The field frame (label row · control · support row) holding the value, the open state and the search query.
+`ref` → `HTMLDivElement`. The field frame (label row · control · support row) holding the value, the open state and the search query. Inside `Input.Wrapper` it is the box's start segment instead: no frame, the trigger named by `aria-label` and the value.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -75,6 +76,7 @@ an icon) goes inside `Select.ItemMeta`.
 | `closeOnOutsideClick` | `boolean` | `true` | A press outside the list and its trigger closes it; focus follows the pointer. |
 | `label` | `ReactNode` | — | Field label above; names the trigger. |
 | `hint` | `ReactNode` | — | Support text under the field; linked by `aria-describedby`. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message; replaces the hint and implies `invalid`. |
 | `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the trigger. |
 | `optional` | `boolean` | — | Muted `labels.optional` after the label. |
@@ -224,6 +226,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | searching | typing in the search | panel `data-searching="true"`; groups without matches and separators hide; the match in an option's title, description and plain text is a `<mark>` in `accent-text` (not in the trigger); the query clears when the list closes (`onSearchChange("")`) |
 | nothing to show | no option matches (and not loading) | a compact EmptyPage with `role="status"`: `labels.empty`, plus `labels.emptyHint` while a query is typed; a `Select.Action` stays under it, highlighted |
 | sheet | viewport below 640px | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the panel; the sheet carries `data-state`, the panel keeps its role and ref; page scroll locked; a swipe down from the handle closes it |
+| segment | inside `Input.Wrapper` | no frame (label, hint, error, support row): the root is `data-field-segment`, the trigger `data-segment="true"` — a tinted section flush with the box's start edge, a stronger fill on hover and while open, an inset focus ring; named «`aria-label`: value» |
 | option highlighted / selected / disabled | keyboard and pointer / value / `disabled` | `data-highlighted`, `data-selected` + `aria-selected`, `data-disabled` + `aria-disabled`; highlight is a fill only |
 
 ## Layout & spacing
@@ -350,8 +353,9 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 - `<ClientAvatar />` or `<RoleBadge />` (your own component) inside an item → the item reads parts by element type and puts an unknown component in the text column; call the helper as a function (`{clientAvatar(client)}`) so `Avatar.Root` / `Badge.Root` is the direct child.
 - A custom trailing element (a Kbd, an icon with a price) as a bare child → wrap it in `Select.ItemMeta`.
 - A «Новый клиент» row faked as a `Select.Item` with a sentinel value, or a button under the field → use `Select.Action`: never filtered, reached by the arrows, never a value.
+- An icon-only Select set beside an Input for one value (an icon + a name) → put it inside `Input.Wrapper` with an `aria-label`; `label`, `hint` and `error` belong to the Input there.
 - Saving the choice in `onValueChange` and resetting the value by hand on failure → return the promise; the Select shows the value, waits and rolls back by itself.
 
 ## Related
-- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (list), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in `multiple`), [Spinner](../spinner/COMPONENT.md) (`loading` and saving in the trigger), [Skeleton](../skeleton/COMPONENT.md) (loading rows), [EmptyPage](../empty-page/COMPONENT.md) (empty state, load error), [Button](../button/COMPONENT.md) (retry), [Divider](../divider/COMPONENT.md) (`Separator`), [Thumbnail](../thumbnail/COMPONENT.md) and [Avatar](../avatar/COMPONENT.md) (row media), [Badge](../badge/COMPONENT.md) (row badge), [VisuallyHidden](../visually-hidden/COMPONENT.md) (loading and save-failure announcements), `Icon` (chevron, clear, check, search, retry), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (list), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in `multiple`), [Spinner](../spinner/COMPONENT.md) (`loading` and saving in the trigger), [Skeleton](../skeleton/COMPONENT.md) (loading rows), [EmptyPage](../empty-page/COMPONENT.md) (empty state, load error), [Button](../button/COMPONENT.md) (retry), [Divider](../divider/COMPONENT.md) (`Separator`), [Thumbnail](../thumbnail/COMPONENT.md) and [Avatar](../avatar/COMPONENT.md) (row media), [Badge](../badge/COMPONENT.md) (row badge), [VisuallyHidden](../visually-hidden/COMPONENT.md) (loading and save-failure announcements), `Icon` (chevron, clear, check, search, retry), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame), [Input](../input/COMPONENT.md) (the start segment of `Input.Wrapper`)
 - **See also:** [NativeSelect](../native-select/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Radio](../radio/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

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

@@ -59,8 +59,9 @@ Slider                 field frame (FieldFrame): className, ref, rest
 | `required` | `boolean` | — | Red `*` after the label (`aria-hidden`); a range always has a value, so there is no native `required`. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the track (`aria-describedby`). Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
-| `invalid` | `boolean` | — | `aria-invalid` on the range input and a danger focus ring on the thumb. A non-empty `error` implies it. |
+| `invalid` | `boolean` | — | `aria-invalid` on the range input, a danger fill (over any `tone`) and a danger focus ring on the thumb. A non-empty `error` implies it. |
 | `showValue` | `boolean` | `false` | Shows the current value at the end of the label row (tabular numbers, `aria-hidden` — the input announces it). |
 | `formatValue` | `(value: number) => string` | — | Formats the shown value and `aria-valuetext` (units, currency). |
 | `id` | `string` | — | Id of the range input (generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
@@ -121,10 +122,10 @@ Tone never carries meaning alone: the label names what the value means.
 |---|---|---|
 | default | — | `data-size`, `data-tone` (`data-orientation="vertical"` when upright); track `fill-strong`, tone pill up to the thumb centre, opaque thumb |
 | hover | pointer (fine pointers only) | light liquid glass: the thumb grows to 110%, turns translucent and slightly frosted |
-| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the root, `aria-invalid` on the input; the error replaces the hint, danger focus ring; the control shakes once when an error arrives (`data-shake` on the frame) |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the root, `aria-invalid` on the input; the error replaces the hint, danger fill over any `tone`, danger focus ring; the control shakes once when an error arrives (`data-shake` on the frame) |
 | pressed | dragging | clear glass: the thumb grows to 125%, the rounded end of the fill shows through |
 | focus-visible | keyboard | outer focus ring around the thumb |
-| disabled | `disabled` | `data-disabled="true"` on the root, native `disabled`; muted track and fill, flat thumb, `cursor: not-allowed` |
+| disabled | `disabled` | `data-disabled="true"` on the root, native `disabled`; muted track and fill, a flat opaque thumb, `cursor: not-allowed` |
 | saving | `onCommit` returned a pending promise | `data-pending="true"` on the root, `aria-busy` on the input; the thumb quiets to 0.6 (`fast`, both ways); the slider stays usable — only the latest commit's answer counts |
 | refused | that promise rejected | the value goes back to the last saved one (`onValueChange` when controlled); `data-settling` glides the thumb and the fill there (`base`, emphasized) |