prime-ui-kit 0.9.3 → 0.11.0

package/dist/skill/reference/layout/app-shell/COMPONENT.md

@@ -0,0 +1,156 @@
+# AppShell
+
+**Category:** page
+**Kind:** layout
+
+> The app frame: a content panel that is the page itself and a navigation rail one layer above it.
+
+## When to use
+- The root layout of an application: navigation column, an optional AppHeader, scrolling main column, a bottom bar for phone navigation.
+- Any page that needs the kit's responsive gutters and the surface ladder for cards and fields.
+
+## When not to use
+- The navigation itself → use [Sidebar](../sidebar/COMPONENT.md) inside `AppShell.Nav`, [BottomNav](../bottom-nav/COMPONENT.md) inside `AppShell.Footer`.
+- The top bar (title, search, actions, the menu button) → use [AppHeader](../app-header/COMPONENT.md) as a child of Root.
+- Page heading, actions and sections inside main → use [PageContent](../../components/page-content/COMPONENT.md).
+- A temporary side panel over the page → use [Drawer](../../components/drawer/COMPONENT.md).
+- A scroll region inside a page → use [ScrollContainer](../../components/scroll-container/COMPONENT.md).
+
+## Import
+```tsx
+import { AppShell } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+AppShell.Root                grid: nav column | content panel (the page, layer 0)
+├─ AppShell.Nav              navigation column (usually Sidebar.Root, a surface one layer above the page)
+├─ AppHeader.Root            sticky top bar of the panel (a separate component)
+├─ AppShell.Main             <main>, scrolls, carries the gutters
+└─ AppShell.Footer           sticky bottom bar of the panel (usually BottomNav.Root)
+AppShell.Template            Root + Nav + the header + Main + Footer in one component
+```
+Every child of Root that is not `AppShell.Nav` is placed into the content panel.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### AppShell.Root
+`ref` → `HTMLDivElement`. Grid of the nav column (Sidebar, a surface one layer above the page) and the content panel (the page itself); every child that is not `AppShell.Nav` goes into the panel.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `fillViewport` | `boolean` | `false` | The shell is exactly the viewport high and only `AppShell.Main` scrolls; otherwise the document scrolls and the nav is sticky. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Nav, `AppHeader.Root`, Main, Footer), `className` and the other div attributes. |
+
+### AppShell.Nav
+`ref` → `HTMLDivElement`. The navigation column slot (not a landmark: Sidebar renders the `<nav>`).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (usually `Sidebar.Root`), `className` and the other div attributes. |
+
+### AppShell.Main
+`ref` → `HTMLElement`. The `<main>` with the canonical gutters: a vertical `ScrollContainer`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `contentWidth` | `"contained" \| "full"` | `"full"` | `full` — the whole panel with gutters; `contained` — a centred column up to `--prime-layout-content-max-width`. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes. |
+
+### AppShell.Footer
+`ref` → `HTMLDivElement`. Sticky bottom bar of the panel for `BottomNav`; no padding of its own. Shows only while the shell has no navigation column on screen (no `AppShell.Nav`, or the Sidebar is off-canvas); with the rail on screen the footer leaves.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (usually `BottomNav.Root`), `className` and the other div attributes. |
+
+### AppShell.Template
+`ref` → the `<main>`. Root + Nav + the header + Main + Footer in one; main scrolls to the top when `scrollResetKey` changes.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `nav` | `ReactNode` | — | Navigation column content; without it the panel takes the full width. |
+| `header` | `ReactNode` | — | The top bar of the panel, an `AppHeader.Root`; no header when omitted. |
+| `footer` | `ReactNode` | — | Footer content (`BottomNav`); no footer when omitted. |
+| `mainProps` | `Omit<AppShellMainProps, "children">` | — | Props for Main (e.g. `contentWidth`). |
+| `scrollResetKey` | `unknown` | — | Main scrolls back to the top whenever this value changes; pass the router pathname. |
+| `children` | `ReactNode` | — | Page content inside Main. |
+| `…rest` | `Omit<AppShellRootProps, "children">` | — | Root props: `fillViewport`, `className` and the div attributes. |
+
+## Variants
+
+### fillViewport (Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `false` | Shell at least viewport high; the document scrolls; nav sticks to the top | Content sites, simple apps | yes |
+| `true` | Shell exactly viewport high; only Main scrolls; header and nav stay put | Dense apps with a fixed frame | |
+
+### contentWidth (Main)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `full` | Content spans the panel with responsive gutters | Tables, dashboards | yes |
+| `contained` | Centred column up to the content max width | Long-read pages | |
+
+### Structure
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| with `AppShell.Nav` | Two columns: a rail one layer above the page + the panel that is the page | Apps with navigation | |
+| without Nav | Panel takes the full width | Single-page tools, auth screens | |
+| with `AppHeader.Root` | Sticky bar at the top of the panel | Title or breadcrumbs, global search, actions, the mobile menu button | |
+| with `AppShell.Footer` | Sticky bar at the bottom of the panel, shown while no navigation column is on screen | BottomNav on a phone | |
+
+`AppShell.Template` with `nav={<Sidebar.Root …/>}` and `PageContent` inside is the standard app; `contentWidth="contained"` + `PageContent.Root maxWidth="readable"` for docs and articles.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| fixed frame | `fillViewport` | `data-fill-viewport="true"` on Root |
+| navigation column | an `AppShell.Nav` child | `data-nav="true"` on Root (two grid columns) |
+| content width | `contentWidth` | `data-content-width` on Main |
+| footer bar | the navigation column: `AppShell.Nav` with a Sidebar that is not off-canvas | the footer is `display: none` while the rail is on screen; without Nav or with an off-canvas Sidebar it stays at any width |
+
+## Layout & spacing
+- Two full-height planes edge to edge: no inset, radius, shadow or border — the boundary is the fill change (the Sidebar rail is layer 1, the panel the page: white rail beside a gray page in light, a rail one step lighter than the near-black page in dark).
+- Gutters in Main (and in an `AppHeader.Root` in the panel): `--prime-layout-gutter-s` (16) → `-m` (24) from 640px → `-l` (32) from 1024px. Main top padding `--prime-space-6` (24) → `--prime-space-10` (40) from 1024px; bottom `--prime-space-16`. Children of Main start from their own gutters, not the shell's.
+- A page that fills the panel height (`PageContent.Root fill`): Main's bottom padding drops to the side gutter, so no long scroll tail stays under it.
+- Main scrolls with `overscroll-behavior: contain`, so its scroll never chains to the document.
+- Nav column: sticky at the top, viewport high, `z-index: --prime-z-sticky` (above the panel, so the compact Sidebar toggle can ride the rail edge); with `fillViewport` it fills the shell height instead.
+- Footer: no padding of its own (BottomNav keeps the bottom safe-area inset), sticky at the bottom, `z-index: --prime-z-sticky`.
+- A floating BottomNav (`floating`) in the footer: the footer takes no height, the capsule overlays the page, and Main keeps extra bottom room (the capsule height and the safe-area inset) so its last line never ends up under it.
+- The panel is the page (layer 0 of the surface ladder, gray in light): fields on it take the page fill, a Card inside is layer 1 — white in light with the raised whisper — and cards in cards go deeper.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Main is the `<main>` landmark; the banner comes from AppHeader (`<header>`), the navigation landmarks from Sidebar and BottomNav (`<nav>`).
+- Give the page one `<h1>` (PageContent.Title).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | The app frame: Sidebar in the nav column, breadcrumbs in the AppHeader, the page in main; only main scrolls — `fillViewport`. |
+| [contained.tsx](examples/contained.tsx) | A shell without navigation whose main column is centred and capped for long reads — `contentWidth`. |
+| [footer.tsx](examples/footer.tsx) | A phone app without a Sidebar: the bar in the footer stays at the bottom while main scrolls under it — `AppShell.Footer`. |
+| [template.tsx](examples/template.tsx) | Root, nav, header and main in one component; main scrolls back to the top whenever the page changes — `AppShell.Template` with `scrollResetKey`. |
+
+## Mistakes
+- Adding padding around the page content → Main already has the gutters.
+- Wrapping Main content in another scroll container → Main scrolls (with `fillViewport`) or the document does.
+- A border or shadow between nav and panel → the fill change is the boundary.
+- Putting the Sidebar directly in Root without `AppShell.Nav` → it lands inside the content panel.
+- BottomNav anywhere but `AppShell.Footer` → it stays next to the Sidebar rail on a desktop; the footer is what leaves while the rail is on screen.
+- `AppShell.Template` in a router app without `scrollResetKey` → a new page opens at the old scroll position; pass the pathname.
+
+## Related
+- **Built from:** [ScrollContainer](../../components/scroll-container/COMPONENT.md)
+- **See also:** [AppHeader](../app-header/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [BottomNav](../bottom-nav/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)

package/dist/skill/reference/layout/app-shell/examples/contained.tsx

@@ -0,0 +1,30 @@
+/** A shell without navigation whose main column is centred and capped for long reads — `contentWidth`. */
+import { AppShell, PageContent, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function AppShellContainedExample() {
+  return (
+    <div className={styles.stage}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppShell.Main contentWidth="contained">
+          <PageContent.Root maxWidth="readable">
+            <PageContent.Header>
+              {/* In a real app this is PageContent.Title (the page h1). */}
+              <Typography as="h2" variant="heading-m">
+                Как подключить оплату
+              </Typography>
+              <PageContent.Description>Обновлено 1 октября 2026 года.</PageContent.Description>
+            </PageContent.Header>
+            <PageContent.Body>
+              <Typography as="p" variant="body-l">
+                Откройте раздел «Настройки», выберите «Оплата» и укажите реквизиты. После проверки
+                банк пришлёт подтверждение, и приём платежей включится автоматически.
+              </Typography>
+            </PageContent.Body>
+          </PageContent.Root>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  );
+}

package/dist/skill/reference/layout/app-shell/examples/examples.module.css

@@ -0,0 +1,44 @@
+/* Layout for the AppShell examples: a small "app window" frame. Semantic tokens only. */
+
+.stage {
+  box-sizing: border-box;
+  display: flex;
+  width: 100%;
+  height: calc(var(--prime-space-24) * 5);
+  overflow: hidden;
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-layer-current);
+  /* The window is a page on the preview's page: a hairline keeps its edge visible. */
+  box-shadow:
+    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
+    var(--prime-shadow-raised);
+}
+
+/* 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);
+}
+
+/* The shell fills the window frame instead of the viewport. */
+.shell {
+  height: 100%;
+}
+
+/* footer.tsx: the same window, phone-wide; no Nav, so the bar in the footer stays. */
+.phone {
+  box-sizing: border-box;
+  display: flex;
+  width: min(100%, var(--prime-drawer-width-s));
+  height: calc(var(--prime-space-24) * 5);
+  margin-inline: auto;
+  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);
+}

