prime-ui-kit 0.7.11 → 0.9.0

package/src/components/empty-page/COMPONENT.md

@@ -1,143 +1,143 @@
 # EmptyPage
 
-## About
+**Category:** feedback
 
-Центрированный блок **пустого состояния**: **`EmptyPage.Icon`** (область под глиф), **`EmptyPage.Title`** (**`<h2>`**), **`EmptyPage.Description`**, **`EmptyPage.Actions`** (ряд кнопок). Ось **`size`** (`s`–`xl`) задаёт иконку, кегль и отступы и пробрасывается в **`ControlSizeProvider`** для дочерних **`Button`**.
+> Empty state of a page or a block: icon, title, explanation and an action.
 
-- **Используйте** на странице списка, в теле таблицы, в карточке или в **`ScrollContainer`**, когда данных нет и нужен явный призыв к действию.
-- **`layout="fill"`** — блок растягивается по высоте **flex**-родителя с заданной **`min-height`** (типично «область таблицы»); **`default`** — компактный блок по содержимому.
-- **Не** подменяйте **`Title`** на **`PageContent.Title`** (**`<h1>`**): пустое состояние — регион страницы, заголовок вью остаётся один на маршруте.
+## When to use
+- A list, table or page has no data yet (first run) and the user should know what to do.
+- A search or filter returned nothing.
+- Data failed to load and the user can retry.
+- Inside a card or data region that should keep its height (`layout="fill"`).
 
-## Composition
-
-- **`EmptyPage.Root`** — колонка по центру, **`text-align: center`**; **`size`**, **`layout`** через `data-*`.
-- **`EmptyPage.Icon`** — подложка под глиф в духе иконки шапки [**`Modal.Panel`**](../modal/COMPONENT.md) (`headerIcon`): скругление **`--prime-sys-size-control-*-radius`**, фон **`--prime-sys-color-status-error-background`**, цвет глифа **`--prime-sys-color-status-error-foreground`** (не «сырой» красный). Внутрь — **`lucide-react`** или **`Icon`** с **`aria-hidden`**.
-- **`EmptyPage.Title`** — **`h2`**; связывайте с **`aria-labelledby`** на корне.
-- **`EmptyPage.Description`** — **`p`**, вторичный цвет контента.
-- **`EmptyPage.Actions`** — **`flex`**-ряд с **`gap`** по размеру; внутри — **`Button`**, **`ButtonGroup`**, **`LinkButton`**.
-
-### Canonical example
+## When not to use
+- A short "no rows" line inside a table → use the [DataTable](../data-table/COMPONENT.md) `empty` slot.
+- A message about the page while data is present → use [Banner](../banner/COMPONENT.md).
+- A transient result of an action → use [Notification](../notification/COMPONENT.md).
+- Loading in progress → show a loading state, not an empty state.
 
+## Import
 ```tsx
-import { Search } from "lucide-react";
-import { Button, EmptyPage } from "prime-ui-kit";
-
-export function EmptySearchResults() {
-  return (
-    <EmptyPage.Root aria-labelledby="empty-heading">
-      <EmptyPage.Icon aria-hidden>
-        <Search strokeWidth={2} aria-hidden />
-      </EmptyPage.Icon>
-      <EmptyPage.Title id="empty-heading">Ничего не найдено</EmptyPage.Title>
-      <EmptyPage.Description>
-        Измените фильтры или сбросьте поиск — тогда мы снова покажем результаты.
-      </EmptyPage.Description>
-      <EmptyPage.Actions>
-        <Button.Root type="button" variant="primary">
-          Сбросить фильтры
-        </Button.Root>
-      </EmptyPage.Actions>
-    </EmptyPage.Root>
-  );
-}
+import { EmptyPage } from "prime-ui-kit";
 ```
 
