prime-ui-kit 0.7.11 → 0.9.0

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

@@ -0,0 +1,34 @@
+/** Every `tone` on the same `body-m` line: default, secondary, muted and the semantic accent / success / warning / danger text colors. Use to pick a text color by meaning. */
+import { Divider, type TextTone, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TONES: { tone: TextTone; use: string }[] = [
+  { tone: "default", use: "основной текст" },
+  { tone: "secondary", use: "пояснения, вторичный текст" },
+  { tone: "muted", use: "мета, подписи" },
+  { tone: "accent", use: "выделенное значение" },
+  { tone: "success", use: "успешный результат" },
+  { tone: "warning", use: "предупреждение" },
+  { tone: "danger", use: "ошибка, опасное действие" },
+];
+
+export default function TypographyTonesExample() {
+  return (
+    <div className={styles.scaleList}>
+      {TONES.map(({ tone, use }) => (
+        <div key={tone} className={styles.scaleRow}>
+          <Typography.Root variant="body-m" tone={tone}>
+            Оплата по счёту № 4821 получена 12 марта.
+          </Typography.Root>
+          <Divider.Root align="start">
+            <Typography.Root as="span" variant="code" tone="muted">
+              tone="{tone}"
+            </Typography.Root>{" "}
+            — {use}
+          </Divider.Root>
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,19 @@
+/** `truncate` clamps a block to one line with an ellipsis; `title` keeps the full text available. Use for names and titles in fixed-width cells, cards and list rows. */
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const name = "Эргономичное кресло с подголовником и поддержкой поясницы";
+
+export default function TypographyTruncateExample() {
+  return (
+    <div className={styles.truncateBox}>
+      <Typography.Root variant="title-s" truncate title={name}>
+        {name}
+      </Typography.Root>
+      <Typography.Root variant="body-s" tone="muted">
+        Артикул 48 213
+      </Typography.Root>
+    </div>
+  );
+}

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

@@ -1,107 +1,41 @@
-import { Divider, Typography } from "prime-ui-kit";
+/** Every text role from `display-l` to `caption` and `code`, each labelled with its size, weight and purpose. Use to pick the role for a piece of text. */
+import { Divider, Typography, type TypographyRole } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/** Каталог всех ролей `variant` из `typography.role` — зеркало `playground/snippets/typography/variant-catalog.tsx`. */
-export default function TypographyExampleVariantCatalog() {
+const ROLES: { variant: TypographyRole; spec: string; use: string }[] = [
+  { variant: "display-l", spec: "60/68 · 600", use: "герой экрана" },
+  { variant: "display-m", spec: "48/56 · 600", use: "крупная метрика" },
+  { variant: "display-s", spec: "36/44 · 600", use: "метрика, промо" },
+  { variant: "heading-l", spec: "30/36 · 600", use: "крупный заголовок страницы" },
+  { variant: "heading-m", spec: "24/32 · 600", use: "заголовок страницы" },
+  { variant: "heading-s", spec: "20/28 · 600", use: "подзаголовок страницы" },
+  { variant: "title-l", spec: "18/24 · 600", use: "крупный заголовок блока" },
+  { variant: "title-m", spec: "16/24 · 600", use: "заголовок модалки, секции" },
+  { variant: "title-s", spec: "14/20 · 600", use: "заголовок карточки, группы" },
+  { variant: "body-l", spec: "16/24 · 400", use: "текст для чтения" },
+  { variant: "body-m", spec: "14/20 · 400", use: "основной текст интерфейса" },
+  { variant: "body-s", spec: "13/20 · 400", use: "вторичный текст, плотный UI" },
+  { variant: "caption", spec: "12/16 · 400", use: "подсказки, мета, шапка таблицы" },
+  { variant: "code", spec: "13/20 · mono", use: "код, идентификаторы" },
+];
+
+export default function TypographyVariantCatalogExample() {
   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 className={styles.scaleList}>
+      {ROLES.map(({ variant, spec, use }) => (
+        <div key={variant} className={styles.scaleRow}>
+          <Typography.Root variant={variant}>
+            Съешь же ещё этих мягких французских булок да выпей чаю
+          </Typography.Root>
+          <Divider.Root align="start">
+            <Typography.Root as="span" variant="code" tone="muted">
+              {variant}
+            </Typography.Root>{" "}
+            · {spec} — {use}
+          </Divider.Root>
+        </div>
+      ))}
     </div>
   );
 }

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

@@ -1,60 +1,48 @@
+/** One `variant="body-m"` line with each `weight`, the extreme `tracking` values and `tone="secondary"`. Use to see how the override props change a role. */
 import { Divider, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const line = "Один размер `m`, разные оси оформления: `weight`, `tracking` и `tone`.";
+const line = "Съешь же ещё этих мягких французских булок да выпей чаю";
 
-/** `weight`, крайние `tracking` и `tone` на `variant="body-default"`. Зеркало `playground/snippets/typography/variants.tsx`. */
-export default function TypographyExampleVariants() {
+export default function TypographyVariantsExample() {
   return (
-    <div className={styles.typographyScaleList}>
-      <div className={styles.typographyScaleRow}>
-        <Typography.Root variant="body-default" weight="regular">
-          {line} (regular)
+    <div className={styles.scaleList}>
+      <div className={styles.scaleRow}>
+        <Typography.Root variant="body-m" weight="regular">
+          {line}
         </Typography.Root>
-        <Divider.Root variant="text" align="start">
-          weight regular
-        </Divider.Root>
+        <Divider.Root align="start">weight regular</Divider.Root>
       </div>
-      <div className={styles.typographyScaleRow}>
-        <Typography.Root variant="body-default" weight="medium">
-          {line} (medium)
+      <div className={styles.scaleRow}>
+        <Typography.Root variant="body-m" weight="medium">
+          {line}
         </Typography.Root>
-        <Divider.Root variant="text" align="start">
-          weight medium
-        </Divider.Root>
+        <Divider.Root align="start">weight medium</Divider.Root>
       </div>
-      <div className={styles.typographyScaleRow}>
-        <Typography.Root variant="body-default" weight="semibold">
-          {line} (semibold)
+      <div className={styles.scaleRow}>
+        <Typography.Root variant="body-m" weight="semibold">
+          {line}
         </Typography.Root>
-        <Divider.Root variant="text" align="start">
-          weight semibold
-        </Divider.Root>
+        <Divider.Root align="start">weight semibold</Divider.Root>
       </div>
-      <div className={styles.typographyScaleRow}>
-        <Typography.Root variant="body-default" tracking="tighter">
-          {line} (tracking tighter)
+      <div className={styles.scaleRow}>
+        <Typography.Root variant="body-m" tracking="tighter">
+          {line}
         </Typography.Root>
-        <Divider.Root variant="text" align="start">
-          tracking tighter
-        </Divider.Root>
+        <Divider.Root align="start">tracking tighter</Divider.Root>
       </div>
-      <div className={styles.typographyScaleRow}>
-        <Typography.Root variant="body-default" tracking="wide">
-          {line} (tracking wide)
+      <div className={styles.scaleRow}>
+        <Typography.Root variant="body-m" tracking="wide">
+          {line}
         </Typography.Root>
-        <Divider.Root variant="text" align="start">
-          tracking wide
-        </Divider.Root>
+        <Divider.Root align="start">tracking wide</Divider.Root>
       </div>
-      <div className={styles.typographyScaleRow}>
-        <Typography.Root variant="body-default" tone="muted">
-          {line} (tone muted)
+      <div className={styles.scaleRow}>
+        <Typography.Root variant="body-m" tone="secondary">
+          {line}
         </Typography.Root>
-        <Divider.Root variant="text" align="start">
-          tone muted — вторичный цвет текста
-        </Divider.Root>
+        <Divider.Root align="start">tone secondary — вторичный цвет текста</Divider.Root>
       </div>
     </div>
   );

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

@@ -1,140 +1,150 @@
 # AppShell
 
-## About
+**Category:** layout
 
-Каркас приложения: **сетка** `nav` + **`main`** (прокручиваемая колонка). Поля контентной колонки (**`--prime-sys-spacing-x6`** по вертикали и горизонтали) **встроены в `AppShell.Main`** — отдельной обёртки нет.
+> The app frame: a navigation rail on the canvas and a content panel on the surface.
 
-**`AppShell.Template`** — рекомендуемая сборка: **`Root`** + **`Nav`** + **`Main`**, дети шаблона рендерятся **прямо внутри** `<main>`, плюс при монтировании **внутри React Router** сбрасывается прокрутка **`main`** при смене пути.
+## When to use
+- The root layout of an application: navigation column, optional sticky header, scrolling main column.
+- Any page that needs the kit's responsive gutters and the surface context for cards and fields.
 
-**Не** дублируйте те же поля вокруг страницы: внутри **`main`** используйте **`PageContent.Section`** или **`PageContent.Root`** (у **`PageContent`** краевых полей к колонке нет — их даёт **`Main`**).
+## When not to use
+- The navigation itself → use [Sidebar](../sidebar/COMPONENT.md) inside `AppShell.Nav`.
+- 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).
 
----
-
-## Схема слоёв и отступов
-
-Внешние поля у контента в правой колонке задаёт **сам** элемент **`AppShell.Main`** (класс **`layoutMain`** в сборке; в DOM — **`data-app-shell-main-padded`** для проверки в DevTools).
-
-### Дерево регионов
+## Import
+```tsx
+import { AppShell } from "prime-ui-kit";
+```
 
+## Anatomy
 ```
-┌─ 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.*
+AppShell.Root                grid: nav column | content panel (bg-surface)
+├── AppShell.Nav             navigation column on the canvas (usually Sidebar.Root)
+├── AppShell.Header          sticky top bar of the panel
+└── AppShell.Main            <main>, scrolls, carries the gutters
+AppShell.Template            Root + Nav + Header + Main in one component
 ```
+Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 
-### Зазор между колонками
+## API
 
-На **`min-width: 48rem`**, если **`data-layout-template="app"`** и сайдбар **`expanded`** или **`compact`**, между **`Nav`** и **`Main`** — **`column-gap: var(--prime-sys-spacing-x3)`** (разделитель колонок, не замена полей внутри `main`).
+### AppShell.Root
+`forwardRef` to `<div>`.
 
-### Сводка по токенам
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `fillViewport` | `boolean` | `false` | Shell is exactly the viewport height and only `AppShell.Main` scrolls; otherwise the document scrolls and the nav is sticky. |
+| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | `AppShell.Nav`, `AppShell.Header`, `AppShell.Main`. |
 
-| Участок | Токен / правило |
-|--------|------------------|
-| Поля контента внутри `main` | `--prime-sys-spacing-x6` (block + inline) |
-| Зазор nav ↔ main (широкий экран + открытый sidebar) | `--prime-sys-spacing-x3` |
-| Корень сетки, слот `nav` | `padding: 0` у оболочек; поля `main` — см. выше |
++ native `<div>` props.
 
-### Диаграмма (Mermaid)
+### AppShell.Nav
+No ref. A `<div>` grid slot (not a landmark; Sidebar renders the `<nav>`). + native `<div>` props.
 
-```mermaid
-flowchart TB
-  subgraph Root["AppShell.Root"]
-    Nav["AppShell.Nav"]
-    Main["AppShell.Main\nx6 padding + scroll"]
-  end
-  Nav --- Main
-  Main --> Page["Страница / Outlet / PageContent"]
-```
+### AppShell.Header
+`forwardRef` to `<header>`. A flex row (gap 12) for breadcrumbs, search and actions. + native `HTMLAttributes<HTMLElement>`.
 
----
+### AppShell.Main
+`forwardRef` to `<main>` (a vertical ScrollContainer with `overscroll-behavior: contain`).
 
-## Composition
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `contentWidth` | `"contained" \| "full"` | `"full"` | `full`: whole panel with gutters; `contained`: centred column up to `--prime-layout-content-max-width`. |
+| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | Page content. |
 
-- **`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).
++ native `HTMLAttributes<HTMLElement>`.
 
-### Пример (сайдбар + маршруты)
+### AppShell.Template
+`forwardRef` to the `<main>` element. Renders Root, Nav (when `nav` is set), Header (when `header` is set) and Main. Inside a react-router tree it scrolls main to the top on every route change.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `nav` | `ReactNode` | — | Navigation column content; without it the panel takes the full width. |
+| `header` | `ReactNode` | — | Header content; no header row when omitted. |
+| `mainProps` | `Omit<AppShellMainProps, "children">` | — | Props for Main (e.g. `contentWidth`). |
+| `fillViewport` | `boolean` | `false` | Passed to Root. |
+| `children` | `ReactNode` | — | Page content inside Main. |
+
++ other Root props (native `<div>` props on Root).
+
+## 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: canvas rail + surface panel | Apps with navigation | |
+| without Nav | Panel takes the full width | Single-page tools, auth screens | |
+| with `AppShell.Header` | Sticky bar at the top of the panel | Breadcrumbs, page actions, mobile menu button | |
+
+**Combinations** — `AppShell.Template` with `nav={<Sidebar.Root …/>}` and `PageContent` inside is the standard app. `contentWidth="contained"` + `PageContent.Root maxWidth="readable"` for docs/articles.
+
+## States
+Static layout. DOM: `data-fill-viewport="true"` on Root (only when set), `data-content-width` on Main.
+
+## Layout & spacing
+- Two full-height planes edge to edge: no inset, radius, shadow or border — the boundary is the fill change (canvas → surface).
+- Gutters in Main and Header: `--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`.
+- Header: min height = control m + 2 × `--prime-space-3`, padding-block `--prime-space-3`, `z-index: --prime-z-sticky`.
+- The panel is a surface context: fields use the surface field fill, Cards inside become sunken tiles without shadow.
+
+## Accessibility
+- Main is the `<main>` landmark and Header is `<header>`; the navigation landmark comes from Sidebar (`<nav>`).
+- Give the page one `<h1>` (PageContent.Title).
+- No keyboard behaviour, no `labels`.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [with-sidebar.tsx](examples/with-sidebar.tsx) | Sidebar in Nav, breadcrumbs in Header, page with action and metric card in Main, `fillViewport` | Root layout of an app |
+| [contained.tsx](examples/contained.tsx) | No Nav, `Main contentWidth="contained"` with a readable page | Docs, articles, long-read pages |
 
 ```tsx
-import { AppShell, Sidebar } from "prime-ui-kit";
-import { Outlet } from "react-router-dom";
+import { AppShell, PageContent, Sidebar } from "prime-ui-kit";
 
-export function AppLayout() {
+export function Example() {
   return (
-    <AppShell.Template fillViewport nav={<Sidebar.Root /* … */>{/* … */}</Sidebar.Root>}>
-      <Outlet />
+    <AppShell.Template
+      fillViewport
+      nav={
+        <Sidebar.Root>
+          <Sidebar.Content>
+            <Sidebar.Item active>Обзор</Sidebar.Item>
+          </Sidebar.Content>
+        </Sidebar.Root>
+      }
+    >
+      <PageContent.Section>
+        <PageContent.Header>
+          <PageContent.Title>Обзор</PageContent.Title>
+        </PageContent.Header>
+      </PageContent.Section>
     </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`**.
+## 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.
 
 ## Related
-
-- [PageContent](../../components/page-content/COMPONENT.md)
-- [Sidebar](../sidebar/COMPONENT.md)
+[Sidebar](../sidebar/COMPONENT.md) · [PageContent](../../components/page-content/COMPONENT.md) · [ScrollContainer](../../components/scroll-container/COMPONENT.md) · [Breadcrumb](../../components/breadcrumb/COMPONENT.md)

package/src/layout/app-shell/examples/contained.tsx

@@ -0,0 +1,30 @@
+/** A shell without navigation and `AppShell.Main contentWidth="contained"`: the page column is centred and capped at the content max width. Use for docs, articles and other long-read pages. */
+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.Root as="h2" variant="heading-m">
+                Как подключить оплату
+              </Typography.Root>
+              <PageContent.Description>Обновлено 1 октября 2026 года.</PageContent.Description>
+            </PageContent.Header>
+            <PageContent.Body>
+              <Typography.Root as="p" variant="body-l">
+                Откройте раздел «Настройки», выберите «Оплата» и укажите реквизиты. После проверки
+                банк пришлёт подтверждение, и приём платежей включится автоматически.
+              </Typography.Root>
+            </PageContent.Body>
+          </PageContent.Root>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,20 @@
+/* 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-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);
+}
+
+/* The shell fills the window frame instead of the viewport. */
+.shell {
+  height: 100%;
+}