prime-ui-kit 0.9.1 → 0.9.3

package/src/components/tabs/COMPONENT.md

@@ -26,8 +26,8 @@ import { Tabs } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItemWidth; horizontal: the frame
-├─ Tabs.List              role="tablist" on a ScrollContainer, sliding folder / pill; collapses, then scrolls
+Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItemWidth; the frame (a layer)
+├─ Tabs.List              role="tablist" on a ScrollContainer, sliding folder; collapses, then scrolls
 │  ├─ Tabs.Item           one tab (role="tab") in an item wrapper; onRemove adds a close button; parts:
 │  │  ├─ Tabs.Icon        decorative icon; hidden first, kept last
 │  │  ├─ Tabs.Label       title; keeps its width when it turns medium weight
@@ -42,25 +42,25 @@ Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItem
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Tabs.Root
-`ref` → `HTMLDivElement`. `<div>` that owns the active value, size and orientation and lays out the list and the panel; horizontal, it is the frame: a sunken strip over the panel surface.
+`ref` → `HTMLDivElement`. `<div>` that owns the active value, size and orientation and lays out the list and the panel. It is the frame and a layer of the surface ladder in both orientations: a strip two steps off the layer and the panel in the layer's own color — above the panel when horizontal, at its inline start when vertical.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `string` | — | Active tab (controlled). |
 | `defaultValue` | `string` | `""` | Initial active tab (uncontrolled). With `""` no tab is selected. |
 | `onValueChange` | `(value: string) => void` | — | Called with the new active value. |
-| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | List direction and arrow keys. A vertical list stacks above the panel when the container is narrower than 600px. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | List direction and arrow keys. Vertical: a column of sections at the panel's inline start, the active one the panel reaching into the column; when the container is narrower than 600px the column becomes the horizontal strip above the panel. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier: text, icon, spacing, folder radius and panel padding. A horizontal tab is the control height plus the folder rise on both sides; a vertical one is the control height. |
-| `fullWidth` | `boolean` | `true` | Horizontal tabs share the list width equally, within `minItemWidth` … `maxItemWidth`; `false` sizes each tab to its content within the same bounds. |
+| `fullWidth` | `boolean` | `true` | Horizontal tabs fill the list and tend to equal widths within `minItemWidth` … `maxItemWidth`, never narrower than their content: a long label keeps its width, short ones share the rest; when they do not fit, the list collapses, then scrolls. `false` sizes each tab to its content within the same bounds. |
 | `tone` | `"neutral" \| "accent"` | `"neutral"` | Colour of the active tab: `neutral` is primary text with an accent icon, `accent` puts text and icon in accent. |
-| `minItemWidth` | `number \| string` | `2.5 × control height` | Narrowest a horizontal tab with a label gets, px or a CSS length; past it the list scrolls. Icon-only tabs are square. |
+| `minItemWidth` | `number \| string` | `2.5 × control height` | Narrowest a horizontal tab with a label gets, px or a CSS length; a tab is also never narrower than its content (up to `maxItemWidth`). When tabs do not fit, the list collapses, then scrolls. Icon-only tabs are square. |
 | `maxItemWidth` | `number \| string` | `7 × control height` | Widest a horizontal tab gets, px or a CSS length (`"none"` lifts the cap); a longer label ends with an ellipsis. |
 | `labels` | `Partial<TabsLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | `Tabs.List` and `Tabs.Panel`s. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">` | — | `className` and the other div attributes. |
 
 ### Tabs.List
-`ref` → `HTMLDivElement`. `role="tablist"` on a `ScrollContainer` (horizontal, edge fade, hidden scrollbar) with the sliding folder (vertical: pill). When tabs do not fit or a label would be cut, it hides icons and descriptions, then labels (icons with tooltips stay; only when every tab has an icon); tabs then shrink to `minItemWidth` and the list scrolls.
+`ref` → `HTMLDivElement`. `role="tablist"` on a `ScrollContainer` (horizontal, edge fade, hidden scrollbar) with the sliding folder (in both orientations), which glides only into a choice by click or keys and is placed without motion on mount, resize and collapse. When tabs do not fit or a label would be cut, it hides icons and descriptions, then labels (icons with tooltips stay; only when every tab has an icon); then the list scrolls; a label is never cut to make room. The active tab is kept in view and clear of the edge fades (the first and the last tab scroll all the way to the end); only the list scrolls, never the page.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -128,7 +128,7 @@ Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItem
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
 
 ## Variants
