From a8add4cd12f2efe35ef0a04905915023eee5603e Mon Sep 17 00:00:00 2001
From: Aaron Reisman <aaron.reisman@plane.so>
Date: Tue, 23 Jun 2026 16:02:25 +0700
Subject: [PATCH 1/3] Align pagination to architecture goals

- Move all className composition into cva variants; drop cx from component
  files and from the exported slotBase helper (now an internal constant).
- Add ellipsisVariants cva so PaginationEllipsis no longer calls cx directly.
- Make PaginationEllipsis accept children (NodeSlot pattern) instead of baking
  MoreHorizontal inline, keeping it a single rendered element.
- Add required magnitude prop to every ui part (PaginationArrowButton,
  PaginationPageButton, PaginationEllipsis, PaginationPerPageTrigger) with
  an md value covering the current 24px Figma size; no defaultVariants.
- Switch [&_svg] descendant selectors to [&>svg] direct-child selectors to
  match the single-element/children-passed-in pattern.
- Export PaginationMagnitude and ellipsisVariants from the ui entry; drop
  the now-internal slotBase from the public export.
- Thread magnitude="md" through the Pagination composition and both story
  files.
---
 .../src/components/pagination/pagination.tsx  | 13 +++-
 packages/propel/src/ui/pagination/index.tsx   |  5 +-
 .../ui/pagination/pagination-arrow-button.tsx | 16 +++--
 .../src/ui/pagination/pagination-ellipsis.tsx | 21 ++++---
 .../ui/pagination/pagination-page-button.tsx  | 12 ++--
 .../pagination-per-page-trigger.tsx           | 15 +++--
 .../src/ui/pagination/pagination.stories.tsx  | 20 +++---
 packages/propel/src/ui/pagination/variants.ts | 62 ++++++++++++++-----
 8 files changed, 115 insertions(+), 49 deletions(-)

diff --git a/packages/propel/src/components/pagination/pagination.tsx b/packages/propel/src/components/pagination/pagination.tsx
index 013845bd..8c16ca52 100644
--- a/packages/propel/src/components/pagination/pagination.tsx
+++ b/packages/propel/src/components/pagination/pagination.tsx
@@ -1,4 +1,4 @@
-import { ArrowLeft, ArrowRight, ChevronDown, LoaderCircle } from "lucide-react";
+import { ArrowLeft, ArrowRight, ChevronDown, LoaderCircle, MoreHorizontal } from "lucide-react";
 import * as React from "react";
 
 import { Menu, MenuTrigger } from "../../ui/menu/index";
@@ -177,7 +177,7 @@ export function Pagination({
             arrows move, Enter selects).
           */}
           <Menu>
-            <MenuTrigger render={<PaginationPerPageTrigger />}>
+            <MenuTrigger render={<PaginationPerPageTrigger magnitude="md" />}>
               <span>{l.perPageValue(pageSize.value)}</span>
               <span className="sr-only">{l.perPage}</span>
               <ChevronDown aria-hidden className="transition-transform" />
