prime-ui-kit 0.15.0 → 0.17.0

package/dist/skill/choosing.md

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

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,25 +136,23 @@ 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`)
 
-The frame and structure of a screen: app shell, app header, page column, page panel, separators, scroll regions, and ready-made screen blocks (sign-in).
+The frame and structure of a screen: app shell, the page (its top bar, header, tools, sections, grid, list and detail), separators, scroll regions, and ready-made screen blocks (sign-in).
 
 | 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/) |
+| AppShell | The app frame — navigation and the page: 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/) |
+| Page | The page inside the app frame: everything at the top belongs to it — a top bar with the title, tools and buttons, the large document title in the flow — then sections, the tile grid and the list + detail layout. | [COMPONENT.md](reference/layout/page/COMPONENT.md) · [examples](reference/layout/page/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 +161,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 +170,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 -->