-### Пустое состояние в области таблицы
-
-Родитель с **`min-height`** (и обычно рамкой области данных) + **`layout="fill"`** — контент визуально по центру «подложки».
-
-```tsx
-import { PackagePlus } from "lucide-react";
-import { Button, EmptyPage } from "prime-ui-kit";
-
-export function OrdersTableEmpty() {
-  return (
-    <div className="ordersTableBodyRegion">
-      <EmptyPage.Root layout="fill" aria-labelledby="empty-table-heading">
-        <EmptyPage.Icon aria-hidden>
-          <PackagePlus strokeWidth={2} aria-hidden />
-        </EmptyPage.Icon>
-        <EmptyPage.Title id="empty-table-heading">Пока нет позиций</EmptyPage.Title>
-        <EmptyPage.Description>Добавьте первую строку или импортируйте каталог.</EmptyPage.Description>
-        <EmptyPage.Actions>
-          <Button.Root type="button" variant="primary">
-            Добавить позицию
-          </Button.Root>
-        </EmptyPage.Actions>
-      </EmptyPage.Root>
-    </div>
-  );
-}
+## Anatomy
+```
+EmptyPage.Root              centered column, provides size to children
+├─ EmptyPage.Icon           rounded icon tile (tone)
+├─ EmptyPage.Title          <h2>
+├─ EmptyPage.Description    <p>, secondary text
+└─ EmptyPage.Actions        centered row of buttons
 ```
-
-### Связь с DataTable
-
-У **`DataTable`** пустой набор строк может отображаться через **`emptyText`** (строка в таблице). Для **богатого** пустого состояния с кнопкой и иконкой не подставляйте разметку внутрь **`emptyText`**: рендерите **`EmptyPage`** **вместо** таблицы или **в** ячейке-обёртке с **`layout="fill"`**, когда **`rows.length === 0`** и не **`loading`**.
-
-### Playground
-
-Живые примеры: **`playground/sections/EmptyPageSection.tsx`**.
-
-## Extended examples
-
-| Playground (сниппет) | Runnable (`examples/*.tsx`) |
-|----------------------|------------------------------|
-| [`canonical.tsx`](../../../playground/snippets/empty-page/canonical.tsx) | [`examples/canonical.tsx`](./examples/canonical.tsx) |
-| [`sizes.tsx`](../../../playground/snippets/empty-page/sizes.tsx) | [`examples/sizes.tsx`](./examples/sizes.tsx) |
-| [`table-region.tsx`](../../../playground/snippets/empty-page/table-region.tsx) | [`examples/table-region.tsx`](./examples/table-region.tsx) |
-
-## Rules
-
-- Заголовок вью — один **`h1`** ([`PageContent.Title`](../page-content/COMPONENT.md)); в **`EmptyPage`** используйте **`Title`** (**`h2`**).
-- Иконка декоративная — **`aria-hidden`** на обёртке или SVG.
-- Размеры кнопок в **`Actions`** наследуются от **`ControlSizeProvider`** на **`Root`**; при необходимости оберните действия в отдельный **`ControlSizeProvider`**.
 
 ## API
 
 ### EmptyPage.Root
+`forwardRef` to `HTMLDivElement`. + native `<div>` props (`aria-labelledby`, `role`, …).
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | `s` \| `m` \| `l` \| `xl` | `m` | No | Шкала иконки, текста, отступов; `ControlSizeProvider` для потомков. |
-| layout | `default` \| `fill` | `default` | No | `fill` — растянуть по высоте flex-родителя (пустое тело таблицы / панели). |
-| className | `string` | — | No | Дополнительный класс корня. |
-| children | `React.ReactNode` | — | No | Icon, Title, Description, Actions. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | В т.ч. `ref` (`forwardRef`), `aria-*`. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Icon tile, type sizes and padding. Provided to children via the control-size context (pass it to Buttons explicitly). |
+| `layout` | `"default" \| "fill"` | `"default"` | `default`: compact block sized by content. `fill`: stretches over the height of a flex parent and centers the content. |
+| `className` | `string` | — | Class on the root. |
+| `children` | `ReactNode` | — | Parts. |
 
 ### EmptyPage.Icon
+No ref. + native `<div>` props.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Класс подложки под иконку. |
-| children | `React.ReactNode` | — | No | Глиф (например из `lucide-react`). |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Атрибуты обёртки. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `"neutral" \| "accent" \| "danger"` | `"neutral"` | Tile color. |
+| `children` | `ReactNode` | — | An svg icon (mark it `aria-hidden`); sized by the tier. |
+| `className` | `string` | — | Class. |
 
 ### EmptyPage.Title
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Класс на **`h2`**. |
-| children | `React.ReactNode` | — | No | Заголовок блока. |
-| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | В т.ч. `ref` (`forwardRef`), `id` для `aria-labelledby`. |
+`forwardRef` to `HTMLHeadingElement`. + native `<h2>` props. Semibold title capped at the reading width.
 
 ### EmptyPage.Description
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Класс на **`p`**. |
-| children | `React.ReactNode` | — | No | Пояснение. |
-| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
+`forwardRef` to `HTMLParagraphElement`. + native `<p>` props. Secondary text capped at the reading width.
 
 ### EmptyPage.Actions
+No ref. + native `<div>` props. Wrapping centered row, gap `--prime-space-2`.
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | Padding 24 × 12, tile 32 / icon 16, title 14/20, description 12/16 | Inside small cards, popovers | |
+| `s` | Padding 32 × 16, tile 40 / icon 20, title 14/20, description 13/20 | Cards, side panels, table regions | |
+| `m` | Padding 40 × 16, tile 48 / icon 24, title 16/24, description 14/20 | Sections and data regions | yes |
+| `l` | Padding 48 × 24, tile 56 / icon 24, title 18/24, description 14/20 | Large regions | |
+| `xl` | Padding 64 × 32, tile 64 / icon 32, title 20/28, description 16/24 | A whole empty page | |
+
+### tone (EmptyPage.Icon)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | `fill-muted` tile, secondary icon | No data / no results | yes |
+| `accent` | Accent soft tile, accent icon | First run, invitation to create something | |
+| `danger` | Danger soft tile, danger icon | Loading failed | |
+
+### layout
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `default` | Height by content | Standalone empty states | yes |
+| `fill` | Grows to fill a flex parent, content centered | Inside cards/regions with a fixed or min height | |
+
+**Combinations**
+- Recommended: `neutral` + "Сбросить фильтры" for no results; `accent` + a primary action for first run; `danger` + an outline "Повторить".
+- Hierarchy: at most one primary (solid) button, placed last; the rest outline/ghost.
+- Pointless: `layout="fill"` in a parent that is not a flex column with height.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| size | `size` | `data-size` on Root |
+| fill | `layout="fill"` | `data-layout="fill"` on Root |
+| tone | Icon `tone` | `data-tone` on Icon |
+
+## Layout & spacing
+- Base gap `--prime-space-2`; icon → title gets `--prime-space-2` more; description → actions `--prime-space-3` more.
+- Text is centered and capped at `--prime-layout-reading-max-width`; long words wrap.
+- EmptyPage has no fill or radius of its own: the host card/region provides the surface.
+
+## Accessibility
+- Give the title an `id` and the root `aria-labelledby` so the region is named.
+- Mark the icon `aria-hidden`; the title carries the meaning.
+- Title is an `<h2>`: make sure it fits the page heading outline.
+- EmptyPage has no `labels`.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [data-region.tsx](examples/data-region.tsx) | Card region with a header and `layout="fill"`, accent icon, two actions | Empty list/table area |
+| [no-results.tsx](examples/no-results.tsx) | Search with no results: Icon, Title, Description, Actions | Filters/queries returning nothing |
+| [icon-tones.tsx](examples/icon-tones.tsx) | `neutral`, `accent`, `danger` icon tones | Choosing the tone by cause |
+| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl` with a button of the same size | Picking a size |
+
+```tsx
+import { Button, EmptyPage } from "prime-ui-kit";
+
+export function NoInvoices() {
+  return (
+    <EmptyPage.Root aria-labelledby="no-invoices-title">
+      <EmptyPage.Title id="no-invoices-title">Счетов нет</EmptyPage.Title>
+      <EmptyPage.Description>Выставленные счета появятся здесь.</EmptyPage.Description>
+      <EmptyPage.Actions>
+        <Button.Root>Выставить счёт</Button.Root>
+      </EmptyPage.Actions>
+    </EmptyPage.Root>
+  );
+}
+```
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Класс на flex-контейнере действий. |
-| children | `React.ReactNode` | — | No | Кнопки и т.п. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Атрибуты **`div`**. |
+## Mistakes
+- Buttons in a non-`m` EmptyPage without `size` → pass the same `size` to them.
+- `tone` on `EmptyPage.Root` → `tone` belongs to `EmptyPage.Icon`.
+- Showing an empty state while data is loading → show loading first.
+- Several primary buttons → one primary, placed last.
 
 ## Related
-
-- [PageContent](../page-content/COMPONENT.md) — шапка маршрута (**`h1`**).
-- [DataTable](../data-table/COMPONENT.md) — **`emptyText`** vs отдельный **`EmptyPage`**.
-- [Button](../button/COMPONENT.md) — действия в **`Actions`**.
+- [DataTable](../data-table/COMPONENT.md) — built-in `empty` slot for tables.
+- [Banner](../banner/COMPONENT.md), [Notification](../notification/COMPONENT.md).
+- [Card](../card/COMPONENT.md) — host surface for data regions.

package/src/components/empty-page/examples/data-region.tsx

@@ -0,0 +1,35 @@
+/** An empty data region: a card with a header and a minimum height where `layout="fill"` stretches the empty state over the remaining height. Use it instead of a table when there are no rows yet. */
+import { PackagePlus } from "lucide-react";
+import { Button, EmptyPage, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function EmptyPageDataRegionExample() {
+  return (
+    <section className={styles.region} aria-labelledby="orders-region-title">
+      <div className={styles.regionHeader}>
+        <Typography.Root as="h3" variant="title-s" id="orders-region-title">
+          Заказы
+        </Typography.Root>
+        <Button.Root variant="outline" tone="neutral" size="s">
+          Импорт
+        </Button.Root>
+      </div>
+      <EmptyPage.Root layout="fill" aria-labelledby="orders-empty-title">
+        <EmptyPage.Icon tone="accent">
+          <PackagePlus aria-hidden />
+        </EmptyPage.Icon>
+        <EmptyPage.Title id="orders-empty-title">Заказов пока нет</EmptyPage.Title>
+        <EmptyPage.Description>
+          Создайте заказ вручную или подключите магазин — заказы начнут появляться автоматически.
+        </EmptyPage.Description>
+        <EmptyPage.Actions>
+          <Button.Root variant="outline" tone="neutral">
+            Подключить магазин
+          </Button.Root>
+          <Button.Root>Создать заказ</Button.Root>
+        </EmptyPage.Actions>
+      </EmptyPage.Root>
+    </section>
+  );
+}

package/src/components/empty-page/examples/examples.module.css

@@ -0,0 +1,40 @@
+/* Layout helpers for the EmptyPage examples. Semantic tokens only. */
+
+/* Columns of at least 16rem. */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-16) * 4)), 1fr));
+  align-items: start;
+  gap: var(--prime-space-6);
+  width: 100%;
+  min-width: 0;
+}
+
+.group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  min-width: 0;
+}
+
+/* Data region: white surface with a fixed minimum height, EmptyPage fills it. */
+.region {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  min-height: calc(var(--prime-space-24) * 3);
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-card-bg);
+  box-shadow: var(--prime-card-shadow);
+  overflow: hidden;
+}
+
+.regionHeader {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+  padding: var(--prime-space-4) var(--prime-card-padding-m);
+}

