prime-ui-kit 0.9.3 → 0.11.0

package/dist/skill/components.md

@@ -0,0 +1,177 @@
+# Components
+
+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 in
+[composition.md](composition.md) and [patterns/](patterns/).
+
+## Actions (`actions`)
+
+Trigger an action.
+
+| Component | Purpose | Docs |
+|---|---|---|
+| Button | A button for explicit actions, with variants, tones, sizes and a built-in loading state. | [COMPONENT.md](reference/components/button/COMPONENT.md) · [examples](reference/components/button/examples/) |
+| ButtonGroup | Joined buttons and toggle segments in one neutral bar. | [COMPONENT.md](reference/components/button-group/COMPONENT.md) · [examples](reference/components/button-group/examples/) |
+| LinkButton | A real link styled as a text action, sized on the control tiers. | [COMPONENT.md](reference/components/link-button/COMPONENT.md) · [examples](reference/components/link-button/examples/) |
+
+## Inputs (`inputs`)
+
+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. | [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/) |
+| 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/) |
+
+## Selection (`selection`)
+
+Pick from options: toggles, lists, ranges, filters, dates, colors.
+
+| Component | Purpose | Docs |
+|---|---|---|
+| Checkbox | A checkbox for an independent yes/no choice that submits with a form: checked, indeterminate, with a hint or an error. | [COMPONENT.md](reference/components/checkbox/COMPONENT.md) · [examples](reference/components/checkbox/examples/) |
+| 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/) |
+| 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/) |
+| 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/) |
+
+## Data display (`data-display`)
+
+Show data: labels, people, objects, cards, tables, boards, feeds, code, disclosed sections.
+
+| Component | Purpose | Docs |
+|---|---|---|
+| 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 line or bar chart with its headline — the value at rest, its change against the point before and its date — where 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): 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/) |
+| 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: 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/) |
+| 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/) |
+
+## Messages (`messages`)
+
+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. | [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`. | [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/) |
+
+## Status and loading (`status`)
+
+Say what happens: system messages, progress, loading placeholders, state swaps, empty states.
+
+| Component | Purpose | Docs |
+|---|---|---|
+| Banner | Full-width in-flow message for a page, section or card: status icon, title, description, actions and dismiss. | [COMPONENT.md](reference/components/banner/COMPONENT.md) · [examples](reference/components/banner/examples/) |
+| Notification | Pop-up toast notifications: `NotificationProvider` at the app root and `notify()` from any screen. | [COMPONENT.md](reference/components/notification/COMPONENT.md) · [examples](reference/components/notification/examples/) |
+| ProgressBar | Linear progress: one value on a native `<progress>`, `segments` that split a whole (storage by type, leads by source) with an optional legend, or a ranking of rows (top cities, a funnel). | [COMPONENT.md](reference/components/progress-bar/COMPONENT.md) · [examples](reference/components/progress-bar/examples/) |
+| ProgressCircle | Circular progress — the ring version of ProgressBar: one value or `segments` that split a whole, with status colors and optional content in the center. | [COMPONENT.md](reference/components/progress-circle/COMPONENT.md) · [examples](reference/components/progress-circle/examples/) |
+| Spinner | An indeterminate loading indicator: the kit ring with the share unknown — a quarter arc turning on a faint track while a request runs. | [COMPONENT.md](reference/components/spinner/COMPONENT.md) · [examples](reference/components/spinner/examples/) |
+| Skeleton | A placeholder in the shape of the content that is loading — text lines, a control, an avatar, a block — so the layout is in place before the data arrives. | [COMPONENT.md](reference/components/skeleton/COMPONENT.md) · [examples](reference/components/skeleton/examples/) |
+| EmptyPage | Empty or failed state of a page, a block or a menu: icon, title, explanation and an action — a retry for a failed load. | [COMPONENT.md](reference/components/empty-page/COMPONENT.md) · [examples](reference/components/empty-page/examples/) |
+| Crossfade | A region that cross-fades between its states (loading → data → empty → error) and glides to the new height, so the page below does not jump. | [COMPONENT.md](reference/components/crossfade/COMPONENT.md) · [examples](reference/components/crossfade/examples/) |
+| VisuallyHidden | Text that screen readers read and nobody sees: the words behind an icon, a badge or a change on the screen. | [COMPONENT.md](reference/components/visually-hidden/COMPONENT.md) · [examples](reference/components/visually-hidden/examples/) |
+
+## Navigation (`navigation`)
+
+Move between places: app navigation (side rail, bottom bar on phones), tabs, the path, pages, steps.
+
+| 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/) |
+| 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/) |
+| 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/) |
+| 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/) |
+
+## Overlays (`overlays`)
+
+Floating layers above the page, from tooltip to modal.
+
+| Component | Purpose | Docs |
+|---|---|---|
+| 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/) |
+| 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/) |
+| 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/) |
+
+## Page (`page`)
+
+The frame and structure of a screen: app shell, app header, page column, page panel, separators, scroll regions.
+
+| 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 bar at the top of the content panel: where you are, ⌘K search, a few actions, the phone menu button; as high as the Sidebar brand row. May carry the page title (`AppHeader.Title as="h1"`) and the page tools (`AppHeader.Tools`). | [COMPONENT.md](reference/layout/app-header/COMPONENT.md) · [examples](reference/layout/app-header/examples/) |
+| PageContent | Page structure inside the main column: title, description, page actions and content sections; 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/) |
+| 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/) |
+
+## Interaction (`interaction`)
+
+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/) |
+
+## Composition (`composition`)
+
+Ready-made screen blocks; whole screens are in [composition.md](composition.md) and [patterns/](patterns/).
+
+| Component | Purpose | Docs |
+|---|---|---|
+| 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/) |
+
+## 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) |
+
+## Infrastructure (`infrastructure`)
+
+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/) |

package/dist/skill/composition.md

@@ -0,0 +1,312 @@
+# Composition — how a screen is assembled
+
+A screen made from the kit looks finished when every block sits on the same few rules: one skeleton,
+one rhythm, one size, one primary action, fill instead of lines, and a state for every region. This
+file is those rules; [patterns/](patterns/) are the same rules as working screens.
+
+## Patterns
+
+**Start from a pattern.** Each one is a complete page (React + one CSS module on tokens), copyable as
+is, and is shown live with its code in the playground (category «Композиция»):
+
+| Screen | Pattern | Shows |
+|---|---|---|
+| List / registry | [list-page.tsx](patterns/list-page.tsx) | header with one primary action, SmartFilter in the DataTable toolbar, statuses, row menu, pages, filtered empty state |
+| One record | [detail-page.tsx](patterns/detail-page.tsx) | Breadcrumb + status in the header, actions by weight, main column + side column of Cards, Timeline |
+| Settings | [settings-page.tsx](patterns/settings-page.tsx) | heading column + panel per section, form with its own save, Switches that apply at once, danger zone with a confirm |
+| Create in a side panel | [form-drawer.tsx](patterns/form-drawer.tsx) | Drawer form: groups, errors on submit, focus on the first invalid field, loading, toast |
+| Dashboard | [dashboard.tsx](patterns/dashboard.tsx) | period switch, 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.tsx](patterns/screen-states.tsx) | page error in a Banner with retry, region loading with a Skeleton, Crossfade between states, table error in place, first-run EmptyPage |
+| Messenger | [chat.tsx](patterns/chat.tsx) | PageContent.Split of dialogs and a `Chat`: `Chat.Header` with the back button, avatar, title, the status that turns into «печатает…» (`typing`) and the search button, `Chat.Search`, `Chat.Pinned`, `Chat.Messages` from `items` + a stable `renderMessage` (dates, runs, the unread band and service events from the data, history loaded above with `hasOlder` / `onLoadOlder`), every kind of Message (photos, file, contact, voice in a VoicePlayer with a transcript, round video), reactions, 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`, selection with `Chat.SelectionBar`, delivery ticks, the Composer in `Chat.Footer` |
+
+Pick the closest one, rename the domain, keep the skeleton. Change structure only when the task needs
+it, and then by the rules below.
+
+## 1. Page skeleton
+
+```
+AppShell.Root                      once per app (layouts.md#app-frame-once-per-app)
+├─ AppShell.Nav → Sidebar          navigation rail, one layer above the page
+├─ AppHeader.Root                  menu button / title or path / ⌘K search / app actions
+└─ AppShell.Main                   gutters; the page renders here
+   └─ PageContent.Section | Root   the page you deliver
+      ├─ PageContent.Header
+      │  ├─ Breadcrumb             only below a top-level section; first child → 8 above the title
+      │  ├─ PageContent.Title      the one h1
+      │  ├─ PageContent.Description one sentence of context (or a status Badge + the key fact)
+      │  └─ PageContent.Actions    page buttons; wrap under the title on narrow screens
+      └─ PageContent.Body          blocks 40 apart: Banner, KPI grid, table, sections, Cards
+```
+
+- A screen component renders only its page. Styles, `applyTheme`, `NotificationProvider` and
+  `AppShell` live at the app root.
+- `PageContent.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, `PageContent` has header → body 32 and
+  block → block 40. Your CSS lays out only the inside of a block.
+
+```tsx
+import { Button, Dropdown, Icon, PageContent } from "prime-ui-kit";
+
+export function OrdersHeader() {
+  return (
+    <PageContent.Header>
+      <PageContent.Title>Заказы</PageContent.Title>
+      <PageContent.Description>Все заказы магазина за выбранный период.</PageContent.Description>
+      <PageContent.Actions>
+        <Dropdown.Root>
+          <Dropdown.Trigger>
+            <Button.Root variant="soft" tone="neutral" aria-label="Другие действия">
+              <Button.Icon>
+                <Icon name="action.more" />
+              </Button.Icon>
+            </Button.Root>
+          </Dropdown.Trigger>
+          <Dropdown.Content>
+            <Dropdown.Item>Настроить колонки</Dropdown.Item>
+            <Dropdown.Item>Импорт из CSV</Dropdown.Item>
+          </Dropdown.Content>
+        </Dropdown.Root>
+        <Button.Root variant="soft" tone="neutral">
+          Экспорт
+        </Button.Root>
+        <Button.Root>Создать заказ</Button.Root>
+      </PageContent.Actions>
+    </PageContent.Header>
+  );
+}
+```
+
+## 2. Rhythm — the 4px grid
+
+Every gap is a `--prime-space-N` token (N × 4px) set as `gap` on the parent. Closer means related.
+
+| Between | px | Token |
+|---|---|---|
+| label → field, field → hint | 4–8 | built into fields — never add |
+| buttons, chips, filters in a row | 8 | `--prime-space-2` |
+| text lines of one item (name over meta) | 0–4 | `--prime-space-1` |
+| heading → its content (group, section without a card) | 16 | `--prime-space-4` |
+| tile → tile in a grid (KPI, panels) | 16 | `--prime-space-4` |
+| field → field, switch → switch | 20 | `--prime-space-5` |
+| main column → side column | 24 | `--prime-space-6` |
+| group → group in a form | 32 | `--prime-space-8` |
+| page header → body | 32 | `PageContent` |
+| block → block on a page | 40 | `PageContent.Body` |
+
+A screen with one gap everywhere reads as a list of unrelated things. Use at least three levels: inside
+an item, between items, between blocks.
+
+## 3. Hierarchy — air first, then type
+
+Hierarchy comes from space and a handful of type roles, not from size jumps, color or weight tricks.
+
+| Text | Use |
+|---|---|
+| page title | `PageContent.Title` (`heading-m`, the only `h1`) |
+| section heading without a card | `Typography as="h2" variant="title-m"` |
+| card / panel title | `Card.Title as="h2"` (under the page title) |
+| heading of a group of fields | `Fieldset label` (`title-s` in the `<legend>`) |
+| other group heading inside a card | `Typography as="h3" variant="title-s"` |
+| body text, cells | `body-m` |
+| lead under a heading | `body-m` + `tone="secondary"` |
+| meta: dates, ids, labels of values | `caption` + `tone="muted"` |
+| the number that matters (KPI, total) | `Card.Value`, or `title-m` for a total row |
+
+- Headings descend without skipping levels. One page title.
+- Secondary text is a `tone`, never a custom color. Amounts and dates are tabular
+  (`numeric` columns; `font-variant-numeric: tabular-nums` on your own totals).
+- Emphasis by position and air: the total is larger and last; the status sits next to the fact it
+  qualifies («Отправлен · Оплатить до 14 октября»).
+
+## 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.
+- **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).
+- Floating layers (menus, popovers, dialogs) come only from kit overlays.
+
+## 5. Density and size
+
+- `m` everywhere by default — omit `size`. Change the tier for a whole region, never for one control:
+  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.
+
+## 6. Actions
+
+- **One primary per area** (page header, card, dialog, form): `solid`, last in its row. Secondary:
+  `soft` + `tone="neutral"`. Dismiss / revert: `ghost` + `neutral` in pages and cards, `outline` +
+  `neutral` in Modal / Drawer footers. Rare actions: a `Dropdown` behind an `action.more` icon button —
+  `soft` + `neutral` in a header row (it has a shape beside the other buttons), `ghost` size `s` in a
+  table cell.
+- Placement: page actions in `PageContent.Actions`; card actions in `Card.Footer`; dialog actions in
+  `Modal.Footer` / `Drawer.Footer`; row actions in the last column; bulk actions in the table toolbar.
+- An empty state's action replaces the header's primary, it does not duplicate it.
+- Destructive: `tone="danger"`; a standalone trigger is `outline`, in a menu it is the last item, the
+  confirm is a `ConfirmDialog` (its `onConfirm` returns the request's Promise).
+- Going somewhere is a link (`LinkButton`, `Button.Root asChild` + `<a>`), doing something is a Button.
+  One action — one label on the whole screen.
+
+## 7. Forms
+
+- Labels above every field (`label`), placeholder is an example value, help in `hint`, problems in
+  `error` — after blur or on submit. Mark the minority (`required` or `optional`).
+- Fields 20 apart; related short fields side by side in an `auto-fit` grid 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.
+- Where: ≤ 4 fields → `Modal`; long create / edit → `Drawer` or a page; settings → a panel Card per
+  section, the whole `Card.Root` inside `<form>`, buttons in `Card.Footer`.
+- Submit: `noValidate`, validate all, set `error`s, focus the first invalid field, `loading` on the
+  submit button and the fields disabled (one `Fieldset disabled` per group of fields), then the
+  result: the form stays on screen → the button says «Сохранено»; the form goes away (closes,
+  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.
+
+## 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).
+- 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
+  page the server returned, `rowCount` its total; `sort` / `page` / the SmartFilter value make the
+  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
+  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.
+- 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.
+
+## 9. Feedback
+
+| Situation | Component |
+|---|---|
+| the result of an action (sent, created, failed to save; saved when the form goes away) | `Notification` via `notify()` |
+| 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 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) |
+| nothing matches the filter | the table's `empty`, with a reset action |
+
+Stale data beats an empty block: show the last known values and say when they are from.
+
+State change is continuous across the kit: a region never jumps from one state
+to the next. Give every region its states, render them inside `Crossfade`, and let the loading state
+mirror the data's rows and gaps with `Skeleton`, so the swap moves nothing on the page.
+
+## 10. Overlays
+
+| Need | Use |
+|---|---|
+| a blocking decision or a short form | `Modal` (`size="s"` for confirms) |
+| a long form, filters, record details beside the page | `Drawer` |
+| a short task that ends by itself: a pick, an action, a short note | `Sheet` |
+| a small non-modal panel at a control | `Popover` |
+| a list of actions | `Dropdown` |
+| a value for a field | `Select` / `NativeSelect` / `TagSelect` / `Datepicker` |
+| 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).
+
+## 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: header actions wrap under the title (built in), 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 right under them, one row when wide, stacked rows
+  12 apart when narrow, the primary action always top right.
+- 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`.
+- Text in flex rows gets `min-width: 0`; long names wrap or truncate, never widen the page.
+- The full rules and the narrow-screen checklist: [responsive.md](responsive.md).
+
+## 12. Motion
+
+Kit components already move: press, hover, selection, open/close, enter/exit, label morph, rolling
+counters, progress and hold fills. Add nothing on top of them. When to move your own elements at all,
+the tokens and the recipes: [motion.md](motion.md).
+
+## 13. Screen-level anti-slop
+
+What makes a screen look generated, with bad → good code: [anti-slop.md](anti-slop.md).
+
+## 14. When the kit has no ready component
+
+Go down this ladder and stop at the first step that works.
+
+1. **Find it in the kit.** Search [components.md](components.md), then the Variants and Anatomy of the
+   closest component: Card has 7 templates, Input has icons / affixes / a clear button / a counter / a strength meter,
+   Select has rich items and search, Dropdown has a profile header, DataTable has a toolbar slot, nested
+   rows and a detail row (`renderExpanded`), Sparkline is a small trend chart, Kanban a status board.
+2. **Compose kit parts.** Put existing components together on a layout wrapper (CSS Module, `gap` on
+   tokens). Most "missing components" are a Card + Typography + Button arrangement.
+3. **Last resort: a new element on tokens.** Only when 1–2 cannot express it (a chart with axes and
+   several series, a map).
+
+Rules for your own component:
+
+- Lives in the consumer project (`shared/ui/<name>/` or the project's equivalent), not inside
+  `node_modules`.
+- 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.
+- **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.
+
+### Worked example: a metric panel with a period switch
+
+The kit has the metric templates; the switch is a composition: `Card.Root variant="panel"` + a
+SegmentedControl right after `Card.Title` in `Card.Header`, one tier down because it sits in the card's
+header row.
+
+```tsx
+import { Card, SegmentedControl } from "prime-ui-kit";
+
+export function RevenuePanel() {
+  return (
+    <Card.Root variant="panel">
+      <Card.Header>
+        <Card.Title as="h2">Выручка</Card.Title>
+        <SegmentedControl.Root size="s" defaultValue="month" aria-label="Период">
+          <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
+          <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
+        </SegmentedControl.Root>
+      </Card.Header>
+      <Card.Body>
+        <Card.Value>4,2 млн ₽</Card.Value>
+        <Card.Delta tone="success">+18% к прошлому месяцу</Card.Delta>
+      </Card.Body>
+    </Card.Root>
+  );
+}
+```
+
+For a plain KPI row use `Card.Root variant="stat-trend"` (Label · Value · Delta) in an `auto-fit` grid —
+see [patterns/dashboard.tsx](patterns/dashboard.tsx). When the trend over days matters, put a
+`Sparkline` in the `Card.Body` instead: it brings the value, the change and a line to scrub.