-Tabs have no `variant`: navigation tabs are always a folder (horizontal) or pills (vertical).
+Tabs have no `variant`: navigation tabs are always a folder — rising from the panel's top edge (horizontal) or reaching out of its side (vertical).
 
 ### tone
 | Value | Looks like | Use when | Default |
@@ -139,8 +139,8 @@ Tabs have no `variant`: navigation tabs are always a folder (horizontal) or pill
 ### orientation
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `horizontal` | a `bg-sunken` strip over a padded `bg-surface` panel, tabs edge to edge; the active tab is the panel surface rising into the strip with concave flares, gliding between tabs; primary text, medium weight, accent icon; hover is the same shape in `fill-faint` | switching sections above the content | yes |
-| `vertical` | items padded like controls, no rail; active item is a `fill-muted` pill with a short accent mark at the start; hover `fill-subtle`; below a 600px container it becomes a scrolling row above the panel | settings pages with a side list of sections | |
+| `horizontal` | a layer of the surface ladder: a `fill-muted-hover` strip (two steps off the layer) over a padded panel in the layer's own color, tabs edge to edge; the active tab is the panel rising into the strip with concave flares, gliding between tabs; primary text, medium weight, accent icon; hover is the same shape in `fill-faint` | switching sections above the content | yes |
+| `vertical` | the same folder on its side: a column of sections in the `fill-muted-hover` strip at the panel's inline start; the active section is the panel reaching into the column, rounded on the outer side, with concave flares above and below where it meets the panel; hover is the same shape in `fill-faint`. Below a 600px container the column becomes the horizontal strip above the panel (it scrolls, never wraps) | settings pages with a side list of sections | |
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -156,13 +156,13 @@ A horizontal tab is the control height of the tier plus the rise above and below
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `fullWidth` | horizontal tabs share the list width equally (up to `maxItemWidth`), content centred; `false` sizes each tab to its content, the strip still spans the frame | `false` for tabs of very different label lengths | `true` |
+| `fullWidth` | horizontal tabs fill the list and tend to equal widths (`flex: 1 1 0`, up to `maxItemWidth`), content centred; a tab is never narrower than its content or `minItemWidth`, so a long label keeps its width and the short ones share the rest; `false` sizes each tab to its content, the strip still spans the frame | `false` for tabs of very different label lengths | `true` |
 
 ### minItemWidth · maxItemWidth
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | defaults | a horizontal tab is 2.5 to 7 control heights wide (90 … 252 at `m`); tabs never stretch into wide bars | most screens | yes |
-| lengths (`128`, `"16rem"`) | browser tabs: grow up to `maxItemWidth` with the label cut by an ellipsis past it, shrink to `minItemWidth` in a crowded list, then the list scrolls | open documents, records, chats — many tabs with long titles | |
+| lengths (`128`, `"16rem"`) | browser tabs: grow up to `maxItemWidth` with the label cut by an ellipsis past it, never narrower than `minItemWidth` or their title up to the cap; in a crowded list the list scrolls | open documents, records, chats — many tabs with long titles | |
 | `maxItemWidth="none"` | tabs share the whole strip | a few sections that must fill a wide frame | |
 
 ### Item content
