@spark-web/design-system 5.1.0 → 5.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spark-web/design-system",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "license": "MIT",
   "main": "dist/spark-web-design-system.cjs.js",
   "module": "dist/spark-web-design-system.esm.js",
@@ -13,7 +13,7 @@
   "dependencies": {
     "@spark-web/a11y": "5.3.0",
     "@spark-web/accordion": "5.2.0",
-    "@spark-web/action-dropdown": "2.0.0",
+    "@spark-web/action-dropdown": "2.0.1",
     "@spark-web/alert": "5.2.0",
     "@spark-web/analytics": "5.1.0",
     "@spark-web/badge": "^5.1.1",
@@ -31,7 +31,7 @@
     "@spark-web/description-list": "0.1.0",
     "@spark-web/divider": "5.1.0",
     "@spark-web/dropzone": "6.0.0",
-    "@spark-web/field": "5.3.1",
+    "@spark-web/field": "5.3.2",
     "@spark-web/fieldset": "5.1.0",
     "@spark-web/float-input": "6.0.0",
     "@spark-web/heading": "5.2.0",
@@ -52,7 +52,7 @@
     "@spark-web/row": "5.1.1",
     "@spark-web/section-card": "0.1.0",
     "@spark-web/section-header": "0.1.0",
-    "@spark-web/select": "6.0.1",
+    "@spark-web/select": "6.0.2",
     "@spark-web/spinner": "5.1.1",
     "@spark-web/ssr": "5.0.0",
     "@spark-web/stack": "5.1.1",
@@ -60,8 +60,8 @@
     "@spark-web/switch": "5.0.3",
     "@spark-web/tabs": "5.2.1",
     "@spark-web/text": "5.3.1",
-    "@spark-web/text-area": "6.0.0",
-    "@spark-web/text-input": "6.0.1",
+    "@spark-web/text-area": "6.0.1",
+    "@spark-web/text-input": "6.0.2",
     "@spark-web/text-link": "5.4.0",
     "@spark-web/text-list": "5.1.0",
     "@spark-web/theme": "5.13.1",

package/patterns/internal-admin/details-page.md

@@ -0,0 +1,358 @@
+# Internal admin — details page pattern
+
+## Before using this pattern
+
+Read node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md
+fully before implementing this pattern. The interaction rules, badge tone
+mapping, and action dropdown rules defined there all apply to this pattern.
+
+## What this pattern is
+
+A full page layout for displaying the detail view of a single record in an
+internal admin interface. The page shows structured data and contextual
+sub-tables in a two-column layout, with record-level actions surfaced through a
+header dropdown.
+
+## When to use this pattern
+
+Use this pattern when the PRD describes any of the following:
+
+- A single-record view reachable by clicking a row on a list page
+- A page showing a record's fields, history, or associated sub-records
+- The words "detail", "profile", "view", "record page", or "user/vendor page"
+
+---
+
+## Component docs to read
+
+Read these before implementing — they own the component-level rules:
+
+- `packages/action-dropdown/CLAUDE.md` — dropdown construction, ordering, hide
+  vs. disable
+- `packages/modal-dialog/CLAUDE.md` — ContentDialog API,
+  ACCREDITATION_MODAL_CSS, destructive modal anatomy
+- `packages/data-table/CLAUDE.md` — DataTable API, loading/empty states,
+  expandable rows
+- `packages/tabs/CLAUDE.md` — Tabs API, internal-admin background override, null
+  guard
+- `packages/section-card/CLAUDE.md` — SectionCard API (note: portal-hub uses a
+  custom wrapper; see Section 6 below)
+- `packages/badge/CLAUDE.md` — status tone mapping
+- `packages/columns/CLAUDE.md` — responsive two-column layout
+- `packages/box/CLAUDE.md` — flex layout utilities
+- `packages/stack/CLAUDE.md` — vertical stacking and gap
+
+---
+
+## Page structure
+
+```
+Outer wrapper Stack              paddingX="xlarge" paddingY="xxlarge" gap="xlarge"
+  Header Box                     spaceBetween row: [Heading level="1" + Badge] | [ActionDropdown]
+  Page-level feedback Alert      conditional — only for inline (non-modal) action feedback
+  Modals                         all ContentDialog modals declared here, controlled by openModal state
+  Content Columns                template=[1,1] gap="xlarge" collapseBelow="desktop"
+    Left column Stack            gap="xlarge" — primary record fields + primary sub-tables
+    Right column Stack           gap="xlarge" — secondary/contextual sections
+      SectionCard (per section)
+        DataTable                PAGE_SIZE=5 items; see data-table/CLAUDE.md
+        TablePagination          only when total > PAGE_SIZE
+```
+
+---
+
+## Section 1 — Outer wrapper
+
+```tsx
+<Stack height="full" paddingX="xlarge" paddingY="xxlarge" gap="xlarge">
+```
+
+All spacing uses Spark tokens. This is distinct from list-page spacing
+(`padding="large"` on a neutral-background Stack) — do not mix the two.
+
+---
+
+## Section 2 — Page header
+
+```tsx
+<Box
+  display="flex"
+  flexDirection={{ mobile: 'column', tablet: 'row' }}
+  justifyContent={{ tablet: 'spaceBetween' }}
+  gap="medium"
+>
+  <Box
+    display="flex"
+    flexDirection={{ mobile: 'columnReverse', tablet: 'row' }}
+    alignItems={{ mobile: 'start', tablet: 'center' }}
+    gap={{ mobile: 'medium', tablet: 'small' }}
+  >
+    <Heading level="1">{recordTitle}</Heading>
+    <Badge tone={statusTone}>{statusLabel}</Badge>
+  </Box>
+
+  {actions.length > 0 && (
+    <Box className={css({ minWidth: 130 })}>
+      <ActionDropdown label="Actions" actions={actions} />
+    </Box>
+  )}
+</Box>
+```
+
+Rules:
+
+- Status badge follows the heading — never precedes it
+- Only render `ActionDropdown` when `actions.length > 0`
+- No action buttons directly in the header — always use `ActionDropdown`
+
+---
+
+## Section 3 — Actions dropdown
+
+See `packages/action-dropdown/CLAUDE.md` for full API and ordering rules.
+
+Page-level decisions:
+
+- **Order**: non-destructive actions first, restore-type actions second,
+  `tone: 'critical'` destructive actions always last
+- **Hide vs. disable**: hide actions permanently unavailable for the current
+  record state (conditional spread); disable actions temporarily unavailable
+  (e.g. mutation in-flight)
+- **Direct vs. modal**: direct actions (password reset, restore, activate) call
+  the mutation inline and surface feedback via page-level `actionStatus` Alert;
+  destructive actions (delete, suspend) always open a `ContentDialog` modal
+  first
+
+---
+
+## Section 4 — Page-level feedback
+
+```tsx
+{
+  actionStatus && (
+    <Alert tone={actionStatus.isSuccessful ? 'positive' : 'critical'}>
+      <Text>{actionStatus.message}</Text>
+    </Alert>
+  );
+}
+```
+
+State shape: `{ isSuccessful: boolean; message: string } | undefined`
+
+Rendered between the header and content columns. Only used for direct inline
+mutations. Modal confirmations own their own error Alert inside the
+`ContentDialog` — see `packages/modal-dialog/CLAUDE.md`.
+
+---
+
+## Section 5 — Confirmation modals
+
+See `packages/modal-dialog/CLAUDE.md` for ContentDialog API, sizing,
+form-in-modal anatomy, and the full destructive modal pattern.
+
+Declare all modals in the component JSX, controlled by a single `openModal`
+state union:
+
+```ts
+const [openModal, setOpenModal] = useState<'delete' | 'suspend' | null>(null);
+```
+
+```tsx
+{
+  openModal === 'delete' && recordId && (
+    <DeleteModal
+      isOpen
+      onToggle={() => setOpenModal(null)}
+      recordId={recordId}
+      onSuccess={() => {
+        refetch();
+        setOpenModal(null);
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Section 6 — Content columns
+
+```tsx
+<Columns gap="xlarge" template={[1, 1]} collapseBelow="desktop">
+  <Stack gap="xlarge">{/* left column */}</Stack>
+  <Stack gap="xlarge">{/* right column */}</Stack>
+</Columns>
+```
+
+Always equal columns (`template={[1, 1]}`), always collapse below desktop.
+
+---
+
+## Section 7 — Section cards
+
+Each content section is wrapped in a `SectionCard`.
+
+**Portal-hub uses a custom wrapper** at `@components/PortalTable/SectionCard`
+(not `@spark-web/section-card`). The API differs:
+
+```tsx
+import { SectionCard } from '@components/PortalTable/SectionCard';
+
+<SectionCard label="Section Title">{/* section content */}</SectionCard>;
+```
+
+| Prop       | Type        | Notes                                 |
+| ---------- | ----------- | ------------------------------------- |
+| `label`    | `string`    | Required — card header text           |
+| `action`   | `ReactNode` | Optional — right-side header control  |
+| `controls` | `ReactNode` | Optional — additional header controls |
+
+Return `null` for sections conditionally hidden — never render an empty card.
+
+---
+
+## Section 8 — Section data tables
+
+See `packages/data-table/CLAUDE.md` for DataTable API, column definitions, and
+loading/empty state props.
+
+Detail-page-specific rules (differ from list pages):
+
+- **`PAGE_SIZE = 5`** — always 5 items per section table (not 20 like list
+  pages)
+- **Pagination threshold**: render `TablePagination` only when
+  `total > PAGE_SIZE`
+- **Reset page**: reset to 1 when the record context changes (e.g. `userId`)
+
+```tsx
+const PAGE_SIZE = 5;
+const [page, setPage] = useState(1);
+
+useEffect(() => {
+  setPage(1);
+}, [recordId]);
+
+// Client-side pagination — fetch all, slice
+const allItems = data?.items ?? [];
+const total = allItems.length;
+const pageItems = allItems.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);
+
+// Server-side pagination — skip/take API
+const { data } = useQuery({ skip: (page - 1) * PAGE_SIZE, take: PAGE_SIZE });
+const total = countData?.count ?? 0;
+const pageItems = data?.items ?? [];
+```
+
+```tsx
+<Stack gap="large">
+  <DataTable
+    items={pageItems}
+    columns={columns}
+    isLoading={isLoading}
+    emptyState={
+      <Text tone="muted" size="small" align="center">
+        No items.
+      </Text>
+    }
+  />
+  {total > PAGE_SIZE && (
+    <TablePagination
+      total={total}
+      pageSize={PAGE_SIZE}
+      dataShowing={pageItems.length}
+      onChange={setPage}
+      current={page}
+    />
+  )}
+</Stack>
+```
+
+---
+
+## Section 9 — Tabbed sections
+
+See `packages/tabs/CLAUDE.md` for the Tabs API, dynamic tab construction, the
+required internal-admin background override, and the null guard pattern.
+
+Use tabs when a section has multiple sub-views (e.g. Email / SMS history). Each
+tab panel follows the same PAGE_SIZE=5 and pagination rules as Section 8.
+
+---
+
+## Structural skeleton
+
+```tsx
+<Stack height="full" paddingX="xlarge" paddingY="xxlarge" gap="xlarge">
+  {/* Header */}
+  <Box
+    display="flex"
+    flexDirection={{ mobile: 'column', tablet: 'row' }}
+    justifyContent={{ tablet: 'spaceBetween' }}
+    gap="medium"
+  >
+    <Box
+      display="flex"
+      flexDirection={{ mobile: 'columnReverse', tablet: 'row' }}
+      alignItems={{ mobile: 'start', tablet: 'center' }}
+      gap={{ mobile: 'medium', tablet: 'small' }}
+    >
+      <Heading level="1">{recordTitle}</Heading>
+      <Badge tone={statusTone}>{statusLabel}</Badge>
+    </Box>
+    {actions.length > 0 && (
+      <Box className={css({ minWidth: 130 })}>
+        <ActionDropdown label="Actions" actions={actions} />
+      </Box>
+    )}
+  </Box>
+
+  {/* Page-level feedback — direct actions only */}
+  {actionStatus && (
+    <Alert tone={actionStatus.isSuccessful ? 'positive' : 'critical'}>
+      <Text>{actionStatus.message}</Text>
+    </Alert>
+  )}
+
+  {/* Modals */}
+  {openModal === 'delete' && recordId && (
+    <DeleteModal
+      isOpen
+      onToggle={() => setOpenModal(null)}
+      recordId={recordId}
+      onSuccess={() => {
+        refetch();
+        setOpenModal(null);
+      }}
+    />
+  )}
+
+  {/* Content */}
+  <Columns gap="xlarge" template={[1, 1]} collapseBelow="desktop">
+    <Stack gap="xlarge">
+      <SectionCard label="Details">{/* fields */}</SectionCard>
+    </Stack>
+    <Stack gap="xlarge">
+      <SectionCard label="History">{/* table + pagination */}</SectionCard>
+    </Stack>
+  </Columns>
+</Stack>
+```
+
+---
+
+## Do NOTs
+
+- NEVER apply list-page spacing to a detail page — outer wrapper uses
+  `paddingX="xlarge" paddingY="xxlarge"`, not `padding="large"`
+- NEVER place a destructive action before non-destructive actions in the
+  dropdown
+- NEVER call a destructive mutation directly from a dropdown item — open a modal
+- NEVER surface modal errors as page-level Alerts — see `modal-dialog/CLAUDE.md`
+- NEVER use `PAGE_SIZE = 20` on section tables — always 5 on detail pages
+- NEVER render `TablePagination` when `total <= PAGE_SIZE`
+- NEVER render an empty `SectionCard` for hidden sections — return `null`
+- NEVER render `ActionDropdown` when `actions` is empty — gate with
+  `actions.length > 0`
+- NEVER render `Tabs` inside `SectionCard` without the background override — see
+  `tabs/CLAUDE.md`
+- NEVER use `Container` as the outer page wrapper

package/patterns/internal-admin/list-page.md

@@ -23,53 +23,26 @@ Use this pattern when the PRD describes any of the following:
 
 ---
 
-## Required imports
-
-```tsx
-import { Stack } from '@spark-web/stack';
-import { Box } from '@spark-web/box';
-import { Columns } from '@spark-web/columns';
-import { Field } from '@spark-web/field';
-import { PageHeader } from '@spark-web/page-header';
-import { Text } from '@spark-web/text';
-import { TextInput } from '@spark-web/text-input';
-import { createColumnHelper, DataTable } from '@spark-web/data-table';
-import { Badge } from '@spark-web/badge';
-import { MeatballMenu } from '@spark-web/meatball-menu';
-import {
-  MultiSelectField,
-  SelectField,
-  TextInputField,
-} from '@brighte/ui-components'; // portal-hub only — @spark-web/multi-select not available
-import { css } from '@emotion/css';
-import { css as reactCss } from '@emotion/react';
-import { useTheme } from '@spark-web/theme';
-```
-
----
-
 ## Component docs to read
 
-Read these files at Step 4 — no others:
+Read these before implementing — they own the component-level rules:
 
-- packages/page-header/CLAUDE.md
-- packages/data-table/CLAUDE.md
-- packages/badge/CLAUDE.md
-- packages/meatball-menu/CLAUDE.md
-- packages/stack/CLAUDE.md
-- packages/box/CLAUDE.md
-- packages/columns/CLAUDE.md
-- packages/field/CLAUDE.md
-- packages/text/CLAUDE.md
-- packages/text-input/CLAUDE.md
+- `packages/page-header/CLAUDE.md` — PageHeader API, action type rules
+- `packages/data-table/CLAUDE.md` — DataTable API, column defs, loading/empty
+  states, headerClassName tokens
+- `packages/badge/CLAUDE.md` — status tone mapping
+- `packages/meatball-menu/CLAUDE.md` — MeatballMenu API
+- `packages/stack/CLAUDE.md` — vertical stacking and gap
+- `packages/box/CLAUDE.md` — flex layout utilities
+- `packages/columns/CLAUDE.md` — responsive multi-column layout
+- `packages/field/CLAUDE.md` — Field API, labelVisibility
+- `packages/text/CLAUDE.md` — Text API
+- `packages/text-input/CLAUDE.md` — TextInput API
 
 ---
 
 ## Page structure
 
-The page is composed in this exact order, top to bottom. Do not change the order
-or omit any required section.
-
 ```
 Page
   Outer wrapper Stack            — full height, no padding