package/src/components/empty-page/examples/icon-tones.tsx

@@ -0,0 +1,43 @@
+/** `EmptyPage.Icon tone`: `neutral` — no data yet, `accent` — first run and a call to start, `danger` — failed to load. Pick the tone by why the area is empty. */
+import { CloudOff, Inbox, Rocket } from "lucide-react";
+import { Button, EmptyPage } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function EmptyPageIconTonesExample() {
+  return (
+    <div className={styles.grid}>
+      <EmptyPage.Root size="s" aria-labelledby="tone-neutral">
+        <EmptyPage.Icon tone="neutral">
+          <Inbox aria-hidden />
+        </EmptyPage.Icon>
+        <EmptyPage.Title id="tone-neutral">Входящих нет</EmptyPage.Title>
+        <EmptyPage.Description>Новые заявки появятся здесь.</EmptyPage.Description>
+      </EmptyPage.Root>
+
+      <EmptyPage.Root size="s" aria-labelledby="tone-accent">
+        <EmptyPage.Icon tone="accent">
+          <Rocket aria-hidden />
+        </EmptyPage.Icon>
+        <EmptyPage.Title id="tone-accent">Создайте первый проект</EmptyPage.Title>
+        <EmptyPage.Description>Проекты объединяют задачи, файлы и команду.</EmptyPage.Description>
+        <EmptyPage.Actions>
+          <Button.Root size="s">Создать проект</Button.Root>
+        </EmptyPage.Actions>
+      </EmptyPage.Root>
+
+      <EmptyPage.Root size="s" aria-labelledby="tone-danger">
+        <EmptyPage.Icon tone="danger">
+          <CloudOff aria-hidden />
+        </EmptyPage.Icon>
+        <EmptyPage.Title id="tone-danger">Не удалось загрузить</EmptyPage.Title>
+        <EmptyPage.Description>Сервер не ответил. Проверьте соединение.</EmptyPage.Description>
+        <EmptyPage.Actions>
+          <Button.Root variant="outline" tone="neutral" size="s">
+            Повторить
+          </Button.Root>
+        </EmptyPage.Actions>
+      </EmptyPage.Root>
+    </div>
+  );
+}

