prime-ui-kit 0.3.1 → 0.4.0

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

@@ -0,0 +1,123 @@
+# PageContent
+
+## About
+
+Semantic **page column** primitives: **`PageContent.Section`** (a **`<section>`** page region without its own outer padding), **`PageContent.Root`** (full padded column with optional **`maxWidth`**), **`PageContent.Title`** → **`<h1>`**, **`PageContent.Description`** with **`measure`**, and **`PageContent.Body`**. Typography uses kit tokens.
+
+- **Use `PageContent.Section`** when the shell (e.g. **`AppShell.Main`** with `variant="page"`) already applies padding — same pattern as playground routes, without wrapping in **`Root`**.
+- **Use `PageContent.Root`** when you need that outer padding and optional **`maxWidth`** (`full` | `readable` | `wide`; default **`full`**).
+- **Use `Description` `measure="full"`** when the parent column is already inset; default **`measure="readable"`** keeps the lead ~65ch for reading.
+
+## Composition
+
+- **`PageContent.Root`** — outer wrapper: padding + optional max-width (`data-max-width`).
+- **`PageContent.Section`** — **`<section>`** without extra outer padding; pair with **`aria-labelledby`** pointing at **`PageContent.Title`** `id`.
+- **`PageContent.Header`** — stacks title + description with spacing.
+- **`PageContent.Title`** — **`<h1>`** (one per route).
+- **`PageContent.Description`** — **`<p>`** lead; **`measure`** controls max width.
+- **`PageContent.Body`** — main blocks below the header (demos, forms, tables).
+
+### Canonical example (inside padded `main`)
+
+```tsx
+import { PageContent } from "prime-ui-kit";
+
+export function DocRouteBody() {
+  return (
+    <PageContent.Section aria-labelledby="page-heading">
+      <PageContent.Header>
+        <PageContent.Title id="page-heading">Settings</PageContent.Title>
+        <PageContent.Description measure="full">
+          Manage your workspace profile and notifications.
+        </PageContent.Description>
+      </PageContent.Header>
+      <PageContent.Body>{/* page blocks */}</PageContent.Body>
+    </PageContent.Section>
+  );
+}
+```
+
+### Canonical example (standalone column)
+
+```tsx
+import { PageContent } from "prime-ui-kit";
+
+export function StandalonePage() {
+  return (
+    <PageContent.Root maxWidth="readable">
+      <PageContent.Header>
+        <PageContent.Title>Account</PageContent.Title>
+        <PageContent.Description>Billing and security.</PageContent.Description>
+      </PageContent.Header>
+      <PageContent.Body>{/* … */}</PageContent.Body>
+    </PageContent.Root>
+  );
+}
+```
+
+### Playground
+
+Live demo and API tables: **`playground/sections/PageContentSection.tsx`** — **`Section`** → **`Header`** (**`Title`**, **`Description measure="full"`**) → **`Body`**. There is no **`playground/snippets/page-content/`** tree; the section is the single demo surface.
+
+## Rules
+
+- Prefer **one** `h1` per view — **`PageContent.Title`**.
+- Do not nest **`PageContent.Root`** inside a **`main`** that already applies page padding unless you intentionally want double padding; use **`Section`** instead.
+- **`Description`** defaults to a readable measure; use **`measure="full"`** when the layout already constrains width.
+
+## API
+
+### PageContent.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| maxWidth | `full` \| `readable` \| `wide` | `full` | No | Limits the content column; drives `data-max-width` when not `full`. |
+| className | `string` | — | No | Class on the root wrapper. |
+| children | `React.ReactNode` | — | No | Header, body, nested sections. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native `div` attributes, including `ref` (`forwardRef`). |
+
+### PageContent.Section
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on **`<section>`** (page region without outer padding—typical inside padded `main`). |
+| children | `React.ReactNode` | — | No | Usually **`Header`** + **`Body`** (playground routes follow this). |
+| …rest | `React.HTMLAttributes<HTMLElement>` | — | No | Native **`<section>`** attributes, including `ref` (`forwardRef`). |
+
+### PageContent.Header
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the header block (title + description). |
+| children | `React.ReactNode` | — | No | Usually **`PageContent.Title`** and **`PageContent.Description`** (`measure` as needed). |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native `div` attributes. |
+
+### PageContent.Title
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on **`<h1>`**. |
+| children | `React.ReactNode` | — | No | Page heading. |
+| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | Native **`h1`** attributes, including `ref` (`forwardRef`). |
+
+### PageContent.Description
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| measure | `readable` \| `full` | `readable` | No | `readable` — ~65ch; `full` — parent width (e.g. when **`AppShell.Main`** already insets). |
+| className | `string` | — | No | Class on the lead **`<p>`**. |
+| children | `React.ReactNode` | — | No | Intro text under the title. |
+| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | Native **`p`** attributes, including `ref` (`forwardRef`). |
+
+### PageContent.Body
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the main content wrapper below the header. |
+| children | `React.ReactNode` | — | No | Page content under the header. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native `div` attributes. |
+
+## Related
+
+- [Typography](../typography/COMPONENT.md) — inline roles elsewhere on the page.
+- [AppShell](../../layout/app-shell/AppShell.tsx) — grid + main padding (`variant="page"`).

