prime-ui-kit 0.15.0 → 0.16.0

package/dist/skill/cheatsheet.md

@@ -15,8 +15,8 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 
 - Omit `size` for the default `m` — never write `size="m"`.
 - Set `size` on the root (`Input.Root size="s"`, `Select.Root size="s"`) — not on `Input.Field` or `Select.Trigger`.
-- One tier for a whole region: `<ControlSizeProvider value="s">` around a dense toolbar — not `size="s"` on one control to make it fit. Select, NativeSelect, TagSelect, Datepicker, Tabs and SmartFilter do not read the host tier: give them the same `size` yourself.
-- Inside a host (Popover, Banner, LoginForm, the DataTable `toolbar`) leave `Button.Root`, `Input.Root`, `Textarea.Root`, `Checkbox.Root`, `DigitInput` and the other host-reading controls without `size` — the host passes its tier ([full list](api-contract.md)).
+- One tier for a whole region: `<ControlSizeProvider value="s">` around a dense toolbar — not `size="s"` on one control to make it fit.
+- Inside a sized host (Popover, Banner, LoginForm, the DataTable `toolbar`) leave the kit controls without `size` — the host passes its tier ([the host tier](api-contract.md#size-and-the-host-tier)).
 - A control in a table cell or a card header row is one tier down: `<Button.Root size="s" variant="ghost" tone="neutral">`.
 
 ## Structure
@@ -28,9 +28,9 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 ## Fields
 
 - Frame a field with props on the root: `<Input.Root label="Почта" hint="…" error="…" required>` — not a separate `Label` / `Hint` next to it.
-- Mark the minority: `required` when most fields are optional, `optional` when most are required — not both everywhere.
+- Mark the minority, never both everywhere ([the rule](api-contract.md#forms)).
 - Placeholder is an example value (`name@company.ru`) — never the label.
-- Checkbox, Switch, Radio: the text is the part `<Checkbox.Label>`, `hint` / `error` sit on `Checkbox.Root` — not a `label` prop.
+- Checkbox, Switch, Radio: the text is the part `<Checkbox.Label>`, `hint` / `error` sit on `Checkbox.Root` — and a radio choice's on `Radio.Group` ([choice controls](api-contract.md#choice-controls)) — not a `label` prop.
 - Show `error` after blur or on submit; `<form noValidate onSubmit>` + `<Button.Root type="submit" loading>` — not validation on every keystroke.
 - Groups of fields: `<Fieldset label="Контакты" disabled={saving}>` with the submit `<Button.Root loading>` outside it — not a hand-reset `<fieldset>` with a `Typography` heading, not `disabled` on every field while saving. One choice with a heading (`Radio.Group label`) needs no Fieldset.
 - Uploads: `const queue = useUploadQueue({ upload })` → `<FileUpload.Root queue={queue} />` (`FileUpload.Queue` when the picker lives elsewhere) — progress, «В очереди», the reason of a failure, retry and remove come with it (three at once by default, `concurrency`); not a hand-kept list of files with own progress bars. A photo appears at once from its local preview.
@@ -49,7 +49,7 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - Uncontrolled by default: `defaultValue`, `defaultChecked`, `defaultOpen`.
 - Controlled triads, same names everywhere: `value` / `onValueChange`, `checked` / `onCheckedChange`, `open` / `onOpenChange` — not `onChange(event)` (except the native `Input.Field` / Textarea `onChange`), `isOpen`, `onToggle`.
 - Selection count is `multiple` (`Select.Root multiple`) — not `type="multiple"`.
-- A slow or risky action is an async event: return the request's Promise from `onConfirm`, `onCommit`, `onReorder`, `onBarChange`, `onSend`, a Switch's `onCheckedChange`, a Slider's `onCommit`, a DigitInput's `onComplete`, a Kanban or FileUpload change, a Badge `onRemove`, TagSelect `onCreate`… — the component shows pending, keeps the change on resolve and rolls it back on reject; not `true` / `false`, not your own pending flag, no `onBeforeX`.
+- A slow or risky action is an async event: return the request's Promise from `onConfirm`, `onCommit`, `onReorder`, `onBarChange`, `onSend`, a Switch's `onCheckedChange`, a Slider's `onCommit`, a DigitInput's `onComplete`, a Kanban or FileUpload change, a Badge `onRemove`, TagSelect `onCreate`… — the component shows pending, keeps the change on resolve and undoes it on reject (each component's COMPONENT.md says how); not `true` / `false`, not your own pending flag, no `onBeforeX`.
 - A Select that saves on pick: return the save's Promise from `onValueChange` — the value shows at once with a Spinner on the trigger and a rejection rolls it back (`labels.changeFailed`); never reset the value by hand. A «Новый клиент» row in the list is `Select.Action` (`onSelect`), never a fake `Select.Item` with a sentinel value or a button under the field.
 - An option reads its parts by element type: put `Avatar.Root`, `Thumbnail.Root`, `Badge.Root` and `Select.Item*` straight in the item and call your helper as a function (`{clientAvatar(c)}`), not as `<ClientAvatar />`; anything else trailing goes in `Select.ItemMeta`.
 - Create from a search: one `persistent` `CommandMenu.Item` at the end («Создать клиента «{query}»», while the query is not empty) — it stays when a namesake matches; `CommandMenu.Empty` holds only the text.
@@ -86,58 +86,58 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 ## Cards and surfaces
 
 - `Card.Root` only for a bounded block with its own title: a KPI tile (`variant="stat-trend"`), a settings panel (`variant="panel"`), side facts — not around a whole section, a form field or a page.
-- Never a card in a card, and never a `DataTable` inside a Card — the table is already a filled block.
+- Never a `DataTable` inside a Card — the table is already a filled block; a card in a card only sparingly ([the rule](foundations.md#card-in-a-card)).
 - Section without a card: `<PageContent.Section label="…">` + the content (a link or button beside the heading in `PageContent.Actions`) — not a hand-made `<section>` + `Typography as="h2"` + own gap.
-- The tiles of a screen (KPI cards, charts, panels): one `<PageContent.Grid>` with a `<PageContent.Cell span>` per tile — not an `auto-fit` grid per row (the rows would stand 24 apart instead of 16).
+- The tiles of a screen (KPI cards, charts, panels): one `<PageContent.Grid>` with a `<PageContent.Cell span>` per tile — not a grid per row (the rows would stand 24 apart instead of 16).
 - Depth from fill, not lines: no borders around blocks; `<Divider />` only inside a block.
 - Every scroll region is a `ScrollContainer` — never `overflow: auto` on a `div`: its hidden edges fade by themselves (`edges="shadow"` on a filled surface, `"none"` only for a page column), `scrollbar="hidden"` on strips, `snap` on strips of cards, `lock` to hold a list still, `anchor="end"` for a log. Kit components already scroll through it; do not wrap them again.
 - Tabs are a bar, not a container: `Tabs.Root` stands in the host's padding and the panel content goes straight into `Tabs.Panel` — never a Card or a padded `div` around the tabs or inside a panel. In a Modal / Drawer, `Tabs.Root` wraps `X.Header` + `X.Body` and `Tabs.List` goes last into the header — not a tab strip at the top of the body.
 
 ## Tables
 
-- A list page is `<DataTable columns rows getRowKey toolbar={…}>` with `<SmartFilter.Root fields value onValueChange>` + `<SmartFilter.Toolbar />` + `<SmartFilter.Chips />` in `toolbar`; filter rows with `matchesSmartFilter` — not a search Input and a row of Selects above the table.
+- A list page is a `<DataTable columns rows getRowKey>` under the page's `<SmartFilter.Root fields value onValueChange>` with `<SmartFilter.Toolbar />` + `<SmartFilter.Chips />` in its `PageToolbar` ([where the filters go](composition.md#where-the-filters-go)); filter rows with `matchesSmartFilter` — not a search Input and a row of Selects above the table.
 - Search over a table or a list page is always SmartFilter, even with no filter fields yet (`fields={[]}` is a plain search that grows into filters). A search `Input` only outside a filtered list: inside a picker, a settings section, a panel.
 - Paging is built in: `paging="pages"` (default) with `pageSize`, `paging="infinite"` for feeds, `paging="none"` for short lists — not a separate `<Pagination>` under a DataTable.
 - Long lists are virtualized inside the kit: pass the whole array to `DataTable` (with `scrollHeight` or `paging="infinite"`; over 100 rows — grouped, `onReorder` and `renderExpanded` bodies render every row, keep those short or paged), `TagSelect options`, `Chat.Messages items`, `Gantt rows` — never slice it by hand, never wrap a kit list in react-window / react-virtual or your own windowing. Big remote data is still paged or loaded on scroll by the server (`source="server"`, `onLoadMore`).
 - Data the server sorts and pages (thousands of records): `source="server"` + `rowCount`, controlled `sort` / `page` as the request, `page` back to 1 on a new search or filter, old rows kept with `loading` while the next page loads — not a server page passed to the default client mode, and not `rows={[]}` between pages.
-- Categories (sources, platforms, regions) get `color` and the same order of `chartColors` in charts; statuses and meanings get `tone` — never paint categories with tones.
-- A chart with axes or several series: `<ChartFrame.Root series state>` around the library (or your SVG) with `ChartFrame.Plot renderPlot`, `Legend`, `Table` — not a hand-made Card with a grey box while loading and a legend of colored dots.
+- Categories (sources, platforms, regions, teams) get `color` and the same order of `chartColors` in charts; statuses and meanings get `tone` — never paint a status with a palette hue or a category with a tone.
+- A chart with axes or several series: `<ChartFrame.Root series rows state>` around the library (or your SVG) with `ChartFrame.Plot renderPlot` and `Legend`; `rows` is the data table screen readers get — not a hand-made Card with a grey box while loading and a legend of colored dots.
 - A tooltip on your own SVG chart: `<ChartFrame.Tooltip point={{ x, y }} items>` with the pointer in plot coordinates — not a `foreignObject` or a div placed and clamped by hand; it flips only when out of room.
-- Amounts, counts and dates are `numeric` columns; statuses are `Badge.Root color` from one status → color map.
+- Amounts, counts and dates are `numeric` columns; statuses are `Badge.Root tone` from one status → tone map.
 - Rows people order by hand: `onReorder(id, beforeId)` (apply it with `moveBefore`, return the save's Promise) — not a Dnd list rebuilt next to the table.
 - A short list of records people order by hand (stages, priorities) is `<List.Root onReorder>` with `List.Item value` — not up / down buttons or a hand-made `Dnd.Sortable`.
 - Groups that fold: pass `defaultCollapsedGroups={[]}` (or the controlled `collapsedGroups` + `onCollapsedGroupsChange`) — not your own button in `renderGroupHeader` or filtering `rows`. One heatmap over several columns: the same `scale: { min, max }` on each.
 - A trend in a table row is `<Sparkline layout="compact">` in the column's `cell` (a column `width`, series built once, not inline, the same `min` / `max` on every row when rows compare by size); the number itself goes in its own column. A missing day is `value: null`, never `0`.
 - Properties of one record: `<DescriptionList.Root>` of `DescriptionList.Item` — not a hand-made grid of label / value text, not a one-row DataTable.
 - Who is busy when, a plan with dates: `Gantt` with `onBarChange` / `onBarCreate` — not bars drawn by hand or a DataTable of start and end dates. Statuses moved by hand: `Kanban` — `plain` (default, a header plate) or `line` (a header over a line) for a board that is the page's main region, `variant="well"` only when columns must read as bounded queues (WIP limits, sparse columns); never a Card or a filled box around a column.
-- Open a board card with `Kanban.Root onItemClick` (click, Enter, Space, never after a drag) or `getItemHref`; a Gantt row with `onRowClick` / `getRowHref` (the DataTable contract), a bar with `onSelect`; more facts in a bar tooltip with `renderBarTooltip` (it adds lines under the dates). A legend of hues is a row of `Badge.Root color` + `Badge.Dot` in the host's `toolbar`, the category also in text. Hour slots (bookings, appointments) are not Gantt — its unit is a calendar day.
+- Open a board card with `Kanban.Root onItemOpen` (click, Enter, Space, never after a drag) or `getItemHref`; a Gantt row with `onRowClick` / `getRowHref` (the DataTable contract), a bar with `onItemOpen`; more facts in a bar tooltip with `renderBarTooltip` (it adds lines under the dates). A legend of hues is a row of `Badge.Root color` + `Badge.Dot` in the host's `toolbar`, the category also in text. Hour slots (bookings, appointments) are not Gantt — its unit is a calendar day.
 
 ## Chat
 
 - A conversation is `Chat`: `<Chat.Root typing selected search>` with `Chat.Header` (avatar, `Chat.Title`, `Chat.Description`, `Chat.Actions` + `Chat.SearchButton`), `Chat.Search`, `Chat.Pinned`, `<Chat.Messages items getKey getAuthor getDate renderMessage>` and `<Chat.Footer><Composer.Root /></Chat.Footer>` — not a header, a ScrollContainer and a list of your own, not Cards or a Timeline styled as bubbles, not a Textarea with a send button. A list without the rest is `Chat.Root` with `Chat.Messages` alone; one message on its own is `Message.Root`.
 - The list of conversations is `ChatList` — not a `List` or Cards with your own preview, unread counts and «печатает…». Back button and avatar in the chat header are plain children of `Chat.Header`: it lays them out side by side.
 - A dialog loading is `<Chat.Messages loading>` (bubble skeletons that cross-fade into the list) — not a Spinner or grey boxes. A bot's buttons under a message are `Message.Actions` rows of `Button.Root variant="soft" tone="neutral"` (`asChild` for links), never buttons inside `Message.Text`.
-- `renderMessage` returns a `Message.Root` (its `value` and `position` are set for you) or a `Chat.Service`; keep it stable with `useCallback` (other messages it looks up through a ref) — an item renders again only when it, its place or the function changes. Dates, runs and the unread band (`unread={key}`) come from the list.
-- A group chat is `<Chat.Messages type="group">`: put `Message.Author` (`color={hueOf(user.id)}`, `tag`, `Message.AuthorIcon` for a crown) and `Message.Avatar` on every message — the list shows the header on the first of a run and the avatar on the last; a direct chat shows neither.
+- `renderMessage` returns a `Message.Root` (its `value` and `position` are set for you) or a `Chat.Service`; an inline function is fine: an item renders again only when it or its place changes, so a row shows what its item holds, and another message (a reply's original) comes from `entry.find(key)`. Dates, runs and the unread band (`unread={key}`) come from the list.
+- A group chat is `<Chat.Messages group>`: put `Message.Author` (`color={hueOf(user.id)}`, `tag`, `Message.AuthorIcon` for a crown) and `Message.Avatar` on every message — the list shows the header on the first of a run and the avatar on the last; a direct chat shows neither.
 - A voice message is `VoicePlayer` inside `Message.Root`; a round video is `VideoNote` inside `Message.Root`; photos, files, places and contacts are `Message` parts — not FileUpload rows or Cards. The same album outside a chat is `Gallery`. The two players share one API: learn one, use both.
 - A transfer either way is one prop set on every message content (VoicePlayer, VideoNote, `Message.File`, `Message.Media` / `Gallery` items): `transfer` (`remote` · `queued` · `loading` · `failed` · `done`), `transferProgress`, `transferDirection` (`upload` / `download` — the words only), `onCancel` / `onRetry` / `onDownload` (a Promise keeps the disk pending, a rejection is announced; on `Message.Media` / `Gallery` they sit on the root and get the item's index). A `useUploadQueue` item maps as is: `transfer={item.status} transferProgress={item.progress}`. Never your own spinner, bar or ring over media.
 - Send optimistically: `onSend` adds the message with `status="sending"` under a client id and returns; patch `status` to `sent` / `read` / `failed` as the server answers. Keep the row's `key` and `value` when the server id arrives — a re-keyed row enters a second time. Give `Message.Root` `onRetry` for `failed`.
-- A reply or an edit: `<Composer.Context value={id}>` — `onSend` gets `replyTo` / `editOf` and the bar closes itself after the send; never read the replied message from a closure. ↑ in an empty field is `onEditLast`.
+- A reply or an edit: `<Composer.Context messageId={id}>` — `onSend` gets `replyTo` / `editOf` and the bar closes itself after the send; never read the replied message from a closure. ↑ in an empty field is `onEditLast`.
 - «печатает…» on the other side: `Composer onActivityChange` (`typing` / `voice` / `video` / `null`, on a change only) → your socket; on the receiving side `<Chat.Root typing={activity === "typing"}>` (the header's status and the list's typing bubble together). Never send it from `onValueChange`.
 - Appearance: messages that are new at the end enter by themselves — mine and theirs float up a little from below and fade in; the first render, history loaded above and rows scrolled into view never animate. Do not add your own enter animation or `scrollTop = scrollHeight`.
 - `Chat.Messages` scrolls to my message, stays at the end for theirs while the reader is there, and otherwise shows the «N новых» button; `onNewMessage(value, { direction })` is for a sound or a counter, `onRead(values)` for read receipts (only what was really seen). The first unread is `unread={key}`; older history is `hasOlder` + `onLoadOlder`.
-- Jump to a message: `Message.Reply target={id}`, a press on `Chat.Pinned`, or `Chat.Root current={id}` (the chat scrolls to it and the message blinks); search: `Chat.SearchButton` + `Chat.Search` mark, count and step through the matches in texts and transcripts, keeping the others stepped back. Never an outline or a wash of your own on the target or on selected messages. Never `scrollIntoView` or your own transforms on rows.
+- Jump to a message: `Message.Reply target={id}`, a press on `Chat.Pinned`, or `Chat.Root jumpTo={id}` (the chat scrolls to it and the message blinks); search: `Chat.SearchButton` + `Chat.Search` mark, count and step through the matches in texts and transcripts, keeping the others stepped back. Never an outline or a wash of your own on the target or on selected messages. Never `scrollIntoView` or your own transforms on rows.
 - A long history (thousands of messages): nothing to switch on — `Chat.Messages` renders only the rows around the view and keeps the reader's place. With children, every top-level child is one row (a `Message.Root`, or a fragment / your own row component keyed by the message `value`); give pictures their `width` / `height` so a row's size is final before load; jumps, search, selection and the keyboard still reach every message. Not a hand-rolled window, `content-visibility` on rows or a measured bubble.
 - A message's layout is CSS: the bubble fits its content and the time sits at the end of the last line (or of the reactions row). Every size change of a message (reactions, a transcript, an edit, an upload) plays as one built-in stroke, width and height together; a reaction grows the message upward with the time still, the rows above gliding as one block. Never size, measure or animate a bubble yourself; an own content part declares itself with the kit's part contract instead of a wrapper.
 - One sound at a time is built in: a voice message, a video message and a chat video pause each other; `playing` / `onPlayingChange` on `VoicePlayer` or `VideoNote` when the app needs to know. A round video never plays or loops before a press. A recorded voice message without levels gets them from `getWaveform(blob)` once, stored with the message.
-- Transcripts: `transcript="…"` on `VoicePlayer` or `VideoNote` when the text is known, or `onTranscribe={() => api.transcribe(id)}` returning a Promise of the text; the button, the skeleton, the bubble's one-stroke growth and the rollback on a rejection are built in. Store the resolved text with the message. Not a `Message.Text` under the voice message, not a disclosure of your own.
+- Transcripts: `transcript="…"` on `VoicePlayer` or `VideoNote` when the text is known, or `onTranscribe={() => api.transcribe(id)}` returning a Promise of the text; the button and its pending state, the bubble's one-stroke growth and the rollback on a rejection are built in. Store the resolved text with the message. Not a `Message.Text` under the voice message, not a disclosure of your own.
 
 ## Overlays
 
 - Blocking decision or ≤ 4 fields → `Modal` (`<Modal.Content size="s">` for a confirm); long form, filters, details → `Drawer`; a short task that ends by itself (a date, an action, a note) → `Sheet`; small panel at a control → `Popover`; list of actions → `Dropdown`; a field value → `Select`; a name for an icon button → `Tooltip`; ⌘K → `CommandMenu`; a photo, a scan or a video full screen from its thumbnail → `MediaViewer` (an album in a grid is `Gallery`, which opens it for you; a standalone viewer keeps `open` and `index` in two states) — not a Modal with an `<img>`.
 - A record's drawer or modal shows its person or object as `Drawer.Icon` / `Modal.Icon` around `Avatar.Root` / `Thumbnail.Root`. A confirm that asks for input (a reason) is a `Modal size="s"` with the field, `Modal.Confirm` and `Modal.Guard busy` — `ConfirmDialog` is a question only.
 - Never a hand-made `div` backdrop, dialog, menu or tooltip.
-- Every Modal and Drawer has all three zones: `Header` (title, ×) · `Body` (content, scrolls) · `Footer` (actions). Details: `<Drawer.Footer><Drawer.Close><Button.Root variant="outline" tone="neutral">Закрыть</Button.Root></Drawer.Close></Drawer.Footer>`, plus the main action last; a form: «Отмена» + submit. Not a drawer that ends with the body, not Save at the bottom of the body. A `Sheet` (from the bottom edge) is the opposite: no footer by default — a pick or a swipe ends it — and its header is optional: keep it when the content needs a title, drop it (× and hairline go too) when the content speaks for itself, with `aria-label` on `Sheet.Content`. Never `Drawer.Content side="bottom"`.
+- Every Modal and Drawer has its `Header` (title, ×); `Body` (content, scrolls) and `Footer` (actions) are there when it has content and actions. Actions always go into the `Footer`: details `<Drawer.Footer><Drawer.Close><Button.Root variant="outline" tone="neutral">Закрыть</Button.Root></Drawer.Close></Drawer.Footer>`, plus the main action last; a form: «Отмена» + submit — not Save at the bottom of the body. A `Sheet` (from the bottom edge) is the opposite: no footer by default — a pick or a swipe ends it — and its header is optional: keep it when the content needs a title, drop it (× and hairline go too) when the content speaks for itself, with `aria-label` on `Sheet.Content`. Never `Drawer.Content side="bottom"`.
 - Content inside a Drawer, a Sheet or a Card is the host's own: a calendar is `Datepicker.Panel` straight in the body, across its width — no card, no padded box around it.
 - A destructive confirm is `<ConfirmDialog.Root title description confirmLabel onConfirm={remove}>` with a `ConfirmDialog.Trigger` — not a Modal assembled as a confirm with your own pending state; a reversible delete offers «Отменить» in the notification instead.
 - Overlays close smoothly only if they stay mounted: render the `Root` always and drive visibility with `open` alone — never `{open && <Drawer.Root>}`, never a changing `key` on the Root. The kit keeps the last content on screen while the exit plays.
@@ -153,7 +153,7 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - One ring in the kit: a share → `ProgressCircle value` (`null` while unknown, `spin` while it grows); an anonymous busy mark → `Spinner`; a ring you press → circle Button `progress`. Never your own `@keyframes` ring or conic gradient.
 - A single destructive action that is easy to redo by hand (clear a draft, revoke a token), no list and no dialog: `<Button.Root tone="danger" variant="soft" holdToConfirm onConfirm={remove}>` — the action in `onConfirm`, not `onClick`. A row in a list: delete at once and offer «Отменить» in the notification.
 - Counts: a number child of `Badge` rolls its digits — not a string you re-render with your own fade.
-- New password: `<Input.Root strength>`; steps of a whole: `<ProgressBar steps value={2} max={5} />`; a trend tile: `<Sparkline data label formatValue />`.
+- New password: `<Input.Root strength>`; steps of a whole: `<ProgressBar label="Шаги настройки" steps value={2} max={5} />`; a trend tile: `<Sparkline data label formatValue />`.
 - A rare milestone only: `celebrate({ origin: event.currentTarget })` — never for a saved form.
 - No motion on keyboard-driven or high-frequency actions; tokens only, no bounce. Full guide: [motion.md](motion.md).
 
@@ -165,15 +165,15 @@ State change is continuous in the whole kit: every region that changes what it s
 - Region loading: `<Skeleton>` in the geometry of the data — same rows, same gaps (`<Skeleton />` for a text line, `shape="circle"` for an avatar, `shape="control"` for a field, `shape="block"` for an image or chart) — not a spinner in an empty card, not a grey box or shimmer you draw.
 - `Spinner` only where there is no shape to hold (a running job, a status line); a busy button is `<Button.Root loading>`.
 - Refreshing data already on screen: keep it, set `aria-busy` — not back to a skeleton on every refetch.
-- Table states in place: `loading` (+ `loadingRows`), `empty`, `error` on `DataTable` — the head and toolbar stay.
+- Table states in place: `loading` (+ `loadingRows`), `empty`, `loadError` on `DataTable` — the head and toolbar stay.
 - First run of a page or region: `EmptyPage.Root` + `EmptyPage.Icon` + `EmptyPage.Title` + `EmptyPage.Description` + `EmptyPage.Actions` with one action — not «Здесь пока ничего нет».
 - Page-level persistent problem: `<Banner.Root tone="danger">` first in `PageContent.Body`; the result of an action: `useNotifications().notify({ tone, title })`.
 
 ## Sidebar
 
 - Brand header: `Sidebar.Header` > `Sidebar.Brand href description` (with `Sidebar.BrandLogo`) + `<Sidebar.Toggle variant="header" />` — not a Toggle in the footer when the rail has a brand.
-- Off-canvas: `offCanvas="auto"` (default, below 768px) with `open` / `onOpenChange` and a menu button that opens it; `offCanvas="always"` for navigation behind a menu at any width; `offCanvas="never"` for a rail that always stays.
-- Every item has `Sidebar.ItemIcon` (compact mode shows only icons) and is a link: `href` or `asChild` with the router `NavLink`; `current` marks the page.
+- Off-canvas: `offCanvas="auto"` (default, below 768px), `"always"` for navigation behind a menu at any width, `"never"` for a rail that always stays; the AppHeader draws the menu button that opens it — no menu state of your own; another trigger reads `useAppShellNav()`.
+- Every item is a link (`href` or `asChild` with the router `NavLink`; `current` marks the page), with a `Sidebar.ItemIcon` on the [top-level items and sub-list parents](layouts.md#sidebar-icons).
 - The signed-in user: `Sidebar.Account` inside `Dropdown.Trigger` at the end of `Sidebar.Footer`.
 - Structure: everyday places on top without a label, categories as `Sidebar.Group label collapsible` (one short word, 3–7 items), views of one section as `Sidebar.Sub` (one level, the parent only discloses) — not every group folded, not a sub-list inside a sub-list.
 - Counts: plain `Sidebar.ItemCount` for information; `color` only when it needs action — it becomes a dot on the rail and on folded parents.
@@ -183,9 +183,9 @@ State change is continuous in the whole kit: every region that changes what it s
 
 Full rules: [responsive.md](responsive.md).
 
-- The page panel is `<PageToolbar.Root>` with, in this order, `Tools` (`SmartFilter.Toolbar`: search, then filter), `Sections` (a `fullWidth` SegmentedControl), `View`, `Actions`, `Chips` — the active filters sit under the top row, never under the sections; on a phone the primary action takes its own row by itself when the search would be squeezed; not a hand-made flex row of tabs, search and buttons.
+- The page panel is `<PageToolbar.Root>` with `Tools` (`SmartFilter.Toolbar`), `Sections` (a `fullWidth` SegmentedControl), `View`, `Actions`, `Chips` — it orders and wraps them itself ([the page panel](responsive.md#page-panel--pagetoolbar)); not a hand-made flex row of tabs, search and buttons.
 - Rearrange, never hide: every desktop function is on the phone, in another place or a menu — not `display: none` below a breakpoint.
-- Breakpoints 640 · 768 · 1024 · 1280 only for the app frame; inside a page — intrinsic grids (`auto-fill, minmax`) and container queries.
+- Breakpoints only in [their scope](responsive.md#breakpoints); inside a page — [intrinsic grids](responsive.md#intrinsic-grids) and container queries.
 - A wide table scrolls inside itself; offer `DataTable.ColumnsMenu` in its `toolbar` — never drop columns by breakpoint, never hand-build the chooser.
 - A row that opens a record page is `getRowHref` (a real link: ⌘-click, new tab), a row that opens a drawer is `onRowClick` — never `navigate()` in `onRowClick`, never your own `event.target` checks for buttons in the row.
 - A list + detail screen is `PageContent.Split` in a `PageContent.Root fill` page, its records a `List` (`current` on the open one) — never ghost Buttons with a soft current; a full-height table is `scrollHeight="fill"` — never a height computed from `100vh`.
@@ -198,7 +198,7 @@ Full rules: [responsive.md](responsive.md).
 
 - Gaps are `gap` on the parent with `--prime-space-N` (N × 4px): 8 in a row of buttons, 16 tile → tile, 20 field → field, 32 group → group; `PageContent` already spaces blocks 24 and sections 40 — not margins, not outer padding.
 - Tokens only: `var(--prime-space-4)`, `var(--prime-color-text-secondary)`, `var(--prime-radius-m)` — never raw `px` / `rem` / hex, never `--prime-ref-*`, never inline `style`.
-- Text through `Typography` roles (`title-m`, `title-s`, `body-m`, `caption`) and `tone="secondary" | "muted"` — not `font-size` or `color` in CSS.
+- Text through `Typography` roles (`title-m`, `title-s`, `body-m`, `caption`) and its `tone` — not `font-size` or `color` in CSS ([text colour](foundations.md#text-colour)).
 
 ## UX — what goes on the screen
 
@@ -207,11 +207,11 @@ Full rules: [responsive.md](responsive.md).
 - Every label carries something new: once per column, never numbered, never repeating its heading; no hint that explains what the layout shows (a lock already says «закреплено»).
 - Buttons say the verb and the object («Выставить счёт»), errors say how to fix it («Формат: +7 912 404-18-20»), empty states offer the next step — not «ОК», «Ошибка», «Нет данных».
 - Money, numbers and dates through `Intl` (`ru-RU`); «ёлочки», `…`, a non-breaking space before a unit — not `toFixed` and string glue.
-- Friction matches the cost: a reversible action at once with «Отменить» in a `Notification`; `ConfirmDialog` only for irreversible or weighty ones, naming the thing and the loss — not «Вы уверены?» on every delete.
+- Friction matches the cost of a mistake ([the ladder](ux.md#5-friction-matches-the-cost-of-a-mistake)) — not «Вы уверены?» on every delete.
 - A disabled control says why when the reason is not on screen; an action without permission is hidden.
 - Tabs, filters, search, page and the open record live in the URL.
 - Changing a screen that exists: audit it against [ux.md](ux.md), [checklist.md](checklist.md) and [anti-slop.md](anti-slop.md) first, fix the shape, then make the change.
-- Before handing over, look at it in a browser: both themes, 1280 and 375 px, every text read aloud.
+- Before handing over, look at it in a browser ([the visual check](ux.md#9-look-at-it-before-handing-it-over)).
 
 ## Anti-slop
 
@@ -228,8 +228,8 @@ import { applyTheme } from "prime-ui-kit";
 applyTheme("light");
 ```
 
-The frame itself (providers, `AppShell` with `Sidebar` and the phone menu button) is built once too:
-copy it from [layouts.md](layouts.md#app-frame-once-per-app).
+The frame itself (providers, `AppShell` with the `Sidebar`) is built once too: copy it from
+[layouts.md](layouts.md#app-frame-once-per-app).
 
 A document page (a form) — its title is in main, its header carries none:
 
@@ -262,10 +262,10 @@ export function ProfilePage() {
 ```
 
 A region with all its states — loading, data, empty, error — that flow into each other. Copy this
-shape for every block that fetches data (a table uses DataTable `loading` / `empty` / `error` instead):
+shape for every block that fetches data (a table uses DataTable `loading` / `empty` / `loadError` instead):
 
 ```tsx
-import { Button, Card, Crossfade, EmptyPage, Icon, Skeleton, Typography } from "prime-ui-kit";
+import { Card, Crossfade, EmptyPage, Icon, Skeleton, Typography } from "prime-ui-kit";
 import styles from "./InvoicesCard.module.css";
 // .rows { display: grid; gap: var(--prime-space-3); margin: 0; padding: 0; list-style: none; }
 // .row { display: flex; align-items: center; justify-content: space-between; gap: var(--prime-space-4); }
@@ -276,7 +276,8 @@ type Invoice = { id: string; client: string; amount: string };
 type InvoicesCardProps = {
   status: "loading" | "ready" | "error";
   invoices: Invoice[];
-  onRetry: () => void;
+  /** Loads the invoices again; the retry button stays busy until the Promise settles. */
+  onRetry: () => Promise<void>;
 };
 
 const PLACEHOLDER_ROWS = ["a", "b", "c"];
@@ -329,8 +330,9 @@ export function InvoicesCard({ status, invoices, onRetry }: InvoicesCardProps) {
             </EmptyPage.Root>
           ) : null}
           {state === "error" ? (
-            <EmptyPage.Root size="s" role="alert" aria-labelledby="invoices-error">
-              <EmptyPage.Icon tone="danger">
+            // tone="danger": the danger tile, and the region announces itself (role="alert").
+            <EmptyPage.Root size="s" tone="danger" aria-labelledby="invoices-error">
+              <EmptyPage.Icon>
                 <Icon name="status.danger" />
               </EmptyPage.Icon>
               <EmptyPage.Title as="h3" id="invoices-error">
@@ -338,9 +340,7 @@ export function InvoicesCard({ status, invoices, onRetry }: InvoicesCardProps) {
               </EmptyPage.Title>
               <EmptyPage.Description>Сервер не ответил. Данные не потеряны.</EmptyPage.Description>
               <EmptyPage.Actions>
-                <Button.Root variant="soft" tone="neutral" onClick={onRetry}>
-                  Повторить
-                </Button.Root>
+                <EmptyPage.RetryButton onRetry={onRetry} />
               </EmptyPage.Actions>
             </EmptyPage.Root>
           ) : null}

package/dist/skill/checklist.md

@@ -1,113 +1,81 @@
 # Checklist before handing over a screen
 
-Answer every item yes or no. Any «no» is fixed before handing over.
+Answer every item yes or no. Any «no» is fixed before handing over. Each item links to the rule it
+checks.
 
 ## Composition
-- [ ] The screen starts from the closest screen in [composition.md](composition.md#screens) (list, detail,
-      settings, form in a Drawer, dashboard, states, messenger) and keeps its skeleton.
-- [ ] The page titles itself in its `AppHeader`: `AppHeader.Title`, a line of data in
-      `AppHeader.Description`, the page's tools in `AppHeader.Tools` (`PageToolbar`); main has no
-      `PageContent.Header`. Only a document page (settings, a long form, help) has `PageContent.Header`
-      and no title in the header. Blocks in `PageContent.Body`.
-- [ ] The header row holds only what this page needs: no global search, no app-wide buttons.
-- [ ] Cards only for standalone blocks; no card around a table, a single field or the whole page.
+- [ ] The screen starts from the closest working screen and keeps its skeleton ([screens](composition.md#screens)).
+- [ ] An app page titles itself in its `AppHeader`; only a document page has `PageContent.Header` ([page skeleton](composition.md#1-page-skeleton)).
+- [ ] The header row holds only this page's title, buttons and tools — nothing app-wide ([page skeleton](composition.md#1-page-skeleton)).
+- [ ] A Card only for a standalone titled block — never around a table, a single field or the page ([surfaces](composition.md#4-surfaces)).
 
 ## UX ([ux.md](ux.md))
-- [ ] I wrote the brief first: who and what for, the data and its shape, the main action, the states, the narrow screen.
-- [ ] Every entity is laid out by its shape: one record is one row or one block, never split over lines;
-      records a person edits are a `FieldList`, records a person reads a `DataTable`.
-- [ ] Labels on a form of rows ≤ columns + the list label: no label repeated per row, none numbered
-      («Пункт 1»), none repeating its heading; a unit in one place (the field's affix).
-- [ ] No text that explains the layout; every hint says what the person cannot see.
-- [ ] Buttons say the verb and the object; errors say how to fix it; empty states offer the next step.
-- [ ] Money, numbers and dates through `Intl` with `ru-RU`; «ёлочки», `…`, a non-breaking space before units.
-- [ ] Friction matches the cost: reversible → do it and offer «Отменить»; irreversible → `ConfirmDialog`
-      naming the thing and the loss; bulk → the count.
-- [ ] A disabled control says why when the reason is off screen; an action without permission is hidden.
-- [ ] Defaults prefill what the system knows; each field has the control and `inputMode` its data needs;
-      rare settings sit behind a disclosure.
-- [ ] Tabs, filters, search, page and the open record are in the URL.
-- [ ] I looked at the screen in a browser: both themes, 1280 and 375 px, the longest real values, an
-      empty list, an error on every field.
+- [ ] I wrote the five-line brief before the JSX ([brief](ux.md#1-brief-before-code)).
+- [ ] Every entity is laid out by its shape: a record is one row or one block ([data shape](ux.md#2-the-shape-of-the-data-decides-the-layout)).
+- [ ] Labels on a form of rows ≤ columns + the list label; none repeated, numbered or repeating its heading ([label economy](ux.md#3-label-economy)).
+- [ ] No text explains the layout; every hint says what the person cannot see ([label economy](ux.md#3-label-economy)).
+- [ ] Buttons say the verb and the object, errors say how to fix it, empty states offer the next step ([words](ux.md#4-words)).
+- [ ] Money, numbers and dates go through `Intl` with `ru-RU`, in Russian typography ([words](ux.md#4-words)).
+- [ ] The friction of every action matches the cost of a mistake ([friction](ux.md#5-friction-matches-the-cost-of-a-mistake)).
+- [ ] A disabled control says why when the reason is off screen; an action without permission is hidden ([nothing to guess](ux.md#6-nothing-to-guess)).
+- [ ] A request a value starts — a simulated one too — is cancelled when the value changes again ([nothing to guess](ux.md#6-nothing-to-guess)).
+- [ ] Tabs, filters, search, page and the open record are in the URL ([nothing to guess](ux.md#6-nothing-to-guess)).
+- [ ] Defaults prefill what the system knows; each field has the control and `inputMode` of its data ([ask less](ux.md#7-ask-less)).
+- [ ] I looked at the screen in a browser, filled badly ([the visual check](ux.md#9-look-at-it-before-handing-it-over)).
 
 ## Grid and spacing
-- [ ] Every spacing, size and gap in my CSS is a `--prime-space-*` (or another `--prime-*`) token on the 4px grid.
-- [ ] Spacing is `gap` on the parent; no margins on children; no outer padding duplicating `AppShell.Main` / `PageContent.Body`.
-- [ ] Proximity holds: inline controls 8, tile→tile 16 (one `PageContent.Grid`), field→field 20, block→block 24, group→group 32, section→section 40 (`PageContent.Section`).
-- [ ] Inside a group things are visibly closer than between groups.
+- [ ] Every length in my CSS is a `--prime-*` token on the 4px grid ([grid](foundations.md#1-4px-grid)).
+- [ ] Spacing is `gap` on the parent; no margins, no outer padding of my own ([rhythm](composition.md#2-rhythm--the-4px-grid)).
+- [ ] The proximity scale holds: closer inside a group than between groups ([proximity](foundations.md#2-proximity-scale)).
 
 ## Sizes and alignment
-- [ ] Default size `m`, unless the whole region is deliberately dense (`s`) or prominent (`l`).
-- [ ] Every row of controls uses one size; their heights line up.
-- [ ] Icon-only buttons are square (round `shape="circle"` only for media and transfer actions) and have
-      `aria-label`.
-- [ ] Controls inside table cells are one tier below the table; no CSS sets table row or cell heights.
+- [ ] Default size `m`; a tier changes for a whole region, never for one control ([the host tier](api-contract.md#size-and-the-host-tier)).
+- [ ] Every row of controls uses one size and its heights line up ([density](composition.md#5-density-and-size)).
+- [ ] Controls in table cells are one tier below the table; no CSS sets row or cell heights ([size axis](foundations.md#3-size-axis)).
+- [ ] Icon-only buttons are square (round only for media and transfers) and named ([icons](api-contract.md#icons)).
 
 ## Text
-- [ ] Every text goes through a kit component or `Typography` with a role; no custom font sizes/weights.
-- [ ] One page title, one `<h1>` (`AppHeader.Title`, or `PageContent.Title` on a document page);
-      headings descend without skipping levels (`Card.Title as="h2"` directly under the page title).
-- [ ] Secondary text uses `tone="secondary"`/`"muted"`; numbers in tables and prices are tabular.
-- [ ] No filler copy, no emoji, no text that restates the heading.
+- [ ] Every text goes through a kit part or a `Typography` role ([typography](foundations.md#7-typography)).
+- [ ] One page title, one `<h1>`; headings descend without skipping levels ([hierarchy](composition.md#3-hierarchy--air-first-then-type)).
+- [ ] Text colour comes from `tone`; numbers in tables and prices are tabular ([text colour](foundations.md#text-colour)).
+- [ ] No filler copy, no emoji, no text that restates the heading ([decoration](anti-slop.md#8-decoration-and-filler)).
 
 ## Tokens and surfaces
-- [ ] No raw px/rem/hex, no `--prime-ref-*`, no inline `style`, no overrides of kit internals
-      (allowed: `@media` conditions and length props a COMPONENT.md documents, like DataTable column `width`).
-- [ ] Every scroll region is a `ScrollContainer` (no `overflow: auto` of my own); kit components are not
-      wrapped in another one.
-- [ ] Blocks are separated by fill and air, not borders; no card inside a card without reason.
-- [ ] My own bounded blocks are `Card`s (or plain tiles on `--prime-color-layer-nested` +
-      `--prime-card-radius`); no hard-coded `--prime-color-layer-<n>-*`.
-- [ ] Hover never merges: a whole clickable card lifts (`--prime-shadow-overlay`) instead of a wash;
-      a part touching its surface's edge hovers with `--prime-color-fill-muted-hover`;
-      `--prime-color-fill-subtle` only on transparent, padded rows and ghost controls. Checked in both
-      themes, on the page and inside a card.
+- [ ] No raw values, `--prime-ref-*`, inline `style` or overrides of kit internals ([styling](api-contract.md#styling-your-own-wrappers)).
+- [ ] Every scroll region is a `ScrollContainer`; kit components are not wrapped in another one ([ready components](anti-slop.md#7-div-instead-of-a-ready-component)).
+- [ ] Blocks are separated by fill and air; a card in a card only as a deliberate next layer ([card in a card](foundations.md#card-in-a-card)).
+- [ ] My own bounded blocks are `Card`s or the plain nested tile ([your own block](foundations.md#your-own-bounded-block)).
+- [ ] No hover merges with its neighbour, in both themes, on the page and in a card ([hover](anti-slop.md#3a-hover-that-merges-with-the-neighbour)).
 
 ## Reuse
-- [ ] Every repeated-looking element is one component (kit or `shared/ui`), not copies.
-- [ ] No `div` where a kit component exists (Divider, Kbd, Badge, Card, LinkButton, Typography).
-- [ ] Every overlay (Modal, ConfirmDialog, Drawer, Sheet, Popover, Dropdown, Tooltip, CommandMenu, Select, MediaViewer) is a kit component.
-- [ ] Properties of one record are a `DescriptionList`, uploads go through `useUploadQueue`, a chat is
-      `Chat` (`Chat.Messages` of `Message.Root`, `Chat.Footer` with `Composer.Root`), an album is `Gallery`,
-      a schedule is `Gantt` — no hand-made copies of them.
+- [ ] Every repeated-looking element is one component, not copies ([missing components](composition.md#14-when-the-kit-has-no-ready-component)).
+- [ ] No `div` where a kit component exists ([ready components](anti-slop.md#7-div-instead-of-a-ready-component)).
+- [ ] Every overlay is a kit component ([overlays](composition.md#10-overlays)).
+- [ ] Record properties, uploads, a chat, an album and a schedule are the kit's components ([choosing](choosing.md#2-inside-a-category)).
 
 ## Hierarchy
-- [ ] One primary action per area (an empty state's action replaces the header's, not duplicates it);
-      others `soft`/`ghost`/`outline` neutral; destructive is `tone="danger"`.
-- [ ] The same action has the same label everywhere on the screen.
-- [ ] Primary action is last in action rows (forms, modals).
+- [ ] One primary action per area, last in its row; the rest `soft` / `ghost` / `outline` neutral ([actions](composition.md#6-actions)).
+- [ ] The same action has the same label and variant everywhere on the screen ([secondary actions](api-contract.md#secondary-actions)).
 
 ## States
-- [ ] Hover / focus-visible come from the kit (nothing removed).
-- [ ] Disabled controls use `disabled`; async actions use `loading` (no hand-made spinners).
-- [ ] Fields show `hint` and `error` (a non-empty `error` is already invalid); only the minority is marked `required` or `optional`.
-- [ ] Data blocks have loading, empty and error states (DataTable `loading` / `empty` / `error`, EmptyPage).
-- [ ] Every region swaps its states through `Crossfade` (nothing flips, the page below does not jump);
-      loading is a `Skeleton` in the data's geometry, a `Spinner` only where there is no shape to hold.
-- [ ] While a form saves, its submit button is `loading` and its fields are disabled by `Fieldset
-      disabled` (the submit button outside the Fieldset).
-- [ ] Destructive irreversible actions confirm in a `ConfirmDialog` (async `onConfirm`), reversible ones
-      offer «Отменить» instead; a form that stays on screen after saving says
-      «Сохранено» on its button, a form that goes away (closes, navigates) shows a Notification; failures
-      always show a Notification or a field `error` (instant toggles show one only on failure).
-- [ ] Overlays are always mounted and driven by `open` only (no `{open && …}`, no changing `key`), so they
-      close smoothly.
-- [ ] No hand-written animation on kit parts; custom motion uses motion tokens, `transform`/`opacity` only.
-- [ ] Every glyph comes from the kit — `<Icon name>`, else `prime-ui-kit/icons`, `createIcon` only for one
-      neither has; no raw `lucide-react` in JSX, no other icon library, no inline `<svg>`, no icon
-      animated by hand.
-- [ ] Every state change moves through the kit ([motion.md](motion.md)): a changed button label is new
-      children (it morphs), a long action is `progress`, a counter is a number (it rolls), a new password
-      has `strength`, an accepted code is `success`; nothing moves on frequent or keyboard actions.
+- [ ] Hover and focus-visible come from the kit, nothing removed ([focus](foundations.md#10-focus-and-motion)).
+- [ ] Busy controls use `loading`, unavailable ones `disabled` — no hand-made spinners ([loading](api-contract.md#loading-without-datatable)).
+- [ ] Fields show `hint` and `error`; only the minority is marked `required` or `optional` ([forms](api-contract.md#forms)).
+- [ ] Every data block has its loading, empty and error states ([feedback](composition.md#9-feedback)).
+- [ ] Every region swaps its states through `Crossfade`, loading is a `Skeleton` of the data ([continuity](foundations.md#11-state-changes-are-continuous)).
+- [ ] While a form saves, its submit is `loading` and its fields sit in a `Fieldset disabled` ([forms](api-contract.md#forms)).
+- [ ] A save that stays says «Сохранено» on its button, one that goes away notifies, a failure always shows ([feedback](composition.md#9-feedback)).
+- [ ] Overlays stay mounted and are driven by `open` only ([motion mistakes](motion.md#6-mistakes)).
+- [ ] No hand-written animation on kit parts; my own motion uses the motion tokens ([your own motion](motion.md#4-rules-for-your-own-motion)).
+- [ ] Every glyph comes from the kit, none animated by hand ([icons](api-contract.md#icons)).
+- [ ] Every state change moves through the kit ([what the kit animates](motion.md#1-what-the-kit-already-animates--do-not-rebuild-it)).
 
 ## Themes and widths
-- [ ] Screen checked with `data-theme="dark"`: no hard-coded colors, everything readable.
-- [ ] Screen works at 320px: no horizontal page scroll, grids collapse, toolbars rearrange (`PageToolbar`) and switchers scroll, long text truncates or wraps.
-- [ ] The responsive checklist in [responsive.md](responsive.md#checklist-before-handing-a-screen-over) passes: widths 320 · 390 · 768 · 1024 · 1280 · 1920, the primary action in the top row, one height per row, no hover-only functions, zoom 400%.
-- [ ] Below 768px `AppHeader.MenuButton` opens the Sidebar; the page title stays in the header on every width, the page's tools wrap under it.
+- [ ] The screen passes the responsive checklist in both themes ([responsive](responsive.md#checklist-before-handing-a-screen-over)).
+- [ ] On a phone the Sidebar opens from the menu button the header draws; the page title stays in the header ([app frame](layouts.md#app-frame-once-per-app)).
 
 ## Keyboard and a11y
-- [ ] Every action is reachable by Tab in a logical order and works with Enter/Space.
-- [ ] Every field has a label (visible, or `aria-label` for toolbar search); icons are `aria-hidden` or labelled.
-- [ ] Meaning is never color-only (status badges have text, errors have a message).
-- [ ] Custom `labels` are passed where default Russian strings do not fit the context.
+- [ ] Every action is reachable by Tab in reading order and works with Enter / Space ([interaction](responsive.md#interaction-and-accessibility)).
+- [ ] Every field has a label (visible, or `aria-label` for a toolbar search) ([forms](api-contract.md#forms)).
+- [ ] Meaning is never colour alone ([tone and color](foundations.md#6-tone-and-color)).
+- [ ] Custom `labels` replace the default Russian strings where they do not fit ([system strings](api-contract.md#shared-vocabulary-exported-types)).

package/dist/skill/choosing.md

@@ -55,8 +55,8 @@ contacts, specs, prices by period) → FieldList: one row per record, the headin
 | any color as a field of a form (swatch + hex, picker in a popover) | ColorField |
 | any color in a panel of its own (hex, eyedropper, channels) | ColorPicker |
 
-**Data.** Status, count, removable value or applied filter → Badge (`onRemove` to remove, `onPress` to
-toggle). Person or organization → Avatar. Object (product, vehicle, file, cover) → Thumbnail with a
+**Data.** Status, count, removable value or applied filter → Badge (`tone` for a status, `color` for a
+category, `onRemove` to remove, `pressed` / `onPressedChange` to toggle). Person or organization → Avatar. Object (product, vehicle, file, cover) → Thumbnail with a
 `ratio` — never a round Avatar for things. Keyboard shortcut → Kbd. One block of related
 numbers/content → Card (pick the template; a whole tile that opens its details → `Card.Root asChild`
 with a link). Read-only properties of one record («label — value») → DescriptionList, never a
@@ -80,7 +80,7 @@ the rest (comments as a chat, a read-only history) → `Chat.Root` with `Chat.Me
 message on its own → `Message.Root`. The list of conversations beside the chat (the dialogs pane of a
 messenger or an inbox) → `ChatList` (`items`, `renderItem` with `ChatList.Item`, `value`): unread
 counts, «печатает…», drafts, ticks, a row menu and search come with it — never `List` with a hand-made
-count and preview; `List` stays for records that are not conversations (tickets, letters, invoices). A group chat → `Chat.Messages type="group"`: `Message.Author`
+count and preview; `List` stays for records that are not conversations (tickets, letters, invoices). A group chat → `Chat.Messages group`: `Message.Author`
 (`tag`, `Message.AuthorIcon`) and `Message.Avatar` on every message, the list shows them on the
 first and the last of a run. A voice message → `VoicePlayer` inside `Message.Root`; a call recording
 outside a chat → `VoicePlayer` alone. A round video message → `VideoNote` inside `Message.Root`
@@ -91,7 +91,7 @@ the transcript and the `transfer` set); only VoicePlayer has `waveform` and a ra
 comment, a report) → `Gallery`; one picture of an object → `Thumbnail`. A video with controls →
 `Message.Media` or `Thumbnail.Video`, not VideoNote. «Печатает…» → `Chat.Root typing` (or
 `Message.Typing`), never a text row; a jump to a message → `Message.Reply target`, `Chat.Pinned` or
-`Chat.Root current`, never `scrollIntoView`; search inside a chat → `Chat.Search`. Files, photos,
+`Chat.Root jumpTo`, never `scrollIntoView`; search inside a chat → `Chat.Search`. Files, photos,
 places and contacts sent in a chat → the `Message` parts, not FileUpload rows or Cards.
 
 **Status and loading.** See the pair below. Progress of a single task → ProgressBar `value`; parts of a whole →
@@ -108,11 +108,10 @@ show → EmptyPage; a region that failed to load → EmptyPage `tone="danger"` w
 loading, data, empty and error, or showing one record at a time → its content in
 `Crossfade state={status}`, with a Skeleton as the loading state (DataTable's body does both by itself).
 
-**Overlays.** See the pairs below. Global search over commands and pages (⌘K) → CommandMenu. A short
-task that ends by itself (a date, an action on a record, a short note) raised from the bottom edge →
-Sheet. Menus, selects, pickers and Modal turn into bottom sheets below 640px by themselves — never
-build your own. A photo, a scan or a video opened full screen from its thumbnail (a Gallery tile, a
-Thumbnail button) → MediaViewer, never a Modal with an `<img>`.
+**Overlays.** See the pairs below. Global search over commands and pages (⌘K) → CommandMenu. Menus,
+selects, pickers and Modal turn into bottom sheets below 640px by themselves — never build your own.
+A photo, a scan or a video opened full screen from its thumbnail (a Gallery tile, a Thumbnail button)
+→ MediaViewer, never a Modal with an `<img>`.
 
 **Phone navigation.** App navigation is Sidebar on a wide screen and `BottomNav` in `AppShell.Footer`
 on a phone for 2–6 main sections (the shell hides it by itself while the Sidebar rail is on screen;
@@ -122,31 +121,30 @@ Drawer menu.
 **App frame.** Sidebar collapse control: `Sidebar.Toggle variant="header"` next to `Sidebar.Brand` in
 `Sidebar.Header` — at the header's end while expanded, a small round button on the rail's edge while
 compact (the default for a branded rail); `Sidebar.Toggle` (`variant="item"`) in `Sidebar.Footer` when
-the rail has no brand header. On phones neither replaces `AppHeader.MenuButton` that
-opens the off-canvas Sidebar (`open` / `onOpenChange`). The bar at the top of the panel is the page's
-`AppHeader`: the page title (`AppHeader.Title` + a line of data), the page's own buttons and its
-tools — a `PageToolbar` in `AppHeader.Tools` when the page has several tools above its data (sections,
-search and filters, a view switch, the primary action) that must rearrange on a phone; one search or one
-filter above a single table goes into the DataTable `toolbar` instead. Only a document page (settings,
-a long form, help) has its title in main, `PageContent.Header`, and no title in the header. A record
-opened from a table: its own page → DataTable `getRowHref`; in place → `onRowClick` + Drawer; a list
-worked through record by record (mail, chat, tickets) → `PageContent.Split` with a `List` of the records
-(`current` on the open one). Sections of a long rail → `Sidebar.Group
-collapsible`; a section with sub-pages → `Sidebar.Sub`; the signed-in user → `Sidebar.Account` in a
-`Dropdown.Trigger` at the bottom of `Sidebar.Footer`.
+the rail has no brand header. On phones the off-canvas Sidebar opens from the menu button the
+`AppHeader` draws by itself; a trigger of your own reads `useAppShellNav()`. The bar at the top of the
+panel is the page's `AppHeader`: the page title (`AppHeader.Title` + a line of data), the page's own
+buttons and its tools — [where the tools and filters go](composition.md#where-the-filters-go). Only a
+document page (settings, a long form, help) has its title in main, `PageContent.Header`, and no title
+in the header. A record opened from a table: its own page → DataTable `getRowHref`; in place →
+`onRowClick` + Drawer; a list worked through record by record → `PageContent.Split` with a `List` of
+the records (tickets, letters, invoices; `current` on the open one) or a `ChatList` of the
+conversations. Sections of a long rail → `Sidebar.Group collapsible`; a section with sub-pages →
+`Sidebar.Sub`; the signed-in user → `Sidebar.Account` in a `Dropdown.Trigger` at the bottom of
+`Sidebar.Footer`.
 
 ## 3. Pairs that are easy to confuse
 
 | Pair | Rule |
 |---|---|
-| List / Sidebar / Tabs / Card list / DataTable | List: the records of a list + detail screen (dialogs, tickets, mail), one open at a time (`current`), each row a button or a link with a text line, a preview, meta and a count. Sidebar: the sections of the **app**. Tabs: panels of **one screen**. `Card.List` (`variant="list"`): static facts in a card, nothing opens. DataTable: many records compared by columns, sorted, filtered, selected in bulk. |
+| List / ChatList / Sidebar / Tabs / Card list / DataTable | List: the records of a list + detail screen that are not conversations (tickets, letters, invoices), one open at a time (`current`), each row a button or a link with a text line, a preview, meta and a count. ChatList: the conversations of a messenger or an inbox. Sidebar: the sections of the **app**. Tabs: panels of **one screen**. `Card.List` (`variant="list"`): static facts in a card, nothing opens. DataTable: many records compared by columns, sorted, filtered, selected in bulk. |
 | FieldList / DataTable / Fieldset / TagSelect | FieldList: records of one shape a person **edits** in a form, a row of fields each, added and removed by hand, up to four short fields per row. DataTable: records a person **reads**, sorts, filters and selects; edits open a Drawer. Fieldset: **one** record's fields under a heading. TagSelect: values **picked** from options, shown as tags. One value in several units is none of them — fields in one row under one heading. |
 | Tabs / SegmentedControl | Tabs switch **panels of content** (navigation inside a screen). SegmentedControl switches a **value or mode** of the same content (period, view mode, filter). |
 | Modal / Drawer / Sheet / Popover / Tooltip | Modal: blocking decision or a short form (≤ 4 fields) that needs full attention. Drawer: long form, filters, record details beside the page, while keeping page context. Sheet: a short task that ends by itself — a pick, an action, a short note — raised from the bottom edge. Popover: small non-modal panel anchored to a control (quick edit, explanation with a link). Tooltip: a few words naming or explaining a control, no interactive content. |
 | Select / NativeSelect | Select: the kit's floating list — icons, descriptions, groups, search, `multiple`, `clearable`. NativeSelect: a plain text list where the OS picker is better (phones) or the value must post with a form by `name`. |
 | Select / Dropdown / CommandMenu / TagSelect | Select picks a **value** for a field (form data). Dropdown runs **actions** (Edit, Duplicate, Delete). CommandMenu searches commands and pages across the app (locally or on the server) — it is not a field. TagSelect picks **several values** as tags. |
-| SmartFilter / Select in a toolbar | One field with a few options → SegmentedControl or Select in the table toolbar. Several fields, search, include / exclude → SmartFilter. |
-| Badge / Button | A badge labels or holds a value (status, filter, keyword): `onRemove` drops it, `onPress` toggles it. A command (save, open, go) is always a Button. |
+| SmartFilter / SegmentedControl / Select | Search and filters over a list → SmartFilter (`fields={[]}` for a search alone), even with one field. A switch of what the same data shows (sections with counts, a period, a view) → SegmentedControl, or a Select when the options are many. |
+| Badge / Button | A badge labels or holds a value (status, filter, keyword): `onRemove` drops it, `pressed` toggles it. A command (save, open, go) is always a Button. |
 | Banner / Notification / Hint | Banner: persistent message in the page flow about a page/section state (sync failed, trial ends). Notification: transient toast about the result of an action (saved, failed). Hint / `error`: help or validation text under one field. |
 | ProgressBar / ProgressCircle / Spinner | ProgressBar: a share with width to spare and words beside it (an upload row, an import, a quota line). ProgressCircle: a share on the data scale (24–80) where width is short or a ring reads better (a KPI goal, a ring breakdown, a named import card); `value={null}` while the share is unknown, `spin` while a share grows, an icon in the centre. Spinner: an anonymous «busy» on the icon scale inside a control or a status line, no share, no name of its own. A ring you can press (cancel, retry, download a transfer) → Button `shape="circle"` with `progress`, not any of the three. |
 | Button / LinkButton | Button does something (submit, open, delete). LinkButton goes somewhere (a URL, «Подробнее», «Все заказы»). |
@@ -163,7 +161,7 @@ collapsible`; a section with sub-pages → `Sidebar.Sub`; the signed-in user →
 | Stepper / Tabs | Stepper for a sequential process with completion status; Tabs for non-sequential views. |
 | Gantt / Timeline / Kanban / DataTable | Gantt: records with a start and an end compared across time (who is busy when, a plan with phases and milestones), moved, stretched and drawn by hand (`onBarChange`, `onBarCreate`). Timeline: a history of events at points in time, read top to bottom. Kanban: work items moved between statuses, time does not matter. DataTable: many records compared by many attributes, sorted, filtered and selected — dates are only columns. |
 | DescriptionList / DataTable / Card | DescriptionList: the properties of **one** record as «label — value» pairs (requisites, deal terms, a summary before a confirm). DataTable: **many** records with the same properties. Card: the bounded block they sit in, or one headline number (`mini`, `stat-trend`) — a DescriptionList inside a `Card.Body`, never a Card per property. |
-| ConfirmDialog / Modal / `holdToConfirm` / undo | A row or item in a list that can be restored → delete at once and offer «Отменить» in the Notification. One standalone destructive action that is easy to redo by hand, no list (clear a draft, revoke a token) → `Button.Root holdToConfirm` with the action in `onConfirm`. Irreversible loss of work or a weighty action (delete a project, send an invoice) → ConfirmDialog (`onConfirm` returns the request; pending, failure and dismiss rules are built in). Unsaved changes in a Modal or Drawer form → `Modal.Guard` / `Drawer.Guard dirty`. A form, a choice or more than a sentence of content → Modal; never a Modal hand-built as a confirm. |
+| ConfirmDialog / Modal / `holdToConfirm` / undo | Which of them an action deserves is its cost: [ux.md → friction](ux.md#5-friction-matches-the-cost-of-a-mistake). ConfirmDialog only asks a question (`onConfirm` returns the request; pending, failure and dismiss rules are built in); a form, a choice or more than a sentence of content → Modal; never a Modal hand-built as a confirm. |
 | Composer / Textarea | Composer: the message input of a conversation — Enter sends, attachments, a reply or edit bar, voice and round video. Textarea: long text saved with a form (a description, a comment field) by its submit button. |
 | Chat / Message / Gallery | Chat: a conversation — the header, search, pinned, the one message list (dates, runs, selection, jumps, read receipts, typing) and the Composer in its footer; a list without the rest is `Chat.Root` with `Chat.Messages`. Message: one message and its content parts — a row of that list, or a bubble on its own (a quoted reply in a ticket). Gallery: an album of photos and videos laid out by their ratios — `Message.Media` in a message, `Gallery` anywhere else (a post, a comment, a report). |
 | Message / Timeline / Notification | Message: what people say to each other in a conversation, in bubbles. Timeline: what happened to a record (status changes, an audit log). Notification: the result of the user's own action, for a few seconds. A chat event («Анна добавила Олега») is `Chat.Service`, not a Notification. |