package/dist/skill/reference/layout/app-shell/examples/footer.tsx

@@ -0,0 +1,59 @@
+/** A phone app without a Sidebar: the bar in the footer stays at the bottom while main scrolls under it — `AppShell.Footer`. */
+import { AppHeader, AppShell, BottomNav, Icon, PageContent, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { label: "Главная", icon: "nav.home" },
+  { label: "Счета", icon: "object.receipt" },
+  { label: "Клиенты", icon: "object.users" },
+  { label: "Ещё", icon: "action.more" },
+] as const;
+
+const INVOICES = [
+  "Счёт № 1207 · 84 000 ₽",
+  "Счёт № 1206 · 12 500 ₽",
+  "Счёт № 1205 · 230 000 ₽",
+  "Счёт № 1204 · 47 900 ₽",
+  "Счёт № 1203 · 9 800 ₽",
+  "Счёт № 1202 · 156 000 ₽",
+  "Счёт № 1201 · 31 200 ₽",
+  "Счёт № 1200 · 64 700 ₽",
+];
+
+export default function AppShellFooterExample() {
+  return (
+    <div className={styles.phone}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppHeader.Root>
+          <AppHeader.Start>
+            <AppHeader.Title>Счета</AppHeader.Title>
+          </AppHeader.Start>
+        </AppHeader.Root>
+        <AppShell.Main>
+          <PageContent.Section>
+            <PageContent.Body>
+              {INVOICES.map((invoice) => (
+                <Typography key={invoice} variant="body-m">
+                  {invoice}
+                </Typography>
+              ))}
+            </PageContent.Body>
+          </PageContent.Section>
+        </AppShell.Main>
+        <AppShell.Footer>
+          <BottomNav.Root>
+            {SECTIONS.map((item, index) => (
+              <BottomNav.Item key={item.label} current={index === 1}>
+                <BottomNav.ItemIcon>
+                  <Icon name={item.icon} />
+                </BottomNav.ItemIcon>
+                {item.label}
+              </BottomNav.Item>
+            ))}
+          </BottomNav.Root>
+        </AppShell.Footer>
+      </AppShell.Root>
+    </div>
+  );
+}