@@ -180,23 +180,25 @@ Avoid icons or descriptions on only some tabs (uneven rows; without an icon on e
 | State | Driven by | DOM |
 |---|---|---|
 | active | `value` / `defaultValue` | item `aria-selected="true"`, `data-state="active"`, `tabIndex=0`; others `data-state="inactive"`, `tabIndex=-1` |
-| hover | pointer | text → primary; horizontal: the folder shape in `fill-faint`, under the folder; vertical: `fill-subtle` background |
+| hover | pointer | text → primary; the folder shape in `fill-faint`, under the folder |
 | pressed | pointer down | the tab content scales to `--prime-motion-press-scale-compact` |
-| focus-visible | keyboard | focus ring inside the tab, above the folder; the panel shows an inset ring (vertical: outer ring) |
+| focus-visible | keyboard | focus ring inside the tab, above the folder; the panel shows an inset ring |
 | disabled | `disabled` on Item | native `disabled`, `data-disabled="true"`, `text-disabled`; a removable tab loses its close button |
 | removable | `onRemove` on Item | item wrapper `data-removable="true"`, close button, tab `aria-keyshortcuts="Delete"` |
 | two-line | `Tabs.Description` child | `data-two-line="true"` |
 | collapsed | tabs wider than the list, or a label that would be cut (horizontal) | list `data-collapse="full" \| "compact" \| "icon"`: `compact` hides icons and descriptions; `icon` hides labels (sr-only, shown in a `Tooltip`), counts and close buttons, only when every tab has an icon |
-| overflow | tabs at `minItemWidth` (or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (ScrollContainer), faded edges; the active tab scrolls into view |
+| overflow | tabs at their narrowest (content width, `minItemWidth` or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (ScrollContainer), faded edges as deep as the hidden part at most (they grow and melt with the scroll, never switch); the active tab is kept in view and clear of the fades on mount and on every value change, the first and the last tab scroll all the way to the end — only the list scrolls, never the page |
 
-Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; List `data-indicator="folder" | "pill"`; Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted; a panel's content enters each time it opens.
+The indicator glides (`emphasized` + `base`, `data-animate="true"`) only into a choice by click, arrow keys or closing the active tab; on mount, a value set from outside, a resize, font loading, tabs added or removed and collapse it is placed without motion, and it stays still under `prefers-reduced-motion`. The list scrolls smoothly to the active tab only after such a choice too.
+
+Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; List `data-indicator="folder"`, its indicator `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted; a panel's content enters each time it opens.
 
 ## Layout & spacing
-- Horizontal: the root is the frame (`radius-xl`, `bg-sunken`), the list sits flush on the panel and runs edge to edge; the panel pads its content by tier (`--prime-space-4` … `--prime-space-8`). Do not wrap Tabs in a Card — it already is one.
-- Vertical list → panel: `var(--prime-space-6)`.
-- The list never wraps: it collapses, then scrolls horizontally with faded edges. Give the list's container a width (`min-width: 0` on flex children).
+- The root is the frame and a layer of the ladder in both orientations (`data-depth`, `radius-xl`, the strip two steps off the layer); the list sits flush on the panel; the panel pads its content by tier (`--prime-space-4` … `--prime-space-8`). Do not wrap Tabs in a Card — it already is one.
+- Vertical: the column is as wide as its widest section (at least four control heights, at most 40% of the root), inset by the folder rise from the frame on the outer side, flush with the panel on the other.
+- The list never wraps: it collapses, then scrolls horizontally with faded edges (hidden scrollbar, `overscroll-behavior: contain`). Give the list's container a width (`min-width: 0` on flex children).
+- A horizontal tab is never narrower than its content (`min-width: max-content`; the tab bounds that content between `minItemWidth` and `maxItemWidth`), so a label is never cut to make room. Full width, tabs tend to equal widths, not widths in proportion to their labels (`flex: 1 1 0`): a long label keeps its width, the short ones share the rest.
 - A vertical Tabs.Root is a size container: give it a width (it measures itself to switch to a row).
-- In a vertical layout align the panel heading with the first tab by making the heading row one control tall (`min-height: var(--prime-control-m-height)`).
 
 ## Accessibility
 
@@ -232,9 +234,9 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: text, icon, folder radius and spacing grow together — `size`. |
 | [states.tsx](examples/states.tsx) | A disabled tab that clicks and arrow keys skip — `disabled`. |
 | [with-icon.tsx](examples/with-icon.tsx) | A muted icon before the label and a hairline before the service section — `Tabs.Icon`, `Tabs.Label`, `Tabs.Separator`. |
-| [orientation.tsx](examples/orientation.tsx) | Tabs over the panel and a side list of sections that stacks on top below 600px — `orientation`. |
+| [orientation.tsx](examples/orientation.tsx) | Account settings with a side list of sections: the active section reaches out of the panel, and below 600px the list moves above it — `orientation`. |
 | [overflow.tsx](examples/overflow.tsx) | Drag the frame narrower: icons go first, then labels, and icons with tooltips stay; then the list scrolls — `Tabs.Icon`. |
-| [closable.tsx](examples/closable.tsx) | Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths and scroll past the narrower one — `onRemove`, `minItemWidth`, `maxItemWidth`. |
+| [closable.tsx](examples/closable.tsx) | Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths, and the list scrolls when they do not fit — `onRemove`, `minItemWidth`, `maxItemWidth`. |
 | [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a summary on the second — `Tabs.Count`, `Tabs.Description`. |
 | [controlled.tsx](examples/controlled.tsx) | The active tab lives in parent state, e.g. synced with the URL — `value`, `onValueChange`. |
 

package/src/components/tabs/examples/closable.tsx

@@ -1,4 +1,4 @@
-/** Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths and scroll past the narrower one — `onRemove`, `minItemWidth`, `maxItemWidth`. */
+/** Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths, and the list scrolls when they do not fit — `onRemove`, `minItemWidth`, `maxItemWidth`. */
 import { Button, Tabs, Typography } from "prime-ui-kit";
 import * as React from "react";
 

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

@@ -8,6 +8,20 @@
   margin-inline: auto;
 }
 
+/* A settings block: wide enough for the side list next to a form, never wider than the preview. */
+.wide {
+  box-sizing: border-box;
+  width: min(100%, calc(20 * var(--prime-control-m-height)));
+  margin-inline: auto;
+}
+
+/* Fields and switches of a settings section: field → field rhythm (foundation §1). */
+.form {
+  display: grid;
+  gap: var(--prime-space-5);
+  max-width: calc(10 * var(--prime-control-m-height));
+}
+
 /* The same column, which the reader can drag narrower to watch the tabs collapse and scroll. */
 .resizable {
   composes: frame;

package/src/components/tabs/examples/orientation.tsx

@@ -1,40 +1,94 @@
-/** Tabs over the panel and a side list of sections that stacks on top below 600px — `orientation`. */
-import { Tabs, Typography } from "prime-ui-kit";
+/** Account settings with a side list of sections: the active section reaches out of the panel, and below 600px the list moves above it — `orientation`. */
+import { Button, Icon, Input, Switch, Tabs, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const SECTIONS = [
-  { value: "profile", label: "Профиль", text: "Имя, должность и контакты сотрудника." },
-  { value: "notifications", label: "Уведомления", text: "Письма о заказах и еженедельная сводка." },
-  { value: "deletion", label: "Удаление", text: "Аккаунт и все данные будут удалены." },
-];
-
 export default function TabsOrientationExample() {
   return (
-    <>
-      {(["horizontal", "vertical"] as const).map((orientation) => (
-        <Tabs.Root
-          key={orientation}
-          orientation={orientation}
-          defaultValue="notifications"
-          className={styles.frame}
-        >
-          <Tabs.List aria-label="Настройки">
-            {SECTIONS.map((section) => (
-              <Tabs.Item key={section.value} value={section.value}>
-                {section.label}
-              </Tabs.Item>
-            ))}
-          </Tabs.List>
-          {SECTIONS.map((section) => (
-            <Tabs.Panel key={section.value} value={section.value}>
-              <Typography variant="body-m" tone="secondary">
-                {section.text}
-              </Typography>
-            </Tabs.Panel>
-          ))}
-        </Tabs.Root>
-      ))}
-    </>
+    <Tabs.Root orientation="vertical" defaultValue="notifications" className={styles.wide}>
+      <Tabs.List aria-label="Настройки аккаунта">
+        <Tabs.Item value="profile">
+          <Tabs.Icon>
+            <Icon name="object.user" />
+          </Tabs.Icon>
+          <Tabs.Label>Профиль</Tabs.Label>
+        </Tabs.Item>
+        <Tabs.Item value="notifications">
+          <Tabs.Icon>
+            <Icon name="object.bell" />
+          </Tabs.Icon>
+          <Tabs.Label>Уведомления</Tabs.Label>
+        </Tabs.Item>
+        <Tabs.Item value="security">
+          <Tabs.Icon>
+            <Icon name="object.key" />
+          </Tabs.Icon>
+          <Tabs.Label>Безопасность</Tabs.Label>
+        </Tabs.Item>
+        <Tabs.Separator />
+        <Tabs.Item value="deletion">
+          <Tabs.Icon>
+            <Icon name="action.delete" />
+          </Tabs.Icon>
+          <Tabs.Label>Удаление</Tabs.Label>
+        </Tabs.Item>
+      </Tabs.List>
+
+      <Tabs.Panel value="profile">
+        <div className={styles.form}>
+          <Input.Root label="Имя и фамилия">
+            <Input.Wrapper>
+              <Input.Field defaultValue="Анна Смирнова" autoComplete="name" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Input.Root label="Должность">
+            <Input.Wrapper>
+              <Input.Field defaultValue="Руководитель отдела продаж" />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </Tabs.Panel>
+
+      <Tabs.Panel value="notifications">
+        <div className={styles.form}>
+          <Switch.Root defaultChecked hint="Письмо, как только заказ оплачен или отменён">
+            <Switch.Label>Статусы заказов</Switch.Label>
+          </Switch.Root>
+          <Switch.Root defaultChecked hint="По понедельникам в 09:00">
+            <Switch.Label>Сводка за неделю</Switch.Label>
+          </Switch.Root>
+          <Switch.Root hint="Новые функции и вебинары">
+            <Switch.Label>Новости продукта</Switch.Label>
+          </Switch.Root>
+        </div>
+      </Tabs.Panel>
+
+      <Tabs.Panel value="security">
+        <div className={styles.form}>
+          <Input.Root label="Новый пароль" hint="Не короче 12 символов">
+            <Input.Wrapper>
+              <Input.Field type="password" autoComplete="new-password" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Switch.Root defaultChecked hint="Код из приложения при каждом входе">
+            <Switch.Label>Двухфакторная проверка</Switch.Label>
+          </Switch.Root>
+        </div>
+      </Tabs.Panel>
+
+      <Tabs.Panel value="deletion">
+        <div className={styles.form}>
+          <Typography variant="body-m" tone="secondary">
+            Аккаунт и все данные будут удалены через 30 дней. До этого срока удаление можно
+            отменить.
+          </Typography>
+          <div>
+            <Button.Root tone="danger" variant="soft">
+              Удалить аккаунт
+            </Button.Root>
+          </div>
+        </div>
+      </Tabs.Panel>
+    </Tabs.Root>
   );
 }

package/src/components/tooltip/COMPONENT.md

@@ -74,16 +74,18 @@ No DOM: clones the single child, composes its `ref`, appends the tooltip id to i
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "role" \| "onPointerEnter" \| "onPointerLeave">` | — | `className`, `style` and the other attributes of the chip. |
 
 ## Variants
-Tooltip has no `variant` or `tone`: it is always a flat inverse chip (`tooltip-bg`, `tooltip-text`) with an arrow and no shadow, so it reads the same on canvas, cards and floating layers. The arrow (`--prime-tooltip-arrow-width` × `--prime-tooltip-arrow-height`) always points at the trigger's centre, also after flipping, aligning or shifting, and never slides into the chip's rounded corner.
+Tooltip has no `variant` or `tone`: it is always a flat inverse chip (`tooltip-bg`, `tooltip-text`) — dark in the light theme, light in the dark one — with an arrow and no shadow, so it reads the same on every layer. The chip is a host of its own: it points the text and fill roles at `tooltip-muted` / `tooltip-fill`, so a Kbd or a secondary line inside reads on it. Content flows inline: a label and its key stay on one line, block children stack. The arrow (`--prime-tooltip-arrow-width` × `--prime-tooltip-arrow-height`) always points at the trigger's centre, also after flipping, aligning or shifting, and never slides into the chip's rounded corner.
 
 ### size (Content)
+A chip of tier T is as tall as a menu item of tier T; text, padding and radius step together (`--prime-tooltip-<tier>-*`).
+
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | caption 12/16, padding 4 × 8 | Next to xs controls | |
-| `s` | caption 12/16, padding 4 × 8 | Dense toolbars, s controls | |
-| `m` | caption 12/16, padding 4 × 8 | Most controls | yes |
-| `l` | body-s 13/20, padding 4 × 8 | l controls, longer sentences | |
-| `xl` | body-s 13/20, padding 8 × 12 | xl controls | |
+| `xs` | 12/16, padding 4 × 6, radius 4 — 24 tall | Next to xs controls | |
+| `s` | 12/16, padding 6 × 8, radius 6 — 28 tall | Dense toolbars, s controls | |
+| `m` | 13/20, padding 6 × 10, radius 6 — 32 tall | Most controls | yes |
+| `l` | 14/20, padding 8 × 12, radius 8 — 36 tall | l controls, longer sentences | |
+| `xl` | 16/24, padding 8 × 16, radius 8 — 40 tall | xl controls | |
 
 ### side (Content)
 | Value | Looks like | Use when | Default |

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

@@ -7,8 +7,8 @@
   gap: var(--prime-space-1);
   padding: var(--prime-space-1);
   border-radius: var(--prime-radius-l);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
+  background: var(--prime-color-layer-nested);
+  box-shadow: var(--prime-shadow-raised);
 }
 
 /* disabled-trigger.tsx: a focusable wrapper around the disabled button, with the outer ring. */

package/src/layout/app-header/COMPONENT.md

@@ -0,0 +1,178 @@
+# AppHeader
+
+**Category:** page
+**Kind:** layout
+
+> The bar at the top of the app's content panel: where you are, global search and a few actions.
+
+## When to use
+- The top row of an app built on [AppShell](../app-shell/COMPONENT.md): the section title or the path, the ⌘K search entry, notifications, the account, one primary action.
+- The phone header: the menu button that opens the off-canvas Sidebar, the title, search as an icon.
+
+## When not to use
+- The page heading, its description and page actions inside main → use [PageContent](../../components/page-content/COMPONENT.md) (`PageContent.Title` is the `<h1>`).
+- Tabs, filters and search for the data on the page → use [PageToolbar](../../components/page-toolbar/COMPONENT.md).
+- App navigation → use [Sidebar](../sidebar/COMPONENT.md) and, on a phone, [BottomNav](../bottom-nav/COMPONENT.md); the header holds at most the menu button.
+- The search dialog itself → use [CommandMenu](../../components/command-menu/COMPONENT.md); `AppHeader.Search` only opens it.
+
+## Import
+```tsx
+import { AppHeader } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+AppHeader.Root               <header>, one sticky row as high as the Sidebar brand row
+├─ AppHeader.Start           leading zone, takes the free width
+│  ├─ AppHeader.MenuButton   opens the off-canvas Sidebar (below 768px by default)
+│  ├─ AppHeader.Separator    short vertical line between groups (a back Button | a Breadcrumb)
+│  └─ AppHeader.Title        name, truncates (or a Breadcrumb instead)
+│     ├─ AppHeader.Icon      decorative glyph on a tile shaped like a soft button m
+│     └─ AppHeader.Description  muted caption under the name
+├─ AppHeader.Search          field-looking button that opens the CommandMenu
+└─ AppHeader.Actions         trailing buttons: notifications, account, primary action
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### AppHeader.Root
+`ref` → `HTMLElement`. The `<header>` bar at the top of the content panel: one row as high as the Sidebar brand row, on the panel surface with no divider, sticky with the top safe-area inset (static below 480px of viewport height); inline padding is the shell gutter, so it lines up with the page in main (16 outside a shell). Its controls are size `m`; icon buttons inside are `soft` (a light fill), not `ghost`. A container (`prime-app-header`): below 36rem the icon tile and the description go and the search folds into an icon.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `labels` | `Partial<AppHeaderLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (`AppHeader.Start`, `AppHeader.Search`, `AppHeader.Actions`), `className` and the other attributes. |
+
+### AppHeader.Start
+`ref` → `HTMLDivElement`. The leading zone that takes the free width: the menu button, a back button, the title or a Breadcrumb.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### AppHeader.Title
+`ref` → `HTMLDivElement`. Where you are: an optional `AppHeader.Icon`, the name (title-s, truncates) and an optional `AppHeader.Description` under it — the anatomy of the Sidebar brand. Not a heading: the page `<h1>` is PageContent.Title.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the name, `AppHeader.Icon`, `AppHeader.Description` in any order), `className` and the other div attributes. |
+
+### AppHeader.Icon
+`ref` → `HTMLSpanElement`. Decorative glyph before the title (`aria-hidden`) on a tile shaped like the bar's soft buttons: control m square (36), its radius and the subtle fill.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (an `Icon`), `className` and the other span attributes. |
+
+### AppHeader.Description
+`ref` → `HTMLSpanElement`. Muted caption under the title (a workspace, a period); hidden on a narrow header.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+### AppHeader.Separator
+`ref` → `HTMLDivElement`. A short vertical `Divider` (20) between groups in a zone — a back button and the path — with 16 of air on each side.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<DividerProps, "orientation" \| "children">` | — | `className` and the other div attributes. |
+
+### AppHeader.Search
+`ref` → `HTMLButtonElement`. The global search entry: a `<button type="button">` drawn as a field (search icon, placeholder text, key hint) that opens your CommandMenu. Below 36rem of header width it folds into a square button named by its text.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The placeholder text; also the accessible name. |
+| `shortcut` | `ReactNode` | `"⌘K"` | The key hint at the end (a `Kbd`, hidden from assistive tech); `null` hides it. Bind the key yourself. |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `className` and the other button attributes. |
+
+### AppHeader.Actions
+`ref` → `HTMLDivElement`. The trailing row of buttons: notifications, the account, one primary action. Never wraps.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### AppHeader.MenuButton
+`ref` → `HTMLButtonElement`. A soft neutral icon `Button` named by `labels.menu` that opens the off-canvas Sidebar; wire `onClick` and `aria-expanded`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `show` | `"narrow" \| "always"` | `"narrow"` | `narrow` — only below 768px, where a Sidebar with `offCanvas="auto"` leaves the layout; `always` — on every width (`offCanvas="always"`). |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `aria-expanded`, `aria-label` (replaces `labels.menu`), `className` and the other button attributes. |
+
+## Variants
+
+### show (MenuButton)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `narrow` | The menu button shows only below 768px | Sidebar with `offCanvas="auto"` | yes |
+| `always` | The menu button on every width | Sidebar with `offCanvas="always"`, or you decide visibility yourself | |
+
+### Structure
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `AppHeader.Title` | Icon, name and a caption under it, like the Sidebar brand | A top-level section | |
+| Breadcrumb in Start | A soft back button, `AppHeader.Separator` and the path | A nested record page | |
+| with `AppHeader.Search` | A field-looking button with a key hint between Start and Actions | The app has a CommandMenu | |
+| with `AppHeader.Actions` | A row of buttons at the end | Notifications, account, one primary action | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| narrow header | header width below 36rem (container `prime-app-header`) | the icon tile and the description hide; the search folds into a square button, its text stays as the name |
+| menu button hidden | `show="narrow"` and viewport from 768px | `data-show="narrow"` on MenuButton |
+| short viewport | viewport below 480px high (a phone on its side) | Root stops sticking |
+
+## Layout & spacing
+- Row min height = control m + `--prime-space-2` (44), padding-block `--prime-space-3` (the top grows to the safe-area inset): 68 in all, the height of the Sidebar header, so the brand and the title share one line.
+- Inline padding: the shell gutters (16 → 24 → 32, the same as `AppShell.Main`) in the shell's panel, so the header lines up with the page; `--prime-space-4` elsewhere.
+- Icon buttons are `soft` neutral (MenuButton is), never `ghost`: the search folds into a filled square too, so every button on the bar has a shape.
+- Gaps: `--prime-space-3` between zones, `--prime-space-2` inside Start and Actions; `AppHeader.Separator` adds `--prime-space-2` on each side (16 in all) and is 20 high.
+- `AppHeader.Icon` is a 36 tile with the radius and fill of a soft neutral button m, so it lines up with the buttons on the bar.
+- On the panel surface with no divider or shadow (depth from fill); `z-index: --prime-z-sticky`.
+- Search: up to 288 wide, shrinks first; field tier m and the fill of the panel layer it sits on. Controls inside are size `m`.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves through the menu button, the path links, the search and the actions in reading order. |
+| `Enter` · `Space` | Presses the focused button: opens the menu, the search or runs the action. |
+
+### ARIA
+- Root is a `<header>`: the banner landmark when it sits at the top level of the page.
+- Search is a button named by its text; the key hint is `aria-hidden`, and the app binds the shortcut.
+- MenuButton is named by `labels.menu`; pass `aria-expanded` (whether the Sidebar is open).
+- Title is not a heading: the page `<h1>` stays with PageContent.Title.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `menu` | `"Открыть меню"` | Name of `AppHeader.MenuButton`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | The top bar of a screen: where you are, global search, notifications and the primary action — `AppHeader.Title`, `AppHeader.Search`, `AppHeader.Actions`. |
+| [breadcrumbs.tsx](examples/breadcrumbs.tsx) | A nested page: a back button, a separator and the path instead of a title, actions on the record at the end — `AppHeader.Separator`, `AppHeader.Actions`. |
+| [in-app-shell.tsx](examples/in-app-shell.tsx) | The header in the app frame: one row with the Sidebar brand across the two planes, sticky over main — `AppShell`, `Sidebar.Brand`. |
+| [narrow.tsx](examples/narrow.tsx) | On a phone: the menu button opens the navigation, the description goes and the search folds into an icon — `AppHeader.MenuButton`, `show`. |
+
+## Mistakes
+- A border or shadow under the header → it sits on the panel surface; the fill is the boundary.
+- `AppHeader.Title` as the page `<h1>` → the heading belongs to PageContent.Title in main.
+- A real text input for global search → `AppHeader.Search` opens the CommandMenu, where typing happens.
+- More than three actions → keep one primary action; the rest go into the page or a Dropdown.
+- A hand-made menu button with a media query → `AppHeader.MenuButton` follows the Sidebar breakpoint.
+- `ghost` icon buttons in the header → `variant="soft" tone="neutral"`: a light fill gives each button a shape on the bar.
+
+## Related
+- **Built from:** [Button](../../components/button/COMPONENT.md), [Kbd](../../components/kbd/COMPONENT.md), [Divider](../../components/divider/COMPONENT.md), Icon (`action.search`, `nav.menu`)
+- **See also:** [AppShell](../app-shell/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [PageToolbar](../../components/page-toolbar/COMPONENT.md), [CommandMenu](../../components/command-menu/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)

package/src/layout/app-header/examples/breadcrumbs.tsx

@@ -0,0 +1,36 @@
+/** A nested page: a back button, a separator and the path instead of a title, actions on the record at the end — `AppHeader.Separator`, `AppHeader.Actions`. */
+import { AppHeader, Breadcrumb, Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function AppHeaderBreadcrumbsExample() {
+  return (
+    <div className={styles.window}>
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <Button.Root variant="soft" tone="neutral" aria-label="Назад к клиентам">
+            <Button.Icon>
+              <Icon name="nav.chevronLeft" />
+            </Button.Icon>
+          </Button.Root>
+          <AppHeader.Separator />
+          <Breadcrumb.Root>
+            <Breadcrumb.Item href="#crm">CRM</Breadcrumb.Item>
+            <Breadcrumb.Item href="#clients">Клиенты</Breadcrumb.Item>
+            <Breadcrumb.Item current>ООО «Север»</Breadcrumb.Item>
+          </Breadcrumb.Root>
+        </AppHeader.Start>
+        <AppHeader.Actions>
+          <Button.Root variant="soft" tone="neutral">
+            Экспорт
+          </Button.Root>
+          <Button.Root variant="soft" tone="neutral" aria-label="Ещё действия">
+            <Button.Icon>
+              <Icon name="action.more" />
+            </Button.Icon>
+          </Button.Root>
+        </AppHeader.Actions>
+      </AppHeader.Root>
+    </div>
+  );
+}

package/src/layout/app-header/examples/examples.module.css

@@ -0,0 +1,47 @@
+/* Layout of the AppHeader scenarios: an app window and a phone-wide screen. Semantic tokens only. */
+
+/* The top of an app window: the content panel (the page) with the header on it. */
+.window {
+  box-sizing: border-box;
+  width: 100%;
+  overflow: hidden;
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-layer-current);
+  box-shadow:
+    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
+    var(--prime-shadow-raised);
+}
+
+/* narrow.tsx: the same window, phone-wide, so the header folds its search. */
+.phone {
+  width: min(100%, var(--prime-drawer-width-s));
+  margin-inline: auto;
+}
+
+/* in-app-shell.tsx: a whole app window with the rail on the page. */
+.stage {
+  box-sizing: border-box;
+  display: flex;
+  width: 100%;
+  height: calc(var(--prime-space-24) * 4);
+  overflow: hidden;
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-layer-current);
+  box-shadow:
+    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
+    var(--prime-shadow-raised);
+}
+
+/* The shell fills the window frame instead of the viewport. */
+.shell {
+  height: 100%;
+}
+
+/* The product mark inside `Sidebar.BrandLogo`: an accent tile with a glyph. */
+.logo {
+  display: grid;
+  place-items: center;
+  border-radius: var(--prime-radius-m);
+  background: var(--prime-color-accent-default);
+  color: var(--prime-color-accent-fg);
+}