prime-ui-kit 0.0.1

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

@@ -0,0 +1,95 @@
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.stackTight {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+}
+
+.formFields {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-l);
+}
+
+.hero {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-l);
+  max-width: 40rem;
+}
+
+.scaleList {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+}
+
+/* Layout parity with playground/snippets/typography (PlaygroundExampleFrame preview). */
+.typographyScaleList {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x4);
+}
+
+.typographyScaleRow {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x2);
+}
+
+.articleLandmarks {
+  display: grid;
+  gap: var(--prime-sys-spacing-x4);
+  max-width: 40rem;
+  text-align: start;
+}
+
+.articleLandmarks blockquote {
+  margin: 0;
+  padding-inline-start: var(--prime-sys-spacing-x3);
+  border-inline-start: 3px solid var(--prime-sys-color-border-subtle);
+}
+
+.readingAndForm {
+  display: grid;
+  gap: var(--prime-sys-spacing-x3);
+  max-width: 22rem;
+  text-align: start;
+}
+
+.readingAndFormFields {
+  display: grid;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.readingAndFormActions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-x2);
+}
+
+.fullWidthColumns {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-l);
+}
+
+.fullWidthNarrow {
+  flex: 1 1 12.5rem;
+  min-width: 0;
+  max-width: 17.5rem;
+}
+
+.fullWidthWide {
+  flex: 2 1 20rem;
+  min-width: 0;
+}
+
+.inlineLinkInherit {
+  color: inherit;
+}

package/src/components/typography/examples/full-width.tsx