@@ -86,29 +59,18 @@ Page
 
 ## Section 1 — Page header
 
-Renders the page title as an H1 using `PageHeader` from
-`@spark-web/page-header`.
+Always use `PageHeader` from `@spark-web/page-header`. Never replace with a
+manual `Stack + Heading`.
 
 ```tsx
 <PageHeader label={pageTitle} />
 ```
 
-Optional variants — see `@spark-web/page-header` CLAUDE.md for full prop docs:
-
-```tsx
-{/* With status badge */}
-<PageHeader label={pageTitle} statusBadge={{ children: 'Active', tone: 'positive' }} />
-
-{/* With a single action button */}
-<PageHeader label={pageTitle} action={{ type: 'button', label: 'Add', onClick: handleAdd }} />
-
-{/* With overflow menu (2+ actions) */}
-<PageHeader label={pageTitle} action={{ type: 'meatball', items: [...] }} />
-```
+See `packages/page-header/CLAUDE.md` for action types (button, link, meatball),
+statusBadge, and controls props.
 
 Rules:
 
-- Always use `PageHeader` — never replace with a manual `Stack + Heading`
 - `PageHeader` always renders an H1 — do not pass a different heading level
 - Page-level actions (e.g. "Add new") belong in the `action` prop, not in the
   content area