package/src/components/empty-page/examples/no-results.tsx

@@ -0,0 +1,23 @@
+/** An empty search result with the basic parts: Icon, Title (`h2`), Description and Actions. Use it when filters or a query return nothing. */
+import { Search } from "lucide-react";
+import { Button, EmptyPage } from "prime-ui-kit";
+
+export default function EmptyPageNoResultsExample() {
+  return (
+    <EmptyPage.Root aria-labelledby="empty-search-title">
+      <EmptyPage.Icon>
+        <Search aria-hidden />
+      </EmptyPage.Icon>
+      <EmptyPage.Title id="empty-search-title">Ничего не найдено</EmptyPage.Title>
+      <EmptyPage.Description>
+        По запросу «монитор 32″» нет товаров. Измените фильтры или сбросьте поиск.
+      </EmptyPage.Description>
+      <EmptyPage.Actions>
+        <Button.Root variant="outline" tone="neutral">
+          Сбросить фильтры
+        </Button.Root>
+        <Button.Root>Новый поиск</Button.Root>
+      </EmptyPage.Actions>
+    </EmptyPage.Root>
+  );
+}

package/src/components/empty-page/examples/sizes.tsx

@@ -1,22 +1,30 @@
-import { Inbox } from "lucide-react";
-import { EmptyPage, type EmptyPageSize } from "prime-ui-kit";
+/** Sizes xs–xl change the icon tile, title size and padding; pass the same `size` to the buttons in Actions. Use small sizes inside cards and tables, large ones for whole pages. */
+import { FileText } from "lucide-react";
+import { Button, type ControlSize, EmptyPage, Typography } from "prime-ui-kit";
 
