prime-ui-kit 0.3.1 → 0.4.0

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/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"`**.
+- Desktop width toggle (expanded vs icon rail) with optional tooltips in **`compact`**.
+- Mobile drawer behavior when **`responsive={true}`** (default): overlay, backdrop, floating open control on narrow viewports when the panel is closed.
+
+**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.
+- Встроенная кнопка и плавающая кнопка открытия (на узком окне, пока панель скрыта) используют **`aria-controls`** с id **`NavPanel`**.
+
+### 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 + floating open when the panel is closed. |
+| 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`** — не дублируйте в разметке.

package/src/layout/sidebar/examples/01-app-shell-nav.tsx

@@ -0,0 +1,90 @@
+import { FileText, LayoutDashboard, Settings } from "lucide-react";
+import { AppShell, Sidebar, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+/**
+ * Primary app layout: `AppShell.Template` nav slot holds `Sidebar` with `sidebarSlot="page-nav"`.
+ * `NavPanel` включает встроенную кнопку на грани (`data-placement="edge"`); режим — через `Sidebar.Root`.
+ */
+export default function SidebarExampleAppShellNav() {
+  return (
+    <div className={styles.demoViewport}>
+      <AppShell.Template
+        className={styles.appGrid}
+        fillViewport={false}
+        nav={
+          <Sidebar.Root
+            size="m"
+            sidebarSlot="page-nav"
+            responsive={false}
+            defaultState="expanded"
+            aria-label="Application"
+          >
+            <Sidebar.NavPanel>
+              <Sidebar.Header>
+                <Sidebar.HeaderRow>
+                  <Sidebar.HeaderMain>
+                    <Sidebar.IdentityButton
+                      leading={<span aria-hidden="true">A</span>}
+                      title="Acme Console"
+                      subtitle="Production 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.MenuItem>
+                    <Sidebar.MenuButton type="button">
+                      <Sidebar.MenuIcon>
+                        <Settings size={16} strokeWidth={1.9} />
+                      </Sidebar.MenuIcon>
+                      <Sidebar.MenuLabel>Settings</Sidebar.MenuLabel>
+                    </Sidebar.MenuButton>
+                  </Sidebar.MenuItem>
+                </Sidebar.Menu>
+              </Sidebar.Content>
+              <Sidebar.Footer>
+                <Sidebar.IdentityButton
+                  leading={<span aria-hidden="true">●</span>}
+                  title="Signed in"
+                  subtitle="user@acme.dev"
+                />
+              </Sidebar.Footer>
+            </Sidebar.NavPanel>
+          </Sidebar.Root>
+        }
+        mainProps={{ variant: "page" }}
+      >
+        <Typography.Root
+          as="p"
+          variant="body-default"
+          tone="muted"
+          className={styles.mainPlaceholder}
+        >
+          Main scrolls inside <span className={styles.code}>AppShell.Main</span>; the sidebar stays
+          in the nav column. Use{" "}
+          <span className={styles.code}>sidebarSlot=&quot;page-nav&quot;</span> so spacing and grid
+          behavior match the app template.
+        </Typography.Root>
+      </AppShell.Template>
+    </div>
+  );
+}