package/src/components/pagination/COMPONENT.md

@@ -1,23 +1,59 @@
 # Pagination
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default `size`:** use **`m`** for the size axis unless the toolbar or table footer explicitly needs another tier.
 
-## About
+## Canonical
 
-Page navigation for chunked lists: previous and next controls with chevron icons, numeric page buttons, and ellipsis cells when there are many pages.
+- **`Pagination`** is a single compound export: **`Pagination.Root`** only (`Pagination = { Root }`).
+- **Controlled API:** **`page`**, **`totalPages`**, and **`onPageChange`** are all required; there is no uncontrolled mode.
+- **Semantics:** root is a **`nav`** with **`aria-label="Pagination"`**, **`data-size`**, previous/next **ghost** **`Button.Root`** cells with **`Button.Icon`**, numeric page **`Button.Root`** cells (current page **`primary`** **`filled`**), and ellipsis **`span`**s (**`aria-hidden`**).
+- **Range logic:** if **`totalPages ≤ 7`**, every page index is shown; otherwise the row is shortened with **`siblingCount`** (default **`1`**) and **`…`** segments while keeping first and last pages visible.
+- **Edge cases:** **`totalPages < 1`** renders **`null`**; **`page`** is clamped to **`1 … totalPages`** for display and clicks; previous/next are **`disabled`** on the first/last page.
+- **Copy:** arrow and **“Page N”** strings are fixed in the implementation (English); there are no i18n props on **`Pagination`**.
 
-- **Use** for server-driven or client-paged tables, search results, and any UI where the user moves between discrete page indices.
-- **Use** when you already know **`totalPages`** and can keep **`page`** in sync (controlled pattern).
-- **Do not use** as the only paging affordance when you rely on infinite scroll and never expose page numbers—this component assumes explicit pages.
-- **Do not use** when **`totalPages` is less than 1** and you still need a visible empty state; the root returns **`null`** in that case, so render a message or hide the bar in the parent.
-- **Do not use** expecting localized arrow or “Page N” strings from props; labels are fixed in the implementation (English).
-- **Do not use** if you must replace inner markup (custom arrows, slots); structure and **`Button`** wiring are fixed—extend or fork for deep customization.
+## Extended
 
-## Composition
+### About
 