@@ -211,6 +211,7 @@ export function Pagination({
       <ul className="flex items-center gap-1.5">
         <li>
           <PaginationArrowButton
+            magnitude="md"
             aria-label={l.previous}
             disabled={atStart}
             onClick={() => onPageChange(page - 1)}
@@ -221,12 +222,17 @@ export function Pagination({
 
         {tokens.map((token) => {
           if (token === "ellipsis-start" || token === "ellipsis-end") {
-            return <PaginationEllipsis key={token} />;
+            return (
+              <PaginationEllipsis key={token} magnitude="md">
+                <MoreHorizontal aria-hidden />
+              </PaginationEllipsis>
+            );
           }
           const isCurrent = token === page;
           return (
             <li key={token}>
               <PaginationPageButton
+                magnitude="md"
                 aria-label={l.page(token)}
                 aria-current={isCurrent ? "page" : undefined}
                 current={isCurrent}
@@ -248,6 +254,7 @@ export function Pagination({
 
         <li>
           <PaginationArrowButton
+            magnitude="md"
             aria-label={l.next}
             disabled={atEnd}
             onClick={() => onPageChange(page + 1)}
diff --git a/packages/propel/src/ui/pagination/index.tsx b/packages/propel/src/ui/pagination/index.tsx
index 724a07b7..14112daf 100644
--- a/packages/propel/src/ui/pagination/index.tsx
+++ b/packages/propel/src/ui/pagination/index.tsx
@@ -1,5 +1,5 @@
 export { PaginationArrowButton, type PaginationArrowButtonProps } from "./pagination-arrow-button";
-export { PaginationEllipsis } from "./pagination-ellipsis";
+export { PaginationEllipsis, type PaginationEllipsisProps } from "./pagination-ellipsis";
 export { PaginationPageButton, type PaginationPageButtonProps } from "./pagination-page-button";
 export {
   PaginationPerPageTrigger,
@@ -7,7 +7,8 @@ export {
 } from "./pagination-per-page-trigger";
 export {
   arrowButtonVariants,
+  ellipsisVariants,
   pageButtonVariants,
   perPageTriggerVariants,
-  slotBase,
+  type PaginationMagnitude,
 } from "./variants";
diff --git a/packages/propel/src/ui/pagination/pagination-arrow-button.tsx b/packages/propel/src/ui/pagination/pagination-arrow-button.tsx
index 9f7fbd16..51eff57c 100644
--- a/packages/propel/src/ui/pagination/pagination-arrow-button.tsx
+++ b/packages/propel/src/ui/pagination/pagination-arrow-button.tsx
@@ -1,16 +1,20 @@
 import type * as React from "react";
 
-import { arrowButtonVariants } from "./variants";
+import { type PaginationMagnitude, arrowButtonVariants } from "./variants";
 
 export type PaginationArrowButtonProps = Omit<
   React.ComponentProps<"button">,
   "className" | "style"
->;
+> & {
+  /** Size of the slot. Pass the icon as `children`; it is sized via `[&>svg]`. */
+  magnitude: PaginationMagnitude;
+};
 
 /**
- * A styled prev/next arrow button. Applies `arrowButtonVariants()`; pass the (directional,
- * RTL-mirrored) arrow icon as `children` and wire `aria-label`/`disabled`/`onClick` through props.
+ * A styled prev/next arrow button. Applies `arrowButtonVariants({ magnitude })`; pass the
+ * (directional, RTL-mirrored) arrow icon as `children` and wire `aria-label`/`disabled`/`onClick`
+ * through props.
  */
-export function PaginationArrowButton(props: PaginationArrowButtonProps) {
-  return <button type="button" className={arrowButtonVariants()} {...props} />;
+export function PaginationArrowButton({ magnitude, ...props }: PaginationArrowButtonProps) {
+  return <button type="button" className={arrowButtonVariants({ magnitude })} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-ellipsis.tsx b/packages/propel/src/ui/pagination/pagination-ellipsis.tsx
index 2af318f6..cdc6a329 100644
--- a/packages/propel/src/ui/pagination/pagination-ellipsis.tsx
+++ b/packages/propel/src/ui/pagination/pagination-ellipsis.tsx
@@ -1,13 +1,20 @@
-import { cx } from "class-variance-authority";
-import { MoreHorizontal } from "lucide-react";
+import type * as React from "react";
 
-import { slotBase } from "./variants";
+import { type PaginationMagnitude, ellipsisVariants } from "./variants";
 
-/** A non-interactive gap marker between distant page numbers. */
-export function PaginationEllipsis() {
+export type PaginationEllipsisProps = {
+  magnitude: PaginationMagnitude;
+  children: React.ReactNode;
+};
+
+/**
+ * A non-interactive gap marker between distant page numbers. Pass the ellipsis icon as `children`;
+ * it is sized via `[&>svg]`.
+ */
+export function PaginationEllipsis({ magnitude, children }: PaginationEllipsisProps) {
   return (
-    <li aria-hidden className={cx(slotBase, "text-icon-placeholder")}>
-      <MoreHorizontal className="size-3.5 shrink-0" />
+    <li aria-hidden className={ellipsisVariants({ magnitude })}>
+      {children}
     </li>
   );
 }
diff --git a/packages/propel/src/ui/pagination/pagination-page-button.tsx b/packages/propel/src/ui/pagination/pagination-page-button.tsx
index cc5d819e..4feb25f9 100644
--- a/packages/propel/src/ui/pagination/pagination-page-button.tsx
+++ b/packages/propel/src/ui/pagination/pagination-page-button.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { pageButtonVariants } from "./variants";
+import { type PaginationMagnitude, pageButtonVariants } from "./variants";
 
 export type PaginationPageButtonProps = Omit<
   React.ComponentProps<"button">,
@@ -8,12 +8,14 @@ export type PaginationPageButtonProps = Omit<
 > & {
   /** Whether this button represents the current page (renders the pressed/selected fill). */
   current: boolean;
+  /** Size of the slot. */
+  magnitude: PaginationMagnitude;
 };
 
 /**
- * A styled page-number button. Applies `pageButtonVariants({ current })`; pass the page number (or
- * a loading spinner) as `children` and wire `aria-current`/`onClick` through props.
+ * A styled page-number button. Applies `pageButtonVariants({ current, magnitude })`; pass the page
+ * number (or a loading spinner) as `children` and wire `aria-current`/`onClick` through props.
  */
-export function PaginationPageButton({ current, ...props }: PaginationPageButtonProps) {
-  return <button type="button" className={pageButtonVariants({ current })} {...props} />;
+export function PaginationPageButton({ current, magnitude, ...props }: PaginationPageButtonProps) {
+  return <button type="button" className={pageButtonVariants({ current, magnitude })} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx b/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx
index f313a4b9..ccffa0a1 100644
--- a/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx
+++ b/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx
@@ -1,21 +1,28 @@
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
 
-import { perPageTriggerVariants } from "./variants";
+import { type PaginationMagnitude, perPageTriggerVariants } from "./variants";
 
 export type PaginationPerPageTriggerProps = Omit<
   useRender.ComponentProps<"button">,
   "className" | "style"
->;
+> & {
+  /** Size of the trigger pill. */
+  magnitude: PaginationMagnitude;
+};
 
 /**
  * The per-page selector pill, styled as a `layer-3` Menu trigger. Compose a `Menu.Trigger` through
  * the `render` prop; pass the visible size, the `sr-only` label, and the chevron as `children`.
  */
-export function PaginationPerPageTrigger({ render, ...props }: PaginationPerPageTriggerProps) {
+export function PaginationPerPageTrigger({
+  magnitude,
+  render,
+  ...props
+}: PaginationPerPageTriggerProps) {
   const defaultProps: useRender.ElementProps<"button"> = {
     ...(render == null ? { type: "button" } : null),
-    className: perPageTriggerVariants(),
+    className: perPageTriggerVariants({ magnitude }),
   };
 
   return useRender({
diff --git a/packages/propel/src/ui/pagination/pagination.stories.tsx b/packages/propel/src/ui/pagination/pagination.stories.tsx
index fc2a34b6..fe12aad9 100644
--- a/packages/propel/src/ui/pagination/pagination.stories.tsx
+++ b/packages/propel/src/ui/pagination/pagination.stories.tsx
@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { ChevronLeft, ChevronRight } from "lucide-react";
+import { ChevronLeft, ChevronRight, MoreHorizontal } from "lucide-react";
 import { expect } from "storybook/test";
 
 import { PaginationArrowButton, PaginationEllipsis, PaginationPageButton } from "./index";
@@ -12,7 +12,7 @@ const meta = {
   title: "UI/Pagination",
   component: PaginationPageButton,
   subcomponents: { PaginationArrowButton, PaginationEllipsis },
-  args: { current: false, children: "1" },
+  args: { current: false, children: "1", magnitude: "md" },
 } satisfies Meta<typeof PaginationPageButton>;
 
 export default meta;
@@ -27,13 +27,14 @@ export const Default: Story = {
     <nav aria-label="Pagination">
       <ul className="flex items-center gap-0.5">
         <li>
-          <PaginationArrowButton aria-label="Go to previous page" disabled>
+          <PaginationArrowButton magnitude="md" aria-label="Go to previous page" disabled>
             <ChevronLeft />
           </PaginationArrowButton>
         </li>
         {PAGES.map((n) => (
           <li key={n}>
             <PaginationPageButton
+              magnitude="md"
               current={n === 1}
               aria-current={n === 1 ? "page" : undefined}
               aria-label={`Go to page ${n}`}
@@ -44,7 +45,7 @@ export const Default: Story = {
           </li>
         ))}
         <li>
-          <PaginationArrowButton aria-label="Go to next page">
+          <PaginationArrowButton magnitude="md" aria-label="Go to next page">
             <ChevronRight />
           </PaginationArrowButton>
         </li>
@@ -66,13 +67,14 @@ export const WithEllipsis: Story = {
     <nav aria-label="Pagination">
       <ul className="flex items-center gap-0.5">
         <li>
-          <PaginationArrowButton aria-label="Go to previous page">
+          <PaginationArrowButton magnitude="md" aria-label="Go to previous page">
             <ChevronLeft />
           </PaginationArrowButton>
         </li>
         {[1, 2, 3].map((n) => (
           <li key={n}>
             <PaginationPageButton
+              magnitude="md"
               current={n === 2}
               aria-current={n === 2 ? "page" : undefined}
               aria-label={`Go to page ${n}`}
@@ -82,14 +84,16 @@ export const WithEllipsis: Story = {
             </PaginationPageButton>
           </li>
         ))}
-        <PaginationEllipsis />
+        <PaginationEllipsis magnitude="md">
+          <MoreHorizontal aria-hidden />
+        </PaginationEllipsis>
         <li>
-          <PaginationPageButton current={false} aria-label="Go to page 100">
+          <PaginationPageButton magnitude="md" current={false} aria-label="Go to page 100">
             100
           </PaginationPageButton>
         </li>
         <li>
-          <PaginationArrowButton aria-label="Go to next page">
+          <PaginationArrowButton magnitude="md" aria-label="Go to next page">
             <ChevronRight />
           </PaginationArrowButton>
         </li>
diff --git a/packages/propel/src/ui/pagination/variants.ts b/packages/propel/src/ui/pagination/variants.ts
index bf74e560..38d9af18 100644
--- a/packages/propel/src/ui/pagination/variants.ts
+++ b/packages/propel/src/ui/pagination/variants.ts
@@ -1,25 +1,29 @@
-import { cva, cx } from "class-variance-authority";
+import { cva } from "class-variance-authority";
 
 // Shared 24px slot used by page numbers, the prev/next buttons and the ellipsis.
 // 24px tall with a 24px minimum width so single digits stay square (per Figma),
 // but the slot grows for wider content — multi-digit page numbers like `100` get
 // their own width plus horizontal padding rather than clipping a fixed square.
 // `radius/sm` for page numbers, `radius/md` for the arrow buttons.
-export const slotBase = cx(
-  "inline-flex h-6 w-auto min-w-6 shrink-0 items-center justify-center px-1",
-  "text-13 text-primary outline-none",
-);
+const slotBase =
+  "inline-flex h-6 w-auto min-w-6 shrink-0 items-center justify-center px-1 text-13 text-primary outline-none";
+
+export type PaginationMagnitude = "md";
 
 export const pageButtonVariants = cva(
-  cx(
+  [
     slotBase,
     "rounded-sm bg-layer-transparent",
     "hover:bg-layer-transparent-hover",
     "focus-visible:ring-2 focus-visible:ring-accent-strong",
     "disabled:pointer-events-none disabled:text-disabled",
-  ),
+  ].join(" "),
   {
     variants: {
+      magnitude: {
+        // md: 24px tall, matches the Figma 24px slot — the only size defined so far.
+        md: "",
+      },
       // The current page reads as pressed: it sits on the `transparent-active` fill
       // (Figma "Selected") and is not interactive. It's marked `disabled` to block
       // re-navigation, but the Figma "Selected" state keeps `text/primary` — so it
@@ -33,7 +37,7 @@ export const pageButtonVariants = cva(
 );
 
 export const arrowButtonVariants = cva(
-  cx(
+  [
     slotBase,
     "rounded-md bg-layer-transparent text-icon-secondary",
     "hover:bg-layer-transparent-hover",
@@ -41,8 +45,30 @@ export const arrowButtonVariants = cva(
     "disabled:pointer-events-none disabled:text-icon-disabled",
     // Prev/next arrows are directional — mirror them under RTL so "previous" always
     // points toward the start of the run.
-    "[&_svg]:size-4 [&_svg]:shrink-0 rtl:[&_svg]:-scale-x-100",
-  ),
+    "[&>svg]:size-4 [&>svg]:shrink-0 rtl:[&>svg]:-scale-x-100",
+  ].join(" "),
+  {
+    variants: {
+      magnitude: {
+        // md: 24px tall, 16px icon — the only size defined so far.
+        md: "",
+      },
+    },
+  },
+);
+
+// The non-interactive gap marker between distant page numbers.
+// Sized via [&>svg] so the caller passes the icon as children (NodeSlot pattern).
+export const ellipsisVariants = cva(
+  [slotBase, "text-icon-placeholder", "[&>svg]:size-3.5 [&>svg]:shrink-0"].join(" "),
+  {
+    variants: {
+      magnitude: {
+        // md: 24px tall, 14px icon — the only size defined so far.
+        md: "",
+      },
+    },
+  },
 );
 
 // The per-page selector trigger (Figma `4762-503`): a `layer-3` pill, 24px tall,
@@ -50,12 +76,20 @@ export const arrowButtonVariants = cva(
 // page-size Menu, so it gets a focus ring and rotates its chevron while the menu
 // is open.
 export const perPageTriggerVariants = cva(
-  cx(
+  [
     "inline-flex h-6 min-w-10 cursor-default items-center justify-center gap-1 rounded-md px-2",
     "bg-layer-3 text-13 font-medium text-secondary outline-none",
     "hover:bg-layer-3-hover",
     "focus-visible:ring-2 focus-visible:ring-accent-strong",
-    "[&_svg]:size-3.5 [&_svg]:shrink-0 [&_svg]:text-icon-secondary",
-    "[&[data-popup-open]_svg]:rotate-180",
-  ),
+    "[&>svg]:size-3.5 [&>svg]:shrink-0 [&>svg]:text-icon-secondary",
+    "[&[data-popup-open]>svg]:rotate-180",
+  ].join(" "),
+  {
+    variants: {
+      magnitude: {
+        // md: 24px tall pill — the only size defined so far.
+        md: "",
+      },
+    },
+  },
 );

From 3e0de464b9312605abcec3bbb359c6ddbc434435 Mon Sep 17 00:00:00 2001
From: Aaron Reisman <aaron.reisman@plane.so>
Date: Tue, 23 Jun 2026 16:37:26 +0700
Subject: [PATCH 2/3] Extract pagination anatomy parts and move styling out of
 the components tier

Each ui/pagination part now renders exactly one element: add the
Pagination (nav), PaginationList, PaginationItem, PaginationPerPage,
PaginationPerPageIndicator, PaginationPerPageLabel, PaginationRange,
PaginationRangeCurrent and PaginationSpinner parts, and turn the ellipsis
into an icon slot. The components tier composes these parts and no longer
carries any className/cva/cx. Drop the single-value magnitude axis (the
24px Figma slot is the only size, so it's baked in).
---
 .../pagination/pagination.stories.tsx         |  28 +++++
 .../src/components/pagination/pagination.tsx  |  99 ++++++++-------
 packages/propel/src/ui/pagination/index.tsx   |  28 ++++-
 .../ui/pagination/pagination-arrow-button.tsx |  16 +--
 .../src/ui/pagination/pagination-ellipsis.tsx |  23 ++--
 .../src/ui/pagination/pagination-item.tsx     |  10 ++
 .../src/ui/pagination/pagination-list.tsx     |  13 ++
 .../ui/pagination/pagination-page-button.tsx  |  12 +-
 .../pagination-per-page-indicator.tsx         |  17 +++
 .../pagination/pagination-per-page-label.tsx  |  16 +++
 .../pagination-per-page-trigger.tsx           |  18 +--
 .../src/ui/pagination/pagination-per-page.tsx |  13 ++
 .../pagination/pagination-range-current.tsx   |  16 +++
 .../src/ui/pagination/pagination-range.tsx    |  13 ++
 .../src/ui/pagination/pagination-spinner.tsx  |  17 +++
 .../src/ui/pagination/pagination.stories.tsx  |  90 +++++++------
 .../propel/src/ui/pagination/pagination.tsx   |  13 ++
 packages/propel/src/ui/pagination/variants.ts | 118 +++++++++++-------
 18 files changed, 381 insertions(+), 179 deletions(-)
 create mode 100644 packages/propel/src/ui/pagination/pagination-item.tsx
 create mode 100644 packages/propel/src/ui/pagination/pagination-list.tsx
 create mode 100644 packages/propel/src/ui/pagination/pagination-per-page-indicator.tsx
 create mode 100644 packages/propel/src/ui/pagination/pagination-per-page-label.tsx
 create mode 100644 packages/propel/src/ui/pagination/pagination-per-page.tsx
 create mode 100644 packages/propel/src/ui/pagination/pagination-range-current.tsx
 create mode 100644 packages/propel/src/ui/pagination/pagination-range.tsx
 create mode 100644 packages/propel/src/ui/pagination/pagination-spinner.tsx
 create mode 100644 packages/propel/src/ui/pagination/pagination.tsx

diff --git a/packages/propel/src/components/pagination/pagination.stories.tsx b/packages/propel/src/components/pagination/pagination.stories.tsx
index 761bb29c..a844039c 100644
--- a/packages/propel/src/components/pagination/pagination.stories.tsx
+++ b/packages/propel/src/components/pagination/pagination.stories.tsx
@@ -2,11 +2,39 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import * as React from "react";
 import { expect, fn, userEvent, waitFor, within } from "storybook/test";
 
+import {
+  PaginationArrowButton,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationList,
+  PaginationPageButton,
+  PaginationPerPage,
+  PaginationPerPageIndicator,
+  PaginationPerPageLabel,
+  PaginationPerPageTrigger,
+  PaginationRange,
+  PaginationRangeCurrent,
+  PaginationSpinner,
+} from "../../ui/pagination/index";
 import { Pagination } from "./index";
 
 const meta = {
   title: "Components/Pagination",
   component: Pagination,
+  subcomponents: {
+    PaginationList,
+    PaginationItem,
+    PaginationPageButton,
+    PaginationArrowButton,
+    PaginationEllipsis,
+    PaginationSpinner,
+    PaginationPerPage,
+    PaginationPerPageTrigger,
+    PaginationPerPageIndicator,
+    PaginationPerPageLabel,
+    PaginationRange,
+    PaginationRangeCurrent,
+  },
   parameters: {
     design: {
       type: "figma",
diff --git a/packages/propel/src/components/pagination/pagination.tsx b/packages/propel/src/components/pagination/pagination.tsx
index 8c16ca52..3c03d3f4 100644
--- a/packages/propel/src/components/pagination/pagination.tsx
+++ b/packages/propel/src/components/pagination/pagination.tsx
@@ -3,10 +3,19 @@ import * as React from "react";
 
 import { Menu, MenuTrigger } from "../../ui/menu/index";
 import {
+  Pagination as PaginationRoot,
   PaginationArrowButton,
   PaginationEllipsis,
+  PaginationItem,
+  PaginationList,
   PaginationPageButton,
+  PaginationPerPage,
+  PaginationPerPageIndicator,
+  PaginationPerPageLabel,
   PaginationPerPageTrigger,
+  PaginationRange,
+  PaginationRangeCurrent,
+  PaginationSpinner,
 } from "../../ui/pagination/index";
 import { MenuContent, MenuItem } from "../menu/index";
 
@@ -16,17 +25,8 @@ import { MenuContent, MenuItem } from "../menu/index";
 // at render time from `page`/`pageCount` — never a prop. What designers can toggle is
 // genuinely additive: an optional per-page selector and an optional range label.
 //
-// Tokens (Figma node 4762-503):
-// - page-number button: 24px square, radius/sm (4px), text/13, transparent bg that
-//   fills to `layer-transparent-hover` on hover and `layer-transparent-active` when
-//   it is the current page; disabled/loading dim to the placeholder/disabled colors.
-// - prev/next: 24px square icon buttons, radius/md (6px), 16px arrows. The arrows are
-//   directional, so they mirror in RTL via `rtl:-scale-x-100`.
-// - ellipsis: a non-interactive 24px slot holding a 14px more-horizontal glyph.
-// - per-page selector: a `layer-3` pill, 24px tall, radius/md, "50" + chevron-down,
-//   followed by "per page" tertiary text. The pill is the trigger for a propel
-//   Menu (single-select) whose menu lists the page-size options; picking one
-//   reports it through `pageSize.onValueChange`.
+// This components tier only COMPOSES the `ui/pagination` parts (each a single styled
+// element); all chrome lives in their cva — there is no className/cva/cx here.
 
 // Builds the sequence of visible page tokens. Always shows the first and last page;
 // shows up to one neighbour either side of the current page; inserts an ellipsis
@@ -89,7 +89,7 @@ export type PaginationLabels = {
   /** Visible text on the per-page selector trigger, given the size. Defaults to `"50"`. */
   perPageValue: (pageSize: number) => React.ReactNode;
   /** Trailing text after the per-page selector. Defaults to `"per page"`. */
-  perPage: React.ReactNode;
+  perPage: string;
 };
 
 const DEFAULT_LABELS: PaginationLabels = {
@@ -165,22 +165,25 @@ export function Pagination({
   const atEnd = page >= pageCount;
 
   return (
-    <nav aria-label={l.root} className="flex items-center gap-4" {...props}>
+    <PaginationRoot aria-label={l.root} {...props}>
       {pageSize ? (
-        <div className="flex min-w-0 flex-1 items-center gap-2">
+        <PaginationPerPage>
           {/*
             The selector is the propel Menu (single-select): the `layer-3` pill is
             its trigger and the menu lists the page sizes, the current one marked with a
-            trailing check. The trigger carries the accessible name (the visible size +
-            the visually-hidden "per page"), and picking a size reports it through
-            `pageSize.onValueChange`. Keyboard works via the Menu (Enter/ArrowDown opens,
-            arrows move, Enter selects).
+            trailing check. The trigger carries the accessible name "<size> per page",
+            and picking a size reports it through `pageSize.onValueChange`. Keyboard
+            works via the Menu (Enter/ArrowDown opens, arrows move, Enter selects).
           */}
           <Menu>
-            <MenuTrigger render={<PaginationPerPageTrigger magnitude="md" />}>
-              <span>{l.perPageValue(pageSize.value)}</span>
-              <span className="sr-only">{l.perPage}</span>
-              <ChevronDown aria-hidden className="transition-transform" />
+            <MenuTrigger
+              render={<PaginationPerPageTrigger />}
+              aria-label={`${pageSize.value} ${l.perPage}`}
+            >
+              {l.perPageValue(pageSize.value)}
+              <PaginationPerPageIndicator>
+                <ChevronDown />
+              </PaginationPerPageIndicator>
             </MenuTrigger>
             <MenuContent width="anchor" align="center">
               {pageSize.options.map((option) => (
@@ -194,45 +197,43 @@ export function Pagination({
               ))}
             </MenuContent>
           </Menu>
-          <span aria-hidden className="text-13 whitespace-nowrap text-tertiary">
-            {l.perPage}
-          </span>
-        </div>
+          <PaginationPerPageLabel>{l.perPage}</PaginationPerPageLabel>
+        </PaginationPerPage>
       ) : null}
 
       {range ? (
-        <p className="text-12 whitespace-nowrap text-tertiary">
-          <span className="text-primary">{range.current}</span>
-          <span>{" of "}</span>
-          <span>{range.total}</span>
-        </p>
+        <PaginationRange>
+          <PaginationRangeCurrent>{range.current}</PaginationRangeCurrent>
+          {" of "}
+          {range.total}
+        </PaginationRange>
       ) : null}
 
-      <ul className="flex items-center gap-1.5">
-        <li>
+      <PaginationList>
+        <PaginationItem>
           <PaginationArrowButton
-            magnitude="md"
             aria-label={l.previous}
             disabled={atStart}
             onClick={() => onPageChange(page - 1)}
           >
             <ArrowLeft aria-hidden />
           </PaginationArrowButton>
-        </li>
+        </PaginationItem>
 
         {tokens.map((token) => {
           if (token === "ellipsis-start" || token === "ellipsis-end") {
             return (
-              <PaginationEllipsis key={token} magnitude="md">
-                <MoreHorizontal aria-hidden />
-              </PaginationEllipsis>
+              <PaginationItem key={token}>
+                <PaginationEllipsis>
+                  <MoreHorizontal />
+                </PaginationEllipsis>
+              </PaginationItem>
             );
           }
           const isCurrent = token === page;
           return (
-            <li key={token}>
+            <PaginationItem key={token}>
               <PaginationPageButton
-                magnitude="md"
                 aria-label={l.page(token)}
                 aria-current={isCurrent ? "page" : undefined}
                 current={isCurrent}
@@ -240,29 +241,27 @@ export function Pagination({
                 onClick={() => onPageChange(token)}
               >
                 {isCurrent && loading ? (
-                  <LoaderCircle
-                    aria-hidden
-                    className="size-3.5 shrink-0 animate-spin text-icon-placeholder"
-                  />
+                  <PaginationSpinner>
+                    <LoaderCircle />
+                  </PaginationSpinner>
                 ) : (
                   token
                 )}
               </PaginationPageButton>
-            </li>
+            </PaginationItem>
           );
         })}
 
-        <li>
+        <PaginationItem>
           <PaginationArrowButton
-            magnitude="md"
             aria-label={l.next}
             disabled={atEnd}
             onClick={() => onPageChange(page + 1)}
           >
             <ArrowRight aria-hidden />
           </PaginationArrowButton>
-        </li>
-      </ul>
-    </nav>
+        </PaginationItem>
+      </PaginationList>
+    </PaginationRoot>
   );
 }
diff --git a/packages/propel/src/ui/pagination/index.tsx b/packages/propel/src/ui/pagination/index.tsx
index 14112daf..6a1395f8 100644
--- a/packages/propel/src/ui/pagination/index.tsx
+++ b/packages/propel/src/ui/pagination/index.tsx
@@ -1,14 +1,40 @@
+export { Pagination, type PaginationProps } from "./pagination";
 export { PaginationArrowButton, type PaginationArrowButtonProps } from "./pagination-arrow-button";
 export { PaginationEllipsis, type PaginationEllipsisProps } from "./pagination-ellipsis";
+export { PaginationItem, type PaginationItemProps } from "./pagination-item";
+export { PaginationList, type PaginationListProps } from "./pagination-list";
 export { PaginationPageButton, type PaginationPageButtonProps } from "./pagination-page-button";
+export { PaginationPerPage, type PaginationPerPageProps } from "./pagination-per-page";
+export {
+  PaginationPerPageIndicator,
+  type PaginationPerPageIndicatorProps,
+} from "./pagination-per-page-indicator";
+export {
+  PaginationPerPageLabel,
+  type PaginationPerPageLabelProps,
+} from "./pagination-per-page-label";
 export {
   PaginationPerPageTrigger,
   type PaginationPerPageTriggerProps,
 } from "./pagination-per-page-trigger";
+export { PaginationRange, type PaginationRangeProps } from "./pagination-range";
+export {
+  PaginationRangeCurrent,
+  type PaginationRangeCurrentProps,
+} from "./pagination-range-current";
+export { PaginationSpinner, type PaginationSpinnerProps } from "./pagination-spinner";
 export {
   arrowButtonVariants,
   ellipsisVariants,
   pageButtonVariants,
+  paginationItemVariants,
+  paginationListVariants,
+  paginationVariants,
+  perPageIndicatorVariants,
+  perPageLabelVariants,
   perPageTriggerVariants,
-  type PaginationMagnitude,
+  perPageVariants,
+  rangeCurrentVariants,
+  rangeVariants,
+  spinnerVariants,
 } from "./variants";
diff --git a/packages/propel/src/ui/pagination/pagination-arrow-button.tsx b/packages/propel/src/ui/pagination/pagination-arrow-button.tsx
index 51eff57c..9f7fbd16 100644
--- a/packages/propel/src/ui/pagination/pagination-arrow-button.tsx
+++ b/packages/propel/src/ui/pagination/pagination-arrow-button.tsx
@@ -1,20 +1,16 @@
 import type * as React from "react";
 
-import { type PaginationMagnitude, arrowButtonVariants } from "./variants";
+import { arrowButtonVariants } from "./variants";
 
 export type PaginationArrowButtonProps = Omit<
   React.ComponentProps<"button">,
   "className" | "style"
-> & {
-  /** Size of the slot. Pass the icon as `children`; it is sized via `[&>svg]`. */
-  magnitude: PaginationMagnitude;
-};
+>;
 
 /**
- * A styled prev/next arrow button. Applies `arrowButtonVariants({ magnitude })`; pass the
- * (directional, RTL-mirrored) arrow icon as `children` and wire `aria-label`/`disabled`/`onClick`
- * through props.
+ * A styled prev/next arrow button. Applies `arrowButtonVariants()`; pass the (directional,
+ * RTL-mirrored) arrow icon as `children` and wire `aria-label`/`disabled`/`onClick` through props.
  */
-export function PaginationArrowButton({ magnitude, ...props }: PaginationArrowButtonProps) {
-  return <button type="button" className={arrowButtonVariants({ magnitude })} {...props} />;
+export function PaginationArrowButton(props: PaginationArrowButtonProps) {
+  return <button type="button" className={arrowButtonVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-ellipsis.tsx b/packages/propel/src/ui/pagination/pagination-ellipsis.tsx
index cdc6a329..2d115e9e 100644
--- a/packages/propel/src/ui/pagination/pagination-ellipsis.tsx
+++ b/packages/propel/src/ui/pagination/pagination-ellipsis.tsx
@@ -1,20 +1,17 @@
 import type * as React from "react";
 
-import { type PaginationMagnitude, ellipsisVariants } from "./variants";
+import { ellipsisVariants } from "./variants";
 
-export type PaginationEllipsisProps = {
-  magnitude: PaginationMagnitude;
-  children: React.ReactNode;
-};
+export type PaginationEllipsisProps = Omit<
+  React.ComponentPropsWithoutRef<"span">,
+  "className" | "style"
+>;
 
 /**
- * A non-interactive gap marker between distant page numbers. Pass the ellipsis icon as `children`;
- * it is sized via `[&>svg]`.
+ * A non-interactive gap marker between distant page numbers. Renders whatever icon you pass (sized
+ * to the slot's `--node-size`, 14px) — never baking a specific glyph in. Decorative, so
+ * `aria-hidden`.
  */
-export function PaginationEllipsis({ magnitude, children }: PaginationEllipsisProps) {
-  return (
-    <li aria-hidden className={ellipsisVariants({ magnitude })}>
-      {children}
-    </li>
-  );
+export function PaginationEllipsis(props: PaginationEllipsisProps) {
+  return <span aria-hidden className={ellipsisVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-item.tsx b/packages/propel/src/ui/pagination/pagination-item.tsx
new file mode 100644
index 00000000..3a7345d8
--- /dev/null
+++ b/packages/propel/src/ui/pagination/pagination-item.tsx
@@ -0,0 +1,10 @@
+import type * as React from "react";
+
+import { paginationItemVariants } from "./variants";
+
+export type PaginationItemProps = Omit<React.ComponentProps<"li">, "className" | "style">;
+
+/** One slot in the pagination list, holding a page button, an arrow button, or the ellipsis. */
+export function PaginationItem(props: PaginationItemProps) {
+  return <li className={paginationItemVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/pagination/pagination-list.tsx b/packages/propel/src/ui/pagination/pagination-list.tsx
new file mode 100644
index 00000000..d23668ba
--- /dev/null
+++ b/packages/propel/src/ui/pagination/pagination-list.tsx
@@ -0,0 +1,13 @@
+import type * as React from "react";
+
+import { paginationListVariants } from "./variants";
+
+export type PaginationListProps = Omit<React.ComponentProps<"ul">, "className" | "style">;
+
+/**
+ * The ordered list of page controls: the previous button, page numbers and ellipses, and the next
+ * button.
+ */
+export function PaginationList(props: PaginationListProps) {
+  return <ul className={paginationListVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/pagination/pagination-page-button.tsx b/packages/propel/src/ui/pagination/pagination-page-button.tsx
index 4feb25f9..cc5d819e 100644
--- a/packages/propel/src/ui/pagination/pagination-page-button.tsx
+++ b/packages/propel/src/ui/pagination/pagination-page-button.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { type PaginationMagnitude, pageButtonVariants } from "./variants";
+import { pageButtonVariants } from "./variants";
 
 export type PaginationPageButtonProps = Omit<
   React.ComponentProps<"button">,
@@ -8,14 +8,12 @@ export type PaginationPageButtonProps = Omit<
 > & {
   /** Whether this button represents the current page (renders the pressed/selected fill). */
   current: boolean;
-  /** Size of the slot. */
-  magnitude: PaginationMagnitude;
 };
 
 /**
- * A styled page-number button. Applies `pageButtonVariants({ current, magnitude })`; pass the page
- * number (or a loading spinner) as `children` and wire `aria-current`/`onClick` through props.
+ * A styled page-number button. Applies `pageButtonVariants({ current })`; pass the page number (or
+ * a loading spinner) as `children` and wire `aria-current`/`onClick` through props.
  */
-export function PaginationPageButton({ current, magnitude, ...props }: PaginationPageButtonProps) {
-  return <button type="button" className={pageButtonVariants({ current, magnitude })} {...props} />;
+export function PaginationPageButton({ current, ...props }: PaginationPageButtonProps) {
+  return <button type="button" className={pageButtonVariants({ current })} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-per-page-indicator.tsx b/packages/propel/src/ui/pagination/pagination-per-page-indicator.tsx
new file mode 100644
index 00000000..7796b41a
--- /dev/null
+++ b/packages/propel/src/ui/pagination/pagination-per-page-indicator.tsx
@@ -0,0 +1,17 @@
+import type * as React from "react";
+
+import { perPageIndicatorVariants } from "./variants";
+
+export type PaginationPerPageIndicatorProps = Omit<
+  React.ComponentPropsWithoutRef<"span">,
+  "className" | "style"
+>;
+
+/**
+ * The chevron inside the per-page trigger. Renders whatever icon you pass (sized to `--node-size`,
+ * 14px) and rotates a half-turn while the menu is open. Decorative — the trigger carries the
+ * accessible name and state — so `aria-hidden`.
+ */
+export function PaginationPerPageIndicator(props: PaginationPerPageIndicatorProps) {
+  return <span aria-hidden className={perPageIndicatorVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/pagination/pagination-per-page-label.tsx b/packages/propel/src/ui/pagination/pagination-per-page-label.tsx
new file mode 100644
index 00000000..da6ca7c5
--- /dev/null
+++ b/packages/propel/src/ui/pagination/pagination-per-page-label.tsx
@@ -0,0 +1,16 @@
+import type * as React from "react";
+
+import { perPageLabelVariants } from "./variants";
+
+export type PaginationPerPageLabelProps = Omit<
+  React.ComponentPropsWithoutRef<"span">,
+  "className" | "style"
+>;
+
+/**
+ * The trailing "per page" text after the selector pill (Figma `50 v per page`). Decorative, so
+ * `aria-hidden`.
+ */
+export function PaginationPerPageLabel(props: PaginationPerPageLabelProps) {
+  return <span aria-hidden className={perPageLabelVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx b/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx
index ccffa0a1..b02ea3d8 100644
--- a/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx
+++ b/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx
@@ -1,28 +1,22 @@
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
 
-import { type PaginationMagnitude, perPageTriggerVariants } from "./variants";
+import { perPageTriggerVariants } from "./variants";
 
 export type PaginationPerPageTriggerProps = Omit<
   useRender.ComponentProps<"button">,
   "className" | "style"
-> & {
-  /** Size of the trigger pill. */
-  magnitude: PaginationMagnitude;
-};
+>;
 
 /**
  * The per-page selector pill, styled as a `layer-3` Menu trigger. Compose a `Menu.Trigger` through
- * the `render` prop; pass the visible size, the `sr-only` label, and the chevron as `children`.
+ * the `render` prop; pass the visible size and the `PaginationPerPageIndicator` chevron as
+ * children.
  */
-export function PaginationPerPageTrigger({
-  magnitude,
-  render,
-  ...props
-}: PaginationPerPageTriggerProps) {
+export function PaginationPerPageTrigger({ render, ...props }: PaginationPerPageTriggerProps) {
   const defaultProps: useRender.ElementProps<"button"> = {
     ...(render == null ? { type: "button" } : null),
-    className: perPageTriggerVariants({ magnitude }),
+    className: perPageTriggerVariants(),
   };
 
   return useRender({
diff --git a/packages/propel/src/ui/pagination/pagination-per-page.tsx b/packages/propel/src/ui/pagination/pagination-per-page.tsx
new file mode 100644
index 00000000..689bd72e
--- /dev/null
+++ b/packages/propel/src/ui/pagination/pagination-per-page.tsx
@@ -0,0 +1,13 @@
+import type * as React from "react";
+
+import { perPageVariants } from "./variants";
+
+export type PaginationPerPageProps = Omit<React.ComponentProps<"div">, "className" | "style">;
+
+/**
+ * The per-page region: the selector pill (`PaginationPerPageTrigger`) followed by the trailing
+ * `PaginationPerPageLabel`.
+ */
+export function PaginationPerPage(props: PaginationPerPageProps) {
+  return <div className={perPageVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/pagination/pagination-range-current.tsx b/packages/propel/src/ui/pagination/pagination-range-current.tsx
new file mode 100644
index 00000000..e0ec0470
--- /dev/null
+++ b/packages/propel/src/ui/pagination/pagination-range-current.tsx
@@ -0,0 +1,16 @@
+import type * as React from "react";
+
+import { rangeCurrentVariants } from "./variants";
+
+export type PaginationRangeCurrentProps = Omit<
+  React.ComponentPropsWithoutRef<"span">,
+  "className" | "style"
+>;
+
+/**
+ * The emphasized current-range portion (e.g. `1-50`) inside `PaginationRange`, in the primary text
+ * color.
+ */
+export function PaginationRangeCurrent(props: PaginationRangeCurrentProps) {
+  return <span className={rangeCurrentVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/pagination/pagination-range.tsx b/packages/propel/src/ui/pagination/pagination-range.tsx
new file mode 100644
index 00000000..c767321e
--- /dev/null
+++ b/packages/propel/src/ui/pagination/pagination-range.tsx
@@ -0,0 +1,13 @@
+import type * as React from "react";
+
+import { rangeVariants } from "./variants";
+
+export type PaginationRangeProps = Omit<React.ComponentProps<"p">, "className" | "style">;
+
+/**
+ * The optional range label shown before the controls (Figma `1-50 of 250`): tertiary, nowrap. The
+ * current range inside it is emphasized via `PaginationRangeCurrent`.
+ */
+export function PaginationRange(props: PaginationRangeProps) {
+  return <p className={rangeVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/pagination/pagination-spinner.tsx b/packages/propel/src/ui/pagination/pagination-spinner.tsx
new file mode 100644
index 00000000..7d285fc2
--- /dev/null
+++ b/packages/propel/src/ui/pagination/pagination-spinner.tsx
@@ -0,0 +1,17 @@
+import type * as React from "react";
+
+import { spinnerVariants } from "./variants";
+
+export type PaginationSpinnerProps = Omit<
+  React.ComponentPropsWithoutRef<"span">,
+  "className" | "style"
+>;
+
+/**
+ * The in-flight indicator a page button shows in place of its number while navigating to it. Spins
+ * whatever icon you pass, sized to `--node-size` (14px) and tinted the placeholder color.
+ * Decorative, so `aria-hidden`.
+ */
+export function PaginationSpinner(props: PaginationSpinnerProps) {
+  return <span aria-hidden className={spinnerVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/pagination/pagination.stories.tsx b/packages/propel/src/ui/pagination/pagination.stories.tsx
index fe12aad9..abdf39ab 100644
--- a/packages/propel/src/ui/pagination/pagination.stories.tsx
+++ b/packages/propel/src/ui/pagination/pagination.stories.tsx
@@ -2,17 +2,31 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { ChevronLeft, ChevronRight, MoreHorizontal } from "lucide-react";
 import { expect } from "storybook/test";
 
-import { PaginationArrowButton, PaginationEllipsis, PaginationPageButton } from "./index";
+import {
+  Pagination,
+  PaginationArrowButton,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationList,
+  PaginationPageButton,
+} from "./index";
 
-// UI-tier story: composes the ATOMIC pagination parts (each renders a single styled control).
+// UI-tier story: composes the ATOMIC pagination parts (each renders a single element).
 // The components-tier `Pagination` story owns the truncation logic, the per-page Menu and the
-// range label. Here you lay out the raw slots yourself inside a `<nav>` › `<ul>`: prev/next
-// arrows, page-number buttons (one marked `current`), and the non-interactive ellipsis.
+// range label. Here you lay out the raw slots yourself: the `Pagination` nav wraps a
+// `PaginationList`, whose `PaginationItem`s hold prev/next arrows, page-number buttons (one
+// marked `current`), and the non-interactive ellipsis (an icon slot).
 const meta = {
   title: "UI/Pagination",
   component: PaginationPageButton,
-  subcomponents: { PaginationArrowButton, PaginationEllipsis },
-  args: { current: false, children: "1", magnitude: "md" },
+  subcomponents: {
+    Pagination,
+    PaginationList,
+    PaginationItem,
+    PaginationArrowButton,
+    PaginationEllipsis,
+  },
+  args: { current: false, children: "1" },
 } satisfies Meta<typeof PaginationPageButton>;
 
 export default meta;
@@ -24,17 +38,16 @@ const PAGES = [1, 2, 3, 4, 5];
 export const Default: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <nav aria-label="Pagination">
-      <ul className="flex items-center gap-0.5">
-        <li>
-          <PaginationArrowButton magnitude="md" aria-label="Go to previous page" disabled>
+    <Pagination aria-label="Pagination">
+      <PaginationList>
+        <PaginationItem>
+          <PaginationArrowButton aria-label="Go to previous page" disabled>
             <ChevronLeft />
           </PaginationArrowButton>
-        </li>
+        </PaginationItem>
         {PAGES.map((n) => (
-          <li key={n}>
+          <PaginationItem key={n}>
             <PaginationPageButton
-              magnitude="md"
               current={n === 1}
               aria-current={n === 1 ? "page" : undefined}
               aria-label={`Go to page ${n}`}
@@ -42,15 +55,15 @@ export const Default: Story = {
             >
               {n}
             </PaginationPageButton>
-          </li>
+          </PaginationItem>
         ))}
-        <li>
-          <PaginationArrowButton magnitude="md" aria-label="Go to next page">
+        <PaginationItem>
+          <PaginationArrowButton aria-label="Go to next page">
             <ChevronRight />
           </PaginationArrowButton>
-        </li>
-      </ul>
-    </nav>
+        </PaginationItem>
+      </PaginationList>
+    </Pagination>
   ),
   play: async ({ canvas }) => {
     // Page 1 is current (pressed fill + aria-current) and the prev arrow is disabled at the start.
@@ -64,17 +77,16 @@ export const Default: Story = {
 export const WithEllipsis: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <nav aria-label="Pagination">
-      <ul className="flex items-center gap-0.5">
-        <li>
-          <PaginationArrowButton magnitude="md" aria-label="Go to previous page">
+    <Pagination aria-label="Pagination">
+      <PaginationList>
+        <PaginationItem>
+          <PaginationArrowButton aria-label="Go to previous page">
             <ChevronLeft />
           </PaginationArrowButton>
-        </li>
+        </PaginationItem>
         {[1, 2, 3].map((n) => (
-          <li key={n}>
+          <PaginationItem key={n}>
             <PaginationPageButton
-              magnitude="md"
               current={n === 2}
               aria-current={n === 2 ? "page" : undefined}
               aria-label={`Go to page ${n}`}
@@ -82,23 +94,25 @@ export const WithEllipsis: Story = {
             >
               {n}
             </PaginationPageButton>
-          </li>
+          </PaginationItem>
         ))}
-        <PaginationEllipsis magnitude="md">
-          <MoreHorizontal aria-hidden />
-        </PaginationEllipsis>
-        <li>
-          <PaginationPageButton magnitude="md" current={false} aria-label="Go to page 100">
+        <PaginationItem>
+          <PaginationEllipsis>
+            <MoreHorizontal />
+          </PaginationEllipsis>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationPageButton current={false} aria-label="Go to page 100">
             100
           </PaginationPageButton>
-        </li>
-        <li>
-          <PaginationArrowButton magnitude="md" aria-label="Go to next page">
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationArrowButton aria-label="Go to next page">
             <ChevronRight />
           </PaginationArrowButton>
-        </li>
-      </ul>
-    </nav>
+        </PaginationItem>
+      </PaginationList>
+    </Pagination>
   ),
 };
 
diff --git a/packages/propel/src/ui/pagination/pagination.tsx b/packages/propel/src/ui/pagination/pagination.tsx
new file mode 100644
index 00000000..0b4fdf4c
--- /dev/null
+++ b/packages/propel/src/ui/pagination/pagination.tsx
@@ -0,0 +1,13 @@
+import type * as React from "react";
+
+import { paginationVariants } from "./variants";
+
+export type PaginationProps = Omit<React.ComponentProps<"nav">, "className" | "style">;
+
+/**
+ * The pagination landmark: a `<nav>` wrapping the optional per-page region, range label, and the
+ * page-control list.
+ */
+export function Pagination(props: PaginationProps) {
+  return <nav className={paginationVariants()} {...props} />;
+}
diff --git a/packages/propel/src/ui/pagination/variants.ts b/packages/propel/src/ui/pagination/variants.ts
index 38d9af18..63e30564 100644
--- a/packages/propel/src/ui/pagination/variants.ts
+++ b/packages/propel/src/ui/pagination/variants.ts
@@ -1,29 +1,45 @@
-import { cva } from "class-variance-authority";
+import { cva, cx } from "class-variance-authority";
+
+import { nodeSlotClass } from "../../internal/node-slot";
+
+// Pagination is a structural navigation primitive: the Figma "variant" axis (all
+// pages visible / near start / middle / near end) is a function of where the current
+// page sits in the total, not a styling axis — so the parts carry only static chrome
+// and the `current` page state. Every part renders ONE element, with its className held
+// in the cva below so no `className` crosses the part boundary. The Figma 24px slot is
+// the only defined size, so it is baked in (no size/magnitude axis to expose).
+
+// The `<nav>` landmark wrapping the whole control: the optional per-page region and
+// range label sit before the page-button list, laid out in a row.
+export const paginationVariants = cva("flex items-center gap-4");
+
+// The ordered list of page controls (prev, page numbers + ellipses, next).
+export const paginationListVariants = cva("flex items-center gap-1.5");
+
+// One slot in the list. A bare list item; its child (a button or the ellipsis) carries
+// the chrome.
+export const paginationItemVariants = cva("flex items-center");
 
 // Shared 24px slot used by page numbers, the prev/next buttons and the ellipsis.
 // 24px tall with a 24px minimum width so single digits stay square (per Figma),
 // but the slot grows for wider content — multi-digit page numbers like `100` get
 // their own width plus horizontal padding rather than clipping a fixed square.
 // `radius/sm` for page numbers, `radius/md` for the arrow buttons.
-const slotBase =
-  "inline-flex h-6 w-auto min-w-6 shrink-0 items-center justify-center px-1 text-13 text-primary outline-none";
-
-export type PaginationMagnitude = "md";
+const slotBase = cx(
+  "inline-flex h-6 w-auto min-w-6 shrink-0 items-center justify-center px-1",
+  "text-13 text-primary outline-none",
+);
 
 export const pageButtonVariants = cva(
-  [
+  cx(
     slotBase,
     "rounded-sm bg-layer-transparent",
     "hover:bg-layer-transparent-hover",
     "focus-visible:ring-2 focus-visible:ring-accent-strong",
     "disabled:pointer-events-none disabled:text-disabled",
-  ].join(" "),
+  ),
   {
     variants: {
-      magnitude: {
-        // md: 24px tall, matches the Figma 24px slot — the only size defined so far.
-        md: "",
-      },
       // The current page reads as pressed: it sits on the `transparent-active` fill
       // (Figma "Selected") and is not interactive. It's marked `disabled` to block
       // re-navigation, but the Figma "Selected" state keeps `text/primary` — so it
@@ -37,59 +53,65 @@ export const pageButtonVariants = cva(
 );
 
 export const arrowButtonVariants = cva(
-  [
+  cx(
     slotBase,
     "rounded-md bg-layer-transparent text-icon-secondary",
     "hover:bg-layer-transparent-hover",
     "focus-visible:ring-2 focus-visible:ring-accent-strong",
     "disabled:pointer-events-none disabled:text-icon-disabled",
     // Prev/next arrows are directional — mirror them under RTL so "previous" always
-    // points toward the start of the run.
+    // points toward the start of the run. Sizes whatever svg is passed to 16px.
     "[&>svg]:size-4 [&>svg]:shrink-0 rtl:[&>svg]:-scale-x-100",
-  ].join(" "),
-  {
-    variants: {
-      magnitude: {
-        // md: 24px tall, 16px icon — the only size defined so far.
-        md: "",
-      },
-    },
-  },
+  ),
 );
 
-// The non-interactive gap marker between distant page numbers.
-// Sized via [&>svg] so the caller passes the icon as children (NodeSlot pattern).
+// A non-interactive gap marker between distant page numbers. Sizes its single child
+// (the more-horizontal glyph, 14px) via the shared node-slot class and tints it the
+// placeholder color, instead of baking a specific glyph/size in.
 export const ellipsisVariants = cva(
-  [slotBase, "text-icon-placeholder", "[&>svg]:size-3.5 [&>svg]:shrink-0"].join(" "),
-  {
-    variants: {
-      magnitude: {
-        // md: 24px tall, 14px icon — the only size defined so far.
-        md: "",
-      },
-    },
-  },
+  cx(slotBase, "text-icon-placeholder [--node-size:0.875rem]", nodeSlotClass),
+);
+
+// The current page can render a spinner in place of its number while navigating to it
+// is in flight. A node-slot sized to 14px that spins its child; placeholder tint.
+export const spinnerVariants = cva(
+  cx(nodeSlotClass, "animate-spin text-icon-placeholder [--node-size:0.875rem]"),
 );
 
+// The per-page region (Figma `50 v per page`): the selector pill followed by the
+// trailing "per page" text. Grows to fill the leading space before the page list.
+export const perPageVariants = cva("flex min-w-0 flex-1 items-center gap-2");
+
 // The per-page selector trigger (Figma `4762-503`): a `layer-3` pill, 24px tall,
 // `radius/md`, holding the current size + a chevron-down. It's the trigger for the
-// page-size Menu, so it gets a focus ring and rotates its chevron while the menu
-// is open.
+// page-size Menu, so it gets a focus ring; the `group` lets its chevron indicator
+// rotate while the menu is open.
 export const perPageTriggerVariants = cva(
-  [
-    "inline-flex h-6 min-w-10 cursor-default items-center justify-center gap-1 rounded-md px-2",
+  cx(
+    "group inline-flex h-6 min-w-10 cursor-default items-center justify-center gap-1 rounded-md px-2",
     "bg-layer-3 text-13 font-medium text-secondary outline-none",
     "hover:bg-layer-3-hover",
     "focus-visible:ring-2 focus-visible:ring-accent-strong",
-    "[&>svg]:size-3.5 [&>svg]:shrink-0 [&>svg]:text-icon-secondary",
-    "[&[data-popup-open]>svg]:rotate-180",
-  ].join(" "),
-  {
-    variants: {
-      magnitude: {
-        // md: 24px tall pill — the only size defined so far.
-        md: "",
-      },
-    },
-  },
+  ),
+);
+
+// The chevron indicator inside the per-page trigger. Sizes its single child (14px) and
+// rotates a half-turn while the menu is open (Base UI sets `data-popup-open` on the
+// trigger, which carries the `group` class).
+export const perPageIndicatorVariants = cva(
+  cx(
+    nodeSlotClass,
+    "text-icon-secondary [--node-size:0.875rem]",
+    "transition-transform duration-200 group-data-popup-open:rotate-180",
+  ),
 );
+
+// The trailing "per page" text after the selector pill.
+export const perPageLabelVariants = cva("text-13 whitespace-nowrap text-tertiary");
+
+// The optional range label shown before the controls (Figma `1-50 of 250`): tertiary,
+// nowrap. The current range inside it is emphasized via `PaginationRangeCurrent`.
+export const rangeVariants = cva("text-12 whitespace-nowrap text-tertiary");
+
+// The emphasized current-range portion (e.g. `1-50`) inside `PaginationRange`.
+export const rangeCurrentVariants = cva("text-primary");

From 88ed5237d60706abfc822e553720b6e905d29dc3 Mon Sep 17 00:00:00 2001
From: Aaron Reisman <aaron.reisman@plane.so>
Date: Tue, 23 Jun 2026 17:01:11 +0700
Subject: [PATCH 3/3] Normalize pagination cva variant function names to match
 their part names
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rename every cva export in ui/pagination/variants.ts (and all consumer
files) so each name is exactly <camelCasePartName>Variants per rule 3a:
pageButtonVariants → paginationPageButtonVariants
arrowButtonVariants → paginationArrowButtonVariants
ellipsisVariants → paginationEllipsisVariants
spinnerVariants → paginationSpinnerVariants
perPageVariants → paginationPerPageVariants
perPageTriggerVariants → paginationPerPageTriggerVariants
perPageIndicatorVariants → paginationPerPageIndicatorVariants
perPageLabelVariants → paginationPerPageLabelVariants
rangeVariants → paginationRangeVariants
rangeCurrentVariants → paginationRangeCurrentVariants
---
 packages/propel/src/ui/pagination/index.tsx   | 20 +++++++++----------
 .../ui/pagination/pagination-arrow-button.tsx |  9 +++++----
 .../src/ui/pagination/pagination-ellipsis.tsx |  4 ++--
 .../ui/pagination/pagination-page-button.tsx  |  8 ++++----
 .../pagination-per-page-indicator.tsx         |  4 ++--
 .../pagination/pagination-per-page-label.tsx  |  4 ++--
 .../pagination-per-page-trigger.tsx           |  4 ++--
 .../src/ui/pagination/pagination-per-page.tsx |  4 ++--
 .../pagination/pagination-range-current.tsx   |  4 ++--
 .../src/ui/pagination/pagination-range.tsx    |  4 ++--
 .../src/ui/pagination/pagination-spinner.tsx  |  4 ++--
 packages/propel/src/ui/pagination/variants.ts | 20 +++++++++----------
 12 files changed, 45 insertions(+), 44 deletions(-)

diff --git a/packages/propel/src/ui/pagination/index.tsx b/packages/propel/src/ui/pagination/index.tsx
index 6a1395f8..13369b6e 100644
--- a/packages/propel/src/ui/pagination/index.tsx
+++ b/packages/propel/src/ui/pagination/index.tsx
@@ -24,17 +24,17 @@ export {
 } from "./pagination-range-current";
 export { PaginationSpinner, type PaginationSpinnerProps } from "./pagination-spinner";
 export {
-  arrowButtonVariants,
-  ellipsisVariants,
-  pageButtonVariants,
+  paginationArrowButtonVariants,
+  paginationEllipsisVariants,
   paginationItemVariants,
   paginationListVariants,
+  paginationPageButtonVariants,
+  paginationPerPageIndicatorVariants,
+  paginationPerPageLabelVariants,
+  paginationPerPageTriggerVariants,
+  paginationPerPageVariants,
+  paginationRangeCurrentVariants,
+  paginationRangeVariants,
+  paginationSpinnerVariants,
   paginationVariants,
-  perPageIndicatorVariants,
-  perPageLabelVariants,
-  perPageTriggerVariants,
-  perPageVariants,
-  rangeCurrentVariants,
-  rangeVariants,
-  spinnerVariants,
 } from "./variants";
diff --git a/packages/propel/src/ui/pagination/pagination-arrow-button.tsx b/packages/propel/src/ui/pagination/pagination-arrow-button.tsx
index 9f7fbd16..918922ea 100644
--- a/packages/propel/src/ui/pagination/pagination-arrow-button.tsx
+++ b/packages/propel/src/ui/pagination/pagination-arrow-button.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { arrowButtonVariants } from "./variants";
+import { paginationArrowButtonVariants } from "./variants";
 
 export type PaginationArrowButtonProps = Omit<
   React.ComponentProps<"button">,
@@ -8,9 +8,10 @@ export type PaginationArrowButtonProps = Omit<
 >;
 
 /**
- * A styled prev/next arrow button. Applies `arrowButtonVariants()`; pass the (directional,
- * RTL-mirrored) arrow icon as `children` and wire `aria-label`/`disabled`/`onClick` through props.
+ * A styled prev/next arrow button. Applies `paginationArrowButtonVariants()`; pass the
+ * (directional, RTL-mirrored) arrow icon as `children` and wire `aria-label`/`disabled`/`onClick`
+ * through props.
  */
 export function PaginationArrowButton(props: PaginationArrowButtonProps) {
-  return <button type="button" className={arrowButtonVariants()} {...props} />;
+  return <button type="button" className={paginationArrowButtonVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-ellipsis.tsx b/packages/propel/src/ui/pagination/pagination-ellipsis.tsx
index 2d115e9e..414c31fb 100644
--- a/packages/propel/src/ui/pagination/pagination-ellipsis.tsx
+++ b/packages/propel/src/ui/pagination/pagination-ellipsis.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { ellipsisVariants } from "./variants";
+import { paginationEllipsisVariants } from "./variants";
 
 export type PaginationEllipsisProps = Omit<
   React.ComponentPropsWithoutRef<"span">,
@@ -13,5 +13,5 @@ export type PaginationEllipsisProps = Omit<
  * `aria-hidden`.
  */
 export function PaginationEllipsis(props: PaginationEllipsisProps) {
-  return <span aria-hidden className={ellipsisVariants()} {...props} />;
+  return <span aria-hidden className={paginationEllipsisVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-page-button.tsx b/packages/propel/src/ui/pagination/pagination-page-button.tsx
index cc5d819e..f9136e4c 100644
--- a/packages/propel/src/ui/pagination/pagination-page-button.tsx
+++ b/packages/propel/src/ui/pagination/pagination-page-button.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { pageButtonVariants } from "./variants";
+import { paginationPageButtonVariants } from "./variants";
 
 export type PaginationPageButtonProps = Omit<
   React.ComponentProps<"button">,
@@ -11,9 +11,9 @@ export type PaginationPageButtonProps = Omit<
 };
 
 /**
- * A styled page-number button. Applies `pageButtonVariants({ current })`; pass the page number (or
- * a loading spinner) as `children` and wire `aria-current`/`onClick` through props.
+ * A styled page-number button. Applies `paginationPageButtonVariants({ current })`; pass the page
+ * number (or a loading spinner) as `children` and wire `aria-current`/`onClick` through props.
  */
 export function PaginationPageButton({ current, ...props }: PaginationPageButtonProps) {
-  return <button type="button" className={pageButtonVariants({ current })} {...props} />;
+  return <button type="button" className={paginationPageButtonVariants({ current })} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-per-page-indicator.tsx b/packages/propel/src/ui/pagination/pagination-per-page-indicator.tsx
index 7796b41a..2765a367 100644
--- a/packages/propel/src/ui/pagination/pagination-per-page-indicator.tsx
+++ b/packages/propel/src/ui/pagination/pagination-per-page-indicator.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { perPageIndicatorVariants } from "./variants";
+import { paginationPerPageIndicatorVariants } from "./variants";
 
 export type PaginationPerPageIndicatorProps = Omit<
   React.ComponentPropsWithoutRef<"span">,
@@ -13,5 +13,5 @@ export type PaginationPerPageIndicatorProps = Omit<
  * accessible name and state — so `aria-hidden`.
  */
 export function PaginationPerPageIndicator(props: PaginationPerPageIndicatorProps) {
-  return <span aria-hidden className={perPageIndicatorVariants()} {...props} />;
+  return <span aria-hidden className={paginationPerPageIndicatorVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-per-page-label.tsx b/packages/propel/src/ui/pagination/pagination-per-page-label.tsx
index da6ca7c5..1bb262db 100644
--- a/packages/propel/src/ui/pagination/pagination-per-page-label.tsx
+++ b/packages/propel/src/ui/pagination/pagination-per-page-label.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { perPageLabelVariants } from "./variants";
+import { paginationPerPageLabelVariants } from "./variants";
 
 export type PaginationPerPageLabelProps = Omit<
   React.ComponentPropsWithoutRef<"span">,
@@ -12,5 +12,5 @@ export type PaginationPerPageLabelProps = Omit<
  * `aria-hidden`.
  */
 export function PaginationPerPageLabel(props: PaginationPerPageLabelProps) {
-  return <span aria-hidden className={perPageLabelVariants()} {...props} />;
+  return <span aria-hidden className={paginationPerPageLabelVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx b/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx
index b02ea3d8..0bd536c0 100644
--- a/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx
+++ b/packages/propel/src/ui/pagination/pagination-per-page-trigger.tsx
@@ -1,7 +1,7 @@
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
 
-import { perPageTriggerVariants } from "./variants";
+import { paginationPerPageTriggerVariants } from "./variants";
 
 export type PaginationPerPageTriggerProps = Omit<
   useRender.ComponentProps<"button">,
@@ -16,7 +16,7 @@ export type PaginationPerPageTriggerProps = Omit<
 export function PaginationPerPageTrigger({ render, ...props }: PaginationPerPageTriggerProps) {
   const defaultProps: useRender.ElementProps<"button"> = {
     ...(render == null ? { type: "button" } : null),
-    className: perPageTriggerVariants(),
+    className: paginationPerPageTriggerVariants(),
   };
 
   return useRender({
diff --git a/packages/propel/src/ui/pagination/pagination-per-page.tsx b/packages/propel/src/ui/pagination/pagination-per-page.tsx
index 689bd72e..793a9400 100644
--- a/packages/propel/src/ui/pagination/pagination-per-page.tsx
+++ b/packages/propel/src/ui/pagination/pagination-per-page.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { perPageVariants } from "./variants";
+import { paginationPerPageVariants } from "./variants";
 
 export type PaginationPerPageProps = Omit<React.ComponentProps<"div">, "className" | "style">;
 
@@ -9,5 +9,5 @@ export type PaginationPerPageProps = Omit<React.ComponentProps<"div">, "classNam
  * `PaginationPerPageLabel`.
  */
 export function PaginationPerPage(props: PaginationPerPageProps) {
-  return <div className={perPageVariants()} {...props} />;
+  return <div className={paginationPerPageVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-range-current.tsx b/packages/propel/src/ui/pagination/pagination-range-current.tsx
index e0ec0470..5112d0c9 100644
--- a/packages/propel/src/ui/pagination/pagination-range-current.tsx
+++ b/packages/propel/src/ui/pagination/pagination-range-current.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { rangeCurrentVariants } from "./variants";
+import { paginationRangeCurrentVariants } from "./variants";
 
 export type PaginationRangeCurrentProps = Omit<
   React.ComponentPropsWithoutRef<"span">,
@@ -12,5 +12,5 @@ export type PaginationRangeCurrentProps = Omit<
  * color.
  */
 export function PaginationRangeCurrent(props: PaginationRangeCurrentProps) {
-  return <span className={rangeCurrentVariants()} {...props} />;
+  return <span className={paginationRangeCurrentVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-range.tsx b/packages/propel/src/ui/pagination/pagination-range.tsx
index c767321e..e87563ee 100644
--- a/packages/propel/src/ui/pagination/pagination-range.tsx
+++ b/packages/propel/src/ui/pagination/pagination-range.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { rangeVariants } from "./variants";
+import { paginationRangeVariants } from "./variants";
 
 export type PaginationRangeProps = Omit<React.ComponentProps<"p">, "className" | "style">;
 
@@ -9,5 +9,5 @@ export type PaginationRangeProps = Omit<React.ComponentProps<"p">, "className" |
  * current range inside it is emphasized via `PaginationRangeCurrent`.
  */
 export function PaginationRange(props: PaginationRangeProps) {
-  return <p className={rangeVariants()} {...props} />;
+  return <p className={paginationRangeVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/pagination-spinner.tsx b/packages/propel/src/ui/pagination/pagination-spinner.tsx
index 7d285fc2..b9e45d40 100644
--- a/packages/propel/src/ui/pagination/pagination-spinner.tsx
+++ b/packages/propel/src/ui/pagination/pagination-spinner.tsx
@@ -1,6 +1,6 @@
 import type * as React from "react";
 
-import { spinnerVariants } from "./variants";
+import { paginationSpinnerVariants } from "./variants";
 
 export type PaginationSpinnerProps = Omit<
   React.ComponentPropsWithoutRef<"span">,
@@ -13,5 +13,5 @@ export type PaginationSpinnerProps = Omit<
  * Decorative, so `aria-hidden`.
  */
 export function PaginationSpinner(props: PaginationSpinnerProps) {
-  return <span aria-hidden className={spinnerVariants()} {...props} />;
+  return <span aria-hidden className={paginationSpinnerVariants()} {...props} />;
 }
diff --git a/packages/propel/src/ui/pagination/variants.ts b/packages/propel/src/ui/pagination/variants.ts
index 63e30564..08aaa58d 100644
--- a/packages/propel/src/ui/pagination/variants.ts
+++ b/packages/propel/src/ui/pagination/variants.ts
@@ -30,7 +30,7 @@ const slotBase = cx(
   "text-13 text-primary outline-none",
 );
 
-export const pageButtonVariants = cva(
+export const paginationPageButtonVariants = cva(
   cx(
     slotBase,
     "rounded-sm bg-layer-transparent",
@@ -52,7 +52,7 @@ export const pageButtonVariants = cva(
   },
 );
 
-export const arrowButtonVariants = cva(
+export const paginationArrowButtonVariants = cva(
   cx(
     slotBase,
     "rounded-md bg-layer-transparent text-icon-secondary",
@@ -68,25 +68,25 @@ export const arrowButtonVariants = cva(
 // A non-interactive gap marker between distant page numbers. Sizes its single child
 // (the more-horizontal glyph, 14px) via the shared node-slot class and tints it the
 // placeholder color, instead of baking a specific glyph/size in.
-export const ellipsisVariants = cva(
+export const paginationEllipsisVariants = cva(
   cx(slotBase, "text-icon-placeholder [--node-size:0.875rem]", nodeSlotClass),
 );
 
 // The current page can render a spinner in place of its number while navigating to it
 // is in flight. A node-slot sized to 14px that spins its child; placeholder tint.
-export const spinnerVariants = cva(
+export const paginationSpinnerVariants = cva(
   cx(nodeSlotClass, "animate-spin text-icon-placeholder [--node-size:0.875rem]"),
 );
 
 // The per-page region (Figma `50 v per page`): the selector pill followed by the
 // trailing "per page" text. Grows to fill the leading space before the page list.
-export const perPageVariants = cva("flex min-w-0 flex-1 items-center gap-2");
+export const paginationPerPageVariants = cva("flex min-w-0 flex-1 items-center gap-2");
 
 // The per-page selector trigger (Figma `4762-503`): a `layer-3` pill, 24px tall,
 // `radius/md`, holding the current size + a chevron-down. It's the trigger for the
 // page-size Menu, so it gets a focus ring; the `group` lets its chevron indicator
 // rotate while the menu is open.
-export const perPageTriggerVariants = cva(
+export const paginationPerPageTriggerVariants = cva(
   cx(
     "group inline-flex h-6 min-w-10 cursor-default items-center justify-center gap-1 rounded-md px-2",
     "bg-layer-3 text-13 font-medium text-secondary outline-none",
@@ -98,7 +98,7 @@ export const perPageTriggerVariants = cva(
 // The chevron indicator inside the per-page trigger. Sizes its single child (14px) and
 // rotates a half-turn while the menu is open (Base UI sets `data-popup-open` on the
 // trigger, which carries the `group` class).
-export const perPageIndicatorVariants = cva(
+export const paginationPerPageIndicatorVariants = cva(
   cx(
     nodeSlotClass,
     "text-icon-secondary [--node-size:0.875rem]",
@@ -107,11 +107,11 @@ export const perPageIndicatorVariants = cva(
 );
 
 // The trailing "per page" text after the selector pill.
-export const perPageLabelVariants = cva("text-13 whitespace-nowrap text-tertiary");
+export const paginationPerPageLabelVariants = cva("text-13 whitespace-nowrap text-tertiary");
 
 // The optional range label shown before the controls (Figma `1-50 of 250`): tertiary,
 // nowrap. The current range inside it is emphasized via `PaginationRangeCurrent`.
-export const rangeVariants = cva("text-12 whitespace-nowrap text-tertiary");
+export const paginationRangeVariants = cva("text-12 whitespace-nowrap text-tertiary");
 
 // The emphasized current-range portion (e.g. `1-50`) inside `PaginationRange`.
-export const rangeCurrentVariants = cva("text-primary");
+export const paginationRangeCurrentVariants = cva("text-primary");