prime-ui-kit 0.7.13 → 0.9.1

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

@@ -1,61 +1,50 @@
-import { Divider, Typography } from "prime-ui-kit";
+/** Every text role from display to caption and code, then every text color on body text — `variant`, `tone`. */
+import { Typography, type TypographyRole } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
+const ROLES: TypographyRole[] = [
+  "display-l",
+  "display-m",
+  "display-s",
+  "heading-l",
+  "heading-m",
+  "heading-s",
+  "title-l",
+  "title-m",
+  "title-s",
+  "body-l",
+  "body-m",
+  "body-s",
+  "caption",
+  "code",
+];
 
-const line = "Один размер `m`, разные оси оформления: `weight`, `tracking` и `tone`.";
+const TONES = ["default", "secondary", "muted", "accent", "success", "warning", "danger"] as const;
 
-/** `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)
-        </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>
+    <>
+      {ROLES.map((variant) => (
+        <div key={variant}>
+          <div>
+            <Typography variant={variant}>Выручка за март</Typography>
+            <Typography as="span" variant="caption" tone="muted">
+              {variant}
+            </Typography>
+          </div>
+        </div>
+      ))}
+      {TONES.map((tone) => (
+        <div key={tone}>
+          <div>
+            <Typography variant="body-m" tone={tone}>
+              Оплата по счёту № 4821 получена
+            </Typography>
+            <Typography as="span" variant="caption" tone="muted">
+              body-m · {tone}
+            </Typography>
+          </div>
+        </div>
+      ))}
+    </>
   );
 }

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

@@ -0,0 +1,31 @@
+/** One role with its weight, tracking or italic overridden — `weight`, `tracking`, `italic`. */
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const LINE = "Отчёт по выручке за первый квартал";
+
+export default function TypographyWeightsExample() {
+  return (
+    <div className={styles.stack}>
+      <Typography variant="body-m" weight="regular">
+        {LINE} · regular
+      </Typography>
+      <Typography variant="body-m" weight="medium">
+        {LINE} · medium
+      </Typography>
+      <Typography variant="body-m" weight="semibold">
+        {LINE} · semibold
+      </Typography>
+      <Typography variant="body-m" tracking="tighter">
+        {LINE} · tracking tighter
+      </Typography>
+      <Typography variant="body-m" tracking="wide">
+        {LINE} · tracking wide
+      </Typography>
+      <Typography variant="body-m" italic>
+        {LINE} · italic
+      </Typography>
+    </div>
+  );
+}

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

@@ -1,140 +1,144 @@
 # AppShell
 
-## About
+**Category:** layout
+**Kind:** 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).
-
-### Дерево регионов
-
-```
-┌─ 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.*
+## Import
+```tsx
+import { AppShell } from "prime-ui-kit";
 ```
 
-### Зазор между колонками
-
-На **`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"]
+## Anatomy
 ```
-
----
-
-## 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>
-  );
-}
+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.
 
-### Пример (одна колонка, без `nav`)
-
-```tsx
-import { AppShell } from "prime-ui-kit";
-
-export function FullWidthMain() {
-  return (
-    <AppShell.Root fillViewport>
-      <AppShell.Main>{/* страница — поля уже на main */}</AppShell.Main>
-    </AppShell.Root>
-  );
-}
-```
+## 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 (canvas) and the content panel (surface); every child that is not `AppShell.Nav` goes into the panel.
 
-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`** (осознанно, точечно).
+| 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, Header, Main), `className` and the other div attributes. |
 
----
+### AppShell.Nav
+`ref` → `HTMLDivElement`. The navigation column slot (not a landmark: Sidebar renders the `<nav>`).
 
-## Rules
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (usually `Sidebar.Root`), `className` and the other div attributes. |
 
-- **`AppShell.Template`** внутри **`BrowserRouter`** / **`MemoryRouter`** — для сброса прокрутки.
-- **`ref`** на **`Template`** вешается на **`<main>`** (`AppShell.Main`).
-- Не дублируйте обёртки с полями **`x6`** вокруг страницы.
+### AppShell.Header
+`ref` → `HTMLElement`. Sticky `<header>` row of the panel for breadcrumbs, search and actions.
 
-## API
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes. |
 
-### AppShell.Root
+### AppShell.Main
+`ref` → `HTMLElement`. The `<main>` with the canonical gutters: a vertical `ScrollContainer`.
 
-| 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`). |
+| 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.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`**.
+`ref` → the `<main>`. Root + Nav + Header + Main 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` | — | Header content; no header row 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: 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 | |
+
+`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 |
+| content width | `contentWidth` | `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
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Main is the `<main>` landmark and Header is `<header>`; the navigation landmark comes from Sidebar (`<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 sticky header, 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`. |
+| [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.
+- `AppShell.Template` in a router app without `scrollResetKey` → a new page opens at the old scroll position; pass the pathname.
 
 ## Related
-
-- [PageContent](../../components/page-content/COMPONENT.md)
-- [Sidebar](../sidebar/COMPONENT.md)
+- **Built from:** [ScrollContainer](../../components/scroll-container/COMPONENT.md)
+- **See also:** [Sidebar](../sidebar/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)

package/src/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/src/layout/app-shell/examples/examples.module.css

@@ -0,0 +1,29 @@
+/* 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 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%;
+}

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

@@ -0,0 +1,72 @@
+/** The app frame: Sidebar in the nav column, breadcrumbs in the sticky header, the page in main; only main scrolls — `fillViewport`. */
+import { 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>
+        <AppShell.Header>
+          <Breadcrumb.Root>
+            <Breadcrumb.Item href="#crm">CRM</Breadcrumb.Item>
+            <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 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/src/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>
+  );
+}