-- **`Pagination`** is a single-part namespace: **`Pagination.Root`** only (exported as **`Pagination = { Root }`**).
-- **`Pagination.Root`** renders a **`nav`** with **`aria-label="Pagination"`**, **`data-size`**, and a row of controls: **previous** (ghost neutral **`Button`** with **`Button.Icon`**), a sequence of numeric page **`Button.Root`** cells or ellipsis **`span`**s (**`aria-hidden`**), then **next** (same as previous).
-- Page items use **`Button.Root`** with **`size`** from the root; the current page uses **`variant="primary"`** and **`mode="filled"`**; other numbers and arrows use **`variant="neutral"`** and **`mode="ghost"`**.
+Chunked navigation for lists and tables: chevron previous/next, numbered pages, and ellipses for long ranges.
+
+- **Use** when the dataset is split into discrete pages and **`totalPages`** is known (server-driven or client-side paging).
+- **Use** in table footers, list toolbars, or search result bars alongside a short range summary.
+- **Do not use** as the only paging affordance when the product is infinite-scroll-only with no page index.
+- **Do not use** when **`totalPages < 1`** and you still need chrome—**`Pagination.Root`** returns nothing; show an empty state or omit the bar in the parent.
+- **Do not use** when you must replace inner markup or strings; structure and **Button** wiring are fixed—fork or wrap at app level if you need deep customization.
+
+### Composition
+
+- **`Pagination.Root`** — the only public part. Renders the **`nav`** row; **`className`** merges onto that **`nav`** only.
+- Full-width or “meta left / pager right” layouts are parent responsibility (flex or grid around **`Pagination.Root`**)—there is no **`fullWidth`** prop on **`Pagination`**.
+
+### Playground snippets
+
+Demos match **`playground/sections/PaginationSection.tsx`** (order and intent). Sources use **`@/`** under **`playground/snippets/pagination/`**; section descriptions and some labels are Russian in the playground UI.
+
+| Playground block | Snippet | Intent |
+|------------------|---------|--------|
+| Размеры | [`sizes.tsx`](../../../playground/snippets/pagination/sizes.tsx) (+ [`sizes.module.css`](../../../playground/snippets/pagination/sizes.module.css)) | **`size`** **`s`–`xl`**, long range (**`totalPages={20}`**), local state per row |
+| Диапазон номеров | [`range-modes.tsx`](../../../playground/snippets/pagination/range-modes.tsx) (+ [`rows.module.css`](../../../playground/snippets/pagination/rows.module.css)) | All indices when **`totalPages ≤ 7`** vs ellipsis row when larger |
+| Состояния | [`states.tsx`](../../../playground/snippets/pagination/states.tsx) | First / last / single-page arrow **`disabled`** semantics |
+| Контролируемый режим | [`controlled.tsx`](../../../playground/snippets/pagination/controlled.tsx) (+ [`controlled.module.css`](../../../playground/snippets/pagination/controlled.module.css)) | Shared **`page`** with external jump buttons |
+| Full width | [`full-width.tsx`](../../../playground/snippets/pagination/full-width.tsx) (+ [`full-width.module.css`](../../../playground/snippets/pagination/full-width.module.css)) | Flex toolbar: meta left, pager right (no **`fullWidth`** prop) |
+| Специфичные фичи | [`features.tsx`](../../../playground/snippets/pagination/features.tsx) | **`siblingCount`** **`0`** / **`2`**; **`totalPages=0`** → **`null`** |
+
+### Scenarios (see `examples/`)
+
+| Scenario | Approach |
+|----------|----------|
+| Size ladder | Same as playground **Размеры**; package copy in English. → [`examples/sizes.tsx`](examples/sizes.tsx) |
+| Range modes | Same as playground **Диапазон номеров**. → [`examples/range-modes.tsx`](examples/range-modes.tsx) |
+| Disabled arrows / single page | Same as playground **Состояния**. → [`examples/states.tsx`](examples/states.tsx) |
+| Sibling window + empty data | Same as playground **Специфичные фичи** (`siblingCount`, `totalPages=0`). → [`examples/features.tsx`](examples/features.tsx) |
+| Table footer | Pair a range summary with **`Pagination.Root`** in a footer row; keep **`page`** in sync with fetched rows. → [`examples/table-footer.tsx`](examples/table-footer.tsx) |
+| Compact toolbar | Set **`size="s"`** for denser toolbars or mobile-adjacent rows. → [`examples/compact.tsx`](examples/compact.tsx) |
+| Full-width list bar | **`display: flex`**, **`justify-content: space-between`**, **`flex-wrap`**: meta text + pager. → [`examples/full-width-list.tsx`](examples/full-width-list.tsx) |
+| Controlled page index | Store **`page`** in React state (or router); update from **`onPageChange`** and any other controls (e.g. jump to first/last). → [`examples/controlled-page.tsx`](examples/controlled-page.tsx) |
+| Canonical wiring | Minimal **`Pagination.Root`** with required props; short row + long row with **`siblingCount`**. → [`examples/canonical-composition.tsx`](examples/canonical-composition.tsx) |
 
 ### Minimal example
 
