prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/cheatsheet.md

@@ -0,0 +1,317 @@
+# Cheatsheet — the decisions agents get wrong
+
+One line per decision: **do** this, **not** that. Every name here exists in the kit; the full
+reference is each component's `COMPONENT.md` ([components.md](components.md)), the reasons are in
+[composition.md](composition.md) and [api-contract.md](api-contract.md).
+
+## Setup
+
+- Import the styles once at the app root: `import "prime-ui-kit/bundle.css"` (tokens, themes, components), plus the opt-in `prime-ui-kit/fonts.css` and `prime-ui-kit/reset.css` when the app has no fonts or reset of its own — not per page, not a copied token file.
+- Switch the theme with `applyTheme("light" | "dark")` — not a class or `style` on `<html>`.
+- Put `NotificationProvider` and `AppShell.Root` in the app root once — not inside a page component.
+- Import everything from `"prime-ui-kit"` — not from `prime-ui-kit/src/...` or `lucide-react` for a glyph the kit has. Two subpaths: `import { ColorField, ColorPicker, parseColor } from "prime-ui-kit/color-picker"` (needs the optional peer `react-aria-components`; `ColorPresets` and `ColorSwatches` come from the root), and `import { BellIcon } from "prime-ui-kit/icons"` for a glyph outside the `<Icon name>` set.
+
+## Size
+
+- 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)).
+- A control in a table cell or a card header row is one tier down: `<Button.Root size="s" variant="ghost" tone="neutral">`.
+
+## Structure
+
+- Components with parts render through `.Root` + parts: `<Button.Root>`, `<Modal.Root>` — `<Button>` and `<Modal>` are not components.
+- Leaves are single exports with no `.Root` (`<Typography>`, `<Skeleton />`, `<DataTable>`, `<Sparkline>`… — [the list](api-contract.md)) — not `<Typography.Root>`.
+- Data-driven components take data as props: `DataTable columns rows`, `SmartFilter.Root fields`, `TagSelect options`, `ProgressBar segments` — not mapped child parts.
+
+## 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.
+- 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.
+- 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.
+- A choice in a form (SegmentedControl, ButtonGroup) is a field too: `label`, `hint`, `error` on its root — not a `Label` wired by hand.
+- A record card that saves each field: `<Input.Root onCommit={save}>` (save returns a Promise) — not hand-written blur / Enter / Escape handlers or a field disabled while saving.
+- Copy or call next to a value: `Input.CopyButton`, `Input.Action` inside `Input.Wrapper` — not a Button beside the field; a password: `Input.RevealButton`.
+
+## State
+
+- 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 value that settles at the end of a gesture saves in its own event: Slider `onCommit` — not a request on every `onValueChange` step.
+
+## Text: labels vs children
+
+- Visible text goes in children or content props: `<Button.Root>Сохранить</Button.Root>`, `<Modal.Title>`.
+- System strings (aria names, counters, default texts) go through `labels`: `<Modal.Root labels={{ close: "Закрыть окно" }}>` — not a `closeLabel` prop. Defaults are Russian; override only what differs.
+
+## Icons
+
+- Every glyph from the kit, in this order: a semantic `<Icon name="action.add" />` ([names](api-contract.md#icons)); else the full animated set `import { ArchiveIcon } from "prime-ui-kit/icons"` → `<ArchiveIcon />` (Lucide name + `Icon`); only a glyph neither has → `const IconTractor = createIcon(Tractor)` once, then `<IconTractor />` — not `import { Plus } from "lucide-react"` in JSX, another icon library or an inline `<svg>`.
+- Kit icons animate by themselves: the gesture plays when their button, link, tab, menu item or row is hovered or pressed — not your own hover rotate or spin on an icon. `animated={false}` only for a glyph repeated in every row of a long list.
+- Put icons into the part: `<Button.Icon>`, `<Input.Icon side="start">`, `<Sidebar.ItemIcon>`, `<Dropdown.ItemIcon>`, `<EmptyPage.Icon>` — not an `icon` prop (only data arrays such as `notify()` take `icon`).
+- Icon-only button: `<Button.Root variant="ghost" tone="neutral" aria-label="Удалить">` with a `Tooltip` — not an unnamed icon.
+- `lucide-react` only through `createIcon`, for a glyph missing from both `<Icon name>` and `prime-ui-kit/icons` — not for `Plus`, `Search`, `Bell`, `Settings`…
+
+## Buttons and actions
+
+- One primary per area (page header, card, dialog): the default `solid` accent, last in the row. Others `variant="soft" tone="neutral"`; dismiss `variant="ghost" tone="neutral"` (pages), `variant="outline" tone="neutral"` (Modal / Drawer footer).
+- Destructive is `tone="danger"` — never `tone="error"`; which variant where and how it is confirmed: [api-contract.md](api-contract.md#destructive-actions) and [choosing.md](choosing.md).
+- Going somewhere is a link: `<LinkButton href>` or `<Button.Root asChild><a href>…</a></Button.Root>` — not `onClick={() => location.assign(url)}`.
+- Busy action: `<Button.Root loading>` — not a hand-made spinner or «Загрузка…» text.
+- An action on a coloured host (a solid Banner, an accent strip): `<Button.Root variant="ghost" tone="inherit">` — it takes the host's text colour; never recolour a Button with a CSS override.
+
+## 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.
+- Section without a card: `<Typography as="h2" variant="title-m">` + the content.
+- 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.
+- 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.
+- Amounts, counts and dates are `numeric` columns; statuses are `Badge.Root color` from one status → color 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.
+- 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`.
+
+## 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`.
+- `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.
+- 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`.
+- «печатает…» 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 other messages blink back around it); 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.
+
+## 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>`.
+- 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"`.
+- 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.
+- Placement of a menu, popover, select or picker: leave the defaults — `side="bottom"`, `align="auto"`: it opens below the trigger, lines up with the trigger edge that has the room (a «⋯» at the end of a row grows toward the start) and flips to the top by itself. Never write `side` or `align` to restate that; set `align` only when the panel must line up with one edge of a block whatever room there is.
+- While a request runs: `<Modal.Guard busy={saving} />` inside the content (`Drawer.Guard`, `Sheet.Guard` alike) — Escape, a press outside, × and `Close` are held, × and `Close` disabled; add `dirty` to ask before unsaved changes are lost. Not `closeOnEscape={false}` or `showClose={false}` by hand.
+
+## Motion — it comes with the components
+
+- Changed button text is new children: `<Button.Root>{saved ? "Сохранено" : "Сохранить"}</Button.Root>` flows in by letters — not two buttons swapped with a condition.
+- Saving a form, one rule: the form stays on screen after saving (a Drawer or card that stays open, a settings section) → the button says «Сохранено», no notification; the form goes away (a Drawer or Modal closes, the page navigates) → a notification. A failure is always a notification (or the field's `error`), never only the button.
+- A long job from a button: `<Button.Root progress={0.42}>Экспорт 42%</Button.Root>` — not a ProgressBar next to it.
+- A round icon action (play, download, cancel or retry a transfer): `<Button.Root shape="circle" aria-label="Отменить отправку" progress={share}>` — its ring is the progress, it stays pressable; over a picture or video `variant="shade"`. Not a `border-radius: 50%` button of your own, not a ProgressCircle with `onClick`.
+- 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 />`.
+- 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).
+
+## Empty, loading, error — states flow, they never flip
+
+State change is continuous in the whole kit: every region that changes what it shows cross-fades, and loading holds the shape of what is coming.
+
+- Every region with loading / data / empty / error (or one record at a time): its content in `<Crossfade state={status} aria-busy={status === "loading"}>` — not `{loading ? <A /> : <B />}` that flips and makes the page jump. DataTable does this itself.
+- 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.
+- 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.
+- 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.
+- Remember the rail and folded groups with `persistKey` on `Sidebar.Root` — not your own `localStorage` code.
+
+## Narrow screens and touch
+
+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 always sit right under the search, never under the sections; 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.
+- 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; a full-height table is `scrollHeight="fill"` — never a height computed from `100vh`.
+- App sections on phones: `BottomNav` in `AppShell.Footer` — not in Main, not `position: fixed`, no own media query: the shell hides the footer while the Sidebar rail is on screen; a short task from the bottom edge: `Sheet` — Select, Dropdown, Popover and Modal become sheets below 640 by themselves.
+- Your hover styles inside `@media (hover: hover)`; nothing hover-only. Do not wrap kit fields to raise their text for iOS — they keep 16px on touch already.
+- A long form saves through the panel action with a count («Сохранить 3 изменения») — not a sticky bar at the bottom of a phone.
+- Sticky comes from the kit (`AppHeader` with `AppHeader.Tools`, the DataTable head, `stickyFirstColumn`, the Gantt header) — not your own `position: sticky` bar.
+
+## Spacing and values
+
+- Gaps are `gap` on the parent with `--prime-space-N` (N × 4px): 8 in a row of buttons, 20 field → field, 32 group → group; `PageContent.Body` already spaces blocks 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.
+
+## Anti-slop
+
+The whole list, bad → good: [anti-slop.md](anti-slop.md). Before handing over: [checklist.md](checklist.md).
+
+## Snippets to copy
+
+App root, once — the styles and the theme:
+
+```tsx
+import "prime-ui-kit/bundle.css";
+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).
+
+A page with one primary action and a field frame:
+
+```tsx
+import { Button, Icon, Input, PageContent } from "prime-ui-kit";
+import styles from "./ProfilePage.module.css"; // .form { display: grid; gap: var(--prime-space-5); }
+
+export function ProfilePage() {
+  return (
+    <PageContent.Root maxWidth="readable">
+      <PageContent.Header>
+        <PageContent.Title>Профиль</PageContent.Title>
+      </PageContent.Header>
+      <PageContent.Body>
+        <form className={styles.form} noValidate onSubmit={(event) => event.preventDefault()}>
+          <Input.Root label="Рабочая почта" hint="На неё придут счета" required>
+            <Input.Wrapper>
+              <Input.Icon side="start">
+                <Icon name="field.email" />
+              </Input.Icon>
+              <Input.Field type="email" placeholder="name@company.ru" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Button.Root type="submit">Сохранить</Button.Root>
+        </form>
+      </PageContent.Body>
+    </PageContent.Root>
+  );
+}
+```
+
+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):
+
+```tsx
+import { Button, 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); }
+// .client { width: 55%; }  .amount { width: 20%; }
+
+type Invoice = { id: string; client: string; amount: string };
+
+type InvoicesCardProps = {
+  status: "loading" | "ready" | "error";
+  invoices: Invoice[];
+  onRetry: () => void;
+};
+
+const PLACEHOLDER_ROWS = ["a", "b", "c"];
+
+export function InvoicesCard({ status, invoices, onRetry }: InvoicesCardProps) {
+  // One key per state: Crossfade cross-fades whenever it changes and glides the height.
+  const state = status === "ready" && invoices.length === 0 ? "empty" : status;
+
+  return (
+    <Card.Root variant="panel">
+      <Card.Header>
+        <Card.Title as="h2">Неоплаченные счета</Card.Title>
+      </Card.Header>
+      <Card.Body>
+        <Crossfade state={state} aria-busy={state === "loading"}>
+          {state === "loading" ? (
+            // Loading: Skeleton rows in the geometry of the data rows — not a Spinner.
+            <ul className={styles.rows}>
+              {PLACEHOLDER_ROWS.map((key) => (
+                <li key={key} className={styles.row}>
+                  <Skeleton className={styles.client} />
+                  <Skeleton className={styles.amount} />
+                </li>
+              ))}
+            </ul>
+          ) : null}
+          {state === "ready" ? (
+            <ul className={styles.rows}>
+              {invoices.map((invoice) => (
+                <li key={invoice.id} className={styles.row}>
+                  <Typography as="span" variant="body-m">
+                    {invoice.client}
+                  </Typography>
+                  <Typography as="span" variant="body-m">
+                    {invoice.amount}
+                  </Typography>
+                </li>
+              ))}
+            </ul>
+          ) : null}
+          {state === "empty" ? (
+            <EmptyPage.Root size="s" aria-labelledby="invoices-empty">
+              <EmptyPage.Icon>
+                <Icon name="status.success" />
+              </EmptyPage.Icon>
+              <EmptyPage.Title as="h3" id="invoices-empty">
+                Все счета оплачены
+              </EmptyPage.Title>
+              <EmptyPage.Description>Новые счета появятся здесь после выставления.</EmptyPage.Description>
+            </EmptyPage.Root>
+          ) : null}
+          {state === "error" ? (
+            <EmptyPage.Root size="s" role="alert" aria-labelledby="invoices-error">
+              <EmptyPage.Icon tone="danger">
+                <Icon name="status.danger" />
+              </EmptyPage.Icon>
+              <EmptyPage.Title as="h3" id="invoices-error">
+                Счета не загрузились
+              </EmptyPage.Title>
+              <EmptyPage.Description>Сервер не ответил. Данные не потеряны.</EmptyPage.Description>
+              <EmptyPage.Actions>
+                <Button.Root variant="soft" tone="neutral" onClick={onRetry}>
+                  Повторить
+                </Button.Root>
+              </EmptyPage.Actions>
+            </EmptyPage.Root>
+          ) : null}
+        </Crossfade>
+      </Card.Body>
+    </Card.Root>
+  );
+}
+```
+
+A refetch of data already on screen keeps `status="ready"` and the rows (set `aria-busy` on the
+card) — it does not go back to the skeleton.

package/dist/skill/checklist.md

@@ -0,0 +1,91 @@
+# Checklist before handing over a screen
+
+Answer every item yes or no. Any «no» is fixed before handing over.
+
+## Composition
+- [ ] The screen starts from the closest pattern in [composition.md](composition.md) (list, detail,
+      settings, form in a Drawer, dashboard, states, messenger) and keeps its skeleton.
+- [ ] One `PageContent.Header` with title, one-line description and actions; blocks in `PageContent.Body`.
+- [ ] Cards only for standalone blocks; no card around a table, a single field or the whole page.
+
+## 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: field→field 20, inline controls 8, group→group 32, section→section 40.
+- [ ] Inside a group things are visibly closer than between groups.
+
+## 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.
+
+## Text
+- [ ] Every text goes through a kit component or `Typography` with a role; no custom font sizes/weights.
+- [ ] One page title (`PageContent.Title`, `<h1>`); 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.
+
+## 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.
+
+## 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.
+
+## 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).
+
+## 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.
+
+## 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 header holds the title or path on every width.
+
+## 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.

package/dist/skill/choosing.md

@@ -0,0 +1,164 @@
+# Choosing a component
+
+First pick the category by the task, then the component inside it, then check the pairs that are easy to
+confuse. Links: [components.md](components.md). Whole screens: [composition.md](composition.md).
+
+## 1. Category by task
+
+| The user needs to… | Category |
+|---|---|
+| trigger an action (save, delete, go on) | Actions — Button, ButtonGroup, LinkButton |
+| type a value (text, number, code, file, photos), group the fields of a form | Inputs — Input, Textarea, DigitInput, FileUpload, Label, Hint, Fieldset |
+| pick from options, toggle, set a range, filter, a date or a color | Selection — Checkbox, Radio, Switch, SegmentedControl, Slider, Select, NativeSelect, TagSelect, SmartFilter, Datepicker, ColorField, ColorPicker, ColorSwatches |
+| see data: status labels, people, objects, numbers and their trend, properties of a record, rows, a board, a schedule, events, code, disclosed sections | Data display — Badge, Avatar, Thumbnail, Kbd, Card, DescriptionList, DataTable, Kanban, Gantt, Timeline, CodeBlock, Accordion, Sparkline, ChartFrame |
+| hold a conversation: read and send chat messages of every kind | Messages — Chat, Message, Gallery, VoicePlayer, VideoNote, Composer |
+| learn what happened, how far along it is, or watch a region load and change state; say it to a screen reader | Status and loading — Banner, Notification, ProgressBar, ProgressCircle, Spinner, Skeleton, Crossfade, EmptyPage, VisuallyHidden |
+| move between places: app sections, panels of a screen, the path, pages, steps | Navigation — Tabs, Breadcrumb, Pagination, Stepper, Sidebar, BottomNav |
+| see something on top of the page, or a photo or video full screen | Overlays — Tooltip, Popover, Dropdown, Modal, ConfirmDialog, Drawer, Sheet, CommandMenu, MediaViewer |
+| get the app frame and the structure of a page | Page — AppShell, AppHeader, PageContent, PageToolbar, Divider, ScrollContainer |
+| drag things by hand | Interaction — Dnd (a status board: Kanban in Data display) |
+| show a whole ready-made screen block (sign-in, sign-up, password reset, code) | Composition — LoginForm |
+| style text | Foundations — Typography |
+
+## 2. Inside a category
+
+**Actions.** One command → `Button.Root`. Several joined commands or toggles in one bar (editor
+toolbar, view switch with `pressed`) → `ButtonGroup`. Navigation to a URL that should look like text →
+`LinkButton` (it is an `<a>`); a URL that should look like a button → `Button.Root asChild` with `<a>`.
+
+**Text input.** One line → Input. Several lines → Textarea. The message input of a chat (Enter sends,
+attachments, replies, voice) → Composer, never a Textarea with a send button. Fixed-length code (OTP, PIN) → DigitInput.
+Files → FileUpload; an image gallery — photos of a listing or a product in order, the first the cover — is FileUpload too: `trigger="tile"` `layout="grid"` `cover` (no separate gallery component). A sign-in, sign-up, password-reset or code screen → LoginForm. Number with a unit →
+Input with `Input.InlineAffix`. Search and filters above a list or table → SmartFilter, a search alone there too
+(`fields={[]}`); a lone search
+field outside a list (a picker, a settings section, a panel) → Input with `Input.Icon` + `type="search"`
+and `aria-label`. Several fields of a form under one heading → Fieldset (`label`, `disabled` while the
+form saves).
+
+**Selection.**
+
+| Situation | Component |
+|---|---|
+| one independent yes/no that is submitted with a form | Checkbox |
+| one setting that applies immediately | Switch |
+| exactly one of 2–5 visible options in a form | Radio (`Radio.Group` with `label`) |
+| exactly one of 2–5 modes that change the view right now | SegmentedControl |
+| one of many (> 5) or a long list; icons, descriptions, search, groups | Select (`Select.Content searchable`) |
+| one record out of thousands for a form field (a client, a contract), searched on the server | Select with `search` / `onSearchChange`, `filter={false}`, `loading`, `hasMore` + `onLoadMore` — never a read-only field that opens a CommandMenu |
+| one value from a plain text list on a mobile-first form, posted with the form (`name`) | NativeSelect — the OS picker opens on phones |
+| several of many, shown as tags, with search / creation | TagSelect (`Select.Root multiple` when tags are not needed) |
+| narrowing a list or table by several fields, with search and show / hide | SmartFilter |
+| an approximate number in a range | Slider (exact number → Input) |
+| a date or a period | Datepicker |
+| a color from a fixed palette in a form or dialog | ColorSwatches (inline grid, default choice) |
+| a compact color next to a field or in a list row | ColorPresets (trigger + popover palette) |
+| 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
+`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
+hand-made grid of text pairs. Rows with columns, sorting, selection → DataTable.
+Items that flow through statuses and are moved by hand → Kanban (a single list to reorder, or items
+dropped onto folders or assignees → Dnd directly).
+Records with a start and an end compared across time — who is busy when, a project plan with
+phases and milestones → Gantt (never a DataTable of dates or hand-drawn bars); moved and resized by
+hand through `onBarChange`.
+Chronological events → Timeline; a conversation between people (support, a team chat) → Message —
+never a Timeline or a list of Cards styled as bubbles. Code → CodeBlock. A number with its trend over days or weeks (revenue, orders, sign-ups) → Sparkline: the latest value, its change and a line you can scrub; values with a sign by period → Sparkline `variant="bars"`; a chart with axes or several series → ChartFrame around a chart library or your own SVG (the panel, legend, tooltip, states and the screen-reader table come from the kit, the colors from `series` / `chartColors` — never status tones); values to read, sort or compare row by row → DataTable, not a chart.
+
+**Messages.** A whole conversation → `Chat`: `Chat.Root` with `Chat.Header` (avatar, `Chat.Title`,
+`Chat.Description`, `Chat.Actions` with `Chat.SearchButton`), `Chat.Search`, `Chat.Pinned`,
+`Chat.Messages` (from `items` with `renderMessage`, or `Message.Root` children) and `Chat.Footer`
+with the Composer — never a hand-built header, ScrollContainer and list. A list of messages without
+the rest (comments as a chat, a read-only history) → `Chat.Root` with `Chat.Messages` alone; one
+message on its own → `Message.Root`. A group chat → `Chat.Messages type="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`
+(alone there it is the message: no bubble); a face-to-camera report outside a chat → `VideoNote`
+alone. The two players take the same props (`src`, `duration`, `unplayed`, `disabled`, `playing`,
+the transcript and the `transfer` set); only VoicePlayer has `waveform` and a rate, only VideoNote a
+`poster`. Photos and videos in a message → `Message.Media`; the same album outside a chat (a post, a
+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,
+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 →
+ProgressBar `segments` (categories wear `color`, meanings wear `tone`; `legend` for color · name ·
+value · share); a ranking «label · value · share — bar» (top cities, a funnel) → ProgressBar
+`layout="rows"` with `scale`; compact goal / KPI ring or a ring breakdown → ProgressCircle (`value` or
+`segments`). Loading with unknown progress → `loading` on the component that has it (Button, Select,
+DataTable, ProgressBar, ProgressCircle, Sparkline, ChartFrame `state`); a region whose content has a shape (list, card,
+form) → Skeleton of that shape; nothing to hold (a running job, a status line) → Spinner. Nothing to
+show → EmptyPage; a region that failed to load → EmptyPage `tone="danger"` with
+`EmptyPage.RetryButton` (async `onRetry`).
+
+**State changes (a foundation of the kit).** A region never flips between states: any region switching between
+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>`.
+
+**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;
+only inside `AppShell.Footer`, never your own media query) — not Tabs, not a
+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 (where you are,
+⌘K search, a few app actions) is `AppHeader`; the page's own heading and actions are `PageContent`, its
+data tools `PageToolbar`. Use `PageToolbar` when a page has several tools above its data — sections,
+search and filters, a view switch, an action — and they must rearrange on a phone; one search or one
+filter above a single table goes into the DataTable `toolbar` instead. A page that gives all its
+height to the work (a board, a chat) may let `AppHeader` carry the page instead: `AppHeader.Title
+as="h1"` and the PageToolbar in `AppHeader.Tools` — then main has no `PageContent.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`. 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 |
+|---|---|
+| 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. |
+| 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, «Подробнее», «Все заказы»). |
+| Checkbox / Switch / Radio | Checkbox: choice submitted later with a button, can be multiple. Switch: on/off that applies at once (no Save button). Radio: one of several, submitted later. A privacy toggle inside a create form that is submitted → Checkbox. |
+| Gallery / MediaViewer / Thumbnail | Thumbnail: one picture or video of an object in a list, card or picker (selectable with `checked`). Gallery: an album of 1–10 photos and videos laid out by their ratios; it opens MediaViewer itself. MediaViewer: the full-screen viewer on its own, opened from your own thumbnails or a button (`getOrigin` for the zoom out of the tile). A grid of many images to browse → a CSS grid of Thumbnails, not a Gallery. |
+| Sparkline / ChartFrame | Sparkline: one series as a headline number with its change and a small line or bars you can scrub (`variant="bars"` for signed values). ChartFrame: a panel around a real chart (axes, several series, legend, tooltip, states) drawn by a library or your SVG. Rows to compare → DataTable. |
+| VoicePlayer / VideoNote | The same player props (`src`, `duration`, `playing`, transcript, `transfer`). VoicePlayer: audio, a waveform seek slider and a playback rate. VideoNote: a round face-to-camera video with a `poster`; alone in `Message.Root` it is the message. A video with controls → `Thumbnail.Video` / `Message.Media`. |
+| Card / plain section | Card for a bounded block of related content that stands out (metric, settings panel, side facts). A page section that is the only thing in its region needs no card: a `title-m` heading and the content. Never wrap a single field, a DataTable or a whole page in a Card. |
+| EmptyPage / empty DataTable | Empty table (no rows yet or nothing matches the filter): the DataTable `empty` prop — headers and toolbar stay. Whole page or region with no data at all (first run): EmptyPage with one action. |
+| Accordion / Tabs | Accordion when the user may need several sections open or reads them in order (FAQ, settings groups). Tabs when sections are alternatives viewed one at a time. |
+| Divider / gap | Divider inside a block between rows or a form and its footer. Between blocks and groups use air (`gap`), not lines. |
+| Breadcrumb / back button | Breadcrumb on pages below a top-level section (Счета → № 2026-0418) and deeper; not on top-level pages. A single “Back” without hierarchy → `LinkButton` or `Button.Root variant="ghost"`. |
+| Pagination / infinite scroll | Pages for tables people return to or reference: DataTable `paging="pages"` (default, Pagination in the footer). `paging="infinite"` for feeds. Standalone Pagination only for lists that are not a DataTable. |
+| 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. |
+| 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. |
+| FileUpload list / grid / gallery / strip | One component, four shapes. **List** (`layout="list"`, the default, with the drop zone): documents of a form, where the name matters; rows do not reorder. **Cards** (`trigger="tile"` `layout="grid"`): mixed photos and documents whose order matters (an inspection report). **Gallery** (`trigger="tile"` `layout="grid"` `cover` `accept="image/*"`): the photos of one object (a listing, a product); the first is the cover and dragging a photo first makes it the cover — no «make cover» button. **Strip** (`trigger="button"` + `FileUpload.Queue layout="strip"`): a paperclip and one scrolling row of tiles above a message field; the Composer already is this. Files on a server are `value` + `onValueChange` (return a promise to save); uploads are `queue` from `useUploadQueue`. One picture of a person is the avatar zone, not a gallery. |
+| Fieldset / a labelled group control | Fieldset: several **fields** under one heading (`title-s` legend), with one `disabled` for all of them while the form saves. One **choice** with a heading (`Radio.Group label`, SegmentedControl or ButtonGroup `label`, ColorSwatches `label`) is a single field — its own label names the group, no Fieldset around it. |
+| ColorField / ColorPicker / ColorSwatches | ColorField: any color as a form field (swatch + hex, the picker in a popover, `presets`). ColorPicker: the picker panel is the screen itself (a design tool, an inline editor). ColorSwatches: a short fixed palette visible at once. All but ColorSwatches come from `prime-ui-kit/color-picker`. |