prime-ui-kit 0.16.0 → 0.18.0

package/dist/skill/reference/components/field-list/examples/totals.tsx

@@ -0,0 +1,82 @@
+/** A deal bonus split between the team: the share takes a narrow column, and the totals row under the lines sums the shares and the amounts — `renderTotals`, `width`. */
+import { FieldList, type FieldListColumn, Input } from "prime-ui-kit";
+import * as React from "react";
+
+type Share = { id: string; member: string; percent: string };
+
+const BONUS = 240_000;
+
+const COLUMNS: FieldListColumn[] = [
+  { label: "Участник" },
+  { label: "Доля", width: "xs" },
+  { label: "Сумма", width: "m" },
+];
+
+const SHARES: Share[] = [
+  { id: "sokolova", member: "Анна Соколова", percent: "50" },
+  { id: "demin", member: "Олег Демин", percent: "30" },
+  { id: "kotova", member: "Ирина Котова", percent: "20" },
+];
+
+const RUB = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+const percentOf = (share: Share) => Number(share.percent.replace(",", ".")) || 0;
+
+export default function FieldListTotalsExample() {
+  const [shares, setShares] = React.useState(SHARES);
+
+  return (
+    <FieldList
+      label="Бонус по сделке"
+      hint="Доли в сумме дают 100 %."
+      columns={COLUMNS}
+      value={shares}
+      onValueChange={setShares}
+      getId={(share) => share.id}
+      getLabel={(share) => share.member}
+      createItem={() => ({ id: crypto.randomUUID(), member: "", percent: "" })}
+      addLabel="Добавить участника"
+      renderItem={(share, row) => (
+        <>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field
+                value={share.member}
+                onChange={(event) => row.update({ member: event.target.value })}
+              />
+            </Input.Wrapper>
+          </Input.Root>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field
+                value={share.percent}
+                inputMode="decimal"
+                onChange={(event) => row.update({ percent: event.target.value })}
+              />
+              <Input.InlineAffix side="end">%</Input.InlineAffix>
+            </Input.Wrapper>
+          </Input.Root>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field value={RUB.format((BONUS * percentOf(share)) / 100)} readOnly />
+            </Input.Wrapper>
+          </Input.Root>
+        </>
+      )}
+      renderTotals={(items) => {
+        const percent = items.reduce((sum, share) => sum + percentOf(share), 0);
+        return (
+          <>
+            {null}
+            {`${percent} %`}
+            {RUB.format((BONUS * percent) / 100)}
+          </>
+        );
+      }}
+    />
+  );
+}

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

@@ -14,7 +14,7 @@
 ## When not to use
 - One choice among options with a heading → [Radio](../radio/COMPONENT.md) `Radio.Group label`, a [SegmentedControl](../segmented-control/COMPONENT.md) or [ButtonGroup](../button-group/COMPONENT.md) `label`.
 - A bounded block with a surface (a settings panel) → [Card](../card/COMPONENT.md) `Card.Root`; a Fieldset inside it groups the fields.
-- A page section with a title and actions → [PageContent](../page-content/COMPONENT.md) sections.
+- A page section with a title and actions → [Page](../../layout/page/COMPONENT.md) sections (`Page.Section`).
 - A group of settings with a title and a trailing control (a «Сбросить» button, a master switch) → `Card.Root variant="panel"` with `Card.Header` (`Card.Title` + the control) and the Fieldset in `Card.Body`, named by the title (`aria-labelledby`).
 - A single field's label → the field's own `label`.
 

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