package/dist/skill/reference/layout/app-shell/examples/overview.tsx

@@ -0,0 +1,83 @@
+/** The app frame: Sidebar in the nav column, breadcrumbs in the AppHeader, the page in main; only main scrolls — `fillViewport`. */
+import {
+  AppHeader,
+  AppShell,
+  Breadcrumb,
+  Button,
+  Icon,
+  PageContent,
+  Sidebar,
+  Typography,
+} from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function AppShellOverviewExample() {
+  return (
+    <div className={styles.stage}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppShell.Nav>
+          {/* A small app window: the icon rail fits every frame width; the toggle widens it. */}
+          <Sidebar.Root offCanvas="never" defaultMode="compact">
+            <Sidebar.Header>
+              <Sidebar.Brand href="#home" description="Отдел продаж">
+                <Sidebar.BrandLogo>
+                  <span className={styles.logo}>
+                    <Icon name="nav.layoutGrid" />
+                  </span>
+                </Sidebar.BrandLogo>
+                Acme CRM
+              </Sidebar.Brand>
+              <Sidebar.Toggle variant="header" />
+            </Sidebar.Header>
+            <Sidebar.Content>
+              <Sidebar.Item current>
+                <Sidebar.ItemIcon>
+                  <Icon name="nav.home" />
+                </Sidebar.ItemIcon>
+                Обзор
+              </Sidebar.Item>
+              <Sidebar.Item>
+                <Sidebar.ItemIcon>
+                  <Icon name="nav.layoutGrid" />
+                </Sidebar.ItemIcon>
+                Отчёты
+              </Sidebar.Item>
+            </Sidebar.Content>
+          </Sidebar.Root>
+        </AppShell.Nav>
+        <AppHeader.Root>
+          <AppHeader.Start>
+            <Breadcrumb.Root>
+              <Breadcrumb.Item href="#crm">CRM</Breadcrumb.Item>
+              <Breadcrumb.Item current>Обзор</Breadcrumb.Item>
+            </Breadcrumb.Root>
+          </AppHeader.Start>
+        </AppHeader.Root>
+        <AppShell.Main>
+          <PageContent.Section>
+            <PageContent.Header>
+              {/* In a real app this is PageContent.Title (the page h1). */}
+              <Typography as="h2" variant="heading-m">
+                Обзор
+              </Typography>
+              <PageContent.Actions>
+                <Button.Root>
+                  <Button.Icon>
+                    <Icon name="action.add" />
+                  </Button.Icon>
+                  Новая сделка
+                </Button.Root>
+              </PageContent.Actions>
+            </PageContent.Header>
+            <PageContent.Body>
+              <Typography variant="body-m" tone="secondary">
+                Выручка за месяц — 4,8 млн ₽, 37 сделок в работе.
+              </Typography>
+            </PageContent.Body>
+          </PageContent.Section>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  );
+}