@@ -31,16 +67,31 @@ export function Example() {
 }
 ```
 
-## Rules
+### Canonical composition (reference)
+
+For **default wiring**, **long ranges**, and **`siblingCount`**, open **`examples/canonical-composition.tsx`** next to this file. Imports use **`"prime-ui-kit"`** so snippets work in an app after installing the package.
+
+### Example files in `examples/`
+
+| File | Scenario |
+|------|----------|
+| `sizes.tsx` | **`size`** ladder + long range (mirror [`sizes.tsx`](../../../playground/snippets/pagination/sizes.tsx)) |
+| `range-modes.tsx` | Short vs long `totalPages` (mirror [`range-modes.tsx`](../../../playground/snippets/pagination/range-modes.tsx)) |
+| `states.tsx` | First / last / single page (mirror [`states.tsx`](../../../playground/snippets/pagination/states.tsx)) |
+| `controlled-page.tsx` | Controlled `page` + jump buttons (mirror [`controlled.tsx`](../../../playground/snippets/pagination/controlled.tsx)) |
+| `full-width-list.tsx` | Full-width bar (mirror [`full-width.tsx`](../../../playground/snippets/pagination/full-width.tsx)) |
+| `features.tsx` | `siblingCount` and `totalPages=0` (mirror [`features.tsx`](../../../playground/snippets/pagination/features.tsx)) |
+| `canonical-composition.tsx` | Required props, default size, short row + long row with `siblingCount` |
+| `table-footer.tsx` | Table footer: row range + pager |
+| `compact.tsx` | Compact row: `size="s"` |
 
-- **Controlled only:** **`page`**, **`totalPages`**, and **`onPageChange`** are required; there is no uncontrolled mode.
+### Rules
+
+- **Controlled only:** **`page`**, **`totalPages`**, and **`onPageChange`** are required.
 - **`page`** is clamped internally to **`1 … totalPages`** before rendering and when handling clicks.
-- If **`totalPages < 1`**, the component returns **`null`** (render nothing).
-- With **`totalPages ≤ 7`**, every page number is shown. With more pages, the row is shortened using **`siblingCount`** (default **`1`**) and ellipsis segments (**`…`**).
-- **First page:** previous control is **`disabled`**. **Last page:** next is **`disabled`**. **Single page:** both arrows are **`disabled`**.
-- The active page button sets **`aria-current="page"`**; other page buttons use **`aria-label={`Page ${n}`}`**; arrows use **“Previous page”** / **“Next page”**.
-- **`className`** merges onto the root **`nav`** only.
-- Syncing **`page`** to the URL, router, or query params is the responsibility of the parent.
+- If **`totalPages < 1`**, the component returns **`null`**.
+- The active page button sets **`aria-current="page"`**; other page buttons use **`aria-label`** of the form **`Page {n}`**; arrows use **“Previous page”** / **“Next page”**.
+- Syncing **`page`** to the URL, router, or query params is the parent’s responsibility.
 
 ## API
 
@@ -57,5 +108,16 @@ export function Example() {
 
 ## Related
 
-- [Button](../button/COMPONENT.md)
-- [DataTable](../data-table/COMPONENT.md)
+- [Button](../button/COMPONENT.md) — page and arrow cells are **`Button.Root`** + **`Button.Icon`**.
+- [DataTable](../data-table/COMPONENT.md) — typical host for a footer pager.
+
+## LLM note
+
+- **Playground:** demos and order — **`playground/sections/PaginationSection.tsx`** + **`playground/snippets/pagination/*.tsx`**; **`examples/`** files in the table above mirror those snippets with **`prime-ui-kit`** imports where noted.
+- **Imports:** **`import { Pagination } from "prime-ui-kit"`** — use **`Pagination.Root`** only; there is no flat **`Pagination`** element.
+- **Props:** **`page`**, **`totalPages`**, **`onPageChange`** required; optional **`siblingCount`**, **`size`**, **`className`**.
+- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**; maps to **`data-size`** on the root **`nav`**.
+- **`totalPages < 1`:** render is **`null`** — parent must handle empty data or hide the footer.
+- **No uncontrolled mode** — always pass **`page`** and **`onPageChange`**; lift state to the parent or router.
+- **Layout:** no **`fullWidth`** on **`Pagination`**; wrap in flex/grid and align in the parent.
+- **Strings:** labels are English and built-in; do not assume i18n props exist on **`Pagination`**.

package/src/components/pagination/examples/canonical-composition.tsx

@@ -0,0 +1,20 @@
+import { Pagination } from "prime-ui-kit";
+
+/**
+ * Canonical wiring: required props on Pagination.Root only. Long ranges use siblingCount to widen the numeric window.
+ */
+export default function CanonicalCompositionExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "flex-start",
+      }}
+    >
+      <Pagination.Root page={2} totalPages={5} onPageChange={() => {}} />
+      <Pagination.Root page={10} totalPages={40} onPageChange={() => {}} siblingCount={2} />
+    </div>
+  );
+}

