prime-ui-kit 0.15.0 → 0.17.0

package/dist/skill/composition.md

@@ -13,140 +13,166 @@ playground page. What each screen teaches is in [Screen rules](#screen-rules) at
 
 | Screen | Main component | File | Shows |
 |---|---|---|---|
-| [List page](#list-page) | data-table | [screen.tsx](reference/components/data-table/examples/screen.tsx) | the title, a line of figures, SmartFilter search and filters, export and one primary action in the AppHeader; statuses, row menu, pages, filtered empty state |
-| [Detail page](#detail-page) | description-list | [screen.tsx](reference/components/description-list/examples/screen.tsx) | a nested record: Breadcrumb, the title with status and due date and the record's actions by weight in the AppHeader; main column + side column of Cards, Timeline |
-| [Settings page](#settings-page) | page-content | [screen.tsx](reference/components/page-content/examples/screen.tsx) | heading column + panel per section, form with its own save, Switches that apply at once, danger zone with a confirm |
-| [Form in a Drawer](#form-in-a-drawer) | drawer | [screen.tsx](reference/components/drawer/examples/screen.tsx) | the title, counts, search and the Drawer trigger in the AppHeader; Drawer form: groups, errors on submit, focus on the first invalid field, loading, toast |
-| [Record editor](#record-editor) | field-list | [screen.tsx](reference/components/field-list/examples/screen.tsx) | a document page (a long form): the title, a line of description and «Сохранить тариф» in `PageContent.Header`; a plan card edited in aside sections: name and description, specs in a `FieldList` (icon-only `Select` and `ColorPresets` in compact columns, pinned rows, reorder), the price and its changes by month in one list with the base row pinned, a setup fee in three currencies in one row under one heading, save with «Сохранено» on the button |
-| [Dashboard](#dashboard) | card | [screen.tsx](reference/components/card/examples/screen.tsx) | title + a line of data in `AppHeader`, period switch and report in its `PageToolbar`; KPI row that cross-fades to the new period, a Sparkline revenue trend, invoiced vs paid in a ChartFrame, panels with progress and a split, short table + link to the list |
-| [Screen states](#screen-states) | crossfade | [screen.tsx](reference/components/crossfade/examples/screen.tsx) | title + the statement date in `AppHeader`, page error in a Banner with retry, region loading with a Skeleton, Crossfade between states, table error in place, first-run EmptyPage |
-| [Messenger](#messenger) | chat | [screen.tsx](reference/components/chat/examples/screen.tsx) | title + the unread count in `AppHeader`; a full-height PageContent.Split of a `ChatList` with its search (live last message, ticks, unread counts, «печатает…») and a `Chat`: `Chat.Header` with the back button, avatar, title, the status that turns into «печатает…» (`typing`) and the search button, `Chat.Search`, `Chat.Messages` from `items` + a stable `renderMessage` (dates, runs and the unread band from the data, history loaded above with `hasOlder` / `onLoadOlder`, a first load in skeletons), text, a photo, a file and sent voice, reply and edit from the menu through `Composer.Context value` (`replyTo` / `editOf`), the jump to the quoted message (`Message.Reply target`), optimistic sends whose messages rise from the composer while the client's answer slides in, «печатает…» both ways (`onActivityChange` → `Chat.Root typing`), unread counts from `onNewMessage` and `onRead`, the Composer with attachments in `Chat.Footer` |
-| [Sales pipeline board](#sales-pipeline-board) | kanban | [screen.tsx](reference/components/kanban/examples/screen.tsx) | AppHeader titles the page (`h1` + a Description with the open deals and their sum) and carries a PageToolbar with SmartFilter search, a board / list SegmentedControl and the one primary action; Crossfade between a `plain` Kanban (stages without wells, deal cards on the page) and a DataTable of the same deals, column totals in `renderColumnMeta`, moves saved through an `onValueChange` promise that the server can refuse, the deal in a Drawer with a DescriptionList and stage actions, skeleton first load |
-| [App frame](#app-frame) | app-shell | [screen.tsx](reference/layout/app-shell/examples/screen.tsx) | Sidebar rail on a wide screen, floating BottomNav in `AppShell.Footer` on a phone («Ещё» opens the Sidebar panel), AppHeader with the menu button and the page title (`h1`) with a line of data, counts on items, a home page that cross-fades between sections |
-| [Media library](#media-library) | file-upload | [screen.tsx](reference/components/file-upload/examples/screen.tsx) | AppHeader titles the page (`h1` + a Description with the object) and carries a PageToolbar with sections and counts, search (`SmartFilter` with `fields={[]}`), order and «Загрузить»; uploads through `useUploadQueue` in `FileUpload` tiles (`trigger="tile"`, `layout="grid"`) with progress, a failure and retry, a done file moving into the library; a grid of `Thumbnail` / `Thumbnail.Video` tiles that open `MediaViewer` out of the tile (`getOrigin`, `thumbnails`, `renderActions`) or, in selection mode, are picked (`checked`) for bulk download and a `ConfirmDialog` delete; a Skeleton first load and a filtered `EmptyPage` in a `Crossfade` |
-| [Resource schedule](#resource-schedule) | gantt | [screen.tsx](reference/components/gantt/examples/screen.tsx) | AppHeader titles the page (`h1` + a Description with the people shown) and carries a `PageToolbar` with search, role / client filters, team sections and «Назначить» over a full-height `Gantt` (`scrollHeight="fill"`); people with avatars, client hues, lanes for overlaps, locked absences and milestones; moves saved through an async `onBarChange` or refused and glided back, new work drawn with `onBarCreate` and named in a Modal (cancel fades the ghost), `onSelect` details in a Drawer with a `DescriptionList` and a confirmed removal, `loading` and filtered `empty` |
+| [List page](#list-page) | data-table | [screen.tsx](reference/components/data-table/examples/screen.tsx) | the title, a line of figures, SmartFilter search and filters, export and one primary action in the page's top bar; statuses, row menu, pages, filtered empty state |
+| [Detail page](#detail-page) | description-list | [screen.tsx](reference/components/description-list/examples/screen.tsx) | a nested record: the path ending in the title, status and due date and the record's actions by weight in the top bar; main column + side column of Cards, Timeline |
+| [Settings page](#settings-page) | page | [screen.tsx](reference/layout/page/examples/screen.tsx) | the path in a collapsing top bar, the large title in the flow, heading column + panel per section, form with its own save, Switches that apply at once, danger zone with a confirm |
+| [Form in a Drawer](#form-in-a-drawer) | drawer | [screen.tsx](reference/components/drawer/examples/screen.tsx) | the title, counts, search and the Drawer trigger in the top bar; Drawer form: groups, errors on submit, focus on the first invalid field, loading, toast |
+| [Record editor](#record-editor) | field-list | [screen.tsx](reference/components/field-list/examples/screen.tsx) | a document page (a long form): the title and a line of description in `Page.Heading`, «Сохранить тариф» in `Page.Actions`, both in a `Page.Header` in the flow; a plan card edited in aside sections: name and description, specs in a `FieldList` (icon-only `Select` and `ColorPresets` in compact columns, pinned rows, reorder), the price and its changes by month in one list with the base row pinned, a setup fee in three currencies in one row under one heading, save with «Сохранено» on the button |
+| [Dashboard](#dashboard) | card | [screen.tsx](reference/components/card/examples/screen.tsx) | the large title + a line of data in the flow, period switch and report in a collapsing `Page.TopBar`; KPI row that cross-fades to the new period, a Sparkline revenue trend, invoiced vs paid in a ChartFrame, panels with progress and a split, short table + link to the list |
+| [Screen states](#screen-states) | crossfade | [screen.tsx](reference/components/crossfade/examples/screen.tsx) | title + the statement date in `Page.TopBar`, page error in a Banner with retry, region loading with a Skeleton, Crossfade between states, table error in place, first-run EmptyPage |
+| [Messenger](#messenger) | chat | [screen.tsx](reference/components/chat/examples/screen.tsx) | title + the unread count in `Page.TopBar`; a full-height Page.Split of a `ChatList` with its search (live last message, ticks, unread counts, «печатает…») and a `Chat`: `Chat.Header` with the back button, avatar, title, the status that turns into «печатает…» (`typing`) and the search button, `Chat.Search`, `Chat.Messages` from `items` + `renderMessage` (dates, runs and the unread band from the data, history loaded above with `hasOlder` / `onLoadOlder`, a first load in skeletons), text, a photo, a file and sent voice, reply and edit from the menu through `Composer.Context messageId` (`replyTo` / `editOf`), the jump to the quoted message (`Message.Reply target`), optimistic sends whose messages rise from the composer while the client's answer slides in, «печатает…» both ways (`onActivityChange` → `Chat.Root typing`), unread counts from `onNewMessage` and `onRead`, the Composer with attachments in `Chat.Footer` |
+| [Sales pipeline board](#sales-pipeline-board) | kanban | [screen.tsx](reference/components/kanban/examples/screen.tsx) | `Page.TopBar` titles the page (`h1` + a Description with the open deals and their sum) with SmartFilter search and a board / list SegmentedControl in `Page.Tools` and the one primary action in `Page.Actions`; Crossfade between a `plain` Kanban (stages without wells, deal cards on the page) and a DataTable of the same deals, column totals in `renderColumnMeta`, moves saved through an `onValueChange` promise that the server can refuse, the deal in a Drawer with a DescriptionList and stage actions, skeleton first load |
+| [App frame](#app-frame) | app-shell | [screen.tsx](reference/layout/app-shell/examples/screen.tsx) | Sidebar rail on a wide screen, floating BottomNav in `AppShell.Footer` on a phone («Ещё» opens the Sidebar panel), a `Page.TopBar` with the menu button and the page title (`h1`) with a line of data, counts on items, a home page that cross-fades between sections |
+| [Media library](#media-library) | file-upload | [screen.tsx](reference/components/file-upload/examples/screen.tsx) | `Page.TopBar` titles the page (`h1` + a Description with the object) with sections and counts, search (`SmartFilter` with `fields={[]}`) and order in `Page.Tools` and «Загрузить» in `Page.Actions`; uploads through `useUploadQueue` in `FileUpload` tiles (`trigger="tile"`, `layout="grid"`) with progress, a failure and retry, a done file moving into the library; a grid of `Thumbnail` / `Thumbnail.Video` tiles that open `MediaViewer` out of the tile (`getOrigin`, `thumbnails`, `renderActions`) or, in selection mode, are picked (`checked`) for bulk download and a `ConfirmDialog` delete; a Skeleton first load and a filtered `EmptyPage` in a `Crossfade` |
+| [Resource schedule](#resource-schedule) | gantt | [screen.tsx](reference/components/gantt/examples/screen.tsx) | `Page.TopBar` titles the page (`h1` + a Description with the people shown) with search, role / client filters and team sections in `Page.Tools` and «Назначить» in `Page.Actions` over a full-height `Gantt` (`scrollHeight="fill"`); people with avatars, client hues, lanes for overlaps, locked absences and milestones; moves saved through an async `onBarChange` or refused and glided back, new work drawn with `onBarCreate` and named in a Modal (cancel fades the ghost), `onItemOpen` details in a Drawer with a `DescriptionList` and a confirmed removal, `loading` and filtered `empty` |
 
 Pick the closest one, rename the domain, keep the skeleton. Change structure only when the task needs
 it, and then by the rules below.
 
 ## 1. Page skeleton
 
-**One title per page, and it lives in the page's header.** Every app page titles itself in the
-app header: `AppHeader.Title` is the page's only `<h1>`, an `AppHeader.Description` under it
-is one line that carries data («Среда, 14 октября · 3 задачи», «Отправлен · оплатить до 14 октября»),
-and a nested record puts the path up (`Breadcrumb` + `AppHeader.Separator`) before it. The header row
-belongs to the page: it holds only what the current page needs — its title, its own buttons in
-`AppHeader.Actions`, and its tools as a `PageToolbar.Root` in `AppHeader.Tools` (the page's own
-search and filters, sections, the view, the primary action). Main has no `PageContent.Header`.
-
-**A document page** — settings, a long form, an article or help text — is the one exception: its big
-title is `PageContent.Header` in main (`PageContent.Title` is the `<h1>`, one sentence of
-`PageContent.Description`, the page's save action in `PageContent.Actions`), and the header carries
-no title. Never two titles; never no `<h1>`.
+**The app is navigation and the page.** `AppShell` holds the Sidebar and `AppShell.Main`; there is no
+app-wide header and no global search. Everything at the top belongs to the page: one `Page.Root` with
+its `Page.TopBar` (sticky) and its `Page.Body`, plus a `Page.Header` in the flow on a document page.
+
+**One title per page.** `Page.Title` is the page's only `<h1>`, a `Page.Description` with it is one
+line that carries data («Среда, 14 октября · 3 задачи», «Отправлен · оплатить до 14 октября»), and a
+nested record puts the path up (a `Breadcrumb.Root` before the title) — all three inside
+`Page.Heading`, the title group. Where the heading stands follows the kind of page; its size follows
+the place:
+
+- **Work screens** — a list, a board, a chat, a schedule, a record: `Page.Heading` stands in
+  `Page.TopBar` beside the page's tools and buttons ([the top bar](#the-top-bar)); there is no header
+  in the flow.
+- **Document pages** — settings, a long form, an article or help text: `Page.Header` in the flow
+  holds `Page.Heading` (the large title with one sentence of `Page.Description`) and the page's save
+  action in `Page.Actions`; optionally a `Page.TopBar collapse` with only the path in its
+  `Page.Heading`, which repeats the title once it scrolls away.
+- **Overviews** — dashboards: a `Page.TopBar collapse` with the page's tools (the period) in
+  `Page.Tools` and its buttons (a report) in `Page.Actions`, and the titled `Page.Header` in the flow.
+
+Never two titles; never no `<h1>`. A bar whose page shows no title still holds a `Page.Title` — inside
+`VisuallyHidden` — unless a flow `Page.Header` has one.
 
 ```
 AppShell.Root                      once per app (layouts.md#app-frame-once-per-app)
 ├─ AppShell.Nav → Sidebar          navigation rail, one layer above the page
-├─ AppHeader.Root                  the page's header: only what this page needs
-│  ├─ AppHeader.Start
-│  │  ├─ AppHeader.MenuButton      opens the Sidebar below 768px
-│  │  ├─ Breadcrumb + Separator    only on a nested record: the path up
-│  │  └─ AppHeader.Title           the one h1 + AppHeader.Description: a line of data
-│  ├─ AppHeader.Actions            the page's own buttons (export, a more menu)
-│  └─ AppHeader.Tools              second row → PageToolbar.Root: search and filter, sections,
-│                                  view, the primary action; Chips under them
 └─ AppShell.Main                   gutters + top air (24, 32 from 1024px); the page renders here
-   └─ PageContent.Page | Root      the page you deliver
-      └─ PageContent.Body          blocks 24 apart, starting at main's top air
-         ├─ PageContent.Grid       every tile of the screen, 16 on both axes
-         │  └─ PageContent.Cell    span (of 12), rows; the tile fills it
-         └─ PageContent.Section    a new topic: h2 label (+ Actions), 40 from its neighbours
-
-Document page: the header without a title, and in main
-   └─ PageContent.Root maxWidth="wide" | "readable"
-      ├─ PageContent.Header        the one h1, a sentence of description, the page's save action; 24 above the body
-      └─ PageContent.Body
+   └─ SmartFilter.Root             a filtered page only: the filter's state, no DOM, around the page
+      └─ Page.Root                 the page you deliver
+         ├─ Page.TopBar            sticky; led by the menu button while the Sidebar is off-canvas
+         │  ├─ Page.Heading        the path › the title on one line, the line of data under it
+         │  │  ├─ Breadcrumb.Root  only on a nested record: the levels above this page
+         │  │  ├─ Page.Title       the one h1, the path's last level
+         │  │  └─ Page.Description a line of data
+         │  ├─ Page.Tools          sections, search and filter, view — kit controls in reading order
+         │  ├─ Page.Actions        every button of the page, each with an icon; the primary last
+         │  └─ Page.Chips          SmartFilter.Chips: a line under everything, gone while empty
+         └─ Page.Body              blocks 24 apart, starting at main's top air
+            ├─ Page.Grid           every tile of the screen, 16 on both axes
+            │  └─ Page.Cell        span (of 12), rows; the tile fills it
+            └─ Page.Section        a new topic: h2 label (+ Page.Actions), 40 from its neighbours
+
+Document page or overview: the title in the flow
+   └─ Page.Root maxWidth="wide" | "readable"
+      ├─ Page.TopBar collapse      the path (an overview: its tools and buttons); repeats the title once it scrolls away
+      ├─ Page.Header               Page.Heading (the one h1, a sentence of description) + Page.Actions; 24 above the body
+      └─ Page.Body
 ```
 
-- A screen component renders its page: its `AppHeader.Root` (through the shell's `header`) and its
-  body. Styles, `applyTheme`, `NotificationProvider` and `AppShell` live at the app root.
-- `PageContent.Page` for app pages (full panel width); `PageContent.Root maxWidth="wide"` for
-  settings, `maxWidth="readable"` for one narrow column of text or fields.
-- No outer padding, no margins: `AppShell.Main` has the gutters and the top air under the header,
-  `PageContent` has block → block 24, section → section 40, tile → tile 16 (and header → body 24 on
-  a document page). Your CSS lays out only the inside of a block.
+- A screen renders its page: one `Page.Root` with its top bar and its body. Styles, `applyTheme`,
+  `NotificationProvider` and `AppShell` live at the app root.
+- `Page.Root` for app pages (full panel width); `Page.Root maxWidth="wide"` for settings,
+  `maxWidth="readable"` for one narrow column of text or fields.
+- No outer padding, no margins: `AppShell.Main` hands the page its gutters and top air, `Page` has
+  block → block 24, section → section 40, tile → tile 16 (and header → body 24). Your CSS lays out
+  only the inside of a block.
+
+### The top bar
+
+`Page.TopBar` holds up to four groups and nothing else. Write them in reading order; the DOM and Tab
+order is Heading, Tools, Actions, Chips whatever the JSX order.
+
+- **`Page.Heading`** — the path ends in the title: `Breadcrumb.Root` with the levels above this page,
+  then `Page.Title` with its name, on one line (the heading draws the chevron between them), and
+  `Page.Description` under the whole line. The title is never a row of its own under the path, and
+  the path never repeats the title as its last item.
+- **`Page.Tools`** — the page's own tools as kit controls, in the order a person reads them: sections
+  (a `SegmentedControl` with counts), search and filter (`SmartFilter.Toolbar`), the view or the
+  period. Named with `aria-label`; no buttons and no wrappers inside.
+- **`Page.Actions`** — the one place for the page's buttons: secondary ones (`soft` + `neutral`)
+  first, the primary (`solid`) last. Every Button carries a `Button.Icon` beside its label: the bar
+  shows it as the icon alone when the line runs short.
+- **`Page.Chips`** — `SmartFilter.Chips`: the active filters.
+- `SmartFilter.Root` draws nothing and its toolbar and chips stand in two groups, so it wraps
+  `Page.Root` (or whatever holds both) — never a group of the bar.
+- The bar gives the title its natural size and decides the rest by width:
+  [the page's top bar](responsive.md#the-pages-top-bar--pagetopbar). The classic mistakes, bad →
+  good: [anti-slop.md](anti-slop.md#7b-a-top-bar-out-of-its-groups).
 
 ```tsx
 import {
-  AppHeader,
+  Breadcrumb,
   Button,
-  Dropdown,
   Icon,
-  PageToolbar,
+  Page,
+  SegmentedControl,
   SmartFilter,
   type SmartFilterField,
   type SmartFilterValue,
 } from "prime-ui-kit";
+import type { ReactNode } from "react";
 
-type OrdersHeaderProps = {
+type DealsPageProps = {
   fields: SmartFilterField[];
   filter: SmartFilterValue;
   onFilterChange: (value: SmartFilterValue) => void;
-  search: string;
-  onSearchChange: (search: string) => void;
+  view: string;
+  onViewChange: (view: string) => void;
+  children: ReactNode;
 };
 
-export function OrdersHeader({ fields, filter, onFilterChange, search, onSearchChange }: OrdersHeaderProps) {
+export function DealsPage({ fields, filter, onFilterChange, view, onViewChange, children }: DealsPageProps) {
   return (
-    <AppHeader.Root>
-      <AppHeader.Start>
-        <AppHeader.Title>
-          Заказы
-          <AppHeader.Description>128 в работе · 6 ждут оплаты</AppHeader.Description>
-        </AppHeader.Title>
-      </AppHeader.Start>
-      <AppHeader.Actions>
-        <Dropdown.Root>
-          <Dropdown.Trigger>
-            <Button.Root variant="soft" tone="neutral" aria-label="Другие действия">
+    <SmartFilter.Root fields={fields} value={filter} onValueChange={onFilterChange}>
+      <Page.Root>
+        <Page.TopBar>
+          <Page.Heading>
+            <Breadcrumb.Root>
+              <Breadcrumb.Item href="/clients">Клиенты</Breadcrumb.Item>
+              <Breadcrumb.Item href="/clients/north">ООО «Север»</Breadcrumb.Item>
+            </Breadcrumb.Root>
+            <Page.Title>Сделки</Page.Title>
+            <Page.Description>7 в работе · 6,5 млн ₽</Page.Description>
+          </Page.Heading>
+          <Page.Tools aria-label="Сделки">
+            <SmartFilter.Toolbar />
+            <SegmentedControl.Root value={view} onValueChange={onViewChange} aria-label="Вид">
+              <SegmentedControl.Item value="board">Доска</SegmentedControl.Item>
+              <SegmentedControl.Item value="list">Список</SegmentedControl.Item>
+            </SegmentedControl.Root>
+          </Page.Tools>
+          <Page.Actions>
+            <Button.Root variant="soft" tone="neutral">
+              <Button.Icon>
+                <Icon name="action.download" />
+              </Button.Icon>
+              Экспорт
+            </Button.Root>
+            <Button.Root>
               <Button.Icon>
-                <Icon name="action.more" />
+                <Icon name="action.add" />
               </Button.Icon>
+              Новая сделка
             </Button.Root>
-          </Dropdown.Trigger>
-          <Dropdown.Content>
-            <Dropdown.Item>Настроить колонки</Dropdown.Item>
-            <Dropdown.Item>Импорт из CSV</Dropdown.Item>
-          </Dropdown.Content>
-        </Dropdown.Root>
-      </AppHeader.Actions>
-      <AppHeader.Tools>
-        <SmartFilter.Root
-          fields={fields}
-          value={filter}
-          onValueChange={onFilterChange}
-          search={search}
-          onSearchChange={onSearchChange}
-        >
-          <PageToolbar.Root aria-label="Заказы">
-            <PageToolbar.Tools>
-              <SmartFilter.Toolbar />
-            </PageToolbar.Tools>
-            <PageToolbar.Actions>
-              <Button.Root>
-                <Button.Icon>
-                  <Icon name="action.add" />
-                </Button.Icon>
-                Создать заказ
-              </Button.Root>
-            </PageToolbar.Actions>
-            <PageToolbar.Chips>
-              <SmartFilter.Chips />
-            </PageToolbar.Chips>
-          </PageToolbar.Root>
-        </SmartFilter.Root>
-      </AppHeader.Tools>
-    </AppHeader.Root>
+          </Page.Actions>
+          <Page.Chips>
+            <SmartFilter.Chips />
+          </Page.Chips>
+        </Page.TopBar>
+        <Page.Body>{children}</Page.Body>
+      </Page.Root>
+    </SmartFilter.Root>
   );
 }
 ```
@@ -160,20 +186,20 @@ Every gap is a `--prime-space-N` token (N × 4px) set as `gap` on the parent. Cl
 | 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) | 16 | `--prime-space-4` (`PageContent.Section` does it) |
-| tile → tile, both axes (KPI, charts, panels) | 16 | `PageContent.Grid` |
+| heading → its content (group, section) | 16 | `--prime-space-4` (`Page.Section` does it) |
+| tile → tile, both axes (KPI, charts, panels) | 16 | `Page.Grid` |
 | field → field, switch → switch | 20 | `--prime-space-5` |
 | main column → side column | 24 | `--prime-space-6` |
-| app header → the page's first block | 12 + 24, 12 + 32 from 1024px | the header's bottom air + `AppShell.Main` top air |
-| page header → body (a document page) | 24 | `PageContent.Header` |
-| block → block on a page | 24 | `PageContent.Body` |
+| top bar → the page's first block | 12 + 24, 12 + 32 from 1024px | the bar's bottom air + the page's top air from `AppShell.Main` |
+| flow header → body (a document page) | 24 | `Page.Header` |
+| block → block on a page | 24 | `Page.Body` |
 | group → group in a form | 32 | `--prime-space-8` |
-| section → section (a new topic with an `h2`) | 40 | `PageContent.Section` |
+| section → section (a new topic with an `h2`) | 40 | `Page.Section` |
 
 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. The tiles of one screen are one board: put them all in one
-`PageContent.Grid` (one gap on both axes), never a grid per row — and keep the large air for a new topic
-with its own heading (`PageContent.Section`).
+`Page.Grid` (one gap on both axes), never a grid per row — and keep the large air for a new topic
+with its own heading (`Page.Section`).
 
 ## 3. Hierarchy — air first, then type
 
@@ -181,8 +207,8 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
 
 | Text | Use |
 |---|---|
-| page title | `AppHeader.Title` (the only `h1`); on a document page `PageContent.Title` (`heading-m`) instead |
-| section heading without a card | `PageContent.Section label` (an `h2` in `title-m`) |
+| page title | `Page.Title` (the only `h1`): `title-m` in the top bar, `heading-m` in the flow |
+| section heading without a card | `Page.Section label` (an `h2` in `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"` |
@@ -200,12 +226,14 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
 ## 4. Surfaces
 
 - Inside the app the content panel is the page (layer 0 of the surface ladder); a `Card` on it is
-  layer 1, and fields take the fill of the layer they sit on. The kit sets this by context — never set backgrounds.
+  layer 1, and fields take the fill of the layer they sit on. The kit sets this by context — never
+  set backgrounds ([the one exception](foundations.md#your-own-bounded-block)).
 - **Card when** the block stands alone and has its own title: a KPI tile, a settings panel, facts in a
   side column, a chart. **No card when** the block is the only thing in its region: a section heading
   and the content are enough.
-- `DataTable` is already a filled block — never inside a Card. No card in a card. No borders around
-  blocks; `Divider` only inside a block (list rows, a form and its footer).
+- `DataTable` is already a filled block — never inside a Card; a card in a card only as
+  [the next layer, sparingly](foundations.md#card-in-a-card). No borders around blocks; `Divider`
+  only inside a block (list rows, a form and its footer).
 - Floating layers (menus, popovers, dialogs) come only from kit overlays.
 
 ## 5. Density and size
@@ -214,8 +242,8 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
   a dense back-office table may be `s` with its toolbar; a sign-in card may be `l`.
 - One row = one size: everything in a toolbar or an actions row lines up.
 - A control nested in another component's row is one tier down: buttons and menus in table cells `s`,
-  a segmented switch in a card header `s`. Kit hosts (Popover, Banner, LoginForm, the DataTable toolbar)
-  size their `Button.Root` / `Input.Root` children themselves.
+  a segmented switch in a card header `s`. A sized kit host ([the host tier](api-contract.md#size-and-the-host-tier))
+  sizes the kit controls inside it itself.
 
 ## 6. Actions
 
@@ -224,7 +252,7 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
   `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: the page's primary action in `PageToolbar.Actions` in `AppHeader.Tools`, its other buttons in `AppHeader.Actions` (a document page: `PageContent.Actions`); card actions in `Card.Footer`; dialog actions in
+- Placement: every button of the page in one `Page.Actions` — of `Page.TopBar` on a work screen, of the flow `Page.Header` on a document page — the primary last; 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
@@ -242,7 +270,8 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
 - One value in several units is one row of fields under one heading, each unit in its field's
   `Input.InlineAffix`; a base value with overrides is one `FieldList` with the base pinned first.
   The shape of the data decides the layout: [ux.md](ux.md#2-the-shape-of-the-data-decides-the-layout).
-- Fields 20 apart; related short fields side by side in an `auto-fit` grid with `align-items: start`
+- Fields 20 apart; related short fields side by side in an
+  [intrinsic grid](responsive.md#intrinsic-grids) with `align-items: start`
   (`reserveSupportRow` on Input / Textarea keeps neighbours aligned); groups 32 apart, each a
   `Fieldset label` (its `title-s` heading 16 above the fields, no frame); no dividers between groups.
 - Form column width: one column up to ~65ch; never stretch a form across a wide panel.
@@ -254,16 +283,23 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
   navigates) → a `Notification`; a failure → a `Notification` or the field's `error`.
 - A footer button outside the form submits it with `form={formId}`.
 - Choice controls: Checkbox when the value is submitted later, Switch when it applies at once (no Save
-  in that section), `Radio.Group label` for one of 2–5 visible options.
+  in that section), `Radio.Group label` for one of a few visible options
+  ([choosing.md](choosing.md#2-inside-a-category)).
 
 ## 8. Tables and lists
 
-- A list page is `DataTable` with the filters in its `toolbar` — `SmartFilter.Toolbar` and
-  `SmartFilter.Chips` inside `SmartFilter.Root` (or one SegmentedControl / Select for a single field).
-- Where the filters go: tools of one table live in its `toolbar`; when the page itself carries
-  sections with counts, a view switch (board / list, grid / list) or filters that drive more than one
-  table — a board, a schedule, a media grid — the page gets `PageToolbar` and the table keeps only its
-  own tools (`DataTable.ColumnsMenu`).
+### Where the filters go
+
+- The page's search and filters are the page's: `SmartFilter.Root` around `Page.Root`,
+  `SmartFilter.Toolbar` in the bar's `Page.Tools`, `SmartFilter.Chips` in its `Page.Chips`
+  ([the list page](#list-page)).
+  A search alone is the same SmartFilter with `fields={[]}`.
+- The DataTable `toolbar` keeps the table's own tools: `DataTable.ColumnsMenu`, a bulk bar of the
+  selected rows. Search and filters go there only when the table is not the page's main region (a
+  table in a section of a record, in a Drawer).
+
+### Tables
+
 - Paging is built in: `paging="pages"` (default, Pagination and the «Показано 1–6 из 10» range in the
   footer), `paging="infinite"` for feeds, `paging="none"` for short lists on dashboards and details.
 - When the server holds more than you load (a CRM list, a register): `source="server"` — `rows` is the
@@ -271,11 +307,11 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
   request, a new search or filter sets `page` to 1, and the old rows stay with `loading` until the
   answer comes ([server.tsx](reference/components/data-table/examples/server.tsx)).
 - Columns: `numeric` for amounts, counts and dates (end-aligned, tabular; `headerAlign="end"` to line the
-  head up); statuses as `Badge` from one status → color map; an avatar + two-line cell for people and
+  head up); statuses as `Badge` from one status → tone map; an avatar + two-line cell for people and
   companies; row menu last.
 - States in place: `loading` (+ `loadingRows`) while there are no rows, `empty` for nothing found
-  (string → compact EmptyPage, or your own `EmptyPage size="s"` with «Сбросить фильтры»), `error` for a
-  failed load. The head and toolbar stay.
+  (string → compact EmptyPage, or your own `EmptyPage size="s"` with «Сбросить фильтры»), `loadError`
+  for a failed load. The head and toolbar stay.
 - Phones: the table scrolls inside itself, `stickyFirstColumn` keeps the key column; never let the page
   scroll sideways. Short lists of objects can be `Card variant="list"` instead of a table.
 
@@ -285,9 +321,9 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
 |---|---|
 | 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 state of the page or a section that persists (sync failed, trial ends, read-only) | `Banner` as the first block of `Page.Body` (or inside the Card it concerns) |
 | a problem with one field | the field's `error` |
-| a region failed to load | the region shows it in place: DataTable `error`, `EmptyPage` with `EmptyPage.Icon tone="danger"` and «Повторить» |
+| a region failed to load | the region shows it in place: DataTable `loadError`, or `EmptyPage tone="danger"` with `EmptyPage.RetryButton` |
 | a region is loading | DataTable `loading`; otherwise a `Skeleton` in the geometry of the content + `aria-busy` on the region; `Spinner` only when there is no shape to hold |
 | a region changes state (loading → data → empty → error, another record) | its content in `Crossfade state={status}` — always, so the change flows instead of flipping |
 | nothing here yet (first run) | `EmptyPage` with one action (`tone="accent"` icon for a call to start) |
@@ -312,20 +348,17 @@ mirror the data's rows and gaps with `Skeleton`, so the swap moves nothing on th
 | a name for an icon button | `Tooltip` |
 | search across commands and pages (⌘K) | `CommandMenu` |
 
-Every overlay takes `closeOnOutsideClick` / `closeOnEscape`. A destructive confirm is `ConfirmDialog`, which
-turns them off itself; a form in a Modal or Drawer holds closing with `Modal.Guard` / `Drawer.Guard`
-(`busy` while a request runs, `dirty` for unsaved changes).
+Every overlay closes on Escape and on a press outside unless you turn it off
+([the Dismiss row](api-contract.md#shared-vocabulary-exported-types)); a form in a Modal or Drawer holds
+closing with `Modal.Guard` / `Drawer.Guard` (`busy` while a request runs, `dirty` for unsaved
+changes) instead.
 
 ## 11. Narrow screens
 
-- Layouts are intrinsic: `repeat(auto-fit, minmax(min(100%, …), 1fr))` grids and flex-wrap with a large
-  `flex-grow` on the main column — no breakpoints needed, and they work in any container. Media queries
-  only for app-frame decisions (the phone menu header) at 640 · 768 · 1024 · 1280.
-- From 320px: the page's tools wrap under the header title and the primary action takes its own row when the search would be squeezed (built in), side columns drop below the main one,
+- Layouts are [intrinsic](responsive.md#intrinsic-grids) — no breakpoints needed, and they work in
+  any container; a media query only in [the breakpoints' scope](responsive.md#breakpoints).
+- From 320px: the page's tools take a line under the page title ([the page's top bar](responsive.md#the-pages-top-bar--pagetopbar)), side columns drop below the main one,
   pairs of fields stack, tables scroll inside themselves, dialogs stack their footers (built in).
-- A page with search and filter, sections, a view switch and the primary action gets `PageToolbar`:
-  search and filter first with the active filters under the top row, one row when wide, stacked rows
-  12 apart when narrow; the primary action at the top row's end, on its own row on a phone.
 - Rearrange, never hide: every function of the desktop screen is on the phone — in another place or a
   menu. App sections on phones: `BottomNav` in `AppShell.Footer`; a short task from the bottom
   edge: `Sheet`.
@@ -362,8 +395,9 @@ Rules for your own component:
 - Follows API v1 ([api-contract.md](api-contract.md)): `size` (default `m`), `tone`/`color`, `X.Root` +
   `X.Part` when it has parts (a single export when it has none), `hint` / `error` props, `labels` for
   system strings, `data-*` for state.
-- Styled with a CSS Module on `--prime-*` tokens. Bounded block: a `Card`, or a plain tile on
-  `--prime-color-layer-nested` + `--prime-card-radius`. Never override kit internals or reach into their class names.
+- Styled with a CSS Module on `--prime-*` tokens. Bounded block:
+  [a `Card`, or the plain tile](foundations.md#your-own-bounded-block). Never override kit internals
+  or reach into their class names.
 - **Threshold:** a pattern used twice becomes a component. Two things that look the same are one
   component with a variant, never two components or two hand-written copies.
 
@@ -396,7 +430,7 @@ export function RevenuePanel() {
 ```
 
 For a plain KPI row use `Card.Root variant="stat-trend"` (Label · Value · Delta), each in a
-`PageContent.Cell span={3}` of the page's `PageContent.Grid` — see [the dashboard screen](reference/components/card/examples/screen.tsx). When the trend over days matters, put a
+`Page.Cell span={3}` of the page's `Page.Grid` — see [the dashboard screen](reference/components/card/examples/screen.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.
 
 ## Screen rules
@@ -407,9 +441,9 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 [data-table/examples/screen.tsx](reference/components/data-table/examples/screen.tsx)
 
-- The page lives in the `AppHeader`: `AppHeader.Title` is the only heading, its `AppHeader.Description` is one line of figures («10 счетов · просрочено 2 на …»), not a sentence about the page; main has no `PageContent.Header`.
-- The tools are `AppHeader.Tools` → `SmartFilter.Root` around a `PageToolbar.Root`: `SmartFilter.Toolbar` in `PageToolbar.Tools`, `SmartFilter.Chips` in `PageToolbar.Chips`, export (an icon-only `soft` + `neutral` button) and the one primary action (`solid`, last) in `PageToolbar.Actions`. The table itself has no `toolbar`.
-- A status is a `Badge` with one color per meaning across the product (`STATUS` is one map); the text carries the meaning, the color repeats it.
+- A work screen titles itself in its `Page.TopBar`: `Page.Title` is the only heading, its `Page.Description` is one line of figures («10 счетов · просрочено 2 на …»), not a sentence about the page; there is no second header in the flow.
+- `SmartFilter.Root` wraps the page: `SmartFilter.Toolbar` in `Page.Tools`, `SmartFilter.Chips` in `Page.Chips`; export (`soft` + `neutral`, an icon beside its label) and the one primary action (`solid`, last) in `Page.Actions`. The table itself has no `toolbar`.
+- A status is a `Badge` with one `tone` per meaning across the product (`STATUS` is one map); the text carries the meaning, the tone repeats it.
 - Numbers and dates are `numeric` columns with `headerAlign="end"` (tabular figures, values and heading on the end edge). On a phone the table scrolls inside itself and `stickyFirstColumn` keeps the number in place — the page never scrolls sideways.
 - Row actions are a `Dropdown` behind an `action.more` icon of size `s`: controls in cells are one tier below the table. Delete is `tone="danger"` at the end of the menu.
 - Empty after a filter is the table's `empty` with `EmptyPage size="s"` and a «Сбросить фильтры» action; the header and the filters stay in place.
@@ -418,19 +452,20 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 [description-list/examples/screen.tsx](reference/components/description-list/examples/screen.tsx)
 
-- A nested record titles itself in the `AppHeader`: `AppHeader.Start` holds the path up (`Breadcrumb` with the list, «Счета»), an `AppHeader.Separator` and `AppHeader.Title` with the record's name; main has no `PageContent.Header`. Top-level pages have no breadcrumb.
-- The status is words next to the fact that matters now, in `AppHeader.Description` («Отправлен · оплатить до 14 октября»), not a separate plate.
-- The record's actions are the header's tools row: `AppHeader.Tools` → `PageToolbar.Root` → `PageToolbar.Actions`, by weight: one primary (`solid`, last), the secondary `soft` + `tone="neutral"`, rare and destructive ones in a `Dropdown` behind an `action.more` icon (also `soft`, so the button has a shape beside its neighbours); voiding is `tone="danger"` at the bottom of the menu.
+- A nested record titles itself in its `Page.TopBar`: `Page.Heading` holds the path up (`Breadcrumb.Root` with the list, «Счета») ending in `Page.Title` with the record's name on the same line; there is no second header in the flow. Top-level pages have no breadcrumb.
+- The status is words next to the fact that matters now, in `Page.Description` («Отправлен · оплатить до 14 октября»), not a separate plate.
+- The record's actions are the bar's `Page.Actions`, by weight: one primary (`solid`, last), the secondary `soft` + `tone="neutral"`, each with an icon beside its label. Rare and destructive ones live in a `Dropdown` behind an `action.more` icon (also `soft`, so the button has a shape beside its neighbours); voiding is `tone="danger"` at the bottom of the menu.
 - Columns are a CSS module on flex-wrap without breakpoints: the main one grows, the side one holds ~18rem and drops below when the main one runs out of room.
-- A section without a frame is `PageContent.Section label`: an h2 heading 16 px above the table; `Card variant="panel"` only for standalone blocks of the side column. A table is already a filled block — never put it in a card.
+- A section without a frame is `Page.Section label`: an h2 heading 16 px above the table; `Card variant="panel"` only for standalone blocks of the side column. A table is already a filled block — never put it in a card.
 - «Label → value» pairs about the client are `DescriptionList.Root orientation="vertical"` with `DescriptionList.Item label`; amounts are tabular figures, the total is larger (`title-m`) and ends where the «Сумма» column ends (the table cell inset).
-- History is a `Timeline`: events top-down from the latest, dates in `Timeline.Meta`; a row highlights on hover.
+- History is a `Timeline`: events top-down from the latest, dates in `Timeline.ItemMeta`; a row highlights on hover.
 
 ### Settings page
 
-[page-content/examples/screen.tsx](reference/components/page-content/examples/screen.tsx)
+[page/examples/screen.tsx](reference/layout/page/examples/screen.tsx)
 
-- A section is `PageContent.Section layout="aside"`: a heading column (`label` + a line of `description`) and a `Card variant="panel"` panel; sections are 40 px apart; on a narrow screen the column moves above the panel by itself (flex-wrap, no breakpoints).
+- A document page: `Page.Root maxWidth="wide"`, the large `Page.Title` with a sentence of `Page.Description` in the `Page.Heading` of a `Page.Header` in the flow, and a `Page.TopBar collapse` whose `Page.Heading` holds only the path and repeats the title once it scrolls away.
+- A section is `Page.Section layout="aside"`: a heading column (`label` + a line of `description`) and a `Card variant="panel"` panel; sections are 40 px apart; on a narrow screen the column moves above the panel by itself (flex-wrap, no breakpoints).
 - The form wraps the whole `Card.Root` in `<form noValidate>`; the buttons are in `Card.Footer`: «Отменить изменения» `ghost` + `neutral`, then the primary «Сохранить». While the request runs — `loading` on the button, and one `Fieldset disabled` turns the fields off; the form stays on screen, so success is the button text «Сохранено» for two seconds, without a notification.
 - Fields are 20 px apart; two short related fields side by side while there is width, with `align-items: start` and `reserveSupportRow`, so an error does not shift the neighbour.
 - An error comes through the field's `error` after submit, not while typing; a format hint goes in `hint`.
@@ -441,8 +476,8 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 [drawer/examples/screen.tsx](reference/components/drawer/examples/screen.tsx)
 
-- The page lives in the `AppHeader`: `AppHeader.Title` with the counts in `AppHeader.Description`, the search (`SmartFilter` with `fields={[]}`) in `PageToolbar.Tools`; main has no `PageContent.Header`.
-- The opening button is the page's primary action in `PageToolbar.Actions`; `Drawer.Trigger` wraps it as a slot.
+- A work screen titles itself in its `Page.TopBar`: `Page.Title` with the counts in `Page.Description`, the search (`SmartFilter` with `fields={[]}`) in `Page.Tools`; there is no second header in the flow.
+- The opening button is the page's primary action in `Page.Actions`; `Drawer.Trigger` wraps it as a slot.
 - The form is tied to the footer button through `form={formId}`: `Drawer.Footer` is outside the `<form>`, and submitting still works, by Enter too.
 - Groups are a `Fieldset` without a frame with a `title-s` heading 16 px above the fields; 32 px of air between groups, no dividers. `Fieldset disabled` turns all the fields off while the request runs.
 - Validation on submit: errors in each field's `error`, focus on the first invalid field; mark the minority: required fields are the majority, so `optional` stands only on the optional ones.
@@ -454,36 +489,36 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 [field-list/examples/screen.tsx](reference/components/field-list/examples/screen.tsx)
 
-- A record editor is a document page — a long form read top to bottom in aside sections, like Settings — so its title stays in content: `PageContent.Header` with the title, one line of description and the primary action; the app header only says where you are and holds no second title.
+- A record editor is a document page — a long form read top to bottom in aside sections, like Settings — so its title stands in the flow: `Page.Header` with the title and one line of description in `Page.Heading` and the primary action in `Page.Actions`; no second title anywhere.
 - The shape of the data decides the layout: records a person adds and removes are a `FieldList`, one row per record; the column headings stand once above the rows, and the fields in the cells take them as their labels.
 - No label in every row and no numbered one («Преимущество 1»): a one-column list has no headings at all — its section names it ([reorder.tsx](reference/components/field-list/examples/reorder.tsx)).
 - Small attributes of a record go in compact columns of its row: the icon is a `Select` with only `Select.TriggerIcon`, the color `ColorPresets`; the first specs are pinned (`getLocked`) — the lock says so itself, without explanatory text.
 - The base price and its changes are one list: the base row is pinned first and shows when it applies, the changes are rows with a month and a price; the ruble sign is in the field (`Input.InlineAffix`), not in every heading.
 - One value in three currencies is three fields in one row under one group heading, each with its own name for screen readers and the currency inside the field.
-- The lists live in the page state, the name and description fields in the `<form>` of the first section; the primary «Сохранить тариф» in the header is tied to it through `form={formId}` and saves everything. While the request runs the fields and the lists are off (`Fieldset disabled`, `disabled`), afterwards «Сохранено» on the button.
+- The lists live in the page state, the name and description fields in the `<form>` of the first section; the primary «Сохранить тариф» in `Page.Actions` is tied to it through `form={formId}` and saves everything. While the request runs the fields and the lists are off (`Fieldset disabled`, `disabled`), afterwards «Сохранено» on the button.
 
 ### Dashboard
 
 [card/examples/screen.tsx](reference/components/card/examples/screen.tsx)
 
-- The header carries the page: `AppHeader.Title` «Обзор» with an `AppHeader.Description` line of data (what and as of when), the page's tools in `AppHeader.Tools` as a `PageToolbar.Root`; main has no `PageContent.Header`, its body starts with the tiles.
-- The period is a `SegmentedControl` in `PageToolbar.View`, the report a `soft` + `neutral` button in `PageToolbar.Actions`: the period changes the values on this same screen. Tabs (`Tabs`) are for different content, not for a period.
-- Every tile of the screen is one `PageContent.Grid`: KPI `Card variant="stat-trend"` in `PageContent.Cell span={3}`, 16 px on both axes; `Card.Delta` with a `tone` by the meaning of the change: overdue growing is `danger`, its decline `success`.
+- An overview: the large `Page.Title` «Обзор» with a `Page.Description` line of data (what and as of when) in a `Page.Header` in the flow; a `Page.TopBar collapse` above it keeps the page's tools and buttons in reach and repeats the title once it scrolls away; the body starts with the tiles.
+- The period is a `SegmentedControl` in the bar's `Page.Tools` and the report a `soft` + `neutral` button with an icon in its `Page.Actions`: the period changes the values on this same screen. Tabs (`Tabs`) are for different content, not for a period.
+- Every tile of the screen is one `Page.Grid`: KPI `Card variant="stat-trend"` in `Page.Cell span={3}`, 16 px on both axes; `Card.Delta` with a `tone` by the meaning of the change: overdue growing is `danger`, its decline `success`.
 - Another period — other values: each KPI tile is wrapped in `Crossfade state={period}` and flows instead of blinking.
 - A trend over days is a `Sparkline` in a `Card` in a full-width cell: the last value, the change and a line you can scrub with a finger; a new series appears by itself.
-- A chart with axes and several series is a `ChartFrame` in `PageContent.Cell span={8} rows={2}` beside two panels; `ChartFrame.Plot height="fill"` takes their height. A sized plot area (`renderPlot`), a legend that turns series off and a table for screen readers; series colors come from `series`, never your own.
+- A chart with axes and several series is a `ChartFrame` in `Page.Cell span={8} rows={2}` beside two panels; `ChartFrame.Plot height="fill"` takes their height. A sized plot area (`renderPlot`), a legend that turns series off and a table for screen readers; series colors come from `series`, never your own.
 - Panels are `Card variant="panel"` with `Card.Title as="h2"` in `Card.Header` and quiet context on the right after the title (`caption` + `muted`).
 - Progress of one value is a `ProgressBar` with `label` and `showValue`; parts of a whole are `ProgressBar segments` with `legend` and `formatValue`: statuses are colored by `tone`, categories by `color`.
-- Tiles of one screen are 16 px apart (`PageContent.Grid`), page blocks 24 px (`PageContent.Body`), a new topic with a heading 40 px (`PageContent.Section`): proximity shows what is related.
-- A short list is a `DataTable paging="none"` in `PageContent.Section label` without a card; «Все счета» is a `LinkButton` in the section's `PageContent.Actions`: it is a way somewhere, not an action.
+- Tiles of one screen are 16 px apart (`Page.Grid`), page blocks 24 px (`Page.Body`), a new topic with a heading 40 px (`Page.Section`): proximity shows what is related.
+- A short list is a `DataTable paging="none"` in `Page.Section label` without a card; «Все счета» is a `LinkButton` in the section's `Page.Actions`: it is a way somewhere, not an action.
 
 ### Screen states
 
 [crossfade/examples/screen.tsx](reference/components/crossfade/examples/screen.tsx)
 
-- The header carries the page: `AppHeader.Title` with an `AppHeader.Description` line of data — the accounts and the date of the statement the screen stands on; main has no `PageContent.Header`.
-- An error that concerns the whole page is a `Banner tone="danger"` as the first block of `PageContent.Body` with a «Повторить» action; the action's result is a `Notification`.
-- A region's error is in the region's place: `error` on the `DataTable` (the table head stays), not a pop-up.
+- The top bar carries the page: `Page.Title` with a `Page.Description` line of data — the accounts and the date of the statement the screen stands on; there is no second header in the flow.
+- An error that concerns the whole page is a `Banner tone="danger"` as the first block of `Page.Body` with a «Повторить» action; the action's result is a `Notification`.
+- A region's error is in the region's place: `loadError` on the `DataTable` (the table head stays), not a pop-up.
 - Table loading is `loading` + `loadingRows` (a skeleton of rows); card loading is a `Skeleton` in the shape of its rows and `aria-busy` on the card, and the block's height does not change. The state change is smooth: the card's region is in `Crossfade state={status}`, the table body changes by itself.
 - Stale data beats emptiness: the balances are shown as of the previous date, and that is said on the right in `Card.Header`.
 - Empty on the first run is `EmptyPage size="s"` inside the panel: an icon with `tone="accent"`, what it is and why, one action. An empty filter result is the table's `empty`.
@@ -493,15 +528,15 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 [chat/examples/screen.tsx](reference/components/chat/examples/screen.tsx)
 
-- A work screen: the title «Поддержка» is `AppHeader.Title` with the unread count in `AppHeader.Description`; main has no `PageContent.Header`.
-- Layout: `PageContent.Split` in a `fill` page: the dialog list `ChatList` (last message, ticks, unread, «печатает…») and the conversation beside it; on a narrow panel one pane at a time with `PageContent.BackButton` in `Chat.Header`.
+- A work screen: the title «Поддержка» is `Page.Title` in `Page.TopBar` with the unread count in `Page.Description`.
+- Layout: `Page.Split` (`Page.List`, `Page.Detail`) in a `fill` page: the dialog list `ChatList` (last message, ticks, unread, «печатает…») and the conversation beside it; on a narrow panel one pane at a time with `Page.BackButton` in `Chat.Header`.
 - Search over the dialogs is the field of `ChatList` itself: `search` and `onSearchChange`; you filter the list (by name and last message), and the list shows the match in rows, the number found and an empty result itself. Never put a field of your own above the list.
 - The conversation is `Chat.Root` in the pane's card: the header, `Chat.Search`, `Chat.Messages` and `Chat.Footer` with the Composer. Never assemble your own header, `ScrollContainer` and feed — the chat links search, jumps, selection and «печатает…» itself.
-- Messages are data: `items` with `getKey`, `getAuthor`, `getDate` (service events through `isService`), the first unread is `unread`; the feed computes dates, runs, tails and the avatar place. `renderMessage` in `useCallback`: only the changed message re-renders.
+- Messages are data: `items` with `getKey`, `getAuthor`, `getDate` (service events through `isService`), the first unread is `unread`; the feed computes dates, runs, tails and the avatar place. `renderMessage` may be inline: only a message whose item or place changed renders again, so whatever a row shows lives in its item, and a reply's original comes from `entry.find(key)`.
 - History is `hasOlder` and `onLoadOlder` with a promise: while it runs, a bubble-shaped `Skeleton` placeholder stands on top, and the view does not jump.
 - Each kind of message is its own part of `Message`: text with markup, photos and albums, a file, a `VoicePlayer`; the screen renders the kinds its domain has. The others (`VideoNote`, a location, a contact, a link preview, reactions, a forwarded header) are shown on the Message, VoicePlayer and VideoNote pages; pinned messages and selection on the Chat page.
 - Sending is a `Composer` with `onSend` without waiting: the message is in the feed at once with a clock under a stable id, then one tick, then two. Your own message rises from the input, the client's answer slides in from the side — the feed animates new messages itself; history and status changes are not animated.
-- Reply and edit from `Message.Menu` open `Composer.Context` with `value`: `onSend` gets `replyTo` / `editOf`, the plate closes itself after sending; ↑ in an empty field is `onEditLast`. A quote in a bubble is `Message.Reply target`: a scroll to the original with a flash.
+- Reply and edit from `Message.Menu` open `Composer.Context` with `messageId`: `onSend` gets `replyTo` / `editOf`, the plate closes itself after sending; ↑ in an empty field is `onEditLast`. A quote in a bubble is `Message.Reply target`: a scroll to the original with a flash.
 - «Печатает…»: your own signal is `Composer onActivityChange` into the socket, the other side's is `Chat.Root typing`: the line in the header and the bubble at the end of the feed together.
 - Unread: `onNewMessage` adds an incoming message to the dialog's count, `onRead` subtracts what the reader really saw. Scrolled up — the round «to the latest» button counts the new ones itself.
 - Search in the conversation is `Chat.SearchButton` and `Chat.Search`; pinned messages, when the domain has them, are `Chat.Pinned` between them and the feed.
@@ -510,34 +545,34 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 [kanban/examples/screen.tsx](reference/components/kanban/examples/screen.tsx)
 
-- The page titles itself in the app header: `AppHeader.Title` with an `AppHeader.Description` that carries data («7 сделок в работе · 6 461 750 ₽», counted over the filtered deals); main has no `PageContent.Header`.
-- Search, filters, the view switch and the one primary action «Новая сделка» are one `PageToolbar` inside `SmartFilter.Root`, in `AppHeader.Tools`.
+- The page titles itself in its top bar: `Page.Title` with a `Page.Description` that carries data («7 сделок в работе · 6 461 750 ₽», counted over the filtered deals).
+- Search, filters and the view switch are the bar's `Page.Tools`, the one primary action «Новая сделка» its `Page.Actions`, the active filters its `Page.Chips`; `SmartFilter.Root` wraps the page.
 - The board and the list are the same data: `Kanban` and `DataTable` replace each other through `Crossfade`, the filter is `matchesSmartFilter`.
 - The board is the main area of the page, so its `variant` is the default, `plain`: stages without wells, headers and deal cards stand right on the page — one level of nesting, no frames of your own around the columns.
 - The placement of deals is `value` as `{ [stage]: id[] }`; `onValueChange` returns the request's promise and applies `value` only after the answer; a server refusal returns the card to its place.
 - Stage totals are in `renderColumnMeta` («2 сделки · 3 575 000 ₽»), the stage color is the column's `color`.
-- A deal opens through `onItemClick` of `Kanban.Root` (click, Enter, Space; never after a drag) in a `Drawer` with a `DescriptionList`; no `onClick` / `onKeyDown` of your own on the card; a deal with its own page — `getItemHref`. The stage change is available in the panel too — dragging is not the only way; `Drawer.Guard busy` holds the panel while saving.
+- A deal opens through `onItemOpen` of `Kanban.Root` (click, Enter, Space; never after a drag) in a `Drawer` with a `DescriptionList`; no `onClick` / `onKeyDown` of your own on the card; a deal with its own page — `getItemHref`. The stage change is available in the panel too — dragging is not the only way; `Drawer.Guard busy` holds the panel while saving.
 - The first load is `loading` on `Kanban` and `DataTable`: skeletons in the geometry of cards and rows.
 
 ### App frame
 
 [app-shell/examples/screen.tsx](reference/layout/app-shell/examples/screen.tsx)
 
-- The frame is `AppShell.Template` (or `AppShell.Root`): `nav` is `Sidebar.Root`, `header` is `AppHeader.Root`, `footer` is `BottomNav.Root`; the page is the children. `scrollResetKey` is the current section (in a router, the pathname), so a new page opens at the top.
-- The kit decides the switch itself: below 768 px the `Sidebar` goes off the edge, `AppHeader.MenuButton` appears and `AppShell.Footer` shows the `BottomNav`; while the rail is on screen the footer is hidden. No media queries or `position: fixed` of your own.
-- `BottomNav` holds 2–6 main sections, one word each; the rest lives in the `Sidebar`, and «Ещё» opens it as a panel (`aria-expanded`). `floating` is a glass capsule; `AppShell.Main` leaves room under it itself.
-- Every page titles itself in the header: `AppHeader.Title` with the section's name and an `AppHeader.Description` that carries data («Среда, 14 октября · открытых задач: 3»); main has no `PageContent.Header`, its body starts with the page's blocks.
+- The frame is `AppShell.Template` (or `AppShell.Root`): `nav` is `Sidebar.Root`, `footer` is `BottomNav.Root`; the page is the children, and everything at the top belongs to it. There is no app-wide header. `scrollResetKey` is the current section (in a router, the pathname), so a new page opens at the top.
+- The kit decides the switch itself: below 768 px the `Sidebar` goes off the edge, the page's `Page.TopBar` draws its menu button and `AppShell.Footer` shows the `BottomNav`; while the rail is on screen the footer is hidden. No media queries, menu state or `position: fixed` of your own.
+- `BottomNav` holds 2–6 main sections, one word each; the rest lives in the `Sidebar`, and «Ещё» opens it as a panel through `useAppShellNav()` (`aria-expanded`, `aria-controls`, `setOpen`). `floating` is a glass capsule; `AppShell.Main` leaves room under it itself.
+- Every page titles itself in its `Page.TopBar`: `Page.Title` with the section's name and a `Page.Description` that carries data («Среда, 14 октября · открытых задач: 3»); its body starts with the page's blocks.
 - Counts: `Sidebar.ItemCount` (a plain number for information, `color="red"` when it needs action) and `BottomNav.ItemCount` only for what needs attention; the number is the same in both navigations.
-- Choosing a section in either navigation goes through one handler that also closes the Sidebar panel.
+- Choosing a section in either navigation goes through one handler; an activated Sidebar item closes the off-canvas panel by itself.
 - A section change is a `Crossfade` by `state`: the page changes smoothly instead of jumping. Menu items in an app with a router are `asChild` + `NavLink`.
 
 ### Media library
 
 [file-upload/examples/screen.tsx](reference/components/file-upload/examples/screen.tsx)
 
-- A work screen titles itself in the app header: `AppHeader.Title` «Медиатека» with an `AppHeader.Description` naming the object; main has no `PageContent.Header`.
-- Sections, search, order and «Загрузить» are one `PageToolbar` panel in `AppHeader.Tools`: search is a `SmartFilter.Toolbar` with `fields={[]}`, sections a `SegmentedControl` with `SegmentedControl.Count`.
-- Uploads are `useUploadQueue` + `FileUpload.Root trigger="tile" layout="grid"`: progress, «В очереди», the failure reason and retry are built in, the add tile is also the drop zone; «Загрузить» opens the same `inputRef`.
+- A work screen titles itself in its top bar: `Page.Title` «Медиатека» with a `Page.Description` naming the object.
+- Sections, search and order are the bar's `Page.Tools`, «Загрузить» its `Page.Actions`: search is a `SmartFilter.Toolbar` with `fields={[]}`, sections a `SegmentedControl` with `SegmentedControl.Count`.
+- Uploads are `useUploadQueue` + `FileUpload.Root trigger="tile" layout="grid"`: progress, «В очереди», the failure reason and retry are built in, the add tile is also the drop zone; «Загрузить» opens the same picker (`picker.current?.open()`).
 - A finished file leaves the queue for the library: its address is `item.result` of the server's answer, not the queue's `preview`.
 - The library grid is a CSS grid of `Thumbnail` with `fullWidth` and one `ratio`; a video is `Thumbnail.Video`, which draws the duration and the play mark itself. `Gallery` does not fit here: it is an album of up to 10.
 - A tile either opens or selects: when browsing it is `Thumbnail.Root asChild` with a button, when selecting — `checked` / `onCheckedChange`; «Выбрать» turns the mode on.
@@ -549,12 +584,12 @@ What each screen in [the index](#screens) demonstrates — keep these when you s
 
 [gantt/examples/screen.tsx](reference/components/gantt/examples/screen.tsx)
 
-- The page titles itself in the app header: `AppHeader.Title` with an `AppHeader.Description` that carries data («Сотрудников: 9 из 9»); main has no `PageContent.Header`.
+- The page titles itself in its top bar: `Page.Title` with a `Page.Description` that carries data («Сотрудников: 9 из 9»).
 - A `fill` page: `Gantt scrollHeight="fill"` takes the free height — the header and the first column stick inside the chart, the page never scrolls sideways.
-- The panel is a `PageToolbar` inside `SmartFilter.Root`, in `AppHeader.Tools`: search and the role and client filter first, teams a `SegmentedControl` with counts in `PageToolbar.Sections`, the primary action «Назначить» in `PageToolbar.Actions`, the active filters `SmartFilter.Chips` right under the search. Zoom and «Сегодня» are built into `Gantt` — never add your own.
+- `SmartFilter.Root` wraps the page: search with the role and client filter and teams (a `SegmentedControl` with counts) in `Page.Tools`, the primary action «Назначить» in `Page.Actions`, the active filters `SmartFilter.Chips` in `Page.Chips`. Zoom and «Сегодня» are built into `Gantt` — never add your own.
 - A row is a person: `renderRowAvatar` with an `Avatar`, `renderRow` with the name and role; on a narrow chart the column keeps only the avatar. Overlapping works lay themselves out in lanes, an absence is a `readOnly` bar, a milestone has `start` equal to `end`.
 - `onBarChange` returns a promise and changes the data only after the service answers: while it runs the bar is busy; a refusal (work on an absence) is `notify` and `throw`, and the bar returns to its previous dates by itself.
 - `onBarCreate`: a range drawn on an empty place holds a busy draft while a `Modal` with `Modal.Guard busy` asks for the name and the client; saving adds the bar and resolves the promise, cancel rejects it — the draft dissolves. Work over an absence is refused at once.
 - The legend of client hues is a row of `Badge.Root color` with `Badge.Dot` in the chart's `toolbar`; `renderBarTooltip` names the client in the tooltip under the dates, so the client reads not only by color.
-- `onSelect` opens a `Drawer` with a `DescriptionList` (the person, the client `Badge`, the period and duration, `ProgressBar`); removing a task is a `ConfirmDialog` with an async `onConfirm`.
+- `onItemOpen` opens a `Drawer` with a `DescriptionList` (the person, the client `Badge`, the period and duration, `ProgressBar`); removing a task is a `ConfirmDialog` with an async `onConfirm`.
 - States are on the chart itself: `loading` draws `Skeleton` placeholder rows in its geometry, `empty` an `EmptyPage size="s"` with «Сбросить фильтры»; the panel stays in place.