prime-ui-kit 0.15.0 → 0.16.0

package/dist/skill/components.md

@@ -3,9 +3,19 @@
 Index of every kit component, grouped like the playground menu — by the task the user has (the same
 categories as [choosing.md](choosing.md)). Each row links to the full reference
 (`COMPONENT.md`: API, variants, states, a11y, mistakes) and to copyable scenarios (`examples/`).
-Paths are relative to this folder in the kit repository; in a consumer project prefix them with
-`node_modules/prime-ui-kit/` instead of `../`. Whole screens built from these components are the `screen.tsx` example of
-their main component, indexed in [composition.md](composition.md#screens).
+Whole screens built from these components are the `screen.tsx` example of their main component,
+indexed in [composition.md](composition.md#screens). The tables below are generated from each
+component's purpose line.
+
+<!-- components:start -->
+## Foundations (`foundations`)
+
+Text roles and icons.
+
+| Component | Purpose | Docs |
+|---|---|---|
+| Typography | Text roles of the Golos Text type scale applied to any text element, with reading-width guidance. | [COMPONENT.md](reference/components/typography/COMPONENT.md) · [examples](reference/components/typography/examples/) |
+| Icon | Animated glyphs: the semantic `<Icon name>` set, the full set of about 500 in `prime-ui-kit/icons`, `createIcon` for the rest; each plays a gesture when its host is hovered or pressed. | [api-contract.md](api-contract.md#icons) · [full list](reference/icon-set.ts) |
 
 ## Actions (`actions`)
 
@@ -24,13 +34,13 @@ Type a value, and the field anatomy: label, hint, error.
 | Component | Purpose | Docs |
 |---|---|---|
 | Input | Single-line text field with label, hint, error and slots for icons, affixes, a clear button and a counter. | [COMPONENT.md](reference/components/input/COMPONENT.md) · [examples](reference/components/input/examples/) |
-| Textarea | Multi-line text field with label, hint, error and a character counter; grows with its content from `rows` lines up to `maxRows`, then scrolls inside; `formatting` adds the Composer's Markdown toolbar and hotkeys. | [COMPONENT.md](reference/components/textarea/COMPONENT.md) · [examples](reference/components/textarea/examples/) |
+| Textarea | Multi-line text field with label, hint, error and a character counter; grows with its content by default. | [COMPONENT.md](reference/components/textarea/COMPONENT.md) · [examples](reference/components/textarea/examples/) |
 | DigitInput | A row of square single-digit cells for a fixed-length code (OTP from SMS, PIN, pickup code), with the field label, hint and error. | [COMPONENT.md](reference/components/digit-input/COMPONENT.md) · [examples](reference/components/digit-input/examples/) |
-| FileUpload | Files and the image gallery in one component: a document field (rows), file cards, an image gallery with a cover (`trigger="tile"` `layout="grid"` `cover`) or an attachment tray (`trigger="button"` + `FileUpload.Queue layout="strip"`); uploads through a queue (`useUploadQueue`), reorder and server saves. | [COMPONENT.md](reference/components/file-upload/COMPONENT.md) · [examples](reference/components/file-upload/examples/) |
+| FileUpload | One component for every set of files a person adds: a document field, file cards, an **image gallery with a cover**, an attachment tray — `trigger` picks how files are added, `layout` how they lie, `cover` makes the first tile the cover; uploads go through a queue, the order and removals can be saved on a server. | [COMPONENT.md](reference/components/file-upload/COMPONENT.md) · [examples](reference/components/file-upload/examples/) |
 | Label | Field label (native `<label>`) with required and optional markers. | [COMPONENT.md](reference/components/label/COMPONENT.md) · [examples](reference/components/label/examples/) |
 | Hint | Help text or a validation error under a field. | [COMPONENT.md](reference/components/hint/COMPONENT.md) · [examples](reference/components/hint/examples/) |
-| Fieldset | A frameless group of form fields: a `title-s` legend, the form rhythm and one `disabled` for all of them. | [COMPONENT.md](reference/components/fieldset/COMPONENT.md) · [examples](reference/components/fieldset/examples/) |
-| FieldList | An editable list of records of one shape: one row of fields per record, the column headings once, add, remove, reorder, pinned rows. | [COMPONENT.md](reference/components/field-list/COMPONENT.md) · [examples](reference/components/field-list/examples/) |
+| Fieldset | A frameless group of related form fields: a native `<fieldset>` with a `title-s` legend, the form rhythm between its fields and one `disabled` for all of them. | [COMPONENT.md](reference/components/fieldset/COMPONENT.md) · [examples](reference/components/fieldset/examples/) |
+| FieldList | An editable list of records of one shape — invoice lines, specs, contacts, prices by period: one row per record, the column headings once above the rows, a remove button per row and an add button under them. | [COMPONENT.md](reference/components/field-list/COMPONENT.md) · [examples](reference/components/field-list/examples/) |
 
 ## Selection (`selection`)
 
@@ -42,15 +52,15 @@ Pick from options: toggles, lists, ranges, filters, dates, colors.
 | Radio | Radio buttons for choosing exactly one option out of a small visible set. | [COMPONENT.md](reference/components/radio/COMPONENT.md) · [examples](reference/components/radio/examples/) |
 | Switch | An on/off switch for a setting that takes effect immediately. | [COMPONENT.md](reference/components/switch/COMPONENT.md) · [examples](reference/components/switch/examples/) |
 | SegmentedControl | A switch between 2–5 mutually exclusive options or modes that takes effect immediately. | [COMPONENT.md](reference/components/segmented-control/COMPONENT.md) · [examples](reference/components/segmented-control/examples/) |
-| Slider | A slider for picking an approximate numeric value within a range, with an optional label and value readout; `onCommit` gives the value once it settles. | [COMPONENT.md](reference/components/slider/COMPONENT.md) · [examples](reference/components/slider/examples/) |
+| Slider | A slider for picking an approximate numeric value within a range, with an optional label and value readout. | [COMPONENT.md](reference/components/slider/COMPONENT.md) · [examples](reference/components/slider/examples/) |
 | Select | A field for choosing one value (or several with `multiple`) from a closed list. | [COMPONENT.md](reference/components/select/COMPONENT.md) · [examples](reference/components/select/examples/) |
 | NativeSelect | The system `<select>` in the kit's field look: the operating system's picker opens on phones. | [COMPONENT.md](reference/components/native-select/COMPONENT.md) · [examples](reference/components/native-select/examples/) |
 | TagSelect | A multi-value field that shows the picked values as coloured tags, filters as you type and can create new tags. | [COMPONENT.md](reference/components/tag-select/COMPONENT.md) · [examples](reference/components/tag-select/examples/) |
-| SmartFilter | The search and filter bar of lists and tables: the search first and a filter button with a panel of values (with no fields it is a plain list search), applied filters as removable tags, and a "show / hide" choice for every value. | [COMPONENT.md](reference/components/smart-filter/COMPONENT.md) · [examples](reference/components/smart-filter/examples/) |
+| SmartFilter | The search and filter bar of lists and tables: the search first and a filter button with a panel of values and ranges, applied filters as removable tags, and a "show / hide" choice for every value. | [COMPONENT.md](reference/components/smart-filter/COMPONENT.md) · [examples](reference/components/smart-filter/examples/) |
 | Datepicker | A calendar for picking a date or a date range: a field with a popover (`Datepicker.Root`) or an embedded panel (`Datepicker.Panel`). | [COMPONENT.md](reference/components/datepicker/COMPONENT.md) · [examples](reference/components/datepicker/examples/) |
-| ColorField | A form field for any color: the swatch and its hex in a field box that opens the ColorPicker in a popover, from `prime-ui-kit/color-picker` (needs `react-aria-components`). | [COMPONENT.md](reference/components/color-field/COMPONENT.md) · [examples](reference/components/color-field/examples/) |
-| ColorPicker | Color selection: a full picker (hex field, area, channel sliders and fields, eyedropper, swatches) from `prime-ui-kit/color-picker` (needs `react-aria-components`), and `ColorPresets` for a quick color from a fixed palette from the root entry. | [COMPONENT.md](reference/components/color-picker/COMPONENT.md) · [examples](reference/components/color-picker/examples/) |
-| ColorSwatches | An inline color choice: preset swatches that wrap inside a form, without a popover. | [COMPONENT.md](reference/components/color-swatches/COMPONENT.md) · [examples](reference/components/color-swatches/examples/) |
+| ColorField | A form field for any color: the swatch and its hex in a field box that opens the ColorPicker in a popover. | [COMPONENT.md](reference/components/color-field/COMPONENT.md) · [examples](reference/components/color-field/examples/) |
+| ColorPicker | Color selection: a full picker (hex field, area, channel sliders and fields, eyedropper, swatches) and `ColorPresets` for a quick color from a fixed palette. | [COMPONENT.md](reference/components/color-picker/COMPONENT.md) · [examples](reference/components/color-picker/examples/) |
+| ColorSwatches | An inline color choice: preset swatches that fill the width of a form or panel and wrap, without a popover. | [COMPONENT.md](reference/components/color-swatches/COMPONENT.md) · [examples](reference/components/color-swatches/examples/) |
 
 ## Data display (`data-display`)
 
@@ -60,18 +70,18 @@ Show data: labels, people, objects, cards, tables, boards, feeds, code, disclose
 |---|---|---|
 | Badge | The kit's one chip: a static label for a status, category or count, a removable value or applied filter, and a pressable toggle with a hover action — in a palette color. | [COMPONENT.md](reference/components/badge/COMPONENT.md) · [examples](reference/components/badge/examples/) |
 | Avatar | A round photo of a person or organization with an initials or icon fallback, a presence dot and overlapping groups. | [COMPONENT.md](reference/components/avatar/COMPONENT.md) · [examples](reference/components/avatar/examples/) |
-| Thumbnail | A preview of an object — product, vehicle, file, cover — at a fixed aspect ratio (`ratio`), an image or a video (`Thumbnail.Video`, first frame and length), a colored icon fallback, and a selectable tile (`checked`). | [COMPONENT.md](reference/components/thumbnail/COMPONENT.md) · [examples](reference/components/thumbnail/examples/) |
-| Sparkline | A small chart — a smooth line over a fading area, a bare line or bars — with its headline: the value at rest, its change and its date; any point can be scrubbed; a tooltip beside the scrubbed point; `layout="compact"` — just the plot, for a table cell. | [COMPONENT.md](reference/components/sparkline/COMPONENT.md) · [examples](reference/components/sparkline/examples/) |
-| ChartFrame | A dashboard panel around any chart (Recharts, ECharts, visx, Chart.js or a hand-drawn SVG): title, headline value, a measured plot area, a series legend that hides series (`hiddenSeries`), loading / empty / error states (`state`, `onRetry`) that cross-fade, a tooltip body and a data table for screen readers. | [COMPONENT.md](reference/components/chart-frame/COMPONENT.md) · [examples](reference/components/chart-frame/examples/) |
+| Thumbnail | A preview of an object — product, vehicle, file, cover, video — at a fixed aspect ratio, with a colored icon fallback; it can open the object or be selected. | [COMPONENT.md](reference/components/thumbnail/COMPONENT.md) · [examples](reference/components/thumbnail/examples/) |
 | Kbd | A key cap for a keyboard key or a shortcut, rendered as a native `<kbd>`. | [COMPONENT.md](reference/components/kbd/COMPONENT.md) · [examples](reference/components/kbd/examples/) |
 | Card | A filled surface block with structural templates for metrics, charts, lists, calls to action and covers. | [COMPONENT.md](reference/components/card/COMPONENT.md) · [examples](reference/components/card/examples/) |
-| DescriptionList | Read-only properties of a record: «label — value» pairs on a `<dl>` that stack by themselves where the room is narrow, with a muted dash for an empty value. | [COMPONENT.md](reference/components/description-list/COMPONENT.md) · [examples](reference/components/description-list/examples/) |
-| DataTable | A data table with sorting, pages or infinite scroll (on the client or by the server, `source="server"`), row selection, row groups, rows reordered by drag (`onReorder`), rows that open a record (link or in place), a column chooser (`DataTable.ColumnsMenu`), nested rows and loading / empty / error states. | [COMPONENT.md](reference/components/data-table/COMPONENT.md) · [examples](reference/components/data-table/examples/) |
-| Kanban | A board of status columns — without wells — cards on the page under a header plate (`plain`, default) or a header line (`line`) — or filled wells (`well`): cards move by drag, touch hold and Alt + arrows, columns reorder by a grip in their header (`reorderableColumns`, `columnOrder`), with column descriptions and colors, WIP limits, loading and empty columns. | [COMPONENT.md](reference/components/kanban/COMPONENT.md) · [examples](reference/components/kanban/examples/) |
-| Gantt | A resource or project schedule: rows with bars on a day / week / month axis, lanes for overlaps, milestones, a today line, a pinned first column, moves and resizes by pointer and keyboard through an async `onBarChange`, new bars drawn on empty space (`onBarCreate`), virtualized rows and days for thousands of rows. | [COMPONENT.md](reference/components/gantt/COMPONENT.md) · [examples](reference/components/gantt/examples/) |
+| DataTable | A data table with sorting, pages or infinite scroll, row selection, row groups, rows that open a record, a column chooser, nested rows and loading / empty / error states. | [COMPONENT.md](reference/components/data-table/COMPONENT.md) · [examples](reference/components/data-table/examples/) |
+| Kanban | A board of status columns: cards reorder within a column and move between columns by pointer, touch hold and keyboard, with announcements, WIP limits, loading and empty states and a layout that scrolls inside itself at any width. | [COMPONENT.md](reference/components/kanban/COMPONENT.md) · [examples](reference/components/kanban/examples/) |
+| Gantt | A resource or project schedule: rows of people, rooms, vehicles or tasks with bars on a day / week / month axis, edited by pointer and keyboard. | [COMPONENT.md](reference/components/gantt/COMPONENT.md) · [examples](reference/components/gantt/examples/) |
 | Timeline | An event feed: dots on a thin line, event title and date, an optional amount on the right, grouped under labels. | [COMPONENT.md](reference/components/timeline/COMPONENT.md) · [examples](reference/components/timeline/examples/) |
 | CodeBlock | A static TypeScript / TSX snippet with syntax highlighting, on a filled panel or bare inside a host. | [COMPONENT.md](reference/components/code-block/COMPONENT.md) · [examples](reference/components/code-block/examples/) |
 | Accordion | Collapsible sections: FAQ, settings groups, checkout steps. | [COMPONENT.md](reference/components/accordion/COMPONENT.md) · [examples](reference/components/accordion/examples/) |
+| Sparkline | A small chart — a smooth line over a fading area, a bare line or bars — with its headline: the value at rest, its change and its date; any point can be scrubbed. | [COMPONENT.md](reference/components/sparkline/COMPONENT.md) · [examples](reference/components/sparkline/examples/) |
+| ChartFrame | A dashboard panel around any chart — Recharts, ECharts, visx, Chart.js or a hand-drawn SVG — with the title, a headline value, a measured plot area, a series legend, a tooltip body and a data table for screen readers. | [COMPONENT.md](reference/components/chart-frame/COMPONENT.md) · [examples](reference/components/chart-frame/examples/) |
+| DescriptionList | Read-only properties of a record: «label — value» pairs on a `<dl>` that stack by themselves where the room is narrow, with a muted dash for an empty value. | [COMPONENT.md](reference/components/description-list/COMPONENT.md) · [examples](reference/components/description-list/examples/) |
 
 ## Messages (`messages`)
 
@@ -79,13 +89,13 @@ A conversation: message bubbles of every kind and the composer.
 
 | Component | Purpose | Docs |
 |---|---|---|
-| Chat | A conversation assembled: `Chat.Header` (avatar, title, status that turns into «печатает…», actions, `Chat.SearchButton`), `Chat.Search` (marks, counts and steps through matches), `Chat.Pinned`, `Chat.Messages` — the one message list: from `items` + `renderMessage` (dates, runs, unread band added) or `Message.Root` children, virtualized, new messages that enter by themselves, the «к последним» button, read receipts, jumps, selection with `Chat.SelectionBar`, history paging, `type="group"` author headers and avatars — and `Chat.Footer` for the Composer; a first-load state of bubble skeletons (`Chat.Messages loading`). | [COMPONENT.md](reference/components/chat/COMPONENT.md) · [examples](reference/components/chat/examples/) |
-| Message | One chat message in its shell (bubble, picture, circle): incoming / outgoing, runs of one author (the tail ends a run), time and delivery ticks in the corner, a group chat's author header (`Message.Author` with `tag` and `Message.AuthorIcon`), reply, forwarded, reactions with the reaction bar, the context menu, and every content kind (text with Markdown, `Message.Media` albums, round video, voice, file, location, contact, link preview); `Message.Typing`; a bot's inline keyboard (`Message.Actions`); spoilers in the Markdown. | [COMPONENT.md](reference/components/message/COMPONENT.md) · [examples](reference/components/message/examples/) |
-| Gallery | Photos and videos as a messenger album: one, or up to ten laid out from their aspect ratios with nothing measured; video tiles with a first frame and length, the shared transfer disk per tile, tiles that open the album in MediaViewer (`viewer={false}` to open your own from `onOpenChange` / `onIndexChange`). `Message.Media` is a Gallery in a message. | [COMPONENT.md](reference/components/gallery/COMPONENT.md) · [examples](reference/components/gallery/examples/) |
-| VoicePlayer | A voice message player: a round play disk, a waveform that is the seek slider, and the time with the playback speed — in a chat bubble or standalone; one sound at a time on the page; `getWaveform` for audio without levels. | [COMPONENT.md](reference/components/voice-player/COMPONENT.md) · [examples](reference/components/voice-player/examples/) |
-| VideoNote | A round video message: a still first frame with the play disk, played with sound on a press; the same player API as VoicePlayer (transcript, transfer either way, one sound at a time); alone in `Message.Root` it is the message. | [COMPONENT.md](reference/components/video-note/COMPONENT.md) · [examples](reference/components/video-note/examples/) |
-| Composer | The message input of a chat: a field that grows from one line, Enter to send, attachments through an upload queue, a reply / edit bar whose id goes with the send, Markdown formatting of a selection, voice and round video messages with pause, and the «печатает…» signal (`onActivityChange`). | [COMPONENT.md](reference/components/composer/COMPONENT.md) · [examples](reference/components/composer/examples/) |
-| ChatList | The conversation list of a messenger, built from List: dialogs from `items` + `renderItem` (`ChatList.Item` with the avatar, name, time, preview), the open one `value`, a search field that marks matches, unread / muted / «@» counts, pin, delivery ticks, «печатает…» and drafts that cross-fade, a row menu at the pointer (`ChatList.ItemMenu`), rows that glide to a new order, virtualized rows, loading placeholders and `hasMore` / `onLoadMore`. | [COMPONENT.md](reference/components/chat-list/COMPONENT.md) · [examples](reference/components/chat-list/examples/) |
+| Chat | A conversation, assembled: the header with who it is with, search, pinned messages, the virtualized message list with dates, runs, selection and jumps, typing, and the Composer at the bottom. | [COMPONENT.md](reference/components/chat/COMPONENT.md) · [examples](reference/components/chat/examples/) |
+| Message | One chat message in its shell: a speech bubble, a picture or a circle, incoming or outgoing, the tail that ends a run, the time and delivery ticks in the corner, reactions, the menu, a group chat's author header, and every content kind of a messenger. | [COMPONENT.md](reference/components/message/COMPONENT.md) · [examples](reference/components/message/examples/) |
+| VoicePlayer | A voice message player: a round play disk, a waveform that is the seek slider, and the time with the playback speed — the same player API as VideoNote. | [COMPONENT.md](reference/components/voice-player/COMPONENT.md) · [examples](reference/components/voice-player/examples/) |
+| VideoNote | A round video message: a still first frame with the play disk that plays with sound on a press — the same player API as VoicePlayer. | [COMPONENT.md](reference/components/video-note/COMPONENT.md) · [examples](reference/components/video-note/examples/) |
+| Composer | The message input of a chat: a field that grows from one line, Enter to send, attachments, a reply / edit bar, Markdown formatting of a selection, and voice or round video messages from the same button. | [COMPONENT.md](reference/components/composer/COMPONENT.md) · [examples](reference/components/composer/examples/) |
+| Gallery | Photos and videos as a messenger album: one, or up to ten laid out from their aspect ratios alone, every box final before a byte loads; a tile opens the album in MediaViewer. | [COMPONENT.md](reference/components/gallery/COMPONENT.md) · [examples](reference/components/gallery/examples/) |
+| ChatList | The conversation list of a messenger: the pane where the reader picks a dialog — avatar, name, time, the last message, counts, «печатает…» and drafts. | [COMPONENT.md](reference/components/chat-list/COMPONENT.md) · [examples](reference/components/chat-list/examples/) |
 
 ## Status and loading (`status`)
 
@@ -109,13 +119,13 @@ Move between places: app navigation (side rail, bottom bar on phones), tabs, the
 
 | Component | Purpose | Docs |
 |---|---|---|
-| Tabs | Tabs for navigating between content panels of one screen. | [COMPONENT.md](reference/components/tabs/COMPONENT.md) · [examples](reference/components/tabs/examples/) |
+| Tabs | A tab bar of folder tabs for navigating between content panels of one screen: the active tab is the host's surface rising into the strip, the panel is the host's content with no frame or padding of its own. | [COMPONENT.md](reference/components/tabs/COMPONENT.md) · [examples](reference/components/tabs/examples/) |
 | Breadcrumb | Breadcrumbs: the path to the current page. | [COMPONENT.md](reference/components/breadcrumb/COMPONENT.md) · [examples](reference/components/breadcrumb/examples/) |
 | Pagination | Page-by-page navigation: arrows, page numbers with ellipsis and a compact «3 / 12» view. | [COMPONENT.md](reference/components/pagination/COMPONENT.md) · [examples](reference/components/pagination/examples/) |
-| List | A selectable list of rows — the list half of a list + detail screen: conversations, tickets, mail, records; the open one is `current`. | [COMPONENT.md](reference/components/list/COMPONENT.md) · [examples](reference/components/list/examples/) |
-| Stepper | Steps of a multi-step process with pending, active, completed and danger statuses. | [COMPONENT.md](reference/components/stepper/COMPONENT.md) · [examples](reference/components/stepper/examples/) |
+| Stepper | Steps of a multi-step process with pending, current, completed and danger statuses. | [COMPONENT.md](reference/components/stepper/COMPONENT.md) · [examples](reference/components/stepper/examples/) |
 | Sidebar | App side navigation in three modes — expanded, compact, hidden — and an off-canvas panel on narrow screens. | [COMPONENT.md](reference/layout/sidebar/COMPONENT.md) · [examples](reference/layout/sidebar/examples/) |
-| BottomNav | Phone navigation: 2–6 sections at the bottom, flat or a floating glass capsule, icons with or without labels, an optional round action. | [COMPONENT.md](reference/layout/bottom-nav/COMPONENT.md) · [examples](reference/layout/bottom-nav/examples/) |
+| BottomNav | Phone navigation: a bar of 2–6 main sections at the bottom of the screen, optionally with a round action beside it. | [COMPONENT.md](reference/layout/bottom-nav/COMPONENT.md) · [examples](reference/layout/bottom-nav/examples/) |
+| List | A selectable navigation list of rows: the master half of a list + detail screen (tickets, mail, records). | [COMPONENT.md](reference/components/list/COMPONENT.md) · [examples](reference/components/list/examples/) |
 
 ## Overlays (`overlays`)
 
@@ -126,12 +136,12 @@ Floating layers above the page, from tooltip to modal.
 | Tooltip | A short hint that appears next to an element on hover or keyboard focus. | [COMPONENT.md](reference/components/tooltip/COMPONENT.md) · [examples](reference/components/tooltip/examples/) |
 | Popover | A non-modal floating panel anchored to a trigger: short forms, filters, confirmations, explanations. | [COMPONENT.md](reference/components/popover/COMPONENT.md) · [examples](reference/components/popover/examples/) |
 | Dropdown | A menu of actions that opens from a trigger: picking an item runs it and closes the menu. | [COMPONENT.md](reference/components/dropdown/COMPONENT.md) · [examples](reference/components/dropdown/examples/) |
-| Modal | A dialog over the page for confirmations, short forms and important text. | [COMPONENT.md](reference/components/modal/COMPONENT.md) · [examples](reference/components/modal/examples/) |
+| Modal | A dialog over the page for a short form or important text that must be finished or acknowledged before the page goes on. | [COMPONENT.md](reference/components/modal/COMPONENT.md) · [examples](reference/components/modal/examples/) |
 | ConfirmDialog | The confirm of a destructive or weighty action in one piece: the question, the consequence, Cancel and an action that runs its own request. | [COMPONENT.md](reference/components/confirm-dialog/COMPONENT.md) · [examples](reference/components/confirm-dialog/examples/) |
-| Drawer | A modal side panel that slides in from the side: filters, forms and record details. | [COMPONENT.md](reference/components/drawer/COMPONENT.md) · [examples](reference/components/drawer/examples/) |
+| Drawer | A modal panel that slides in from the side: filters, forms and record details without leaving the page. | [COMPONENT.md](reference/components/drawer/COMPONENT.md) · [examples](reference/components/drawer/examples/) |
+| Command Menu | A search palette over the page: the query filters commands and pages, Enter runs the active one. | [COMPONENT.md](reference/components/command-menu/COMPONENT.md) · [examples](reference/components/command-menu/examples/) |
 | Sheet | A panel raised from the bottom edge for a short task that ends by itself: pick a date, choose an action, leave a few words. | [COMPONENT.md](reference/components/sheet/COMPONENT.md) · [examples](reference/components/sheet/examples/) |
-| CommandMenu | A search palette over the page: the query filters commands and pages, Enter runs the active one. | [COMPONENT.md](reference/components/command-menu/COMPONENT.md) · [examples](reference/components/command-menu/examples/) |
-| MediaViewer | A full-screen viewer of photos and videos that behaves like a native one: pages follow the finger, pictures zoom and pan with momentum, a swipe closes it, and it opens out of the thumbnail it came from; a filmstrip of every item (`thumbnails`), videos that play in place. | [COMPONENT.md](reference/components/media-viewer/COMPONENT.md) · [examples](reference/components/media-viewer/examples/) |
+| MediaViewer | A full-screen viewer of photos and videos that behaves like a native one: pages follow the finger, pictures zoom and pan with momentum, a swipe closes it, and it opens out of the thumbnail it came from. | [COMPONENT.md](reference/components/media-viewer/COMPONENT.md) · [examples](reference/components/media-viewer/examples/) |
 
 ## Page (`page`)
 
@@ -140,11 +150,11 @@ The frame and structure of a screen: app shell, app header, page column, page pa
 | Component | Purpose | Docs |
 |---|---|---|
 | AppShell | The app frame: a content panel that is the page itself and a navigation rail one layer above it. | [COMPONENT.md](reference/layout/app-shell/COMPONENT.md) · [examples](reference/layout/app-shell/examples/) |
-| AppHeader | The page's bar at the top of the content panel: the page title (`AppHeader.Title`) with a line of data, the page's own buttons, its tools (`AppHeader.Tools` with a PageToolbar) and the phone menu button; as high as the Sidebar brand row. | [COMPONENT.md](reference/layout/app-header/COMPONENT.md) · [examples](reference/layout/app-header/examples/) |
-| PageContent | Page structure inside the main column: title, page actions, titled sections (`PageContent.Section`) and the tile grid (`PageContent.Grid`); a page as high as the panel (`fill`) and list + detail (`PageContent.Split`). | [COMPONENT.md](reference/components/page-content/COMPONENT.md) · [examples](reference/components/page-content/examples/) |
-| PageToolbar | The panel at the top of a page — search and filter, sections, view options and the primary action — laid out from its own width: one row when wide, stacked rows when narrow, the active filters right under the search. | [COMPONENT.md](reference/components/page-toolbar/COMPONENT.md) · [examples](reference/components/page-toolbar/examples/) |
+| AppHeader | The page's bar at the top of the app's content panel: the page title with a line of data, the page's tools and its own buttons — only what the current page needs. | [COMPONENT.md](reference/layout/app-header/COMPONENT.md) · [examples](reference/layout/app-header/examples/) |
+| PageContent | Page structure inside the main column: title, page actions and content blocks, titled sections and the tile grid of a dashboard; a page as high as the panel and the list + detail layout. | [COMPONENT.md](reference/components/page-content/COMPONENT.md) · [examples](reference/components/page-content/examples/) |
+| PageToolbar | The panel at the top of a page — sections, filter and search, view options and the primary action — laid out from its own width: one row when wide, stacked rows when narrow, search and filter always first with the active filters under the top row. | [COMPONENT.md](reference/components/page-toolbar/COMPONENT.md) · [examples](reference/components/page-toolbar/examples/) |
 | Divider | A hairline separator inside one surface, horizontal or vertical, with or without a label. | [COMPONENT.md](reference/components/divider/COMPONENT.md) · [examples](reference/components/divider/examples/) |
-| ScrollContainer | The kit's one scroll region: a thin scrollbar or none (`scrollbar="hidden"`), soft edges where content is hidden (`edges` fade / shadow), `snap`, `lock`, correct shrinking inside flex and grid parents; pinned to the end for chats (`anchor="end"`), edge events for loading more (`onReachStart` / `onReachEnd`). | [COMPONENT.md](reference/components/scroll-container/COMPONENT.md) · [examples](reference/components/scroll-container/examples/) |
+| ScrollContainer | The kit's one scroll region: a thin scrollbar, soft edges wherever content is hidden, and correct shrinking inside flex and grid parents. | [COMPONENT.md](reference/components/scroll-container/COMPONENT.md) · [examples](reference/components/scroll-container/examples/) |
 | LoginForm | A sign-in card with a logo, title, provider buttons and a form; covers sign-in, sign-up, password reset and code confirmation. | [COMPONENT.md](reference/components/login-form/COMPONENT.md) · [examples](reference/components/login-form/examples/) |
 
 ## Interaction (`interaction`)
@@ -153,16 +163,7 @@ Direct manipulation: drag and drop (Kanban builds a board on it).
 
 | Component | Purpose | Docs |
 |---|---|---|
-| Dnd | Pointer-driven drag and drop: reorderable lists, draggable items and drop zones, with touch and keyboard support. | [COMPONENT.md](reference/components/dnd/COMPONENT.md) · [examples](reference/components/dnd/examples/) |
-
-## Foundations (`foundations`)
-
-Text roles and icons.
-
-| Component | Purpose | Docs |
-|---|---|---|
-| Typography | Text roles of the Golos Text type scale applied to any text element, with reading-width guidance. | [COMPONENT.md](reference/components/typography/COMPONENT.md) · [examples](reference/components/typography/examples/) |
-| Icon | Animated glyphs: the semantic `<Icon name>` set, the full set of about 500 in `prime-ui-kit/icons`, `createIcon` for the rest; each plays a gesture when its host is hovered or pressed. | [api-contract.md](api-contract.md#icons) · [full list](reference/icon-set.ts) |
+| Dnd | Pointer-driven drag and drop: reorderable lists, draggable items and drop zones on one shared session, with a lifted clone, a gap where the item lands, auto-scroll, touch support and a keyboard path. | [COMPONENT.md](reference/components/dnd/COMPONENT.md) · [examples](reference/components/dnd/examples/) |
 
 ## Infrastructure (`infrastructure`)
 
@@ -171,3 +172,4 @@ Docs tooling, not product UI.
 | Component | Purpose | Docs |
 |---|---|---|
 | ExampleFrame | A documentation frame: live preview, source code and device width in one block. | [COMPONENT.md](reference/components/example-frame/COMPONENT.md) · [examples](reference/components/example-frame/examples/) |
+<!-- components:end -->

package/dist/skill/composition.md

@@ -20,11 +20,11 @@ playground page. What each screen teaches is in [Screen rules](#screen-rules) at
 | [Record editor](#record-editor) | field-list | [screen.tsx](reference/components/field-list/examples/screen.tsx) | a document page (a long form): the title, a line of description and «Сохранить тариф» in `PageContent.Header`; a plan card edited in aside sections: name and description, specs in a `FieldList` (icon-only `Select` and `ColorPresets` in compact columns, pinned rows, reorder), the price and its changes by month in one list with the base row pinned, a setup fee in three currencies in one row under one heading, save with «Сохранено» on the button |
 | [Dashboard](#dashboard) | card | [screen.tsx](reference/components/card/examples/screen.tsx) | title + a line of data in `AppHeader`, period switch and report in its `PageToolbar`; KPI row that cross-fades to the new period, a Sparkline revenue trend, invoiced vs paid in a ChartFrame, panels with progress and a split, short table + link to the list |
 | [Screen states](#screen-states) | crossfade | [screen.tsx](reference/components/crossfade/examples/screen.tsx) | title + the statement date in `AppHeader`, page error in a Banner with retry, region loading with a Skeleton, Crossfade between states, table error in place, first-run EmptyPage |
-| [Messenger](#messenger) | chat | [screen.tsx](reference/components/chat/examples/screen.tsx) | title + the unread count in `AppHeader`; a full-height PageContent.Split of a `ChatList` with its search (live last message, ticks, unread counts, «печатает…») and a `Chat`: `Chat.Header` with the back button, avatar, title, the status that turns into «печатает…» (`typing`) and the search button, `Chat.Search`, `Chat.Messages` from `items` + a stable `renderMessage` (dates, runs and the unread band from the data, history loaded above with `hasOlder` / `onLoadOlder`, a first load in skeletons), text, a photo, a file and sent voice, reply and edit from the menu through `Composer.Context value` (`replyTo` / `editOf`), the jump to the quoted message (`Message.Reply target`), optimistic sends whose messages rise from the composer while the client's answer slides in, «печатает…» both ways (`onActivityChange` → `Chat.Root typing`), unread counts from `onNewMessage` and `onRead`, the Composer with attachments in `Chat.Footer` |
+| [Messenger](#messenger) | chat | [screen.tsx](reference/components/chat/examples/screen.tsx) | title + the unread count in `AppHeader`; a full-height PageContent.Split of a `ChatList` with its search (live last message, ticks, unread counts, «печатает…») and a `Chat`: `Chat.Header` with the back button, avatar, title, the status that turns into «печатает…» (`typing`) and the search button, `Chat.Search`, `Chat.Messages` from `items` + `renderMessage` (dates, runs and the unread band from the data, history loaded above with `hasOlder` / `onLoadOlder`, a first load in skeletons), text, a photo, a file and sent voice, reply and edit from the menu through `Composer.Context messageId` (`replyTo` / `editOf`), the jump to the quoted message (`Message.Reply target`), optimistic sends whose messages rise from the composer while the client's answer slides in, «печатает…» both ways (`onActivityChange` → `Chat.Root typing`), unread counts from `onNewMessage` and `onRead`, the Composer with attachments in `Chat.Footer` |
 | [Sales pipeline board](#sales-pipeline-board) | kanban | [screen.tsx](reference/components/kanban/examples/screen.tsx) | AppHeader titles the page (`h1` + a Description with the open deals and their sum) and carries a PageToolbar with SmartFilter search, a board / list SegmentedControl and the one primary action; Crossfade between a `plain` Kanban (stages without wells, deal cards on the page) and a DataTable of the same deals, column totals in `renderColumnMeta`, moves saved through an `onValueChange` promise that the server can refuse, the deal in a Drawer with a DescriptionList and stage actions, skeleton first load |
 | [App frame](#app-frame) | app-shell | [screen.tsx](reference/layout/app-shell/examples/screen.tsx) | Sidebar rail on a wide screen, floating BottomNav in `AppShell.Footer` on a phone («Ещё» opens the Sidebar panel), AppHeader with the menu button and the page title (`h1`) with a line of data, counts on items, a home page that cross-fades between sections |
 | [Media library](#media-library) | file-upload | [screen.tsx](reference/components/file-upload/examples/screen.tsx) | AppHeader titles the page (`h1` + a Description with the object) and carries a PageToolbar with sections and counts, search (`SmartFilter` with `fields={[]}`), order and «Загрузить»; uploads through `useUploadQueue` in `FileUpload` tiles (`trigger="tile"`, `layout="grid"`) with progress, a failure and retry, a done file moving into the library; a grid of `Thumbnail` / `Thumbnail.Video` tiles that open `MediaViewer` out of the tile (`getOrigin`, `thumbnails`, `renderActions`) or, in selection mode, are picked (`checked`) for bulk download and a `ConfirmDialog` delete; a Skeleton first load and a filtered `EmptyPage` in a `Crossfade` |
-| [Resource schedule](#resource-schedule) | gantt | [screen.tsx](reference/components/gantt/examples/screen.tsx) | AppHeader titles the page (`h1` + a Description with the people shown) and carries a `PageToolbar` with search, role / client filters, team sections and «Назначить» over a full-height `Gantt` (`scrollHeight="fill"`); people with avatars, client hues, lanes for overlaps, locked absences and milestones; moves saved through an async `onBarChange` or refused and glided back, new work drawn with `onBarCreate` and named in a Modal (cancel fades the ghost), `onSelect` details in a Drawer with a `DescriptionList` and a confirmed removal, `loading` and filtered `empty` |
+| [Resource schedule](#resource-schedule) | gantt | [screen.tsx](reference/components/gantt/examples/screen.tsx) | AppHeader titles the page (`h1` + a Description with the people shown) and carries a `PageToolbar` with search, role / client filters, team sections and «Назначить» over a full-height `Gantt` (`scrollHeight="fill"`); people with avatars, client hues, lanes for overlaps, locked absences and milestones; moves saved through an async `onBarChange` or refused and glided back, new work drawn with `onBarCreate` and named in a Modal (cancel fades the ghost), `onItemOpen` details in a Drawer with a `DescriptionList` and a confirmed removal, `loading` and filtered `empty` |
 
 Pick the closest one, rename the domain, keep the skeleton. Change structure only when the task needs
 it, and then by the rules below.
@@ -47,20 +47,21 @@ no title. Never two titles; never no `<h1>`.
 ```
 AppShell.Root                      once per app (layouts.md#app-frame-once-per-app)
 ├─ AppShell.Nav → Sidebar          navigation rail, one layer above the page
-├─ AppHeader.Root                  the page's header: only what this page needs
-│  ├─ AppHeader.Start
-│  │  ├─ AppHeader.MenuButton      opens the Sidebar below 768px
-│  │  ├─ Breadcrumb + Separator    only on a nested record: the path up
-│  │  └─ AppHeader.Title           the one h1 + AppHeader.Description: a line of data
-│  ├─ AppHeader.Actions            the page's own buttons (export, a more menu)
-│  └─ AppHeader.Tools              second row → PageToolbar.Root: search and filter, sections,
-│                                  view, the primary action; Chips under them
+├─ (header row)                    the page's AppHeader.Root shows here
 └─ AppShell.Main                   gutters + top air (24, 32 from 1024px); the page renders here
-   └─ PageContent.Page | Root      the page you deliver
-      └─ PageContent.Body          blocks 24 apart, starting at main's top air
-         ├─ PageContent.Grid       every tile of the screen, 16 on both axes
-         │  └─ PageContent.Cell    span (of 12), rows; the tile fills it
-         └─ PageContent.Section    a new topic: h2 label (+ Actions), 40 from its neighbours
+   └─ the page you deliver
+      ├─ AppHeader.Root            the page's header: only what this page needs
+      │  ├─ AppHeader.Start        led by the menu button the header draws while the Sidebar is off-canvas
+      │  │  ├─ Breadcrumb + Separator  only on a nested record: the path up
+      │  │  └─ AppHeader.Title     the one h1 + AppHeader.Description: a line of data
+      │  ├─ AppHeader.Actions      the page's own buttons (export, a more menu)
+      │  └─ AppHeader.Tools        second row → PageToolbar.Root: search and filter, sections,
+      │                            view, the primary action; Chips under them
+      └─ PageContent.Root as="section"
+         └─ PageContent.Body       blocks 24 apart, starting at main's top air
+            ├─ PageContent.Grid    every tile of the screen, 16 on both axes
+            │  └─ PageContent.Cell span (of 12), rows; the tile fills it
+            └─ PageContent.Section a new topic: h2 label (+ Actions), 40 from its neighbours
 
 Document page: the header without a title, and in main
    └─ PageContent.Root maxWidth="wide" | "readable"
@@ -68,9 +69,10 @@ Document page: the header without a title, and in main
       └─ PageContent.Body
 ```
 
-- A screen component renders its page: its `AppHeader.Root` (through the shell's `header`) and its
-  body. Styles, `applyTheme`, `NotificationProvider` and `AppShell` live at the app root.
-- `PageContent.Page` for app pages (full panel width); `PageContent.Root maxWidth="wide"` for
+- A screen renders its page: its `AppHeader.Root` and its body. The header shows in the shell's
+  header row wherever the page renders it. Styles, `applyTheme`, `NotificationProvider` and
+  `AppShell` live at the app root.
+- `PageContent.Root as="section"` for app pages (full panel width); `PageContent.Root maxWidth="wide"` for
   settings, `maxWidth="readable"` for one narrow column of text or fields.
 - No outer padding, no margins: `AppShell.Main` has the gutters and the top air under the header,
   `PageContent` has block → block 24, section → section 40, tile → tile 16 (and header → body 24 on
@@ -200,12 +202,14 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
 ## 4. Surfaces
 
 - Inside the app the content panel is the page (layer 0 of the surface ladder); a `Card` on it is
-  layer 1, and fields take the fill of the layer they sit on. The kit sets this by context — never set backgrounds.
+  layer 1, and fields take the fill of the layer they sit on. The kit sets this by context — never
+  set backgrounds ([the one exception](foundations.md#your-own-bounded-block)).
 - **Card when** the block stands alone and has its own title: a KPI tile, a settings panel, facts in a
   side column, a chart. **No card when** the block is the only thing in its region: a section heading
   and the content are enough.
-- `DataTable` is already a filled block — never inside a Card. No card in a card. No borders around
-  blocks; `Divider` only inside a block (list rows, a form and its footer).
+- `DataTable` is already a filled block — never inside a Card; a card in a card only as
+  [the next layer, sparingly](foundations.md#card-in-a-card). No borders around blocks; `Divider`
+  only inside a block (list rows, a form and its footer).
 - Floating layers (menus, popovers, dialogs) come only from kit overlays.
 
 ## 5. Density and size
@@ -214,8 +218,8 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
   a dense back-office table may be `s` with its toolbar; a sign-in card may be `l`.
 - One row = one size: everything in a toolbar or an actions row lines up.
 - A control nested in another component's row is one tier down: buttons and menus in table cells `s`,
-  a segmented switch in a card header `s`. Kit hosts (Popover, Banner, LoginForm, the DataTable toolbar)
-  size their `Button.Root` / `Input.Root` children themselves.
+  a segmented switch in a card header `s`. A sized kit host ([the host tier](api-contract.md#size-and-the-host-tier))
+  sizes the kit controls inside it itself.
 
 ## 6. Actions
 
@@ -242,7 +246,8 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
 - One value in several units is one row of fields under one heading, each unit in its field's
   `Input.InlineAffix`; a base value with overrides is one `FieldList` with the base pinned first.
   The shape of the data decides the layout: [ux.md](ux.md#2-the-shape-of-the-data-decides-the-layout).
-- Fields 20 apart; related short fields side by side in an `auto-fit` grid with `align-items: start`
+- Fields 20 apart; related short fields side by side in an
+  [intrinsic grid](responsive.md#intrinsic-grids) with `align-items: start`
   (`reserveSupportRow` on Input / Textarea keeps neighbours aligned); groups 32 apart, each a
   `Fieldset label` (its `title-s` heading 16 above the fields, no frame); no dividers between groups.
 - Form column width: one column up to ~65ch; never stretch a form across a wide panel.
@@ -254,16 +259,23 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
   navigates) → a `Notification`; a failure → a `Notification` or the field's `error`.
 - A footer button outside the form submits it with `form={formId}`.
 - Choice controls: Checkbox when the value is submitted later, Switch when it applies at once (no Save
-  in that section), `Radio.Group label` for one of 2–5 visible options.
+  in that section), `Radio.Group label` for one of a few visible options
+  ([choosing.md](choosing.md#2-inside-a-category)).
 
 ## 8. Tables and lists
 
-- A list page is `DataTable` with the filters in its `toolbar` — `SmartFilter.Toolbar` and
-  `SmartFilter.Chips` inside `SmartFilter.Root` (or one SegmentedControl / Select for a single field).
-- Where the filters go: tools of one table live in its `toolbar`; when the page itself carries
-  sections with counts, a view switch (board / list, grid / list) or filters that drive more than one
-  table — a board, a schedule, a media grid — the page gets `PageToolbar` and the table keeps only its
-  own tools (`DataTable.ColumnsMenu`).
+### Where the filters go
+
+- The page's tools — its search and filters, sections, the view, the primary action — are the
+  page's: `AppHeader.Tools` → `SmartFilter.Root` around a `PageToolbar.Root`, `SmartFilter.Toolbar`
+  in `PageToolbar.Tools`, `SmartFilter.Chips` in `PageToolbar.Chips` ([the list page](#list-page)).
+  A search alone is the same SmartFilter with `fields={[]}`.
+- The DataTable `toolbar` keeps the table's own tools: `DataTable.ColumnsMenu`, a bulk bar of the
+  selected rows. Search and filters go there only when the table is not the page's main region (a
+  table in a section of a record, in a Drawer).
+
+### Tables
+
 - Paging is built in: `paging="pages"` (default, Pagination and the «Показано 1–6 из 10» range in the
   footer), `paging="infinite"` for feeds, `paging="none"` for short lists on dashboards and details.
 - When the server holds more than you load (a CRM list, a register): `source="server"` — `rows` is the
@@ -271,11 +283,11 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
   request, a new search or filter sets `page` to 1, and the old rows stay with `loading` until the
   answer comes ([server.tsx](reference/components/data-table/examples/server.tsx)).
 - Columns: `numeric` for amounts, counts and dates (end-aligned, tabular; `headerAlign="end"` to line the
-  head up); statuses as `Badge` from one status → color map; an avatar + two-line cell for people and
+  head up); statuses as `Badge` from one status → tone map; an avatar + two-line cell for people and
   companies; row menu last.
 - States in place: `loading` (+ `loadingRows`) while there are no rows, `empty` for nothing found
-  (string → compact EmptyPage, or your own `EmptyPage size="s"` with «Сбросить фильтры»), `error` for a
-  failed load. The head and toolbar stay.
+  (string → compact EmptyPage, or your own `EmptyPage size="s"` with «Сбросить фильтры»), `loadError`
+  for a failed load. The head and toolbar stay.
 - Phones: the table scrolls inside itself, `stickyFirstColumn` keeps the key column; never let the page
   scroll sideways. Short lists of objects can be `Card variant="list"` instead of a table.
 
@@ -287,7 +299,7 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
 | a form saved and still on screen | the submit button's text: «Сохранено» |
 | a state of the page or a section that persists (sync failed, trial ends, read-only) | `Banner` as the first block of `PageContent.Body` (or inside the Card it concerns) |
 | a problem with one field | the field's `error` |
-| a region failed to load | the region shows it in place: DataTable `error`, `EmptyPage` with `EmptyPage.Icon tone="danger"` and «Повторить» |
+| a region failed to load | the region shows it in place: DataTable `loadError`, or `EmptyPage tone="danger"` with `EmptyPage.RetryButton` |
 | a region is loading | DataTable `loading`; otherwise a `Skeleton` in the geometry of the content + `aria-busy` on the region; `Spinner` only when there is no shape to hold |
 | a region changes state (loading → data → empty → error, another record) | its content in `Crossfade state={status}` — always, so the change flows instead of flipping |
 | nothing here yet (first run) | `EmptyPage` with one action (`tone="accent"` icon for a call to start) |
@@ -312,20 +324,17 @@ mirror the data's rows and gaps with `Skeleton`, so the swap moves nothing on th
 | a name for an icon button | `Tooltip` |
 | search across commands and pages (⌘K) | `CommandMenu` |
 
-Every overlay takes `closeOnOutsideClick` / `closeOnEscape`. A destructive confirm is `ConfirmDialog`, which
-turns them off itself; a form in a Modal or Drawer holds closing with `Modal.Guard` / `Drawer.Guard`
-(`busy` while a request runs, `dirty` for unsaved changes).
+Every overlay closes on Escape and on a press outside unless you turn it off
+([the Dismiss row](api-contract.md#shared-vocabulary-exported-types)); a form in a Modal or Drawer holds
+closing with `Modal.Guard` / `Drawer.Guard` (`busy` while a request runs, `dirty` for unsaved
+changes) instead.
 
 ## 11. Narrow screens
 
-- Layouts are intrinsic: `repeat(auto-fit, minmax(min(100%, …), 1fr))` grids and flex-wrap with a large
-  `flex-grow` on the main column — no breakpoints needed, and they work in any container. Media queries
-  only for app-frame decisions (the phone menu header) at 640 · 768 · 1024 · 1280.
-- From 320px: the page's tools wrap under the header title and the primary action takes its own row when the search would be squeezed (built in), side columns drop below the main one,
+- Layouts are [intrinsic](responsive.md#intrinsic-grids) — no breakpoints needed, and they work in
+  any container; a media query only in [the breakpoints' scope](responsive.md#breakpoints).
+- From 320px: the page's tools wrap under the header title ([the page panel](responsive.md#page-panel--pagetoolbar)), side columns drop below the main one,
   pairs of fields stack, tables scroll inside themselves, dialogs stack their footers (built in).
-- A page with search and filter, sections, a view switch and the primary action gets `PageToolbar`:
-  search and filter first with the active filters under the top row, one row when wide, stacked rows
-  12 apart when narrow; the primary action at the top row's end, on its own row on a phone.
 - Rearrange, never hide: every function of the desktop screen is on the phone — in another place or a
   menu. App sections on phones: `BottomNav` in `AppShell.Footer`; a short task from the bottom
   edge: `Sheet`.
@@ -362,8 +371,9 @@ Rules for your own component:
 - Follows API v1 ([api-contract.md](api-contract.md)): `size` (default `m`), `tone`/`color`, `X.Root` +
   `X.Part` when it has parts (a single export when it has none), `hint` / `error` props, `labels` for
   system strings, `data-*` for state.
-- Styled with a CSS Module on `--prime-*` tokens. Bounded block: a `Card`, or a plain tile on
-  `--prime-color-layer-nested` + `--prime-card-radius`. Never override kit internals or reach into their class names.
+- Styled with a CSS Module on `--prime-*` tokens. Bounded block:
+  [a `Card`, or the plain tile](foundations.md#your-own-bounded-block). Never override kit internals
+  or reach into their class names.
 - **Threshold:** a pattern used twice becomes a component. Two things that look the same are one
   component with a variant, never two components or two hand-written copies.
 
@@ -409,7 +419,7 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 - The page lives in the `AppHeader`: `AppHeader.Title` is the only heading, its `AppHeader.Description` is one line of figures («10 счетов · просрочено 2 на …»), not a sentence about the page; main has no `PageContent.Header`.
 - The tools are `AppHeader.Tools` → `SmartFilter.Root` around a `PageToolbar.Root`: `SmartFilter.Toolbar` in `PageToolbar.Tools`, `SmartFilter.Chips` in `PageToolbar.Chips`, export (an icon-only `soft` + `neutral` button) and the one primary action (`solid`, last) in `PageToolbar.Actions`. The table itself has no `toolbar`.
-- A status is a `Badge` with one color per meaning across the product (`STATUS` is one map); the text carries the meaning, the color repeats it.
+- A status is a `Badge` with one `tone` per meaning across the product (`STATUS` is one map); the text carries the meaning, the tone repeats it.
 - Numbers and dates are `numeric` columns with `headerAlign="end"` (tabular figures, values and heading on the end edge). On a phone the table scrolls inside itself and `stickyFirstColumn` keeps the number in place — the page never scrolls sideways.
 - Row actions are a `Dropdown` behind an `action.more` icon of size `s`: controls in cells are one tier below the table. Delete is `tone="danger"` at the end of the menu.
 - Empty after a filter is the table's `empty` with `EmptyPage size="s"` and a «Сбросить фильтры» action; the header and the filters stay in place.
@@ -424,7 +434,7 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 - Columns are a CSS module on flex-wrap without breakpoints: the main one grows, the side one holds ~18rem and drops below when the main one runs out of room.
 - A section without a frame is `PageContent.Section label`: an h2 heading 16 px above the table; `Card variant="panel"` only for standalone blocks of the side column. A table is already a filled block — never put it in a card.
 - «Label → value» pairs about the client are `DescriptionList.Root orientation="vertical"` with `DescriptionList.Item label`; amounts are tabular figures, the total is larger (`title-m`) and ends where the «Сумма» column ends (the table cell inset).
-- History is a `Timeline`: events top-down from the latest, dates in `Timeline.Meta`; a row highlights on hover.
+- History is a `Timeline`: events top-down from the latest, dates in `Timeline.ItemMeta`; a row highlights on hover.
 
 ### Settings page
 
@@ -483,7 +493,7 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 - The header carries the page: `AppHeader.Title` with an `AppHeader.Description` line of data — the accounts and the date of the statement the screen stands on; main has no `PageContent.Header`.
 - An error that concerns the whole page is a `Banner tone="danger"` as the first block of `PageContent.Body` with a «Повторить» action; the action's result is a `Notification`.
-- A region's error is in the region's place: `error` on the `DataTable` (the table head stays), not a pop-up.
+- A region's error is in the region's place: `loadError` on the `DataTable` (the table head stays), not a pop-up.
 - Table loading is `loading` + `loadingRows` (a skeleton of rows); card loading is a `Skeleton` in the shape of its rows and `aria-busy` on the card, and the block's height does not change. The state change is smooth: the card's region is in `Crossfade state={status}`, the table body changes by itself.
 - Stale data beats emptiness: the balances are shown as of the previous date, and that is said on the right in `Card.Header`.
 - Empty on the first run is `EmptyPage size="s"` inside the panel: an icon with `tone="accent"`, what it is and why, one action. An empty filter result is the table's `empty`.
@@ -497,11 +507,11 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 - Layout: `PageContent.Split` in a `fill` page: the dialog list `ChatList` (last message, ticks, unread, «печатает…») and the conversation beside it; on a narrow panel one pane at a time with `PageContent.BackButton` in `Chat.Header`.
 - Search over the dialogs is the field of `ChatList` itself: `search` and `onSearchChange`; you filter the list (by name and last message), and the list shows the match in rows, the number found and an empty result itself. Never put a field of your own above the list.
 - The conversation is `Chat.Root` in the pane's card: the header, `Chat.Search`, `Chat.Messages` and `Chat.Footer` with the Composer. Never assemble your own header, `ScrollContainer` and feed — the chat links search, jumps, selection and «печатает…» itself.
-- Messages are data: `items` with `getKey`, `getAuthor`, `getDate` (service events through `isService`), the first unread is `unread`; the feed computes dates, runs, tails and the avatar place. `renderMessage` in `useCallback`: only the changed message re-renders.
+- Messages are data: `items` with `getKey`, `getAuthor`, `getDate` (service events through `isService`), the first unread is `unread`; the feed computes dates, runs, tails and the avatar place. `renderMessage` may be inline: only a message whose item or place changed renders again, so whatever a row shows lives in its item, and a reply's original comes from `entry.find(key)`.
 - History is `hasOlder` and `onLoadOlder` with a promise: while it runs, a bubble-shaped `Skeleton` placeholder stands on top, and the view does not jump.
 - Each kind of message is its own part of `Message`: text with markup, photos and albums, a file, a `VoicePlayer`; the screen renders the kinds its domain has. The others (`VideoNote`, a location, a contact, a link preview, reactions, a forwarded header) are shown on the Message, VoicePlayer and VideoNote pages; pinned messages and selection on the Chat page.
 - Sending is a `Composer` with `onSend` without waiting: the message is in the feed at once with a clock under a stable id, then one tick, then two. Your own message rises from the input, the client's answer slides in from the side — the feed animates new messages itself; history and status changes are not animated.
-- Reply and edit from `Message.Menu` open `Composer.Context` with `value`: `onSend` gets `replyTo` / `editOf`, the plate closes itself after sending; ↑ in an empty field is `onEditLast`. A quote in a bubble is `Message.Reply target`: a scroll to the original with a flash.
+- Reply and edit from `Message.Menu` open `Composer.Context` with `messageId`: `onSend` gets `replyTo` / `editOf`, the plate closes itself after sending; ↑ in an empty field is `onEditLast`. A quote in a bubble is `Message.Reply target`: a scroll to the original with a flash.
 - «Печатает…»: your own signal is `Composer onActivityChange` into the socket, the other side's is `Chat.Root typing`: the line in the header and the bubble at the end of the feed together.
 - Unread: `onNewMessage` adds an incoming message to the dialog's count, `onRead` subtracts what the reader really saw. Scrolled up — the round «to the latest» button counts the new ones itself.
 - Search in the conversation is `Chat.SearchButton` and `Chat.Search`; pinned messages, when the domain has them, are `Chat.Pinned` between them and the feed.
@@ -516,7 +526,7 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 - The board is the main area of the page, so its `variant` is the default, `plain`: stages without wells, headers and deal cards stand right on the page — one level of nesting, no frames of your own around the columns.
 - The placement of deals is `value` as `{ [stage]: id[] }`; `onValueChange` returns the request's promise and applies `value` only after the answer; a server refusal returns the card to its place.
 - Stage totals are in `renderColumnMeta` («2 сделки · 3 575 000 ₽»), the stage color is the column's `color`.
-- A deal opens through `onItemClick` of `Kanban.Root` (click, Enter, Space; never after a drag) in a `Drawer` with a `DescriptionList`; no `onClick` / `onKeyDown` of your own on the card; a deal with its own page — `getItemHref`. The stage change is available in the panel too — dragging is not the only way; `Drawer.Guard busy` holds the panel while saving.
+- A deal opens through `onItemOpen` of `Kanban.Root` (click, Enter, Space; never after a drag) in a `Drawer` with a `DescriptionList`; no `onClick` / `onKeyDown` of your own on the card; a deal with its own page — `getItemHref`. The stage change is available in the panel too — dragging is not the only way; `Drawer.Guard busy` holds the panel while saving.
 - The first load is `loading` on `Kanban` and `DataTable`: skeletons in the geometry of cards and rows.
 
 ### App frame
@@ -524,11 +534,11 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 [app-shell/examples/screen.tsx](reference/layout/app-shell/examples/screen.tsx)
 
 - The frame is `AppShell.Template` (or `AppShell.Root`): `nav` is `Sidebar.Root`, `header` is `AppHeader.Root`, `footer` is `BottomNav.Root`; the page is the children. `scrollResetKey` is the current section (in a router, the pathname), so a new page opens at the top.
-- The kit decides the switch itself: below 768 px the `Sidebar` goes off the edge, `AppHeader.MenuButton` appears and `AppShell.Footer` shows the `BottomNav`; while the rail is on screen the footer is hidden. No media queries or `position: fixed` of your own.
-- `BottomNav` holds 2–6 main sections, one word each; the rest lives in the `Sidebar`, and «Ещё» opens it as a panel (`aria-expanded`). `floating` is a glass capsule; `AppShell.Main` leaves room under it itself.
+- The kit decides the switch itself: below 768 px the `Sidebar` goes off the edge, the `AppHeader` draws its menu button and `AppShell.Footer` shows the `BottomNav`; while the rail is on screen the footer is hidden. No media queries, menu state or `position: fixed` of your own.
+- `BottomNav` holds 2–6 main sections, one word each; the rest lives in the `Sidebar`, and «Ещё» opens it as a panel through `useAppShellNav()` (`aria-expanded`, `aria-controls`, `setOpen`). `floating` is a glass capsule; `AppShell.Main` leaves room under it itself.
 - Every page titles itself in the header: `AppHeader.Title` with the section's name and an `AppHeader.Description` that carries data («Среда, 14 октября · открытых задач: 3»); main has no `PageContent.Header`, its body starts with the page's blocks.
 - Counts: `Sidebar.ItemCount` (a plain number for information, `color="red"` when it needs action) and `BottomNav.ItemCount` only for what needs attention; the number is the same in both navigations.
-- Choosing a section in either navigation goes through one handler that also closes the Sidebar panel.
+- Choosing a section in either navigation goes through one handler; an activated Sidebar item closes the off-canvas panel by itself.
 - A section change is a `Crossfade` by `state`: the page changes smoothly instead of jumping. Menu items in an app with a router are `asChild` + `NavLink`.
 
 ### Media library
@@ -537,7 +547,7 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 - A work screen titles itself in the app header: `AppHeader.Title` «Медиатека» with an `AppHeader.Description` naming the object; main has no `PageContent.Header`.
 - Sections, search, order and «Загрузить» are one `PageToolbar` panel in `AppHeader.Tools`: search is a `SmartFilter.Toolbar` with `fields={[]}`, sections a `SegmentedControl` with `SegmentedControl.Count`.
-- Uploads are `useUploadQueue` + `FileUpload.Root trigger="tile" layout="grid"`: progress, «В очереди», the failure reason and retry are built in, the add tile is also the drop zone; «Загрузить» opens the same `inputRef`.
+- Uploads are `useUploadQueue` + `FileUpload.Root trigger="tile" layout="grid"`: progress, «В очереди», the failure reason and retry are built in, the add tile is also the drop zone; «Загрузить» opens the same picker (`picker.current?.open()`).
 - A finished file leaves the queue for the library: its address is `item.result` of the server's answer, not the queue's `preview`.
 - The library grid is a CSS grid of `Thumbnail` with `fullWidth` and one `ratio`; a video is `Thumbnail.Video`, which draws the duration and the play mark itself. `Gallery` does not fit here: it is an album of up to 10.
 - A tile either opens or selects: when browsing it is `Thumbnail.Root asChild` with a button, when selecting — `checked` / `onCheckedChange`; «Выбрать» turns the mode on.
@@ -556,5 +566,5 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 - `onBarChange` returns a promise and changes the data only after the service answers: while it runs the bar is busy; a refusal (work on an absence) is `notify` and `throw`, and the bar returns to its previous dates by itself.
 - `onBarCreate`: a range drawn on an empty place holds a busy draft while a `Modal` with `Modal.Guard busy` asks for the name and the client; saving adds the bar and resolves the promise, cancel rejects it — the draft dissolves. Work over an absence is refused at once.
 - The legend of client hues is a row of `Badge.Root color` with `Badge.Dot` in the chart's `toolbar`; `renderBarTooltip` names the client in the tooltip under the dates, so the client reads not only by color.
-- `onSelect` opens a `Drawer` with a `DescriptionList` (the person, the client `Badge`, the period and duration, `ProgressBar`); removing a task is a `ConfirmDialog` with an async `onConfirm`.
+- `onItemOpen` opens a `Drawer` with a `DescriptionList` (the person, the client `Badge`, the period and duration, `ProgressBar`); removing a task is a `ConfirmDialog` with an async `onConfirm`.
 - States are on the chart itself: `loading` draws `Skeleton` placeholder rows in its geometry, `empty` an `EmptyPage size="s"` with «Сбросить фильтры»; the panel stays in place.