prime-ui-kit 0.7.11 → 0.9.0

package/src/layout/app-shell/examples/with-sidebar.tsx

@@ -0,0 +1,63 @@
+/** Full app frame: Sidebar in AppShell.Nav on the canvas, breadcrumbs in AppShell.Header, a page with an action and a card in AppShell.Main; with `fillViewport` only main scrolls. Use as the root layout of an app. */
+import { FileText, LayoutDashboard, Plus, Settings, Users } from "lucide-react";
+import { AppShell, Breadcrumb, Button, Card, PageContent, Sidebar, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function AppShellWithSidebarExample() {
+  return (
+    <div className={styles.stage}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppShell.Nav>
+          <Sidebar.Root responsive={false}>
+            <Sidebar.Header>
+              <Typography.Root variant="title-s">Acme CRM</Typography.Root>
+            </Sidebar.Header>
+            <Sidebar.Content>
+              <Sidebar.Item icon={<LayoutDashboard />} active>
+                Обзор
+              </Sidebar.Item>
+              <Sidebar.Item icon={<Users />}>Клиенты</Sidebar.Item>
+              <Sidebar.Item icon={<FileText />}>Отчёты</Sidebar.Item>
+            </Sidebar.Content>
+            <Sidebar.Footer>
+              <Sidebar.Item icon={<Settings />}>Настройки</Sidebar.Item>
+              <Sidebar.Toggle />
+            </Sidebar.Footer>
+          </Sidebar.Root>
+        </AppShell.Nav>
+        <AppShell.Header>
+          <Breadcrumb.Root>
+            <Breadcrumb.Item href="#crm">CRM</Breadcrumb.Item>
+            <Breadcrumb.Separator />
+            <Breadcrumb.Item current>Обзор</Breadcrumb.Item>
+          </Breadcrumb.Root>
+        </AppShell.Header>
+        <AppShell.Main>
+          <PageContent.Section>
+            <PageContent.Header>
+              {/* In a real app this is PageContent.Title (the page h1). */}
+              <Typography.Root as="h2" variant="heading-m">
+                Обзор
+              </Typography.Root>
+              <PageContent.Actions>
+                <Button.Root>
+                  <Button.Icon>
+                    <Plus />
+                  </Button.Icon>
+                  Новая сделка
+                </Button.Root>
+              </PageContent.Actions>
+            </PageContent.Header>
+            <PageContent.Body>
+              <Card.Root variant="metric">
+                <Card.Label>Выручка за месяц</Card.Label>
+                <Card.Value>4,8 млн ₽</Card.Value>
+              </Card.Root>
+            </PageContent.Body>
+          </PageContent.Section>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  );
+}

package/src/layout/sidebar/COMPONENT.md

@@ -1,160 +1,204 @@
 # Sidebar
 
-**Default sizing:** use **`size="m"`** for the sidebar scale unless a scenario explicitly needs another value.
+**Category:** layout
 
-## About
+> App side navigation in three modes — expanded, compact, hidden — and an off-canvas panel on narrow screens.
 
-`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
+- The main navigation of an app, inside `AppShell.Nav`.
+- Navigation that users can collapse to an icon rail.
+- Router links (`asChild` + NavLink) with an active page.
 
-**When to use**
+## When not to use
+- A temporary panel with a form or details → use [Drawer](../../components/drawer/COMPONENT.md).
+- In-page section switching → use [Tabs](../../components/tabs/COMPONENT.md).
+- A hierarchy trail → use [Breadcrumb](../../components/breadcrumb/COMPONENT.md).
+- A menu of actions → use [Dropdown](../../components/dropdown/COMPONENT.md).
 
-- 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**.
+## Import
+```tsx
+import { Sidebar, useSidebar } from "prime-ui-kit";
+```
 
-## Composition
+## Anatomy
+```
+Sidebar.Root               rail wrapper; renders <nav> inside
+├── Sidebar.Header         brand row
+├── Sidebar.Content        scrolling middle (soft fades at both ends)
+│   └── Sidebar.Group      role="group" with optional label
+│       └── Sidebar.Item   <button> / <a> / asChild element
+└── Sidebar.Footer         bottom items
+    └── Sidebar.Toggle     item-shaped mode / panel toggle
+useSidebar()               state hook for custom parts inside Root
+```
 
-- **`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 панели навигации.
+## API
 
-### Canonical example
+### Sidebar.Root
+`forwardRef` to the outer `<div>`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Item height, icon, text and badge tier. |
+| `mode` | `"expanded" \| "compact" \| "hidden"` | — | Controlled desktop mode. |
+| `defaultMode` | `"expanded" \| "compact" \| "hidden"` | `"expanded"` | Initial mode, uncontrolled. |
+| `onModeChange` | `(mode: SidebarMode) => void` | — | Called by Toggle and `setMode`. |
+| `open` | `boolean` | — | Controlled off-canvas panel (narrow viewports only). |
+| `defaultOpen` | `boolean` | `false` | Initial off-canvas state. |
+| `onOpenChange` | `(open: boolean) => void` | — | Off-canvas open / close (Toggle, scrim, Escape, navigation, leaving the narrow viewport). |
+| `responsive` | `boolean` | `true` | Below 768px the rail leaves the layout and becomes an off-canvas panel. |
+| `labels` | `Partial<SidebarLabels>` | see Accessibility | Built-in strings. |
+| `children` | `ReactNode` | — | Header, Content, Footer. |
+
++ native `<div>` props.
+
+### Sidebar.Header · Sidebar.Footer
+No ref. + native `<div>` props.
+
+### Sidebar.Content
+`forwardRef` to `<div>`. Scrolls vertically without a visible scrollbar. + native `<div>` props.
+
+### Sidebar.Group
+No ref. `<div role="group">`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Group heading (`aria-labelledby`); fades out in compact mode and keeps its space. |
+
++ native `<div>` props except `role`.
+
+### Sidebar.Item
+`forwardRef` to the rendered element. Renders `<button type="button">`, `<a>` with `href`, or the single child with `asChild`. In compact mode it gets a tooltip on the right with its text.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | — | Leading icon; stays in place in every mode. |
+| `badge` | `ReactNode` | — | Counter / status; a dot on the icon in compact mode. |
+| `shortcut` | `ReactNode` | — | Key hint (e.g. Kbd); hidden in compact mode. |
+| `active` | `boolean` | `false` | Current page: `aria-current="page"`, `data-state="active"`. |
+| `disabled` | `boolean` | `false` | Not interactive: `disabled` / `aria-disabled`, `data-disabled`; a link loses its `href`. |
+| `href` | `string` | — | Render an `<a>`. |
+| `target` · `rel` | `string` | — | Link attributes with `href`. |
+| `asChild` | `boolean` | `false` | Render the single child (e.g. router `NavLink`) as the item; its children become the label. |
+| `children` | `ReactNode` | — | Label (also the compact tooltip text). |
+
++ native `<button>` props.
+
+### Sidebar.Toggle
+`forwardRef` to `<button>`. Desktop: expanded ↔ compact (hidden → expanded); off-canvas: closes the panel. Label, icon, `aria-expanded` and `aria-controls` come from state and `labels`. + native `<button>` props except `children`, `aria-label`, `aria-expanded`, `aria-controls`.
+
+### useSidebar()
+Must be called inside Sidebar.Root. Returns:
+
+| Field | Type | Description |
+|---|---|---|
+| `mode` / `setMode` | `SidebarMode` / `(mode) => void` | Desktop mode. |
+| `open` / `setOpen` | `boolean` / `(open) => void` | Off-canvas panel. |
+| `toggle` | `() => void` | Same action as Sidebar.Toggle. |
+| `isMobile` | `boolean` | The sidebar is off-canvas now (responsive and < 768px). |
+| `size` | `ControlSize` | Tier from Root. |
+| `navId` | `string` | Id of the `<nav>` (for `aria-controls` on your own menu button). |
+| `labels` | `SidebarLabels` | Resolved strings. |
+
+## Variants
+The rail sits on `bg-canvas` without a border or card; items are transparent rows with `text-secondary`, `fill-subtle` on hover; the active item is lifted to `bg-surface` + `shadow-raised` with primary text.
+
+### mode (Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `expanded` | `--prime-layout-sidebar-width` (248) with icons and labels | Default desktop navigation | yes |
+| `compact` | `--prime-layout-sidebar-collapsed-width` (56) icon rail; labels fade, tooltips on the right, badges become dots | Users want more content width | |
+| `hidden` | Width 0, panel clipped out and inert | Focus / full-screen views | |
+
+Only the rail width animates (`--prime-motion-duration-base`): icons never move, labels fade.
+
+### size (Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | item 28, text 12/16, icon 14, badge xs | Very dense tools | |
+| `s` | item 32, text 13/20, icon 16, badge xs | Dense apps | |
+| `m` | item 36, text 14/20, icon 16, badge s | Most apps | yes |
+| `l` | item 40, text 16/24, icon 20, badge m | Touch-friendly | |
+| `xl` | item 48, text 16/24, icon 20, badge m | Large screens | |
+
+The rail width does not depend on `size`.
+
+### responsive (Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `true` | Below 768px: zero-width in layout; opens as a fixed panel over a scrim with `shadow-modal` | Apps used on phones | yes |
+| `false` | Always the desktop rail | Previews, embedded frames | |
+
+### Item flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `active` | Surface fill + raised shadow, primary text and icon | Current page | `false` |
+| `disabled` | `text-disabled`, no hover, `cursor: not-allowed` | Unavailable section | `false` |
+| `badge` | Pill on `fill-muted` at the end; accent dot in compact | Counters | — |
+| `shortcut` | Key hint at the end; hidden in compact | Keyboard power users | — |
+
+**Combinations** — `Sidebar.Toggle` in Footer for collapsible rails; `responsive` + a menu button in `AppShell.Header` with `open` / `onOpenChange` on phones. One `active` item at a time.
+
+## States
+- Root DOM: `data-size`, `data-mode`, `data-panel-mode` (the last visible mode while hidden), `data-mobile` (off-canvas), `data-state="open" | "closed"` (off-canvas only).
+- Item DOM: `data-state="active"`, `aria-current="page"`, `data-disabled`.
+- Mode: `mode` / `defaultMode` / `onModeChange`. Off-canvas: `open` / `defaultOpen` / `onOpenChange`; leaving the narrow viewport closes it; navigating from an `href` / `asChild` item closes it.
+- The `<nav>` is `inert` while hidden (desktop) or closed (off-canvas).
+
+## Layout & spacing
+- Panel padding: `--prime-space-3` block, `--prime-space-2` inline; regions 8 apart; groups 16 apart, items 4 apart.
+- Item horizontal padding is derived from the compact width so icons sit in the same place in every mode.
+- Off-canvas panel width: min(sidebar width, 100% − `--prime-space-12`).
+- Inside `AppShell.Nav` the rail takes the full height.
+
+## Accessibility
+- The panel is a `<nav>` named by `labels.navigation`.
+- Items are native buttons / links; focus ring is drawn inside the row (inset). Compact mode shows the label as a tooltip, so icon-only items keep a visible name on hover and focus.
+- Off-canvas: scrim, focus trap and Escape; the scrim is a button labelled `labels.close`.
+- Toggle: `aria-expanded`, `aria-controls` → nav, label from `labels`.
+- `labels`:
+
+| Key | Default | Used for |
+|---|---|---|
+| `navigation` | `"Навигация"` | `aria-label` of the `<nav>` |
+| `collapse` | `"Свернуть панель"` | Toggle label while expanded |
+| `expand` | `"Развернуть панель"` | Toggle label while compact or hidden |
+| `close` | `"Закрыть навигацию"` | Toggle label off-canvas and the scrim label |
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [modes.tsx](examples/modes.tsx) | Controlled `mode` expanded · compact · hidden | Collapsible navigation |
+| [states.tsx](examples/states.tsx) | Active, badge, shortcut, disabled items in groups | Reference for items |
+| [sizes.tsx](examples/sizes.tsx) | `size` xs → xl | Matching the app density |
+| [router.tsx](examples/router.tsx) | `asChild` + `NavLink` with router active state | react-router apps |
+| [responsive.tsx](examples/responsive.tsx) | Off-canvas panel below 768px driven by a menu button | Phones |
+
+The full app frame with a Sidebar is in [AppShell with-sidebar.tsx](../app-shell/examples/with-sidebar.tsx).
 
 ```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>
+      <Sidebar.Content>
+        <Sidebar.Item active>Главная</Sidebar.Item>
+        <Sidebar.Item badge={3}>Входящие</Sidebar.Item>
+      </Sidebar.Content>
+      <Sidebar.Footer>
+        <Sidebar.Toggle />
+      </Sidebar.Footer>
     </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` (опционально)
+## Mistakes
+- Items without `icon` in a rail that can go compact → compact shows only icons; give every item an icon.
+- Wrapping a router link in `Sidebar.Item` without `asChild` → nested interactive elements; use `asChild`.
+- Setting `active` and also relying on router `aria-current` → use one source.
+- Placing the Sidebar outside `AppShell.Nav` → it will not take the rail position.
 
-Экспортируется для редкого **`placement="inline"`** или тестов. В типичном приложении кнопка на грани уже в **`NavPanel`** — не дублируйте в разметке.
+## Related
+[AppShell](../app-shell/COMPONENT.md) · [Drawer](../../components/drawer/COMPONENT.md) · [Tooltip](../../components/tooltip/COMPONENT.md) · [Kbd](../../components/kbd/COMPONENT.md)

package/src/layout/sidebar/examples/examples.module.css

@@ -1,67 +1,50 @@
-.demoViewport {
-  box-sizing: border-box;
-  width: 100%;
-  max-width: 100%;
-  height: 22rem;
-  min-height: 0;
-  overflow: hidden;
-}
+/* Layout for the Sidebar examples: small "app windows" (canvas rail + surface content). Semantic tokens only. */
 
-.demoViewportTall {
+.stage {
   box-sizing: border-box;
+  display: flex;
   width: 100%;
-  max-width: 100%;
-  height: 26rem;
-  min-height: 0;
+  height: calc(var(--prime-space-24) * 4);
   overflow: hidden;
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-bg-canvas);
+  /* The rail shares the preview's canvas fill: a hairline keeps the window edge visible. */
+  box-shadow:
+    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
+    var(--prime-shadow-raised);
 }
 
-.appGrid {
-  height: 100%;
-  min-height: 0;
+/* A window that hugs its rail (size comparison). */
+.stageAuto {
+  height: auto;
 }
 
-.mainPlaceholder {
+/* Content plane next to the rail, like AppShell: surface fill, edge to edge. */
+.content {
   box-sizing: border-box;
-  margin: 0;
-  min-height: 0;
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: var(--prime-space-4);
+  background: var(--prime-color-bg-surface);
 }
 
-.row {
-  display: flex;
-  align-items: stretch;
-  gap: 0;
+.sizes {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(calc(var(--prime-space-24) * 2.5), 1fr));
+  gap: var(--prime-space-4);
   width: 100%;
-  max-width: 100%;
-  min-height: 0;
 }
 
-.toolbar {
+.sizeColumn {
   display: flex;
-  flex-wrap: wrap;
-  gap: var(--prime-sys-spacing-s);
-  margin-bottom: var(--prime-sys-spacing-s);
-}
-
-.note {
-  margin: 0 0 var(--prime-sys-spacing-m);
-  color: var(--prime-sys-color-content-secondary);
-}
-
-.code {
-  font-family: ui-monospace, monospace;
-  font-size: 0.9em;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  min-width: 0;
 }
 
-.controlledColumn {
+.column {
   display: flex;
   flex-direction: column;
-  height: 100%;
-  min-height: 0;
-}
-
-.controlledStage {
-  flex: 1;
-  min-height: 0;
-  min-width: 0;
+  gap: var(--prime-space-4);
+  width: 100%;
 }

package/src/layout/sidebar/examples/modes.tsx

@@ -0,0 +1,55 @@
+/** Controlled `mode` switched by a SegmentedControl: expanded, compact and hidden, all animating the rail width. Use when the app lets users collapse the navigation. */
+import { FileText, Home, Inbox, Settings, Users } from "lucide-react";
+import { SegmentedControl, Sidebar, type SidebarMode } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const MODES: { value: SidebarMode; label: string }[] = [
+  { value: "expanded", label: "Развёрнут" },
+  { value: "compact", label: "Компактный" },
+  { value: "hidden", label: "Скрыт" },
+];
+
+export default function SidebarModesExample() {
+  const [mode, setMode] = React.useState<SidebarMode>("expanded");
+
+  return (
+    <div className={styles.column}>
+      <SegmentedControl.Root
+        value={mode}
+        onValueChange={(next) => setMode(next as SidebarMode)}
+        aria-label="Режим сайдбара"
+      >
+        {MODES.map((m) => (
+          <SegmentedControl.Item key={m.value} value={m.value}>
+            {m.label}
+          </SegmentedControl.Item>
+        ))}
+      </SegmentedControl.Root>
+      <div className={styles.stage} data-testid="sidebar-modes-stage">
+        <Sidebar.Root mode={mode} onModeChange={setMode} responsive={false}>
+          <Sidebar.Content>
+            <Sidebar.Group>
+              <Sidebar.Item icon={<Home />} active>
+                Главная
+              </Sidebar.Item>
+              <Sidebar.Item icon={<Inbox />} badge={3}>
+                Входящие
+              </Sidebar.Item>
+            </Sidebar.Group>
+            <Sidebar.Group label="Работа">
+              <Sidebar.Item icon={<Users />}>Клиенты</Sidebar.Item>
+              <Sidebar.Item icon={<FileText />}>Отчёты</Sidebar.Item>
+            </Sidebar.Group>
+          </Sidebar.Content>
+          <Sidebar.Footer>
+            <Sidebar.Item icon={<Settings />}>Настройки</Sidebar.Item>
+            <Sidebar.Toggle />
+          </Sidebar.Footer>
+        </Sidebar.Root>
+        <div className={styles.content} />
+      </div>
+    </div>
+  );
+}

package/src/layout/sidebar/examples/responsive.tsx

@@ -0,0 +1,44 @@
+/** Below 768px (`responsive`, default) the rail becomes an off-canvas panel with a scrim, focus trap and Escape, driven by `open` / `onOpenChange` from a menu button. Narrow the window to try it. */
+import { Home, Inbox, Menu, Settings } from "lucide-react";
+import { Button, Sidebar } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SidebarResponsiveExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div className={styles.stage}>
+      <Sidebar.Root open={open} onOpenChange={setOpen}>
+        <Sidebar.Content>
+          <Sidebar.Item icon={<Home />} href="#home" active>
+            Главная
+          </Sidebar.Item>
+          <Sidebar.Item icon={<Inbox />} href="#inbox" badge={2}>
+            Входящие
+          </Sidebar.Item>
+          <Sidebar.Item icon={<Settings />} href="#settings">
+            Настройки
+          </Sidebar.Item>
+        </Sidebar.Content>
+        <Sidebar.Footer>
+          <Sidebar.Toggle />
+        </Sidebar.Footer>
+      </Sidebar.Root>
+      <div className={styles.content}>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          aria-expanded={open}
+          onClick={() => setOpen(true)}
+        >
+          <Button.Icon>
+            <Menu />
+          </Button.Icon>
+          Меню
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/layout/sidebar/examples/router.tsx

@@ -0,0 +1,27 @@
+/** `asChild` with a router NavLink: the router sets `aria-current="page"` and the item shows as active. Use inside a react-router app; the links must be rendered within a router. */
+import { LayoutTemplate, PanelLeft, PanelTop } from "lucide-react";
+import { Sidebar } from "prime-ui-kit";
+import { NavLink } from "react-router-dom";
+
+import styles from "./examples.module.css";
+
+export default function SidebarRouterExample() {
+  return (
+    <div className={styles.stage}>
+      <Sidebar.Root responsive={false}>
+        <Sidebar.Content>
+          <Sidebar.Item asChild icon={<LayoutTemplate />}>
+            <NavLink to="/app-shell">AppShell</NavLink>
+          </Sidebar.Item>
+          <Sidebar.Item asChild icon={<PanelTop />}>
+            <NavLink to="/page-content">PageContent</NavLink>
+          </Sidebar.Item>
+          <Sidebar.Item asChild icon={<PanelLeft />}>
+            <NavLink to="/sidebar">Sidebar</NavLink>
+          </Sidebar.Item>
+        </Sidebar.Content>
+      </Sidebar.Root>
+      <div className={styles.content} />
+    </div>
+  );
+}