-import styles from "./examples-demos.module.css";
+import styles from "./examples.module.css";
 
-const sizes = ["s", "m", "l", "xl"] as const satisfies readonly EmptyPageSize[];
+const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
 
-/** Лестница размеров `s`–`xl`: иконка, кегль и отступы согласованы. */
-export function EmptyPageSizes() {
+export default function EmptyPageSizesExample() {
   return (
-    <div className={styles.stack}>
+    <div className={styles.grid}>
       {sizes.map((size) => (
-        <EmptyPage.Root key={size} size={size} aria-labelledby={`empty-size-${size}`}>
-          <EmptyPage.Icon aria-hidden>
-            <Inbox strokeWidth={2} aria-hidden />
-          </EmptyPage.Icon>
-          <EmptyPage.Title id={`empty-size-${size}`}>Размер {size}</EmptyPage.Title>
-          <EmptyPage.Description>Одинаковая структура, разная шкала.</EmptyPage.Description>
-        </EmptyPage.Root>
+        <div key={size} className={styles.group}>
+          <Typography.Root variant="code" tone="muted">
+            size="{size}"
+          </Typography.Root>
+          <EmptyPage.Root size={size} aria-labelledby={`empty-size-${size}`}>
+            <EmptyPage.Icon>
+              <FileText aria-hidden />
+            </EmptyPage.Icon>
+            <EmptyPage.Title id={`empty-size-${size}`}>Счетов нет</EmptyPage.Title>
+            <EmptyPage.Description>Выставленные счета появятся здесь.</EmptyPage.Description>
+            <EmptyPage.Actions>
+              <Button.Root size={size}>Выставить счёт</Button.Root>
+            </EmptyPage.Actions>
+          </EmptyPage.Root>
+        </div>
       ))}
     </div>
   );

package/src/components/example-frame/COMPONENT.md

@@ -0,0 +1,141 @@
+# ExampleFrame
+
+**Category:** infrastructure
+
+> A documentation frame: live preview, source code and device width in one block.
+
+## When to use
+- Documentation and design-system pages that show a live example next to its source.
+- Checking an example in light and dark themes and at desktop / tablet / phone widths.
+
+## When not to use
+- Showing code without a live preview → use [CodeBlock](../code-block/COMPONENT.md).
+- Grouping app content in a box → use [Card](../card/COMPONENT.md).
+- Switching app sections → use [Tabs](../tabs/COMPONENT.md).
+
+## Import
+```tsx
+import { ExampleFrame } from "prime-ui-kit";
+```
+
+## Anatomy
+- `ExampleFrame.Root` — the frame: toolbar (pane switch Preview / Code, theme toggle, copy button, device switch) and either the preview stage or the code pane.
+  - `ExampleFrame.Stage` — marks the content shown in the preview. Without a Stage all `children` are previewed.
+
+## API
+
+### ExampleFrame.Root
+Does not forward a ref; no native props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `code` | `string` | — (required) | Source shown on the code pane (TS/TSX highlighting via CodeBlock) and copied by the copy button. |
+| `children` | `ReactNode` | — | Preview content; if an `ExampleFrame.Stage` is among the children, only its children are previewed. |
+| `className` | `string` | — | Extra class on the frame. |
+| `colorScheme` | `"light" \| "dark"` | — | Preview theme, controlled. |
+| `defaultColorScheme` | `"light" \| "dark"` | `"light"` | Initial preview theme, uncontrolled. |
+| `onColorSchemeChange` | `(scheme: "light" \| "dark") => void` | — | Called when the theme toggle is pressed. |
+| `viewport` | `"desktop" \| "tablet" \| "mobile"` | — | Preview width, controlled. |
+| `defaultViewport` | `"desktop" \| "tablet" \| "mobile"` | `"desktop"` | Initial preview width, uncontrolled. |
+| `onViewportChange` | `(v: "desktop" \| "tablet" \| "mobile") => void` | — | Called when the device switch changes. |
+| `showThemeToggle` | `boolean` | `true` | Show the light/dark toggle in the toolbar. |
+| `onCopy` | `() => void` | — | Called after `code` was copied to the clipboard. |
+| `previewLayout` | `ExampleFramePreviewLayout` | `"default"` | How preview children are laid out (see Variants). |
+| `labels` | `Partial<ExampleFrameLabels>` | see Accessibility | Toolbar and region strings. |
+
+### ExampleFrame.Stage
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Content rendered only in the preview. |
+
+## Variants
+
+### previewLayout
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `default` | single block centered in the stage | one component | yes |
+| `stack` | centered column, gap 16; a child with `fullWidth` or a table stretches | several blocks one under another | |
+| `stack-center` | centered column, gap 12 | short centered items | |
+| `stack-narrow` | column, children capped at `7 × --prime-space-16` and centered | forms and narrow columns | |
+| `dense-stack` | column from the top, gap 4, scrolls past a max height | long lists | |
+| `row` | centered wrapping row, gap 12, extra vertical padding | a few buttons or controls side by side | |
+| `row-start` | wrapping row aligned to the start, gap 12 | toolbars, start-aligned controls | |
+| `row-wrap` | centered wrapping row, items aligned to the top, gap 8 | many small items (badges, tags) | |
+
+### viewport
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `desktop` | stage takes the full frame width | default view | yes |
+| `tablet` | stage capped at 768px (`8 × --prime-space-24`), centered | checking tablet layout | |
+| `mobile` | stage capped at 384px (`4 × --prime-space-24`), centered | checking phone layout | |
+
+### colorScheme
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `light` | stage and code pane in the light theme | default | yes |
+| `dark` | stage and code pane in the dark theme (`data-theme="dark"`), switched without color transitions | checking dark mode | |
+
+Frame look: `bg-sunken` chrome with a `border-subtle` hairline and `radius-xl`; the stage and code pane are `bg-canvas` wells with `radius-l` (16 − 4 padding = 12). The stage resets the card context (`--prime-color-card-bg: bg-surface`).
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| pane | toolbar switch (internal state, starts at Preview) | preview stage or code pane is rendered |
+| viewport | `viewport` / `defaultViewport` | `data-viewport` on the preview viewport |
+| theme | `colorScheme` / `defaultColorScheme` | `data-theme` on the stage and code pane |
+| layout | `previewLayout` | `data-preview-layout` on the stage |
+| copy | copy button | its `aria-label` switches to `labels.copied` / `labels.copyError` for 2 s |
+
+Controlled: pass `colorScheme` / `viewport` with their change handlers (e.g. to sync all frames on a page); uncontrolled: `default*` props.
+
+## Layout & spacing
+- The frame is `max-width: 100%`; long code lines scroll inside the code pane instead of widening the page.
+- The toolbar wraps below 640px of frame width; below 400px the device labels are visually hidden (icons stay).
+- Stack frames one per demo block; spacing between blocks comes from the page (`var(--prime-space-10)`–`var(--prime-space-12)` between sections).
+
+## Accessibility
+- Pane and device switches are SegmentedControls (radio groups); the theme and copy buttons are icon-only Buttons with `aria-label`.
+- The code pane is a focusable `section` (`tabIndex=0`) with `aria-label` from `labels.codeRegion`, so keyboard users can scroll it.
+
+| `labels` key | Default | Used for |
+|---|---|---|
+| `preview` | `"Превью"` | Preview pane option |
+| `code` | `"Код"` | Code pane option |
+| `desktop` | `"Десктоп"` | desktop width option |
+| `tablet` | `"Планшет"` | tablet width option |
+| `mobile` | `"Телефон"` | phone width option |
+| `copy` | `"Копировать код"` | copy button `aria-label` |
+| `copied` | `"Скопировано"` | copy button after success |
+| `copyError` | `"Не удалось скопировать"` | copy button after failure |
+| `themeDark` | `"Включить тёмную тему"` | theme toggle in light mode |
+| `themeLight` | `"Включить светлую тему"` | theme toggle in dark mode |
+| `codeRegion` | `"Код примера"` | `aria-label` of the code pane |
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [basic.tsx](examples/basic.tsx) | Preview + code with the full toolbar and a `row` layout | documentation pages |
+
+```tsx
+import { Button, ExampleFrame } from "prime-ui-kit";
+
+export function SaveButtonDemo() {
+  return (
+    <ExampleFrame.Root code="<Button.Root>Сохранить</Button.Root>">
+      <ExampleFrame.Stage>
+        <Button.Root>Сохранить</Button.Root>
+      </ExampleFrame.Stage>
+    </ExampleFrame.Root>
+  );
+}
+```
+
+## Mistakes
+- Wrapping several preview items in an extra `div` with flex styles → use `previewLayout="row"` or `"stack"`.
+- `code` that differs from the preview → import the example source (`?raw` in Vite) and render the same file.
+- Expecting `colorScheme` to change the page theme → it only themes the frame's stage and code pane.
+
+## Related
+- [CodeBlock](../code-block/COMPONENT.md)
+- [SegmentedControl](../segmented-control/COMPONENT.md)
+- [Card](../card/COMPONENT.md)

package/src/components/example-frame/examples/basic.tsx

@@ -0,0 +1,18 @@
+/** A preview + code frame with the toolbar (pane switch, device width, theme, copy) and a `row` preview layout. Use in documentation pages to show a live example next to its source. */
+import { Button, ExampleFrame } from "prime-ui-kit";
+
+const code = `<Button.Root variant="ghost" tone="neutral">Отмена</Button.Root>
+<Button.Root>Сохранить</Button.Root>`;
+
+export default function ExampleFrameBasicExample() {
+  return (
+    <ExampleFrame.Root code={code} previewLayout="row">
+      <ExampleFrame.Stage>
+        <Button.Root variant="ghost" tone="neutral">
+          Отмена
+        </Button.Root>
+        <Button.Root>Сохранить</Button.Root>
+      </ExampleFrame.Stage>
+    </ExampleFrame.Root>
+  );
+}