@@ -149,15 +111,13 @@ Rules:
 The outermost container fills the full viewport height.
 
 ```tsx
-<Stack
-  height="full"
-  className={css({ minHeight: '100vh' })}
->
+<Stack height="full" className={css({ minHeight: '100vh' })}>
 ```
 
-Documented exceptions — no Spark token equivalent:
+Documented exception:
 
-- `minHeight: '100vh'` — ensures page fills viewport on short content
+- `minHeight: '100vh'` — no Spark token equivalent; ensures page fills viewport
+  on short content
 
 ---
 
@@ -201,6 +161,17 @@ Renders filter dropdowns and a search input in a horizontal row.
 const FieldProps = { labelVisibility: 'hidden' as const };
 
 <Columns gap="large" collapseBelow="desktop">
+  <TextInputField
+    control={control}
+    name="search"
+    label="Search"
+    placeholder="Search by..."
+    FieldProps={FieldProps}
+  >
+    <InputAdornment placement="start">
+      <SearchIcon size="xxsmall" tone="muted" />
+    </InputAdornment>
+  </TextInputField>
   <MultiSelectField
     control={control}
     name="fieldName"
@@ -209,14 +180,6 @@ const FieldProps = { labelVisibility: 'hidden' as const };
     placeholder="Filter by..."
     fieldProps={FieldProps}
   />