package/dist/skill/reference/layout/app-shell/examples/template.tsx

@@ -0,0 +1,54 @@
+/** Root, nav, header and main in one component; main scrolls back to the top whenever the page changes — `AppShell.Template` with `scrollResetKey`. */
+import { AppShell, Icon, PageContent, Sidebar, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PAGES = [
+  { id: "mailings", label: "Рассылки", icon: "field.email", text: "3 активные кампании." },
+  { id: "calendar", label: "Календарь", icon: "field.calendar", text: "5 событий на неделе." },
+] as const;
+
+export default function AppShellTemplateExample() {
+  // In a router app pass the pathname: `scrollResetKey={useLocation().pathname}`.
+  const [pageId, setPageId] = React.useState<(typeof PAGES)[number]["id"]>("mailings");
+  const page = PAGES.find((item) => item.id === pageId) ?? PAGES[0];
+
+  return (
+    <div className={styles.stage}>
+      <AppShell.Template
+        fillViewport
+        className={styles.shell}
+        scrollResetKey={pageId}
+        nav={
+          <Sidebar.Root offCanvas="never">
+            <Sidebar.Content>
+              {PAGES.map((item) => (
+                <Sidebar.Item
+                  key={item.id}
+                  current={item.id === pageId}
+                  onClick={() => setPageId(item.id)}
+                >
+                  <Sidebar.ItemIcon>
+                    <Icon name={item.icon} />
+                  </Sidebar.ItemIcon>
+                  {item.label}
+                </Sidebar.Item>
+              ))}
+            </Sidebar.Content>
+          </Sidebar.Root>
+        }
+      >
+        <PageContent.Section>
+          <PageContent.Header>
+            {/* In a real app this is PageContent.Title (the page h1). */}
+            <Typography as="h2" variant="heading-m">
+              {page.label}
+            </Typography>
+            <PageContent.Description>{page.text}</PageContent.Description>
+          </PageContent.Header>
+        </PageContent.Section>
+      </AppShell.Template>
+    </div>
+  );
+}

package/dist/skill/reference/layout/bottom-nav/COMPONENT.md

@@ -0,0 +1,169 @@
+# BottomNav
+
+**Category:** navigation
+**Kind:** layout
+
+> Phone navigation: a bar of 2–6 main sections at the bottom of the screen, optionally with a round action beside it.
+
+## When to use
+- The main sections of an app on a phone, one tap away (Главная, Заказы, Клиенты, Ещё).
+- Next to Sidebar in one app: Sidebar navigates on a wide screen, BottomNav on a phone (inside `AppShell.Footer` it leaves by itself while the Sidebar rail is on screen).
+
+## When not to use
+- More than six destinations or nested sections → use [Sidebar](../sidebar/COMPONENT.md) (off-canvas on a phone), put the rest under «Ещё».
+- Switching views inside one page → use [Tabs](../../components/tabs/COMPONENT.md) or [SegmentedControl](../../components/segmented-control/COMPONENT.md).
+- Several actions (create, filter, export) → use [Button](../../components/button/COMPONENT.md) in the page header; the bar holds at most one main action (`BottomNav.Action`).
+
+## Import
+```tsx
+import { BottomNav } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+BottomNav.Root                 <nav>, safe-area inset below
+├─ BottomNav.Item              <button>, <a href> or the asChild element, in the bar
+│  ├─ BottomNav.ItemIcon       the glyph above the label (aria-hidden)
+│  ├─ BottomNav.ItemCount      Badge on the icon corner
+│  └─ label                    one short word
+└─ BottomNav.Action            Button shape="circle" beside the bar (aria-label)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### BottomNav.Root
+`ref` → `HTMLElement`. The `<nav>`: the bar of items in equal columns and the actions beside it. Inside `AppShell.Footer` it shows only while no Sidebar rail is on screen.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `iconOnly` | `boolean` | `false` | Icons without visible labels; the labels stay in the DOM as visually hidden text and name the items. |
+| `floating` | `boolean` | `false` | A glass capsule floating over the content at the bottom of its positioned container (`AppShell.Footer`), with a selection capsule gliding under the current item; the page scrolls under it. |
+| `labels` | `Partial<BottomNavLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (2–6 `BottomNav.Item`, optional `BottomNav.Action` before or after them), `aria-label` (replaces `labels.nav`), `className` and the other attributes. |
+
+### BottomNav.Item
+`ref` → the rendered element. `<button type="button">`, `<a>` with `href`, or the single child with `asChild`: the icon (20) above a short label (10).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `current` | `boolean` | `false` | Current section: `aria-current="page"`; the icon and the label turn primary (the others are muted); floating, the item is in the accent on the selection capsule (the others in full ink). |
+| `disabled` | `boolean` | `false` | Not interactive: `disabled` / `aria-disabled`, `data-disabled`, out of the Tab order; an `href` link loses its `href`, an `asChild` child keeps its own and only its clicks are blocked. |
+| `href` | `string` | — | Renders an `<a>` (with `target`, `rel`). |
+| `asChild` | `boolean` | `false` | Renders the single child (e.g. a router `NavLink`) as the item; its children are the label and parts. |
+| `children` | `ReactNode` | — | `BottomNav.ItemIcon`, an optional `BottomNav.ItemCount` and a short label (one word). |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `aria-*`, `className` and the other attributes. |
+
+### BottomNav.ItemIcon
+`ref` → `HTMLSpanElement`. The item glyph (`aria-hidden`, 20) above the label.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="nav.home" />`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### BottomNav.ItemCount
+`ref` → `HTMLSpanElement` (the Badge). An `xs` Badge on the icon's top-end corner; read after the label («Заказы 12»).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The number (or a short status such as «99+»). |
+| `color` | `PaletteColor` | `"red"` | Badge hue: a count on a section asks for attention. |
+| `variant` | `"solid" \| "soft" \| "outline"` | `"solid"` | Badge treatment. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "color">` | — | `className` and the other span attributes. |
+
+### BottomNav.Action
+`ref` → `HTMLButtonElement`. A Button `shape="circle"` (`l`, neutral solid) beside the bar for the screen's main action. Placed before the first item it stands at the start, otherwise at the end.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `aria-label` | `string` | — (required) | The name of the action: the button has no visible text. |
+| `children` | `ReactNode` | — (required) | The glyph, e.g. `<Icon name="action.add" />`. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children">` | — | `onClick`, `disabled`, `className` and the other button attributes. |
+
+## Variants
+
+Two item states only — current and not; no hover fill. Flat: current in the primary color, the others muted. Floating (as iOS): current in the accent on the selection capsule, the others in full ink.
+
+### Flags (Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `floating` | a glass capsule over the content across the width: translucent fill, backdrop blur, glass rim, a selection capsule under the current item; an action becomes a glass disk beside it | the app's look wants depth over the page, the iOS tab-bar feel | `false` |
+| `iconOnly` | icons alone; labels visually hidden, still the items' names | sections with unmistakable icons | `false` |
+
+Without flags the bar is flat at the screen edge on the surface, with a faint top divider.
+
+### Flags (Item)
+| Flag | Part | Effect |
+|---|---|---|
+| `current` | Item | `aria-current="page"`, icon and label in the primary color (floating: the accent, on the selection capsule) |
+| `disabled` | Item | not interactive, disabled text color |
+| `asChild` | Item | the child element (router link) is the item |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| current | `current` or a router link setting `aria-current` | `aria-current="page"` on the item |
+| focus | keyboard | focus ring inside the item edge |
+| disabled | `disabled` | `disabled` / `aria-disabled`, `data-disabled` |
+| hidden | inside `AppShell.Footer` while the Sidebar rail is on screen (`AppShell.Nav` without an off-canvas Sidebar) | `display: none` on the footer |
+| floating / icon only | `floating` / `iconOnly` | `data-floating="true"` / `data-icon-only="true"` on the `<nav>` |
+| selection | floating, an item with `aria-current` | the selection capsule `data-visible="true"`, `data-animate="true"` while it glides |
+| less transparency | `prefers-reduced-transparency: reduce` | a floating capsule and action turn opaque (`--prime-color-layer-floating-bg`), no blur |
+
+Motion: the color of the icon and the label changes over `fast`. Floating, the selection capsule glides to the item that becomes current (`left` / `width` over `base`, emphasized easing — it follows `aria-current`, so a router link moves it too), snaps on a layout change (resize, fonts, new items) and fades when nothing is current; a pressed item's glyph and the action give under the finger (press scale). All instant under reduced motion.
+
+## Layout & spacing
+- Bar `--prime-bottom-nav-height` (52) plus `env(safe-area-inset-bottom)`; side padding `--prime-bottom-nav-padding-x`. With `iconOnly` the bar is `--prime-bottom-nav-icon-only-height` (48).
+- Items share the width equally; the icon (`--prime-bottom-nav-icon-size`, 20 — a light glyph, so the bar stays quiet next to the page) sits in a `--prime-bottom-nav-glyph-width` × `--prime-bottom-nav-glyph-height` box (28 × 20) that anchors the count; the label is `--prime-bottom-nav-label-size` (10, medium, line 12 — the iOS tab-bar size) 4 below it and truncates.
+- Floating (the iOS 26 tab bar at three quarters its size): a full-radius capsule `--prime-bottom-nav-floating-height` (46; `--prime-bottom-nav-floating-icon-only-height`, 40, with `iconOnly`), items inset `--prime-bottom-nav-floating-padding` (4) with a `--prime-bottom-nav-floating-icon-size` (18) icon over a `--prime-bottom-nav-floating-label-size` (9, semibold) label, `--prime-bottom-nav-floating-item-gap` (2) apart. The capsule spans the width left beside its actions and the items share it equally. `--prime-bottom-nav-floating-inset` (12) from the sides and above `env(safe-area-inset-bottom)`. Glass: a dense `--prime-color-bg-glass` tint over a strong `blur(--prime-bottom-nav-blur)` (14) with `saturate(180%)`, so the page shows as soft shapes; the rim is a 1px ring of `--prime-color-bg-glass-edge` that catches at the top-start and bottom-end corners and fades along the sides (a masked gradient), with the overlay shadow. The selection capsule is ink at 12%, no rim. A `BottomNav.Action` is a glass disk as tall as the capsule with an 18 glyph, `--prime-bottom-nav-floating-gap` (8) beside it. The floating bar positions itself at the bottom of its positioned container; `AppShell.Footer` then takes no height, the page scrolls under the capsule and main gets extra bottom padding so the last line clears it.
+- Flat: a `BottomNav.Action` is a muted disk (Button `shape="circle"`, neutral solid) of the `l` control height at the bar's edge.
+- Surface fill with a faint top divider; inside `AppShell.Footer` the bar sticks to the bottom of the panel.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` · `Shift+Tab` | Moves focus through the sections and the action; a disabled one is skipped. |
+| `Enter` | Opens the section (a link or a button) or runs the action. |
+
+### ARIA
+- A `<nav>` landmark named by `labels.nav` («Основные разделы») or its own `aria-label`.
+- The current section has `aria-current="page"`; visually it is the primary-color item among muted ones (a contrast step, not a hue); floating, it also sits on the selection capsule, so the accent is never the only cue.
+- The icon is hidden from assistive tech; the item is named by its label, the count is read after it («Заказы 12»).
+- `BottomNav.Action` is a button without text, named by its required `aria-label`; it sits inside the landmark, before or after the items (where it is placed).
+- A disabled item is a `disabled` button, an `aria-disabled` link without `href`, or an `aria-disabled` `asChild` child out of the Tab order (`tabIndex={-1}`).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `nav` | `"Основные разделы"` | `aria-label` of the `<nav>` landmark. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Four sections of the app, the current one in the primary color and a tap moves it — `current`, `BottomNav.ItemIcon`. |
+| [structure.tsx](examples/structure.tsx) | Counts on the icons and a section that is not available yet — `BottomNav.ItemCount`, `disabled`. |
+| [icon-only.tsx](examples/icon-only.tsx) | Icons alone: the labels are hidden but still name the sections for screen readers — `iconOnly`. |
+| [floating.tsx](examples/floating.tsx) | A glass capsule over the page across the width: the client list scrolls under its blur, the selection glides to a tapped section, with labels or icons alone — `floating`, `iconOnly`. |
+| [floating-action.tsx](examples/floating-action.tsx) | A round action beside the glass capsule for the screen's main action, with labels or icons alone — `BottomNav.Action`, `floating`. |
+| [router.tsx](examples/router.tsx) | A router link as the item: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. |
+| [in-app-shell.tsx](examples/in-app-shell.tsx) | The app frame on a phone: the AppHeader, the page and the bar in the footer, which gives way to the Sidebar rail once one is on screen — `AppShell.Footer`. |
+
+## Mistakes
+- Seven or more items → keep 2–6; the rest goes to a «Ещё» section or Sidebar.
+- Long labels («Управление заказами») → one word; the label truncates.
+- `iconOnly` with icons that need a caption to be understood → keep the labels.
+- A floating bar outside a positioned container → it sits at the bottom of the nearest positioned ancestor; put it in `AppShell.Footer`.
+- An action as an item («Создать» among the sections) → items navigate; put the screen's one main action in `BottomNav.Action` beside the bar, the rest in the page header.
+- `BottomNav.Action` without `aria-label` → the button has no name; it is required.
+- The bar outside `AppShell.Footer` (in Main, Root or `position: fixed` on the page) → it never leaves and shows next to the Sidebar on a desktop; put it in `AppShell.Footer` (or the Template `footer` prop).
+- Hiding the bar with your own media query → the shell already hides the footer while the Sidebar rail is on screen.
+
+## Related
+- **Built from:** [Badge](../../components/badge/COMPONENT.md), VisuallyHidden (internal), [Button](../../components/button/COMPONENT.md) (`shape="circle"`, the action disk)
+- **See also:** [AppShell](../app-shell/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [Tabs](../../components/tabs/COMPONENT.md)

package/dist/skill/reference/layout/bottom-nav/examples/examples.module.css

@@ -0,0 +1,46 @@
+/* Layout of the BottomNav scenarios: a phone-wide screen frame. Semantic tokens only. */
+
+/* A phone screen: the content above, the bar pinned to the bottom edge. */
+.phone {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  width: min(100%, var(--prime-drawer-width-s));
+  height: calc(var(--prime-space-24) * 5);
+  margin-inline: auto;
+  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 page above the bar. */
+.screen {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  min-height: 0;
+  padding: var(--prime-space-6) var(--prime-layout-gutter-s);
+}
+
+/* in-app-shell.tsx: the shell fills the phone frame instead of the viewport. */
+.shell {
+  height: 100%;
+}
+
+/* floating*.tsx: a client row — avatar and two lines of text. */
+.client {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-3);
+}
+
+/* floating*.tsx: the look switch above the list. */
+.options {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2) var(--prime-space-6);
+}