package/src/components/pagination/examples/compact.tsx

@@ -0,0 +1,32 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/** Dense toolbar row: Pagination.Root with size="s". */
+export default function CompactExample() {
+  const [page, setPage] = React.useState(3);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        alignItems: "center",
+        gap: "var(--prime-sys-spacing-x2)",
+        padding: "var(--prime-sys-spacing-x2) var(--prime-sys-spacing-x3)",
+        borderRadius: "var(--prime-sys-radius-m)",
+        background: "var(--prime-sys-color-surface-default)",
+        border: "1px solid var(--prime-sys-color-border-subtle)",
+      }}
+    >
+      <span
+        style={{
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Compact
+      </span>
+      <Pagination.Root page={page} totalPages={12} onPageChange={setPage} size="s" />
+    </div>
+  );
+}

package/src/components/pagination/examples/controlled-page.tsx

@@ -0,0 +1,57 @@
+import { Button, Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+const TOTAL = 12;
+
+/** Page index lives in parent state; Pagination.Root and buttons share the same setter. Parity with `playground/snippets/pagination/controlled.tsx` (English copy). */
+export default function ControlledPageExample() {
+  const [page, setPage] = React.useState(4);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x3)",
+        alignItems: "flex-start",
+      }}
+    >
+      <p
+        style={{
+          margin: 0,
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        Open page {page} of {TOTAL} — updates via <code>page</code> and <code>onPageChange</code>.
+      </p>
+      <Pagination.Root page={page} totalPages={TOTAL} onPageChange={setPage} />
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-x2)",
+        }}
+      >
+        <Button.Root
+          size="s"
+          variant="neutral"
+          mode="stroke"
+          onClick={() => setPage(1)}
+          disabled={page <= 1}
+        >
+          First
+        </Button.Root>
+        <Button.Root
+          size="s"
+          variant="neutral"
+          mode="stroke"
+          onClick={() => setPage(TOTAL)}
+          disabled={page >= TOTAL}
+        >
+          Last
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/pagination/examples/features.tsx

@@ -0,0 +1,107 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * `siblingCount` widens or narrows the numeric window; `totalPages < 1` renders nothing.
+ * Parity with `playground/snippets/pagination/features.tsx`.
+ */
+export default function PaginationFeaturesExample() {
+  const [pageNarrow, setPageNarrow] = React.useState(8);
+  const [pageWide, setPageWide] = React.useState(8);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x4)",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          <code>siblingCount=0</code>
+        </p>
+        <Pagination.Root
+          page={pageNarrow}
+          totalPages={20}
+          onPageChange={setPageNarrow}
+          siblingCount={0}
+        />
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          <code>siblingCount=2</code>
+        </p>
+        <Pagination.Root
+          page={pageWide}
+          totalPages={20}
+          onPageChange={setPageWide}
+          siblingCount={2}
+        />
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          <code>totalPages=0</code>
+        </p>
+        <div
+          style={{
+            display: "flex",
+            flexWrap: "wrap",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-x2)",
+            minHeight: "var(--prime-sys-size-control-m-height)",
+          }}
+        >
+          <Pagination.Root page={1} totalPages={0} onPageChange={() => {}} />
+          <span
+            style={{
+              fontSize: "var(--prime-sys-size-control-s-supportText)",
+              color: "var(--prime-sys-color-content-muted)",
+            }}
+          >
+            empty output
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/pagination/examples/full-width-list.tsx