@@ -14,7 +14,7 @@ export default function FieldsetStatesExample() {
           <Fieldset label="Сделка" disabled={state.disabled}>
             <Input.Root label="Название">
               <Input.Wrapper>
-                <Input.Field defaultValue="Годовая лицензия, 40 мест" />
+                <Input.Field defaultValue="Лицензия, 40 мест" />
               </Input.Wrapper>
             </Input.Root>
             <SegmentedControl.Root label="Тип" defaultValue="new">

package/dist/skill/reference/components/file-upload/COMPONENT.md

@@ -120,6 +120,7 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | `required` | `boolean` | — | Red `*` after the label and native `required` on the input. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the field. 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 field (a rejected file, too few files); implies `invalid`. |
 | `invalid` | `boolean` | — | Danger line and icon of the zone, `aria-invalid` on the input. A non-empty `error` implies it. |
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring of the drop zone and the add tile (`data-focus-ring="false"`); focus, keyboard and ARIA stay. The picker Button keeps its ring. |
@@ -424,7 +425,7 @@ Also `data-size`, `data-variant` on the zone, `data-size` on Item, `data-status`
 | [controlled.tsx](examples/controlled.tsx) | Documents of a deal in one list: the files already on the server and new uploads after them, saved on every change, and a button brings back the saved set — `value`, `onValueChange`, `queue`. |
 | [in-form.tsx](examples/in-form.tsx) | A contract upload form: submit checks the required scan, its error shakes in and leaves once a file is picked or removed — `required`, `error`, `name`, `value`. |
 | [narrow.tsx](examples/narrow.tsx) | In a phone-width column the zone text wraps, a long file name truncates, and a gallery goes three across and then two, the cover keeping two columns and the remove buttons shown without hover — `layout`, `cover`. |
-| [screen.tsx](examples/screen.tsx) | A media library of a catalog object as a work screen: the title, the object and a PageToolbar with sections, search, order and upload in the app header; uploads in FileUpload tiles through a queue; a grid of Thumbnails that open MediaViewer out of the tile or are picked for bulk download and delete; a Skeleton first load and a filtered empty state in a Crossfade — `trigger`, `layout`. |
+| [screen.tsx](examples/screen.tsx) | A media library of a catalog object as a work screen: the title, the object and a toolbar with sections, search, order and upload in its top bar; uploads in FileUpload tiles through a queue; a grid of Thumbnails that open MediaViewer out of the tile or are picked for bulk download and delete; a Skeleton first load and a filtered empty state in a Crossfade — `trigger`, `layout`. |
 
 ## Mistakes
 - A `Label` and a `Hint` placed around the zone by hand → pass `label`, `hint`, `error`.

package/dist/skill/reference/components/file-upload/examples/screen.module.css

@@ -1,5 +1,5 @@
-/* Media library: a work screen — the app header carries the title and the tools; this module lays
-   out the library block only, the page rhythm comes from PageContent. */
+/* Media library: a work screen — the page top bar carries the title and the tools; this module lays
+   out the library block only, the page rhythm comes from Page. */
 
 .bar {
   display: flex;

package/dist/skill/reference/components/file-upload/examples/screen.tsx

@@ -1,6 +1,5 @@
-/** A media library of a catalog object as a work screen: the title, the object and a PageToolbar with sections, search, order and upload in the app header; uploads in FileUpload tiles through a queue; a grid of Thumbnails that open MediaViewer out of the tile or are picked for bulk download and delete; a Skeleton first load and a filtered empty state in a Crossfade — `trigger`, `layout`. */
+/** A media library of a catalog object as a work screen: the title, the object and a toolbar with sections, search, order and upload in its top bar; uploads in FileUpload tiles through a queue; a grid of Thumbnails that open MediaViewer out of the tile or are picked for bulk download and delete; a Skeleton first load and a filtered empty state in a Crossfade — `trigger`, `layout`. */
 import {
-  AppHeader,
   Button,
   ConfirmDialog,
   Crossfade,
@@ -12,8 +11,7 @@ import {
   Icon,
   MediaViewer,
   type MediaViewerItem,
-  PageContent,
-  PageToolbar,
+  Page,
   SegmentedControl,
   Select,
   Skeleton,
@@ -365,76 +363,62 @@ export default function FileUploadScreenExample() {
   const totalSize = visible.reduce((sum, media) => sum + media.size, 0);
 
   return (
-    <>
-      {/* A work screen: in an app this header fills the shell's `header` slot and carries the page —
-          the only h1, the object it belongs to and the page's tools; main has no PageContent.Header. */}
-      <AppHeader.Root>
-        <AppHeader.Start>
-          <AppHeader.Title>
-            Медиатека
-            <AppHeader.Description>БЦ «Северная башня», Невский пр., 112</AppHeader.Description>
-          </AppHeader.Title>
-        </AppHeader.Start>
-        <AppHeader.Tools>
-          <SmartFilter.Root
-            fields={[]}
-            search={search}
-            onSearchChange={setSearch}
-            labels={{ searchPlaceholder: "Поиск по названию" }}
-          >
-            <PageToolbar.Root aria-label="Медиатека">
-              <PageToolbar.Tools>
-                <SmartFilter.Toolbar />
-              </PageToolbar.Tools>
-              <PageToolbar.Sections>
-                <SegmentedControl.Root
-                  fullWidth
-                  value={section}
-                  onValueChange={(value) => setSection(value as Section)}
-                  aria-label="Раздел"
-                >
-                  {SECTIONS.map((item) => (
-                    <SegmentedControl.Item key={item.value} value={item.value}>
-                      {item.label}
-                      {loading ? null : (
-                        <SegmentedControl.Count>{count(item.value)}</SegmentedControl.Count>
-                      )}
-                    </SegmentedControl.Item>
-                  ))}
-                </SegmentedControl.Root>
-              </PageToolbar.Sections>
-              <PageToolbar.View>
-                <Select.Root value={order} onValueChange={(value) => setOrder(value as Order)}>
-                  <Select.Trigger aria-label="Порядок">
-                    <Select.TriggerIcon>
-                      <Icon name="sort.descending" />
-                    </Select.TriggerIcon>
-                    <Select.Value />
-                  </Select.Trigger>
-                  <Select.Content>
-                    {ORDERS.map((item) => (
-                      <Select.Item key={item.value} value={item.value}>
-                        {item.label}
-                      </Select.Item>
-                    ))}
-                  </Select.Content>
-                </Select.Root>
-              </PageToolbar.View>
-              <PageToolbar.Actions>
-                <Button.Root onClick={() => picker.current?.open()}>
-                  <Button.Icon>
-                    <Icon name="action.upload" />
-                  </Button.Icon>
-                  Загрузить
-                </Button.Root>
-              </PageToolbar.Actions>
-            </PageToolbar.Root>
-          </SmartFilter.Root>
-        </AppHeader.Tools>
-      </AppHeader.Root>
-
-      <PageContent.Root>
-        <PageContent.Body>
+    <SmartFilter.Root
+      fields={[]}
+      search={search}
+      onSearchChange={setSearch}
+      labels={{ searchPlaceholder: "Поиск по названию" }}
+    >
+      <Page.Root>
+        {/* A work screen titles itself in its top bar: the only h1, the object it belongs to, the
+          page's tools — sections, search, order — and the upload. */}
+        <Page.TopBar>
+          <Page.Heading>
+            <Page.Title>Медиатека</Page.Title>
+            <Page.Description>БЦ «Северная башня», Невский пр., 112</Page.Description>
+          </Page.Heading>
+          <Page.Tools aria-label="Медиатека">
+            <SegmentedControl.Root
+              value={section}
+              onValueChange={(value) => setSection(value as Section)}
+              aria-label="Раздел"
+            >
+              {SECTIONS.map((item) => (
+                <SegmentedControl.Item key={item.value} value={item.value}>
+                  {item.label}
+                  {loading ? null : (
+                    <SegmentedControl.Count>{count(item.value)}</SegmentedControl.Count>
+                  )}
+                </SegmentedControl.Item>
+              ))}
+            </SegmentedControl.Root>
+            <SmartFilter.Toolbar />
+            <Select.Root value={order} onValueChange={(value) => setOrder(value as Order)}>
+              <Select.Trigger aria-label="Порядок">
+                <Select.TriggerIcon>
+                  <Icon name="sort.descending" />
+                </Select.TriggerIcon>
+                <Select.Value />
+              </Select.Trigger>
+              <Select.Content>
+                {ORDERS.map((item) => (
+                  <Select.Item key={item.value} value={item.value}>
+                    {item.label}
+                  </Select.Item>
+                ))}
+              </Select.Content>
+            </Select.Root>
+          </Page.Tools>
+          <Page.Actions>
+            <Button.Root onClick={() => picker.current?.open()}>
+              <Button.Icon>
+                <Icon name="action.upload" />
+              </Button.Icon>
+              Загрузить
+            </Button.Root>
+          </Page.Actions>
+        </Page.TopBar>
+        <Page.Body>
           {/* Uploads in flight: the add tile is also the drop zone; a done file moves into the grid. */}
           <FileUpload.Root
             label="Новые файлы"
@@ -447,7 +431,7 @@ export default function FileUploadScreenExample() {
             picker={picker}
           />
 
-          <PageContent.Section
+          <Page.Section
             label="Файлы"
             description={
               <span aria-live="polite">
@@ -459,7 +443,7 @@ export default function FileUploadScreenExample() {
               </span>
             }
           >
-            <PageContent.Actions>
+            <Page.Actions>
               <Crossfade state={selecting ? "select" : "browse"}>
                 {selecting ? (
                   <div className={styles.bar}>
@@ -509,7 +493,7 @@ export default function FileUploadScreenExample() {
                   </div>
                 )}
               </Crossfade>
-            </PageContent.Actions>
+            </Page.Actions>
 
             <Crossfade state={state} aria-busy={loading}>
               {loading ? (
@@ -621,7 +605,7 @@ export default function FileUploadScreenExample() {
                 </EmptyPage.Root>
               ) : null}
             </Crossfade>
-          </PageContent.Section>
+          </Page.Section>
 
           <MediaViewer
             items={viewerItems}
@@ -641,8 +625,8 @@ export default function FileUploadScreenExample() {
               </Button.Root>
             )}
           />
-        </PageContent.Body>
-      </PageContent.Root>
-    </>
+        </Page.Body>
+      </Page.Root>
+    </SmartFilter.Root>
   );
 }

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

@@ -97,6 +97,7 @@ Decided by the items, not a prop: the number of items and their ratios.
 - Tiles are `--prime-gallery-gap` (2px) apart; the gaps are the gallery's own background, transparent by default (a host may paint it: a message paints the incoming surface).
 - The outer corners are rounded (`--prime-radius-l`). A host that shapes and clips it itself (a message) passes `maxSize`: the gallery takes that length as its cap instead of its host's width and draws no radius of its own.
 - At any width the album keeps its layout: tiles scale with the gallery, never rearrange.
+- A video tile shorter than 6.5rem (a small tile of a phone album) has no room for the centred play mark under the length pill: it shows the length alone, so the two marks never collide.
 
 ## Accessibility
 

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

@@ -224,7 +224,7 @@ A `tone` wins over `color`. Say the status in the label too, never only by color
 | [states.tsx](examples/states.tsx) | Skeleton rows in the chart's geometry while it loads, an empty period and a report you may only look at, its today line on the report day — `loading`, `empty`, `readOnly`, `today`. |
 | [controlled.tsx](examples/controlled.tsx) | The zoom owned by the page: presets in the toolbar and the built-in switch change one state — `scale`, `onScaleChange`. |
 | [narrow.tsx](examples/narrow.tsx) | At 360 px the first column keeps only the avatars, the toolbar moves to its own row and the axis scrolls under the pinned column — `renderRowAvatar`. |
-| [screen.tsx](examples/screen.tsx) | A team schedule as a work screen: the title with the people shown and a PageToolbar with search, filters, team sections and the primary action in the app header over a full-height Gantt; moves saved or refused, new work drawn and named in a Modal, details in a Drawer — `scrollHeight`, `onBarChange`, `onBarCreate`, `onItemOpen`. |
+| [screen.tsx](examples/screen.tsx) | A team schedule as a work screen: the title with the people shown and a toolbar with search, filters, team sections and the primary action in its top bar over a full-height Gantt; moves saved or refused, new work drawn and named in a Modal, details in a Drawer — `scrollHeight`, `onBarChange`, `onBarCreate`, `onItemOpen`. |
 
 ## Mistakes
 - Updating the rows before the request succeeds (optimistic) → the chart cannot glide back on reject; update them when `onBarChange` resolves, or before you resolve it.

package/dist/skill/reference/components/gantt/examples/screen.module.css

@@ -1,5 +1,5 @@
 /* Schedule: a work screen — the header carries the title and the tools, the page fills the app
-   panel (`AppShell.Root fillViewport` + `PageContent.Root fill`) and the chart takes the free
+   panel (`AppShell.Root fillViewport` + `Page.Root fill`) and the chart takes the free
    height. */
 
 /* On a short screen the chart keeps room for a few rows; the page scrolls instead. */

package/dist/skill/reference/components/gantt/examples/screen.tsx

@@ -1,6 +1,5 @@
-/** A team schedule as a work screen: the title with the people shown and a PageToolbar with search, filters, team sections and the primary action in the app header over a full-height Gantt; moves saved or refused, new work drawn and named in a Modal, details in a Drawer — `scrollHeight`, `onBarChange`, `onBarCreate`, `onItemOpen`. */
+/** A team schedule as a work screen: the title with the people shown and a toolbar with search, filters, team sections and the primary action in its top bar over a full-height Gantt; moves saved or refused, new work drawn and named in a Modal, details in a Drawer — `scrollHeight`, `onBarChange`, `onBarCreate`, `onItemOpen`. */
 import {
-  AppHeader,
   Avatar,
   Badge,
   Button,
@@ -17,8 +16,7 @@ import {
   Input,
   Modal,
   matchesSmartFilter,
-  PageContent,
-  PageToolbar,
+  Page,
   ProgressBar,
   SegmentedControl,
   Select,
@@ -441,73 +439,57 @@ export default function GanttScreenExample() {
   const detail = selected?.bar;
 
   return (
-    <>
-      {/* A work screen: in an app this header fills the shell's `header` slot and carries the page —
-          the only h1 and the page's tools; main has no PageContent.Header. */}
-      <AppHeader.Root>
-        <AppHeader.Start>
-          <AppHeader.Title>
-            Загрузка команды
-            <AppHeader.Description>
+    <SmartFilter.Root
+      fields={FIELDS}
+      value={filter}
+      onValueChange={setFilter}
+      search={search}
+      onSearchChange={setSearch}
+    >
+      <Page.Root fill>
+        {/* A work screen titles itself in its top bar: the only h1, the teams, the search and the
+          filters, the one primary action. */}
+        <Page.TopBar>
+          <Page.Heading>
+            <Page.Title>Загрузка команды</Page.Title>
+            <Page.Description>
               {loading ? "Загружаем график…" : `Сотрудников: ${rows.length} из ${people.length}`}
-            </AppHeader.Description>
-          </AppHeader.Title>
-        </AppHeader.Start>
-        <AppHeader.Tools>
-          <SmartFilter.Root
-            fields={FIELDS}
-            value={filter}
-            onValueChange={setFilter}
-            search={search}
-            onSearchChange={setSearch}
-          >
-            <PageToolbar.Root aria-label="Загрузка команды">
-              <PageToolbar.Tools>
-                <SmartFilter.Toolbar />
-              </PageToolbar.Tools>
-              <PageToolbar.Sections>
-                <SegmentedControl.Root
-                  fullWidth
-                  value={team}
-                  onValueChange={setTeam}
-                  aria-label="Команда"
-                >
-                  <SegmentedControl.Item value="all">
-                    Все<SegmentedControl.Count>{people.length}</SegmentedControl.Count>
-                  </SegmentedControl.Item>
-                  {TEAMS.map((item) => (
-                    <SegmentedControl.Item key={item.value} value={item.value}>
-                      {item.label}
-                      <SegmentedControl.Count>
-                        {people.filter((person) => person.team === item.value).length}
-                      </SegmentedControl.Count>
-                    </SegmentedControl.Item>
-                  ))}
-                </SegmentedControl.Root>
-              </PageToolbar.Sections>
-              <PageToolbar.Actions>
-                <Button.Root
-                  onClick={() => {
-                    setErrors({});
-                    setDraft({ personId: null, dates: null });
-                  }}
-                >
-                  <Button.Icon>
-                    <Icon name="action.add" />
-                  </Button.Icon>
-                  Назначить
-                </Button.Root>
-              </PageToolbar.Actions>
-              <PageToolbar.Chips>
-                <SmartFilter.Chips />
-              </PageToolbar.Chips>
-            </PageToolbar.Root>
-          </SmartFilter.Root>
-        </AppHeader.Tools>
-      </AppHeader.Root>
-
-      <PageContent.Root fill>
-        <PageContent.Body>
+            </Page.Description>
+          </Page.Heading>
+          <Page.Tools aria-label="Загрузка команды">
+            <SegmentedControl.Root value={team} onValueChange={setTeam} aria-label="Команда">
+              <SegmentedControl.Item value="all">
+                Все<SegmentedControl.Count>{people.length}</SegmentedControl.Count>
+              </SegmentedControl.Item>
+              {TEAMS.map((item) => (
+                <SegmentedControl.Item key={item.value} value={item.value}>
+                  {item.label}
+                  <SegmentedControl.Count>
+                    {people.filter((person) => person.team === item.value).length}
+                  </SegmentedControl.Count>
+                </SegmentedControl.Item>
+              ))}
+            </SegmentedControl.Root>
+            <SmartFilter.Toolbar />
+          </Page.Tools>
+          <Page.Actions>
+            <Button.Root
+              onClick={() => {
+                setErrors({});
+                setDraft({ personId: null, dates: null });
+              }}
+            >
+              <Button.Icon>
+                <Icon name="action.add" />
+              </Button.Icon>
+              Назначить
+            </Button.Root>
+          </Page.Actions>
+          <Page.Chips>
+            <SmartFilter.Chips />
+          </Page.Chips>
+        </Page.TopBar>
+        <Page.Body>
           <Gantt<Person, Assignment>
             aria-label="Загрузка команды внедрения"
             className={styles.chart}
@@ -719,8 +701,8 @@ export default function GanttScreenExample() {
               </Drawer.Footer>
             </Drawer.Content>
           </Drawer.Root>
-        </PageContent.Body>
-      </PageContent.Root>
-    </>
+        </Page.Body>
+      </Page.Root>
+    </SmartFilter.Root>
   );
 }

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

@@ -8,6 +8,7 @@
 ## When to use
 - Under a control without `hint` / `error` props (an embedded `Datepicker.Panel`, a custom control), where you wire the ids yourself: format rules, limits, where the value comes from.
 - As the error message of such a control (`invalid`), in the same slot as the hint.
+- A status the field's value has (a deadline that nears, a check that passed): `tone`, with the status in the words.
 
 ## When not to use
 - Input, Textarea, Select, Checkbox, Slider, SegmentedControl and other fields with `hint` / `error` props → pass the props; they render Hint and link the ids ([Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Slider](../slider/COMPONENT.md)).
@@ -36,6 +37,7 @@ Hint.Root      <p> with the text
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the paired field: 12/16 for xs–m, 13/20 for l and xl. Without it the tier of its host, else `m`. |
+| `tone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of the text (a deadline that nears, a check that passed). The words carry the status, the color repeats it; `invalid` and `disabled` take over the color. |
 | `invalid` | `boolean` | `false` | Error styling: danger text that drops in (fade + 4 px from above). |
 | `disabled` | `boolean` | `false` | Disabled text color, next to a disabled control. A disabled `Fieldset` around the hint sets it too. |
 | `children` | `ReactNode` | — | Text, optionally with `Hint.Icon` first. |
@@ -49,7 +51,15 @@ Hint.Root      <p> with the text
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the glyph), `className` and the other span attributes. |
 
 ## Variants
-Hint has no `variant` or `tone`; its states are flags.
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | Muted text | Format rules, limits, where the value comes from | yes |
+| `success` | Success text | The value passed a check («ИНН проверен») | |
+| `warning` | Warning text | The value needs attention soon («Осталось 12 дней») | |
+| `danger` | Danger text, no `aria-invalid` | A status of the data, not a validation error («Срок истёк») | |
+
+The words carry the status; the color only repeats it, and a `Hint.Icon` with the status glyph adds a shape. A validation error is `invalid` (or a field's `error`), never `tone="danger"`. `invalid` and `disabled` take over the tone's color.
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -68,11 +78,12 @@ The hint is always smaller than the field text; use the field's size.
 | `invalid` | Danger text, drops in | Validation error | `false` |
 | `disabled` | Disabled text | Under a disabled control | `false` |
 
-**Combinations** — one element switches between the hint text and the error text with `invalid` (no layout jump); a standalone hint that changes after an action stays mounted with `aria-live="polite"` (inside a field the frame does it). `invalid` and `disabled` together make no sense. There is no success state: use neutral text, or a [Banner](../banner/COMPONENT.md) for a result.
+**Combinations** — one element switches between the hint text and the error text with `invalid` (no layout jump); a standalone hint that changes after an action stays mounted with `aria-live="polite"` (inside a field the frame does it). `invalid` and `disabled` together make no sense. A result of the whole form goes to a [Banner](../banner/COMPONENT.md), not a toned hint.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
+| status | `tone` | `data-tone` with the shared text tone (none for `neutral`, and none while `invalid` or `disabled`); the color eases between tones |
 | error | `invalid` | `data-invalid="true"`; the message drops in over `fast` (fade + `--prime-space-1` from above, no shake, no layout shift) and the color eases from the hint color |
 | disabled | `disabled`, or a disabled `Fieldset` around it | `data-disabled="true"` |
 | size | `size`, else the host tier | `data-size` |
@@ -106,6 +117,7 @@ No `labels`.
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Help text under a calendar that has no hint of its own, linked to it through `id` and `aria-describedby` — `id`. |
+| [variants.tsx](examples/variants.tsx) | Status hints whose words carry the status and the color repeats it — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier, one per field tier: 12/16 for xs–m, 13/20 for l and xl — `size`. |
 | [states.tsx](examples/states.tsx) | Default help text next to an error and a hint under a disabled control — `invalid`, `disabled`. |
 | [with-icon.tsx](examples/with-icon.tsx) | A leading icon centred on the first line, in the default and the error state — `Hint.Icon`. |
@@ -116,6 +128,8 @@ No `labels`.
 - A separate hint and error element at the same time → one element; the error replaces the hint.
 - Hint without `id` + `aria-describedby` → the screen reader does not connect it to the field.
 - Hint size different from the field size → use the same `size`, or none inside a sized host.
+- `tone="danger"` for a validation error → `invalid` (or the field's `error`): only it sets `aria-invalid`.
+- A status by color alone («12 д.» in orange) → the words say it («Осталось 12 дней»), the tone repeats it.
 - `role="alert"` on a field error → none; the field frame announces it, a standalone hint takes `aria-live="polite"`.
 
 ## Related

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

@@ -1,12 +1,21 @@
 /* Layout of the Hint scenarios: semantic tokens only. */
 
-/* overview.tsx, hint-or-error.tsx: control → support row at the m-tier hint gap. */
+/* hint-or-error.tsx: control → support row at the m-tier hint gap. */
 .field {
   display: grid;
   justify-items: start;
   gap: var(--prime-control-m-hint-gap);
 }
 
+/* overview.tsx: the same pair in a 320 px column — an embedded calendar measures its container
+   for its month, so the column gives it one. */
+.calendarField {
+  display: grid;
+  justify-items: start;
+  gap: var(--prime-control-m-hint-gap);
+  width: min(100%, calc(var(--prime-space-20) * 4));
+}
+
 .actions {
   display: flex;
   flex-wrap: wrap;

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

@@ -8,7 +8,7 @@ export default function HintOverviewExample() {
   const hintId = React.useId();
 
   return (
-    <div className={styles.field}>
+    <div className={styles.calendarField}>
       <Datepicker.Panel
         mode="single"
         role="group"