-  <Field label="Search">
-    <TextInput
-      type="search"
-      value={search}
-      onChange={e => setSearch(e.target.value)}
-      placeholder="Search by..."
-    />
-  </Field>
 </Columns>;
 ```
 
@@ -224,42 +187,23 @@ Rules:
 
 - Use `Columns` from @spark-web/columns with `gap="large"`
 - `collapseBelow="desktop"` — stacks vertically on mobile and tablet
+- **Search input always appears first (leftmost)** in the filter row
+- Filter dropdowns follow the search input, ordered by specificity (broadest
+  filter first, most specific last)
 - Multi-select filter dropdowns use `MultiSelectField` from
   `@brighte/ui-components` (portal-hub only — `@spark-web/multi-select` is not
-  available in portal-hub).
-- Single-select filter dropdowns use `SelectField` from
-  `@brighte/ui-components`.
+  available in portal-hub)
+- Single-select filter dropdowns use `SelectField` from `@brighte/ui-components`
 - Always pass `fieldProps={{ labelVisibility: 'hidden' as const }}` on both
   `MultiSelectField` and `SelectField` — define it as a constant outside the
-  component to avoid re-renders. Never wrap in a `Stack` + `Text` label — the
-  label is hidden, not replaced. This rule applies to both components equally.
-
-  ```tsx
-  const FieldProps = { labelVisibility: 'hidden' as const };
-
-  <SelectField
-    control={control}
-    name="vendor"
-    label="Vendor"
-    options={vendorOptions}
-    placeholder="Filter by vendor..."
-    fieldProps={FieldProps}
-  />;
-  ```
-
-- Search input uses `TextInputField` from `@brighte/ui-components` with
-  `FieldProps` (same hidden label constant), with `SearchIcon` adornment on
-  start and a clear button (`XIcon`) on end
-- Filter controls always appear left of the search input
-- Maximum 2 filter dropdowns before the search input
-- Search input always appears on the far right
+  component to avoid re-renders
 - If no filtering or searching is needed, omit this section entirely
 
 ---
 
 ## Section 5 — Table scroll wrapper
 
-Wraps the Table to enable vertical scrolling without the page scrolling.
+Wraps the DataTable to enable vertical scrolling without the page scrolling.
 
 ```tsx
 <Box display="flex" flexDirection="column">