@@ -0,0 +1,37 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/** Full-width bar: meta on the left, Pagination.Root on the right (parent layout). Parity with `playground/snippets/pagination/full-width.tsx` (English copy). */
+export default function FullWidthListExample() {
+  const [page, setPage] = React.useState(2);
+  const totalPages = 21;
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        width: "100%",
+        maxWidth: "36rem",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: "var(--prime-sys-spacing-x3)",
+        flexWrap: "wrap",
+        padding: "var(--prime-sys-spacing-x3) var(--prime-sys-spacing-x4)",
+        borderRadius: "var(--prime-sys-radius-m)",
+        background: "var(--prime-sys-color-surface-raised)",
+        border: "1px solid var(--prime-sys-color-border-subtle)",
+      }}
+    >
+      <span
+        style={{
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+          lineHeight: "var(--prime-sys-typography-body-lineHeight)",
+        }}
+      >
+        Showing 21–40 of 412
+      </span>
+      <Pagination.Root page={page} totalPages={totalPages} onPageChange={setPage} />
+    </div>
+  );
+}

package/src/components/pagination/examples/range-modes.tsx

@@ -0,0 +1,60 @@
+import { Pagination } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Up to seven pages: all indices shown; more pages: shortened row with ellipses (`totalPages` drives logic).
+ * Parity with `playground/snippets/pagination/range-modes.tsx`.
+ */
+export default function PaginationRangeModesExample() {
+  const [shortPage, setShortPage] = React.useState(3);
+  const [longPage, setLongPage] = React.useState(8);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x4)",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          Five pages — all numbers
+        </p>
+        <Pagination.Root page={shortPage} totalPages={5} onPageChange={setShortPage} />
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "var(--prime-sys-spacing-x2)",
+          alignItems: "flex-start",
+        }}
+      >
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--prime-sys-size-control-s-supportText)",
+            color: "var(--prime-sys-color-content-secondary)",
+          }}
+        >
+          Twenty pages — ellipsis
+        </p>
+        <Pagination.Root page={longPage} totalPages={20} onPageChange={setLongPage} />
+      </div>
+    </div>
+  );
+}

package/src/components/pagination/examples/sizes.tsx

@@ -0,0 +1,50 @@
+import { Pagination, type PaginationSize } from "prime-ui-kit";
+import * as React from "react";
+
+function PaginationSizeRow({ size }: { size: PaginationSize }) {
+  const [page, setPage] = React.useState(8);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x2)",
+        alignItems: "flex-start",
+      }}
+    >
+      <p
+        style={{
+          margin: 0,
+          fontSize: "var(--prime-sys-size-control-s-supportText)",
+          color: "var(--prime-sys-color-content-secondary)",
+        }}
+      >
+        {size}
+      </p>
+      <Pagination.Root page={page} totalPages={20} onPageChange={setPage} size={size} />
+    </div>
+  );
+}
+
+/**
+ * Four control tiers on a long page row (arrows, numbers, ellipsis share one scale per `size`).
+ * Parity with `playground/snippets/pagination/sizes.tsx`.
+ */
+export default function PaginationSizesExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-x4)",
+        alignItems: "center",
+      }}
+    >
+      <PaginationSizeRow size="s" />
+      <PaginationSizeRow size="m" />
+      <PaginationSizeRow size="l" />
+      <PaginationSizeRow size="xl" />
+    </div>
+  );
+}