@@ -0,0 +1,32 @@
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Две колонки разной ширины, одинаковые `variant` и `tone`.
+ * Зеркало `playground/snippets/typography/full-width.tsx`.
+ */
+export default function TypographyExampleFullWidth() {
+  return (
+    <div className={styles.fullWidthColumns}>
+      <div className={styles.fullWidthNarrow}>
+        <Typography.Root variant="body-small" tone="muted">
+          Узкая колонка
+        </Typography.Root>
+        <Typography.Root variant="body-default">
+          Длинное предложение в узком контейнере демонстрирует переносы и выравнивание без
+          отдельного пропа ширины.
+        </Typography.Root>
+      </div>
+      <div className={styles.fullWidthWide}>
+        <Typography.Root variant="body-small" tone="muted">
+          Широкая колонка
+        </Typography.Root>
+        <Typography.Root variant="body-default">
+          Тот же размер и стиль в более широком блоке: меньше переносов, читаемость остаётся за счёт
+          связки кегля и межстрочного интервала из токенов для `size="m"`.
+        </Typography.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/typography/examples/reading-and-form.tsx

@@ -0,0 +1,40 @@
+import { Button, Input, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Заголовок и вводный текст — `Typography`; поля и кнопки — `Input` / `Button`.
+ * Зеркало `playground/snippets/typography/reading-and-form.tsx`.
+ */
+export default function TypographyExampleReadingAndForm() {
+  return (
+    <main className={styles.readingAndForm}>
+      <Typography.Root as="h1" variant="heading-page">
+        Заявка на доступ
+      </Typography.Root>
+      <Typography.Root as="p" variant="body-default" tone="muted">
+        Заполните форму: роли текста задаются здесь, оформление полей — компонентами формы.
+      </Typography.Root>
+      <div className={styles.readingAndFormFields}>
+        <Input.Root label="Email">
+          <Input.Wrapper>
+            <Input.Field type="email" placeholder="you@example.com" autoComplete="email" />
+          </Input.Wrapper>
+        </Input.Root>
+        <Input.Root label="Комментарий" hint="Необязательно">
+          <Input.Wrapper>
+            <Input.Field placeholder="Контекст" />
+          </Input.Wrapper>
+        </Input.Root>
+        <div className={styles.readingAndFormActions}>
+          <Button.Root type="button" variant="primary">
+            Отправить
+          </Button.Root>
+          <Button.Root type="button" variant="neutral" mode="stroke">
+            Отмена
+          </Button.Root>
+        </div>
+      </div>
+    </main>
+  );
+}

package/src/components/typography/examples/states.tsx

@@ -0,0 +1,27 @@
+import { Divider, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Курсив `italic` при том же `variant` и `weight`. Зеркало `playground/snippets/typography/states.tsx`. */
+export default function TypographyExampleStates() {
+  return (
+    <div className={styles.typographyScaleList}>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-default" weight="medium">
+          Заголовок карточки без курсива — обычный акцент.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          italic не задан (false)
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-default" weight="medium" italic>
+          Тот же размер и вес с курсивом — цитата или название научной работы.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          italic — курсив через data-атрибут и токены
+        </Divider.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/typography/examples/variant-catalog.tsx

@@ -0,0 +1,107 @@
+import { Divider, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/** Каталог всех ролей `variant` из `typography.role` — зеркало `playground/snippets/typography/variant-catalog.tsx`. */
+export default function TypographyExampleVariantCatalog() {
+  return (
+    <div className={styles.typographyScaleList}>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="display" weight="medium" tracking="tight">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>display</code> · medium · tight — MD3 Display Large, герой экрана
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="headline" weight="medium" tracking="tight">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>headline</code> · medium · tight — MD3 Headline Large, промо/лид
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="heading-page" weight="medium" tracking="tight">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>heading-page</code> · medium · tight — MD3 Headline Medium, заголовок страницы
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="heading-section" weight="medium" tracking="tight">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>heading-section</code> · medium · tight — MD3 Headline Small, секция
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="heading-subsection" weight="medium">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>heading-subsection</code> · medium — MD3 Title Large, подсекция
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="heading-group" weight="medium">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>heading-group</code> · medium — MD3 Title Small, подпись группы
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-large" weight="medium" tracking="tight">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>body-large</code> · medium · tight — MD3 Body Large
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-default">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>body-default</code> · regular — MD3 Body Medium, основной текст
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-small">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>body-small</code> · regular — MD3 Body Small
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-compact" weight="medium" tracking="wide">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>body-compact</code> · medium · wide — MD3 Label Large, плотная строка (14px)
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="caption">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>caption</code> · regular — MD3 Label Medium
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="caption-micro">
+          The quick brown fox jumps over the lazy dog.
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          <code>caption-micro</code> · regular — MD3 Label Small (~11px)
+        </Divider.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/typography/examples/variants.tsx

@@ -0,0 +1,61 @@
+import { Divider, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const line = "Один размер `m`, разные оси оформления: `weight`, `tracking` и `tone`.";
+
+/** `weight`, крайние `tracking` и `tone` на `variant="body-default"`. Зеркало `playground/snippets/typography/variants.tsx`. */
+export default function TypographyExampleVariants() {
+  return (
+    <div className={styles.typographyScaleList}>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-default" weight="regular">
+          {line} (regular)
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          weight regular
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-default" weight="medium">
+          {line} (medium)
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          weight medium
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-default" weight="semibold">
+          {line} (semibold)
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          weight semibold
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-default" tracking="tighter">
+          {line} (tracking tighter)
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          tracking tighter
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-default" tracking="wide">
+          {line} (tracking wide)
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          tracking wide
+        </Divider.Root>
+      </div>
+      <div className={styles.typographyScaleRow}>
+        <Typography.Root variant="body-default" tone="muted">
+          {line} (tone muted)
+        </Typography.Root>
+        <Divider.Root variant="text" align="start">
+          tone muted — вторичный цвет текста
+        </Divider.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,140 @@
+# AppShell
+
+## About
+
+Каркас приложения: **сетка** `nav` + **`main`** (прокручиваемая колонка). Поля контентной колонки (**`--prime-sys-spacing-x6`** по вертикали и горизонтали) **встроены в `AppShell.Main`** — отдельной обёртки нет.
+
+**`AppShell.Template`** — рекомендуемая сборка: **`Root`** + **`Nav`** + **`Main`**, дети шаблона рендерятся **прямо внутри** `<main>`, плюс при монтировании **внутри React Router** сбрасывается прокрутка **`main`** при смене пути.
+
+**Не** дублируйте те же поля вокруг страницы: внутри **`main`** используйте **`PageContent.Section`** или **`PageContent.Root`** (у **`PageContent`** краевых полей к колонке нет — их даёт **`Main`**).
+
+---
+
+## Схема слоёв и отступов
+
+Внешние поля у контента в правой колонке задаёт **сам** элемент **`AppShell.Main`** (класс **`layoutMain`** в сборке; в DOM — **`data-app-shell-main-padded`** для проверки в DevTools).
+
+### Дерево регионов
+
+```
+┌─ AppShell.Root ───────────────────────────────────────────── fillViewport → высота вьюпорта, без padding
+│    data-layout-template="app" (у Template)
+│
+├── AppShell.Nav          data-layout-region="nav"            padding: 0 у оболочки; внутренние отступы — у Sidebar
+│    └── …
+│
+└── AppShell.Main         <main> ScrollContainer, прокрутка по вертикали
+     data-layout-region="main"
+     data-app-shell-main-padded=""
+     padding-block / padding-inline = var(--prime-sys-spacing-x6)   ← канон полей колонки
+     └── маршруты: <Outlet /> / страницы / PageContent.*
+```
+
+### Зазор между колонками
+
+На **`min-width: 48rem`**, если **`data-layout-template="app"`** и сайдбар **`expanded`** или **`compact`**, между **`Nav`** и **`Main`** — **`column-gap: var(--prime-sys-spacing-x3)`** (разделитель колонок, не замена полей внутри `main`).
+
+### Сводка по токенам
+
+| Участок | Токен / правило |
+|--------|------------------|
+| Поля контента внутри `main` | `--prime-sys-spacing-x6` (block + inline) |
+| Зазор nav ↔ main (широкий экран + открытый sidebar) | `--prime-sys-spacing-x3` |
+| Корень сетки, слот `nav` | `padding: 0` у оболочек; поля `main` — см. выше |
+
+### Диаграмма (Mermaid)
+
+```mermaid
+flowchart TB
+  subgraph Root["AppShell.Root"]
+    Nav["AppShell.Nav"]
+    Main["AppShell.Main\nx6 padding + scroll"]
+  end
+  Nav --- Main
+  Main --> Page["Страница / Outlet / PageContent"]
+```
+
+---
+
+## Composition
+
+- **`AppShell.Root`** — корневая сетка; опционально **`fillViewport`**.
+- **`AppShell.Nav`** — слот навигации (**`data-layout-region="nav"`**).
+- **`AppShell.Main`** — **`<main>`** с каноническими полями колонки и прокруткой (**`data-layout-region="main"`**).
+- **`AppShell.Template`** — **`Root`** + **`Nav`** + **`Main`**, дети — **прямые** дочерние узлы **`main`** + сброс прокрутки при смене **`pathname`** (если предок — React Router).
+
+### Пример (сайдбар + маршруты)
+
+```tsx
+import { AppShell, Sidebar } from "prime-ui-kit";
+import { Outlet } from "react-router-dom";
+
+export function AppLayout() {
+  return (
+    <AppShell.Template fillViewport nav={<Sidebar.Root /* … */>{/* … */}</Sidebar.Root>}>
+      <Outlet />
+    </AppShell.Template>
+  );
+}
+```
+
+### Пример (одна колонка, без `nav`)
+
+```tsx
+import { AppShell } from "prime-ui-kit";
+
+export function FullWidthMain() {
+  return (
+    <AppShell.Root fillViewport>
+      <AppShell.Main>{/* страница — поля уже на main */}</AppShell.Main>
+    </AppShell.Root>
+  );
+}
+```
+
+---
+
+## Почему «пропали отступы»
+
+1. **Не подключены стили пакета** — **`prime-ui-kit/styles.css`** и **`prime-ui-kit/bundle.css`** (или эквивалент).
+2. **Маршруты не внутри `AppShell.Template`** — **`Outlet`** должен быть ребёнком **`Template`** (или контент внутри **`AppShell.Main`** при ручной сборке).
+3. **Ожидание полей от `PageContent.Root`** — краевые поля задаёт **`Main`**, не **`PageContent`**.
+4. **Редкий full-bleed в `main`** — при необходимости обнулите поля через **`className`** на **`AppShell.Main`** (осознанно, точечно).
+
+---
+
+## Rules
+
+- **`AppShell.Template`** внутри **`BrowserRouter`** / **`MemoryRouter`** — для сброса прокрутки.
+- **`ref`** на **`Template`** вешается на **`<main>`** (`AppShell.Main`).
+- Не дублируйте обёртки с полями **`x6`** вокруг страницы.
+
+## API
+
+### AppShell.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| fillViewport | `boolean` | `false` | No | Растягивает корень на высоту вьюпорта. |
+| className | `string` | — | No | Класс на корневом `div`. |
+| children | `React.ReactNode` | — | No | Обычно `Nav` + `Main`. |
+| …rest | `HTMLAttributes<HTMLDivElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
+
+### AppShell.Template
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| fillViewport | `boolean` | — | No | Пробрасывается в `Root`. |
+| className | `string` | — | No | Класс на `Root`. |
+| nav | `React.ReactNode` | — | **Yes** | Левая колонка (напр. `Sidebar.Root`). |
+| children | `React.ReactNode` | — | No | Контент внутри `<main>` (прямые дети). |
+| navProps | `Omit<AppShellNavProps, "children">` | — | No | Пропсы на слот навигации. |
+| mainProps | `Omit<AppShellMainProps, "children">` | — | No | Пропсы на `main` (напр. `id`, `tabIndex`). |
+| …rest | `HTMLAttributes<HTMLDivElement>` | — | No | Остальное на `Root`. |
+
+`AppShell.Nav` и `AppShell.Main` — см. исходные типы в **`AppShell.tsx`**.
+
+## Related
+
+- [PageContent](../../components/page-content/COMPONENT.md)
+- [Sidebar](../sidebar/COMPONENT.md)

package/src/layout/sidebar/COMPONENT.md

@@ -0,0 +1,160 @@
+# Sidebar
+
+**Default sizing:** use **`size="m"`** for the sidebar scale unless a scenario explicitly needs another value.
+
+## About
+
+`Sidebar` is a vertical navigation column: **`Sidebar.Root`** owns context and layout (`expanded` | `compact` | `hidden`), **`Sidebar.NavPanel`** is the panel (`nav`) with header / body / footer regions, and **Menu** / **Group** / **NavCategory** build item structure.
+
+**When to use**
+
+- Persistent app navigation beside main content, including **`AppShell.Template`** nav slot with **`sidebarSlot="page-nav"`** (поля контентной колонки на **`AppShell.Main`** — не дублировать).
+- Desktop width toggle (expanded vs icon rail) with optional tooltips in **`compact`**.
+- Mobile drawer behavior when **`responsive={true}`** (default): overlay, backdrop; **edge**-кнопка **`Sidebar.ToggleButton`** на границе панели и смещается вместе с ней (в т.ч. при закрытии drawer).
+
+**When not to use**
+
+- One-off filters or transient panels — prefer **Drawer** or **Modal**.
+- Deep multi-level trees without routing — consider a dedicated tree or doc nav pattern before overloading **NavCategory**.
+
+## Composition
+
+- **`Sidebar.Root`** — required wrapper (`aside`); exposes state, **`useSidebarContext`** values, and responsive / mobile behavior. Режим панели задаётся здесь: **`state`**, **`defaultState`**, **`onStateChange`** (или legacy **`open`** / **`onOpenChange`**).
+- **`Sidebar.NavPanel`** — panel container (`nav`). По умолчанию рендерит **встроенную** кнопку сворачивания на грани панели (**`data-placement="edge"`**); отключить можно только **`showToggle={false}`** (редкие случаи). Не дублируйте переключатель вручную.
+- Типичный порядок: **`Header`** (часто **`IdentityButton`** или **`Text`**) → **`Content`** (часто **`NavPanelBody`** + **`Menu`**) → **`Footer`** (часто **`IdentityButton`**).
+- In **`compact`** on non-mobile viewports, **MenuButton** / **MenuRouterLink** / **MenuLink** can show **tooltips** ( **`Tooltip`**, `side="right"`, `delayDuration={0}` ). On mobile, tooltips are suppressed.
+- Единственная **edge**-кнопка использует **`aria-controls`** с id панели навигации.
+
+### Canonical example
+
+```tsx
+import { FileText, LayoutDashboard } from "lucide-react";
+import { Sidebar } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Sidebar.Root size="m" defaultState="expanded" responsive={false} aria-label="Application">
+      <Sidebar.NavPanel>
+        <Sidebar.Header>
+          <Sidebar.HeaderRow>
+            <Sidebar.HeaderMain>
+              <Sidebar.IdentityButton
+                leading={<span aria-hidden="true">A</span>}
+                title="Acme"
+                subtitle="Workspace"
+              />
+            </Sidebar.HeaderMain>
+          </Sidebar.HeaderRow>
+        </Sidebar.Header>
+        <Sidebar.Content>
+          <Sidebar.Menu>
+            <Sidebar.MenuItem>
+              <Sidebar.MenuButton type="button" active>
+                <Sidebar.MenuIcon>
+                  <LayoutDashboard size={16} strokeWidth={1.9} />
+                </Sidebar.MenuIcon>
+                <Sidebar.MenuLabel>Overview</Sidebar.MenuLabel>
+              </Sidebar.MenuButton>
+            </Sidebar.MenuItem>
+            <Sidebar.MenuItem>
+              <Sidebar.MenuButton type="button">
+                <Sidebar.MenuIcon>
+                  <FileText size={16} strokeWidth={1.9} />
+                </Sidebar.MenuIcon>
+                <Sidebar.MenuLabel>Reports</Sidebar.MenuLabel>
+              </Sidebar.MenuButton>
+            </Sidebar.MenuItem>
+          </Sidebar.Menu>
+        </Sidebar.Content>
+        <Sidebar.Footer>
+          <Sidebar.IdentityButton
+            leading={<span aria-hidden="true">●</span>}
+            title="Account"
+            subtitle="Signed in"
+          />
+        </Sidebar.Footer>
+      </Sidebar.NavPanel>
+    </Sidebar.Root>
+  );
+}
+```
+
+### Extended examples
+
+- [`./examples/01-app-shell-nav.tsx`](./examples/01-app-shell-nav.tsx) — **`AppShell.Template`** with **`sidebarSlot="page-nav"`** and a simple menu.
+- [`./examples/02-collapsible-desktop.tsx`](./examples/02-collapsible-desktop.tsx) — **`responsive={false}`**: edge control cycles **expanded** / **compact** and tooltips on icon rail.
+- [`./examples/03-controlled-state.tsx`](./examples/03-controlled-state.tsx) — controlled **`state`** / **`onStateChange`** with an external control.
+- [`./examples/04-router-navigation.tsx`](./examples/04-router-navigation.tsx) — **`MemoryRouter`** and **`Sidebar.MenuRouterLink`** next to **`Routes`**.
+- [`./examples/05-responsive-behavior.tsx`](./examples/05-responsive-behavior.tsx) — default **`responsive`**: narrow breakpoint note and **`SIDEBAR_MEDIA_QUERY_NARROW`**.
+
+**LLM note:** Prefer the runnable files under **`./examples/*.tsx`** for full composition and imports. **`Sidebar.MenuRouterLink`** uses React Router **`NavLink`**; wrap the app (or story) in **`BrowserRouter`**, **`HashRouter`**, or **`MemoryRouter`** — links throw without a router context. For built-in active styles from the kit, pass **`className` as a function** (e.g. `className={() => ""}`); a plain string **`className`** does not receive **`isActive`**. Additional prop tables and playground demos: `playground/sections/SidebarSection.tsx`, `playground/sections/sidebarApiRows.ts`.
+
+## Visual contract
+
+- **`NavPanel`** is not framed as a floating card: no full-panel border; background follows theme (light: mixed surface/border; dark: surface default). The edge toward main content uses **`border-subtle`** on the inward inline side according to **`side`**.
+- Overlays (**Dropdown**, **Popover**) keep elevated surfaces distinct from the rail.
+
+## State model
+
+- Prefer **`state`**, **`defaultState`**, **`onStateChange`** with **`SidebarLayoutMode`**: **`"hidden"`** | **`"compact"`** | **`"expanded"`**.
+- Legacy **`open`**, **`defaultOpen`**, **`onOpenChange`**, **`mode`**, **`defaultMode`**, **`onModeChange`** remain for compatibility; new code should use the **`state`** model.
+- With **`responsive={true}`**, viewports matching **`SIDEBAR_MEDIA_QUERY_NARROW`** (`max-width: 47.999rem`, i.e. below **`48rem`**) treat the panel as a drawer: **`hidden`** shows overlay affordances; crossing the breakpoint resets open/closed behavior per **`SidebarRoot`** logic.
+- Встроенная кнопка на грани: на мобильном — **hidden** ↔ **expanded**; на десктопе — **expanded** ↔ **compact** (и из **hidden** обратно в **expanded**).
+
+## Data pattern (product menus)
+
+For dynamic menus (modes, roles, brands), keep a data layer above the JSX: e.g. **`navTag`** per mode, **`tags`** on items, optional **`switchByTag`**, and filter at render. That lets you swap categories without restructuring **Sidebar** markup.
+
+## Rules
+
+- Call **`useSidebarContext`** only under **`Sidebar.Root`**.
+- **`sidebarSlot="page-nav"`** aligns the rail with page grid spacing when used inside **`AppShell`**.
+- Export **`SIDEBAR_MEDIA_QUERY_NARROW`**, **`SIDEBAR_MEDIA_QUERY_INLINE`**, **`SIDEBAR_LAYOUT_BREAKPOINT_MAX`**, **`SIDEBAR_MEDIA_QUERY_XS_HIDDEN`** from **`prime-ui-kit`** match **`sidebarLayout.ts`** for JS/CSS alignment.
+
+## API
+
+### `Sidebar.Root`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | Yes | Typically **`NavPanel`** and descendants. |
+| size | `SidebarSize` | `"m"` | No | Scale for controls, type, and rail width. |
+| side | `"left" \| "right"` | `"left"` | No | Physical side; affects toggle icons and borders. |
+| state | `SidebarLayoutMode` | — | No | Controlled layout state. |
+| defaultState | `SidebarLayoutMode` | see below | No | Initial state; with **`responsive`**, narrow viewports start **hidden**. |
+| onStateChange | `(state: SidebarLayoutMode) => void` | — | No | Fires on layout changes. |
+| responsive | `boolean` | `true` | No | When **true**, narrow viewports use drawer + backdrop; the edge toggle stays on the panel edge and moves with the sliding panel. |
+| sidebarSlot | `"page-nav"` | — | No | Page nav embedding; sets **`data-sidebar-slot`**. |
+| aria-label | `string` | `"Sidebar"` | No | Name for the **`aside`** landmark. |
+| open, defaultOpen, onOpenChange | — | — | No | **Deprecated;** maps to hidden vs expanded. |
+| mode, defaultMode, onModeChange | — | — | No | **Deprecated;** use **state** / **onStateChange**. |
+
+Also accepts **`className`** and native **`aside`** attributes via **`…rest`**.
+
+### `Sidebar.NavPanel`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| showToggle | `boolean` | `true` | No | Встроенная кнопка на грани (`placement="edge"`). Переключение состояния — через **`Sidebar.Root`** или **`useSidebarContext`**. |
+
+Также нативные атрибуты **`nav`** и **`children`**.
+
+### `Sidebar.MenuButton` (in addition to native `button` props)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| active | `boolean` | — | No | Selected / current item styling. |
+| asChild | `boolean` | `false` | No | Render via **`Slot`** instead of **`button`**. |
+| tooltip | `React.ReactNode` | — | No | Tooltip in **compact**; fallback from **`aria-label`** or **`children`**; empty string disables. |
+
+### `Sidebar.MenuRouterLink` (extends `NavLink` props)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| tooltip | `React.ReactNode` | — | No | Same behavior as **`MenuButton`**. |
+
+Requires a React Router provider. Use a **function** **`className`** so the implementation can apply **`isActive`**-aware styles.
+
+### `Sidebar.ToggleButton` (опционально)
+
+Экспортируется для редкого **`placement="inline"`** или тестов. В типичном приложении кнопка на грани уже в **`NavPanel`** — не дублируйте в разметке.