prime-ui-kit 0.16.0 → 0.17.0

package/dist/skill/reference/{components/page-content → layout/page}/examples/variants.tsx

@@ -1,5 +1,5 @@
-/** The same page column at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. */
-import { Card, PageContent, Typography } from "prime-ui-kit";
+/** The same page at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. */
+import { Card, Page, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
@@ -9,13 +9,13 @@ const WIDTHS = [
   { value: "readable", text: "Условия использования: не шире колонки для чтения, по центру." },
 ] as const;
 
-export default function PageContentVariantsExample() {
+export default function PageVariantsExample() {
   return (
     <>
       {WIDTHS.map(({ value, text }) => (
         <div key={value} className={styles.main}>
-          <PageContent.Root maxWidth={value}>
-            <PageContent.Body>
+          <Page.Root maxWidth={value}>
+            <Page.Body>
               <Card.Root>
                 <Card.Body>
                   <Typography variant="body-s" tone="secondary">
@@ -23,8 +23,8 @@ export default function PageContentVariantsExample() {
                   </Typography>
                 </Card.Body>
               </Card.Root>
-            </PageContent.Body>
-          </PageContent.Root>
+            </Page.Body>
+          </Page.Root>
         </div>
       ))}
     </>

package/dist/skill/reference/layout/sidebar/COMPONENT.md

@@ -89,7 +89,7 @@ useSidebar()                       state hook for custom parts inside Root (useA
 | `onModeChange` | `(mode: SidebarMode) => void` | — | Called with the new mode (Toggle, `useSidebar().setMode`). |
 | `open` | `boolean` | — | Off-canvas panel on narrow viewports (controlled). |
 | `defaultOpen` | `boolean` | `false` | Initial off-canvas state (uncontrolled). |
-| `onOpenChange` | `(open: boolean) => void` | — | Off-canvas open / close: Toggle, the AppHeader menu button, scrim, Escape, an activated item, leaving the narrow viewport. |
+| `onOpenChange` | `(open: boolean) => void` | — | Off-canvas open / close: Toggle, the menu button of `Page.TopBar`, scrim, Escape, an activated item, leaving the narrow viewport. |
 | `offCanvas` | `"auto" \| "always" \| "never"` | `"auto"` | When the rail becomes an off-canvas panel opened by `open`: `auto` — below 768px (viewport); `always` — at any width; `never` — always a rail. |
 | `closeOnOutsideClick` | `boolean` | `true` | A press on the scrim (outside the off-canvas panel) closes the panel. |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the off-canvas panel. |
@@ -294,13 +294,14 @@ The rail width does not depend on `size`.
 | `closeOnEscape` (Root) | Escape closes the off-canvas panel | default; turn off with `closeOnOutsideClick` for a panel only its toggle closes | on |
 | `asChild` (ItemAction) | the row action is the consumer's link with the button look | the action opens a page or `mailto:` | off |
 
-Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand. Inside an `AppShell` the Sidebar publishes its navigation to the shell: on phones (`offCanvas="auto"`) or always (`offCanvas="always"`) the `AppHeader` draws the menu button that opens the panel by itself, a `Sidebar.Toggle` outside the rail brings back a hidden one, and other triggers (a BottomNav «Ещё») read `useAppShellNav()`. One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
+Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand. Inside an `AppShell` the Sidebar publishes its navigation to the shell: on phones (`offCanvas="auto"`) or always (`offCanvas="always"`) the page's `Page.TopBar` draws the menu button that opens the panel by itself, a `Sidebar.Toggle` outside the rail brings back a hidden one, and other triggers (a BottomNav «Ещё») read `useAppShellNav()`. One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | mode | `mode` / `defaultMode` | Root `data-mode`, `data-panel-mode` (the last visible mode while hidden); `<nav inert>` while hidden |
 | off-canvas | `offCanvas="always"`, or `"auto"` + viewport < 768px | Root `data-off-canvas`, `data-state="open" \| "closed"`; `<nav inert>` while closed; the kit scrim (`role="presentation"`) while open; in an `AppShell` the shell Root `data-off-canvas` |
+| placing | the viewport crossed the off-canvas breakpoint (not a person's choice) | Root `data-placing` for one painted frame: the rail lands at its new width with no motion (no growing from 0, no folding rows, no sliding panel) |
 | dismiss | `closeOnOutsideClick`, `closeOnEscape` | a press on the scrim / Escape closes the open panel, or not |
 | current | `current` or a router's `aria-current` | Item `aria-current="page"`, `data-state="active"` |
 | active path | a child of a Sub (or an item of a Group) is current | SubTrigger (or the `…` row of a folded Group) `data-active-path`; a closed Sub opens, a closed Group opens off the compact rail |
@@ -364,7 +365,7 @@ Leaving the narrow viewport closes the off-canvas panel; activating an item (a l
 - A row action is its own button next to the item (never nested), named by `label` with a tooltip.
 - The account avatar is hidden from screen readers; the name and the muted line name the button.
 - Off-canvas: a decorative scrim (a press on it is a press outside, `closeOnOutsideClick`), focus trap and Escape (`closeOnEscape`); focus returns to the opener.
-- Toggle, the AppHeader menu button and `useAppShellNav` triggers: `aria-expanded`, `aria-controls` → the `<nav>`, label from `labels`.
+- Toggle, the menu button of `Page.TopBar` and `useAppShellNav` triggers: `aria-expanded`, `aria-controls` → the `<nav>`, label from `labels`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -392,7 +393,7 @@ Leaving the narrow viewport closes the off-canvas panel; activating an item (a l
 | [dismiss.tsx](examples/dismiss.tsx) | An off-canvas panel only its own toggle closes: a press on the scrim and Escape leave it open, a picked item still closes it — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the rail mode: expanded, an icon rail with tooltips, or hidden; every switch is one synchronous movement — `mode`, `onModeChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | Navigation behind a menu button at any width: the parent opens the off-canvas panel, the scrim, Escape, the header toggle or a navigation closes it — `offCanvas`, `open`, `onOpenChange`. |
-| [narrow.tsx](examples/narrow.tsx) | Below 768px the rail leaves the layout and slides in over the page from the menu button the header draws by itself; from 768px it is the rail again, and the button leaves — `AppShell`, `labels`. |
+| [narrow.tsx](examples/narrow.tsx) | Below 768px the rail leaves the layout and slides in over the page from the menu button the page top bar draws by itself; from 768px it is the rail again, and the button leaves — `AppShell`, `labels`. |
 
 ## Mistakes
 - `icon={…}` / `badge={…}` props → use the `Sidebar.ItemIcon` and `Sidebar.ItemCount` parts.

package/dist/skill/reference/layout/sidebar/examples/dismiss.tsx

@@ -1,5 +1,5 @@
 /** An off-canvas panel only its own toggle closes: a press on the scrim and Escape leave it open, a picked item still closes it — `closeOnOutsideClick`, `closeOnEscape`. */
-import { AppHeader, AppShell, Icon, Sidebar } from "prime-ui-kit";
+import { AppShell, Icon, Page, Sidebar } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
@@ -35,12 +35,15 @@ export default function SidebarDismissExample() {
             </Sidebar.Content>
           </Sidebar.Root>
         </AppShell.Nav>
-        <AppHeader.Root>
-          <AppHeader.Start>
-            <AppHeader.Title>Сборка заказов</AppHeader.Title>
-          </AppHeader.Start>
-        </AppHeader.Root>
-        <AppShell.Main />
+        <AppShell.Main>
+          <Page.Root>
+            <Page.TopBar>
+              <Page.Heading>
+                <Page.Title>Сборка заказов</Page.Title>
+              </Page.Heading>
+            </Page.TopBar>
+          </Page.Root>
+        </AppShell.Main>
       </AppShell.Root>
     </div>
   );

package/dist/skill/reference/layout/sidebar/examples/narrow.tsx

@@ -1,5 +1,5 @@
-/** Below 768px the rail leaves the layout and slides in over the page from the menu button the header draws by itself; from 768px it is the rail again, and the button leaves — `AppShell`, `labels`. */
-import { AppHeader, AppShell, Icon, Sidebar } from "prime-ui-kit";
+/** Below 768px the rail leaves the layout and slides in over the page from the menu button the page top bar draws by itself; from 768px it is the rail again, and the button leaves — `AppShell`, `labels`. */
+import { AppShell, Icon, Page, Sidebar } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
@@ -43,12 +43,15 @@ export default function SidebarNarrowExample() {
             </Sidebar.Content>
           </Sidebar.Root>
         </AppShell.Nav>
-        <AppHeader.Root>
-          <AppHeader.Start>
-            <AppHeader.Title>Сделки</AppHeader.Title>
-          </AppHeader.Start>
-        </AppHeader.Root>
-        <AppShell.Main />
+        <AppShell.Main>
+          <Page.Root>
+            <Page.TopBar>
+              <Page.Heading>
+                <Page.Title>Сделки</Page.Title>
+              </Page.Heading>
+            </Page.TopBar>
+          </Page.Root>
+        </AppShell.Main>
       </AppShell.Root>
     </div>
   );

package/dist/skill/responsive.md

@@ -38,7 +38,7 @@ everything inside a page breaks by its container.
 - CSS custom properties cannot be used inside media / container conditions: write the number.
 - Inside your own blocks prefer container queries: `container-type: inline-size` on the block,
   `@container (min-width: 30rem)` inside it.
-- The app takes the full width; cap only text (`PageContent.Root maxWidth="readable"`).
+- The app takes the full width; cap only text (`Page.Root maxWidth="readable"`).
 - Required minimum: `<meta name="viewport" content="width=device-width, initial-scale=1">`, no
   `user-scalable=no`, no horizontal page scroll at 320px.
 
@@ -46,8 +46,8 @@ everything inside a page breaks by its container.
 
 A layout inside a page needs no breakpoint: it takes its columns from the room it has.
 
-- The tiles of a page (KPI cards, charts, panels) are one `PageContent.Grid` with a
-  `PageContent.Cell span` per tile: it folds by its own width (below 30rem every tile takes the row,
+- The tiles of a page (KPI cards, charts, panels) are one `Page.Grid` with a
+  `Page.Cell span` per tile: it folds by its own width (below 30rem every tile takes the row,
   then small tiles pair up, from 64rem each its span).
 - A grid inside one block (thumbnails, short fields of one record) is the block's own
   `grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--prime-layout-tile-min-width)), 1fr))`
@@ -61,43 +61,45 @@ Use these as they are; never wrap them in your own breakpoints.
 
 | Need | Built in |
 |---|---|
-| app frame | AppShell gutters 16 → 24 → 32; `AppHeader` un-sticks on screens lower than 480px, respects safe areas and, below 36rem of its width, drops the title icon, the title and its line of data truncate |
-| app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by the menu button the AppHeader draws by itself while the Sidebar is off-canvas; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
-| page panel | `PageToolbar` — search and filter first, one row when wide, stacked rows when narrow, the primary action on its own row when the search would get less than 18rem beside it ([below](#page-panel--pagetoolbar)) |
-| page header | `AppHeader`: the page's tools wrap under the title (`AppHeader.Tools`); a document page's `PageContent.Header`: actions wrap under the title |
+| app frame | `AppShell.Main` hands the page its gutters 16 → 24 → 32 and top air 24 → 32; `Page.TopBar` un-sticks on screens lower than 480px and respects the top safe area; in the bar the title and its line of data truncate |
+| app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by the menu button `Page.TopBar` draws by itself while the Sidebar is off-canvas; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
+| page top bar | `Page.TopBar` lays out its groups from their natural widths: one line while they fit, then the tools on a line of their own, then icon-only buttons, then «⋯», and the heading truncates last ([below](#the-pages-top-bar--pagetopbar)). `Page.Header` in the flow: actions wrap under the title |
 | switchers | [Switchers](#switchers) never wrap or truncate: they scroll inside themselves |
 | tables | DataTable scrolls inside itself, edge shadows show hidden columns, `stickyFirstColumn`, `DataTable.ColumnsMenu` for a column chooser, the toolbar stacks below a 30rem table, sticky head off on short screens |
 | floating layers | Popover (opened from a Trigger), Dropdown, Select (and Datepicker, ColorPresets) never wider than the viewport − 16, 8 from the edges, flip when out of room; below 640 they open as a bottom sheet — scrim, grab handle, swipe down to close, page scroll locked; Tooltip and TagSelect stay anchored |
 | dialogs | Modal is a bottom sheet with a handle below 640 (swipe down closes it while `closeOnOutsideClick` allows); footer actions stack on phones and in a dialog narrower than 360px; `Sheet` is a bottom sheet for a short task at every width (centred at 560 on a tablet or desktop) and closes with a swipe down from its handle or header; a Drawer has no swipe — buttons, Escape and the scrim close it |
 | date picking | Datepicker shows two months and side presets only when they fit; otherwise one month and presets above |
 | system messages | Banner actions move under the text in a narrow container; Notification stays within the viewport with safe-area insets |
-| chat | `Message` bubbles fit their content in CSS and cap at 30rem and 85% of the chat column, file / contact / location cards at 16rem and 75%, a round video at its size token × 1.15 and the row width (the Composer's recording preview at 70%), so a chat works from 320px; the message menu is a bottom sheet below 640, the reaction bar opens on a long press; `Composer` takes its container's width, keeps 16px text and 44px hit areas on touch, and the recording bar covers the field without changing the row height; `VoicePlayer` shrinks its waveform to fit; `Chat` fills its pane, a chat beside its dialogs is `PageContent.Split` (one pane at a time when narrow); `Chat.Header` keeps the avatar, a title that truncates and icon-only actions, `Chat.Search` puts its counter and arrows after a shrinking field, `Chat.Pinned` truncates its line, the «к последним» button floats inside the thread at its bottom-end, and the Composer stays one row (paperclip · field · button) from 320px with its bars above it |
+| chat | `Message` bubbles fit their content in CSS and cap at 30rem and 85% of the chat column, file / contact / location cards at 16rem and 75%, a round video at its size token × 1.15 and the row width (the Composer's recording preview at 70%), so a chat works from 320px; the message menu is a bottom sheet below 640, the reaction bar opens on a long press; `Composer` takes its container's width, keeps 16px text and 44px hit areas on touch, and the recording bar covers the field without changing the row height; `VoicePlayer` shrinks its waveform to fit; `Chat` fills its pane, a chat beside its dialogs is `Page.Split` (one pane at a time when narrow); `Chat.Header` keeps the avatar, a title that truncates and icon-only actions, `Chat.Search` puts its counter and arrows after a shrinking field, `Chat.Pinned` truncates its line, the «к последним» button floats inside the thread at its bottom-end, and the Composer stays one row (paperclip · field · button) from 320px with its bars above it |
 | schedules and boards | `Gantt` scrolls inside itself with the header and the first column pinned; the first column narrows (12 → 10 → 6rem by the chart's width, or only the avatar); a long press on touch creates a one-unit bar; rows and days are virtualized. `Kanban` columns are 18rem from 40rem of board width, below that 85% of it with snapping so the next column peeks; the strip scrolls sideways inside the board |
 | cards and properties | Card templates stack and wrap in a narrow container; `DescriptionList` stacks label over value below 24rem of its width; FileUpload `layout="grid"` shows 5 · 4 · 3 · 2 tiles across by its own width |
 | fields | text ≥ 16px under a coarse pointer (no iOS zoom on focus); labels above fields; affixes in the field row |
 | codes | DigitInput cells 36–64px, `fullWidth` cells share a phone column |
 | touch | hover effects only under `(hover: hover)`; under `(pointer: coarse)` small controls get a 44px hit area; nothing is hover-only |
 
-## Page panel — `PageToolbar`
+## The page's top bar — `Page.TopBar`
 
-One strip at the top of the page — on an app page, the page's tools row in `AppHeader.Tools` — holds
-up to five slots. It renders them in one fixed order whatever the JSX order (that is also the Tab
-order) and lays them out from its own width; how each slot moves at every width is in
-[PageToolbar COMPONENT.md → Layout by width](reference/components/page-toolbar/COMPONENT.md#layout-by-width).
+The bar holds up to four groups ([what goes in each](composition.md#the-top-bar)) and lays them out
+by one plan chosen from their natural widths. As the width runs out it gives way in five steps, always
+in this order, and nothing ever overflows:
 
-| Slot | Holds |
-|---|---|
-| `PageToolbar.Tools` | search + filter button: `SmartFilter.Toolbar` |
-| `PageToolbar.Sections` | sections of the page: a `fullWidth` SegmentedControl with counts |
-| `PageToolbar.View` | period, table / cards, columns |
-| `PageToolbar.Actions` | the primary action («Создать», «Сохранить 3 изменения») |
-| `PageToolbar.Chips` | active filters: `SmartFilter.Chips` |
+1. **One line** — `Page.Heading`, `Page.Tools` and `Page.Actions` side by side while they fit.
+2. **Tools below** — the tools take a line of their own under the first one and fill its width: a
+   search (`SmartFilter.Toolbar`, `Input.Root`) grows first, the switchers share the rest and wrap
+   when one line is not enough. The actions stay on the first line beside the heading at every width.
+3. **Icons** — every Button with an icon shows only the icon, the secondary ones first, then the
+   primary; its label stays its accessible name and becomes its tooltip.
+4. **«⋯»** — the secondary Buttons fold into a menu (`labels.more`); the primary always stays.
+5. **The heading truncates** — only after every button step: the path levels first, then the title.
+
+`Page.Chips` is always a line of its own under everything, gone while no filter is set. The heading
+keeps its natural width: the bar sizes the title, so there is nothing to tune.
 
 ```tsx
 import {
   Button,
   Icon,
-  PageToolbar,
+  Page,
   SegmentedControl,
   Select,
   SmartFilter,
@@ -110,7 +112,7 @@ const FIELDS: SmartFilterField[] = [
   { key: "city", label: "Город", options: [{ value: "msk", label: "Москва" }] },
 ];
 
-export function OrdersPanel() {
+export function OrdersPage() {
   const [section, setSection] = useState("all");
   const [period, setPeriod] = useState("30d");
   const [filter, setFilter] = useState<SmartFilterValue>({});
@@ -124,63 +126,75 @@ export function OrdersPanel() {
       search={search}
       onSearchChange={setSearch}
     >
-      <PageToolbar.Root aria-label="Заказы">
-        <PageToolbar.Tools>
-          <SmartFilter.Toolbar />
-        </PageToolbar.Tools>
-        <PageToolbar.Sections>
-          <SegmentedControl.Root fullWidth value={section} onValueChange={setSection} aria-label="Раздел">
-            <SegmentedControl.Item value="all">
-              Все<SegmentedControl.Count>128</SegmentedControl.Count>
-            </SegmentedControl.Item>
-            <SegmentedControl.Item value="active">
-              В работе<SegmentedControl.Count>12</SegmentedControl.Count>
-            </SegmentedControl.Item>
-          </SegmentedControl.Root>
-        </PageToolbar.Sections>
-        <PageToolbar.View>
-          <Select.Root value={period} onValueChange={setPeriod}>
-            <Select.Trigger aria-label="Период">
-              <Select.Value />
-            </Select.Trigger>
-            <Select.Content>
-              <Select.Item value="7d">7 дней</Select.Item>
-              <Select.Item value="30d">30 дней</Select.Item>
-            </Select.Content>
-          </Select.Root>
-        </PageToolbar.View>
-        <PageToolbar.Actions>
-          <Button.Root>
-            <Button.Icon>
-              <Icon name="action.add" />
-            </Button.Icon>
-            Новый заказ
-          </Button.Root>
-        </PageToolbar.Actions>
-        <PageToolbar.Chips>
-          <SmartFilter.Chips />
-        </PageToolbar.Chips>
-      </PageToolbar.Root>
+      <Page.Root>
+        <Page.TopBar>
+          <Page.Heading>
+            <Page.Title>Заказы</Page.Title>
+            <Page.Description>128 в работе · 6 ждут оплаты</Page.Description>
+          </Page.Heading>
+          <Page.Tools aria-label="Заказы">
+            <SegmentedControl.Root value={section} onValueChange={setSection} aria-label="Раздел">
+              <SegmentedControl.Item value="all">
+                Все<SegmentedControl.Count>128</SegmentedControl.Count>
+              </SegmentedControl.Item>
+              <SegmentedControl.Item value="active">
+                В работе<SegmentedControl.Count>12</SegmentedControl.Count>
+              </SegmentedControl.Item>
+            </SegmentedControl.Root>
+            <SmartFilter.Toolbar />
+            <Select.Root value={period} onValueChange={setPeriod}>
+              <Select.Trigger aria-label="Период">
+                <Select.Value />
+              </Select.Trigger>
+              <Select.Content>
+                <Select.Item value="7d">7 дней</Select.Item>
+                <Select.Item value="30d">30 дней</Select.Item>
+              </Select.Content>
+            </Select.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.add" />
+              </Button.Icon>
+              Новый заказ
+            </Button.Root>
+          </Page.Actions>
+          <Page.Chips>
+            <SmartFilter.Chips />
+          </Page.Chips>
+        </Page.TopBar>
+        <Page.Body>{/* the orders table */}</Page.Body>
+      </Page.Root>
     </SmartFilter.Root>
   );
 }
 ```
 
-- One tier for the whole panel (default `m`): never `size` on one control inside — wrapped rows must
-  stay level. A denser page wraps the toolbar in `<ControlSizeProvider value="s">`; every kit control
+- One tier for the whole bar (default `m`): never `size` on one control inside — wrapped lines must
+  stay level. A denser page wraps the bar in `<ControlSizeProvider value="s">`; every kit control
   inside takes that tier.
-- The primary action is always there: on a phone it may take its own row or become icon-only with
-  `aria-label`; it never disappears.
+- A Button without an icon keeps its label at every step and leaves the bar less room before it
+  folds: give each one a `Button.Icon`.
+- A SegmentedControl in `Page.Tools` needs no `fullWidth`: the bar sets it.
+- The primary action is on screen at every width — as its icon at the narrowest; it never folds and
+  never disappears.
 - Section totals go into `SegmentedControl.Count`, not into stat cards above the table.
-- A long form saves through the panel's action with a count («Сохранить 3 изменения»), never a sticky
-  bar at the bottom of a phone screen.
-- Do not duplicate search: if the panel has one, the list below filters by it.
+- A long form saves through the bar's primary action with a count («Сохранить 3 изменения»), never a
+  sticky bar at the bottom of a phone screen.
+- Do not duplicate search: if the bar has one, the list below filters by it.
 
 ## Switchers
 
-- **Three width modes:** by content (`fullWidth` off), full width (`fullWidth`), full width only when
-  narrow (a `fullWidth` SegmentedControl inside `PageToolbar.Sections` — the toolbar decides).
-- Sections of a page → SegmentedControl in `PageToolbar.Sections`; panels inside a card or a section →
+- **Three width modes:** by content (`fullWidth` off), full width (`fullWidth`), full width only on
+  a line of its own (a SegmentedControl in `Page.Tools` — the bar decides).
+- Sections of a page → SegmentedControl in `Page.Tools`; panels inside a card or a section →
   Tabs (the folder look belongs to its panel).
 - Every switcher — Tabs, SegmentedControl, a horizontal ButtonGroup and BottomNav — scrolls inside
   itself when its items do not fit: never a second line, never a truncated item. Its hidden edges
@@ -195,9 +209,9 @@ export function OrdersPanel() {
 
 ## List + details, side panels
 
-- A list people work through record by record (mail, a messenger, tickets) is `PageContent.Split`:
-  the list in a 16–20rem column with the details beside it from 48rem of the split's own width, one
-  pane at a time with `PageContent.BackButton` below it. Details opened now and then from a table
+- A list people work through record by record (mail, a messenger, tickets) is `Page.Split`:
+  the list (`Page.List`) in a 16–20rem column with the details (`Page.Detail`) beside it from 48rem
+  of the split's own width, one pane at a time with `Page.BackButton` below it. Details opened now and then from a table
   open in a Drawer.
 - A side panel of details becomes full-screen on a phone (`Drawer.Content` is full width below 640).
 - Its period / view controls stay visible on every tab of the panel.
@@ -205,7 +219,7 @@ export function OrdersPanel() {
 ## Components on narrow widths — what you still decide
 
 **Tables.** Let DataTable scroll inside itself; offer a column chooser (`DataTable.ColumnsMenu` in
-`toolbar`; the key column `hideable: false`); `stickyFirstColumn` for the name. On phones a table / cards switch in `PageToolbar.View` is fine — silently dropping columns
+`toolbar`; the key column `hideable: false`); `stickyFirstColumn` for the name. On phones a table / cards switch in `Page.Tools` is fine — silently dropping columns
 by breakpoint is not. Never ask to rotate the phone.
 
 **Card grids.** [Intrinsic grids](#intrinsic-grids), never a breakpoint. Tiles of a row share one
@@ -257,7 +271,7 @@ Target CLS ≤ 0.1: nothing moves while loading or when a filter changes.
 Drag the window through 320, 390, 768, 1024, 1280 and 1920px — continuously, not only at these points.
 
 - [ ] No horizontal page scroll at any width (tables and switchers scroll inside themselves).
-- [ ] The primary action is on screen at every width — never hidden ([the page panel](#page-panel--pagetoolbar)).
+- [ ] The primary action is on screen at every width — never hidden ([the page's top bar](#the-pages-top-bar--pagetopbar)).
 - [ ] Every item alone in its row stretches; items of stretched switchers are equal.
 - [ ] All controls in a row share one height; no «staircase» after a wrap.
 - [ ] Text never overlaps and is cut only at its own block's edge; cut text has a tooltip or `title`.

package/dist/tokens/layers.d.ts

@@ -6,6 +6,8 @@ type LayerTheme = {
     hi: number;
     /** Direction of control fills from their host: −1 darker, +1 lighter. */
     control: 1 | -1;
+    /** Steps from a track up to its selected segment (thumb). */
+    selected: number;
 };
 export declare const LIGHT_LAYERS: LayerTheme;
 export declare const DARK_LAYERS: LayerTheme;

package/dist/tokens/primitives.d.ts

@@ -15,6 +15,8 @@ export declare const primitiveTokens: {
             readonly 100: "#e8eaee";
             readonly 150: "#e0e3e8";
             readonly 300: "#b9bec8";
+            /** Dark muted text: AA on the hovered fill of the deepest layer. */
+            readonly 350: "#a1a8b6";
             readonly 400: "#949bab";
             readonly 500: "#636a79";
             readonly 600: "#575e6d";
@@ -131,9 +133,12 @@ export declare const primitiveTokens: {
             readonly 700: "#be185d";
         };
     };
-    /** 4px grid. Key = number of 4px steps (`4` → 16px). */
+    /**
+     * 4px grid. Key = number of 4px steps (`4` → 16px). `0` carries a unit: a unitless `0` is a
+     * number inside `calc()` / `max()`, and `calc(100% + 0)` is invalid (the declaration drops).
+     */
     readonly space: {
-        readonly 0: "0";
+        readonly 0: "0rem";
         readonly 1: "0.25rem";
         readonly 2: "0.5rem";
         readonly 3: "0.75rem";
@@ -165,6 +170,11 @@ export declare const primitiveTokens: {
             /** `… Fallback`: the metric-matched local faces of the opt-in `fonts.css`. */
             readonly sans: "\"Golos Text\", \"Golos Text Fallback\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
             readonly mono: "\"JetBrains Mono\", \"JetBrains Mono Fallback\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+            /**
+             * Key caps: the mono faces for letters and digits, then the system UI face before the mono
+             * fallbacks — the mono faces have no ⇧ ⌥ ⌃ or ⌘, and Menlo draws them small and light.
+             */
+            readonly key: "\"JetBrains Mono\", \"JetBrains Mono Fallback\", ui-monospace, SFMono-Regular, system-ui, -apple-system, \"Segoe UI Symbol\", Menlo, Consolas, monospace";
         };
         /** Modular scale, ~1.2 in the body range, ~1.25 for headings. */
         readonly size: {

package/dist/tokens/semantic.d.ts

@@ -142,6 +142,12 @@ export declare const semanticTokens: {
         readonly control: {
             /** Switch thumb, slider thumb. */
             readonly thumb: "{color.white}";
+            /** A disabled switch thumb: quiet on the disabled track, like the rest of the control. */
+            readonly thumbDisabled: "{color.white}";
+        };
+        readonly skeleton: {
+            /** A loading placeholder: a wash over whatever layer it sits on, readable in both themes. */
+            readonly fill: "color-mix(in srgb, {color.gray.925} 6%, transparent)";
         };
         /**
          * The tooltip is an inverse chip: everything inside it (a Kbd, a secondary line) reads its
@@ -224,6 +230,7 @@ export declare const semanticTokens: {
         readonly family: {
             readonly sans: "{font.family.sans}";
             readonly mono: "{font.family.mono}";
+            readonly key: "{font.family.key}";
         };
         readonly weight: {
             readonly regular: "{font.weight.regular}";

package/dist/tokens/themes/dark.d.ts

@@ -25,8 +25,9 @@ export declare const darkThemeOverrides: {
         readonly text: {
             readonly primary: "{color.gray.100}";
             readonly secondary: "{color.gray.300}";
-            readonly muted: "{color.gray.400}";
-            readonly placeholder: "{color.gray.400}";
+            /** gray.350: AA on every layer, its fill and the fill's hover (a hovered field, row, chip). */
+            readonly muted: "{color.gray.350}";
+            readonly placeholder: "{color.gray.350}";
             readonly disabled: "{color.gray.600}";
             readonly inverse: "{color.gray.925}";
         };
@@ -80,6 +81,10 @@ export declare const darkThemeOverrides: {
         };
         readonly control: {
             readonly thumb: "{color.gray.100}";
+            readonly thumbDisabled: "{color.gray.600}";
+        };
+        readonly skeleton: {
+            readonly fill: "color-mix(in srgb, {color.gray.100} 10%, transparent)";
         };
         /** A light chip over the dark UI: inverse like in light, so it reads over any layer. */
         readonly tooltip: {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "packageManager": "bun@1.3.13",
-  "description": "React 19 UI kit for product interfaces: 80 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
+  "description": "React 19 UI kit for product interfaces: 78 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
   "bin": {
     "prime-ui-kit": "bin/prime-ui-kit.js"
   },

package/src/components/avatar/COMPONENT.md

@@ -72,7 +72,7 @@ Avatar.Group           overlapping row, gives its size to members
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Avatar.Group
-`ref` → `HTMLDivElement`. An overlapping row (`role="group"`); members overlap by 25% with a ring in `--avatar-ring`.
+`ref` → `HTMLDivElement`. An overlapping row (`role="group"`); members overlap by an eighth of the diameter with a ring in `--avatar-ring`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -119,7 +119,7 @@ The soft fill is opaque: the soft hue is composited over the ground the avatar s
 ## Layout & spacing
 - Inline-flex, never shrinks, `vertical-align: middle`.
 - Avatar → name: space step 3 (12px) in lists and cards, step 2 (8px) in table cells.
-- Group: members overlap by 25% of the diameter with a 2px ring in the ground they stand on: the current layer of the surface around them (no surface sets anything), or `--avatar-ring` from a host whose ground is not a layer (a reaction chip sets its own fill); the fills of initials and «+N» are composited over the same ground.
+- Group: members overlap by an eighth of the diameter (initials are never cut) with a 2px ring in the ground they stand on: the current layer of the surface around them (no surface sets anything), or `--avatar-ring` from a host whose ground is not a layer (a reaction chip sets its own fill); the fills of initials and «+N» are composited over the same ground.
 - An icon fallback is half the diameter: a kit `Icon` reads `--prime-icon-size`, a raw svg too.
 
 ## Accessibility

package/src/components/avatar/examples/team-group.tsx

@@ -28,7 +28,7 @@ const MEMBERS: { name: string; initials: string; color: PaletteColor; src?: stri
 
 export default function AvatarTeamGroupExample() {
   return (
-    <Avatar.Group size="s" aria-label="Участники проекта: 7">
+    <Avatar.Group size="l" aria-label="Участники проекта: 7">
       {MEMBERS.map((member) => (
         <Avatar.Root key={member.initials} color={member.color} aria-label={member.name}>
           {member.src ? <Avatar.Image src={member.src} /> : null}

package/src/components/banner/COMPONENT.md

@@ -29,8 +29,8 @@ Banner.Root                 <div>; variant, tone, size, placement
 │  ├─ Banner.Icon           one Icon on the first line (aria-hidden)
 │  ├─ Banner.Title
 │  ├─ Banner.Description
-│  └─ Banner.Actions        buttons; with onDismiss the close button is last here
-└─ close button             with onDismiss and no Actions: ghost icon Button (tone="inherit"), top-right
+│  └─ Banner.Actions        buttons; with onDismiss the close button is last here (wide banner)
+└─ close button             with onDismiss and no Actions, or Actions under the text: ghost icon Button (tone="inherit"), top-right
 ```
 
 ## API
@@ -72,7 +72,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
 ### Banner.Actions
-`ref` → `HTMLDivElement`. A `<div>` row of buttons; with `onDismiss` the close button becomes its last square button.
+`ref` → `HTMLDivElement`. A `<div>` row of buttons; with `onDismiss` the close button becomes its last square button (in the corner below 36rem).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -115,7 +115,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 |---|---|---|
 | look | `variant`, `tone`, `size`, `placement` | `data-variant`, `data-tone`, `data-size`, `data-placement` |
 | dismissible | `onDismiss` | corner ghost Button (`xs`, `s` on `l` / `xl`), or the last outline Button in `Banner.Actions` |
-| narrow | own width < 36rem (a banner with `Banner.Actions` is a size container) | actions move under the text |
+| narrow | own width < 36rem (a banner with `Banner.Actions` is a size container) | actions move under the text; the close button returns to the corner |
 
 No `open` prop: the parent mounts and unmounts the banner. A mounted banner enters (a short fade and rise); an unmounted one closes up in place, so the content below glides up instead of jumping. To swap the banner for another block in the same spot (a «restore» button), wrap both in [Crossfade](../crossfade/COMPONENT.md).
 

package/src/components/banner/examples/examples.module.css

@@ -8,7 +8,8 @@
   min-width: 0;
 }
 
-/* page-strip.tsx: the page strip above a card with an inset banner. */
+/* page-strip.tsx: a page — the strip spans its whole width, the content below keeps the page's
+   side padding, so the strip reads wider than the card with the inset banner. */
 .sections {
   display: flex;
   flex-direction: column;
@@ -17,6 +18,10 @@
   min-width: 0;
 }
 
+.pageBody {
+  padding-inline: var(--prime-layout-gutter);
+}
+
 /* narrow.tsx: a 320px column; the banner's container query moves actions under the text. */
 .narrow {
   width: min(100%, calc(var(--prime-space-20) * 4));