@@ -271,7 +215,7 @@ Wraps the Table to enable vertical scrolling without the page scrolling.
       overflowY: 'auto',
     })}
   >
-    <Table>...</Table>
+    <DataTable ... />
   </div>
 </Box>
 ```
@@ -287,12 +231,12 @@ Documented exceptions — all required for flex scroll behaviour:
 
 ## Section 6 — Table
 
-The core data display. Always uses `@spark-web/data-table`.
-
-Define columns outside the component using `createColumnHelper`. Pass `items`
-and `columns` to `<DataTable>`.
+Always uses `@spark-web/data-table`. See `packages/data-table/CLAUDE.md` for
+column definition API, loading/empty states, sorting, and expansion.
 
-Always apply `className` and `headerClassName` for canonical list-page styling:
+Apply canonical list-page header styling via `headerClassName`. Use the named
+import `import { css as reactCss } from '@emotion/react'` — `headerClassName`
+accepts `SerializedStyles`, not a string class from `@emotion/css`.
 
 ```tsx
 <DataTable
@@ -305,153 +249,51 @@ Always apply `className` and `headerClassName` for canonical list-page styling:
       svg: { stroke: theme.color.background.primaryDark },
     },
   })}
-  ...
+  items={rows}
+  columns={columns}
+  isLoading={isLoading}
+  emptyState={
+    <Text tone="muted" size="small">
+      No records found. Try adjusting your filters.
+    </Text>
+  }
 />
 ```
 
-Note: `className` and `headerClassName` accept a `SerializedStyles` object from
-`@emotion/react`'s `css` — not a string class from `@emotion/css`. Use the named
-import `import { css as reactCss } from '@emotion/react'` to distinguish them.
-
 Column rules:
 
 - Default column width: equal flex distribution (`size` unset)
 - Actions column: always last, `size: 80`, empty string `header`
-- Status column: always use `<Badge>` (dot + label) — never `<StatusBadge>`,
-  never plain text
+- Status column: always `<Badge>` (dot + label) — never `<StatusBadge>`, never
+  plain text
 - Actions column: always uses `<MeatballMenu>` when 2 or more row-level actions
   exist
 
 Row interaction rules — see
-node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md:
+`packages/design-system/patterns/internal-admin/CLAUDE.md`:
 
 - Pass `onRowClick` and `enableClickableRow` when the record has a detail view
 - Hover state is applied automatically when `enableClickableRow` is true
 
 Status tone mapping — authoritative rules are in
-node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md. Do not
-duplicate them here.
-
-Table states to always implement:
-
-- Default: `items={rows}` with data
-- Loading: `isLoading` prop — renders spinner overlay, replaces data rows
-- Empty: `emptyState={<Text tone="muted" size="small">…</Text>}` — shown when
-  `items` is an empty array
+`packages/design-system/patterns/internal-admin/CLAUDE.md`. Do not duplicate
+them here.
 
 ---
 
 ## Section 7 — Pagination
 
-No dedicated Spark pagination component exists. Implement using Spark primitives
-or flag as a component gap.
-
-- Pagination is rendered outside and below DataTable — never nested inside it
-- Pagination is always rendered regardless of loading or empty state — never
-  conditionally hidden.
-
-Rules:
+Render `TablePagination` outside and below DataTable — never nested inside it.
 
-- Always implement when the data source is an API or database
-- Default pageSize: 20
+- **Only rendered when `total > pageSize`** — hide it when all records fit on
+  one page
+- Default `pageSize` for full list pages: **20**
+- Use the real total count from a dedicated count query — never derive total
+  from the length of the current page's result set
 - No additional wrapper needed — content area `gap="large"` handles spacing
 
 ---
 
-## Complete assembly
-
-```tsx
-const col = createColumnHelper<Row>();
-
-const columns = [
-  col.accessor('column1', {
-    header: 'Column 1',
-    cell: info => <Text size="small">{String(info.getValue())}</Text>,
-  }),
-  col.accessor('status', {
-    header: 'Status',
-    cell: info => (
-      <Badge tone={deriveTone(info.getValue())}>{info.getValue()}</Badge>
-    ),
-  }),
-  col.display({
-    id: 'actions',
-    header: '',
-    size: 80,
-    cell: ({ row }) => <MeatballMenu items={rowActions(row.original)} />,
-  }),
-];
-
-// ---
-
-const theme = useTheme()
-
-<Stack height="full" className={css({ minHeight: '100vh' })}>
-  {/* Section 1: Page header */}
-  <PageHeader label={pageTitle} />
-
-  {/* Sections 3–7: Content area — neutral background */}
-  <Stack
-    padding="large"
-    gap="large"
-    className={css({
-      backgroundColor: theme.color.background.neutral,
-      flex: 1,
-      display: 'flex',
-      flexDirection: 'column',
-      overflow: 'hidden',
-    })}
-  >
-    {/* Section 4: Filters */}
-    <Columns gap="large" collapseBelow="desktop">
-      <MultiSelectField
-        control={control}
-        name="status"
-        label="Status"
-        options={statusOptions}
-        placeholder="Filter by status"
-        fieldProps={FieldProps}
-      />
-      <Field label="Search">
-        <TextInput type="search" value={search} onChange={e => setSearch(e.target.value)} placeholder="Search by..." />
-      </Field>
-    </Columns>
-
-    {/* Section 5 + 6: Table */}
-    <Box display="flex" flexDirection="column">
-      <div className={css({
-        position: 'relative',
-        flex: 1,
-        minHeight: 0,
-        overflowY: 'auto',
-      })}>
-        <DataTable
-          className={reactCss({ width: '100%' })}
-          headerClassName={reactCss({
-            boxShadow: `inset 0 -2px 0 0 ${theme.color.background.primaryDark}`,
-            th: {
-              color: theme.color.background.primaryDark,
-              textTransform: 'capitalize',
-              svg: { stroke: theme.color.background.primaryDark },
-            },
-          })}
-          items={rows}
-          columns={columns}
-          isLoading={isLoading}
-          emptyState={
-            <Text tone="muted" size="small">No records found. Try adjusting your filters.</Text>
-          }
-        />
-      </div>
-
-      {/* Section 7: Pagination — implement with Spark primitives */}
-    </Box>
-  </Stack>
-</Stack>
-```
-
----
-
 ## Structural skeleton
 
 Use this skeleton as the starting point for new builds and uplifts. Do not use
@@ -473,8 +315,7 @@ existing page implementations as a structural reference.
     })}
   >
     <Columns gap="large" collapseBelow="desktop">
-      {/* filters here */}
-      {/* search here */}
+      {/* search first, then filters */}
     </Columns>
 
     <Box display="flex" flexDirection="column">
@@ -495,7 +336,15 @@ existing page implementations as a structural reference.
       </div>
     </Box>
 
-    {/* pagination here */}
+    {total > PAGE_SIZE && (
+      <TablePagination
+        total={total}
+        pageSize={PAGE_SIZE}
+        dataShowing={rows.length}
+        onChange={setPage}
+        current={page}
+      />
+    )}
   </Stack>
 </Stack>
 ```
@@ -529,6 +378,12 @@ exactly as written. Do not substitute alternatives.
   `<Box display="flex" flexDirection="column"> <div className={...}>` scroll
   wrapper from Section 5. Omitting it breaks page scroll containment
 - NEVER put pagination inside DataTable
+- NEVER render pagination when all records fit on one page — only show it when
+  total > pageSize
+- NEVER derive the pagination total from `items.length` — always use a dedicated
+  count query
+- NEVER place filter dropdowns before the search input — search always comes
+  first (leftmost)
 - NEVER use plain text for status values — always use Badge with `children`
 - NEVER import `MeatBall` from `@spark-web/meatball` — the component is
   `MeatballMenu` from `@spark-web/meatball-menu`