@spark-web/design-system 5.1.4 → 5.1.6

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

@@ -2,10 +2,9 @@
 
 ## 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, row clickability rules, and overflow menu rules defined there all apply
-to this pattern.
+Surface rules: read
+`node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md` in
+full first — its rules all apply here.
 
 ## What this pattern is
 
@@ -15,11 +14,9 @@ admin surfaces.
 
 ## When to use this pattern
 
-Use this pattern when the PRD describes any of the following:
-
-- A list of records that can be searched, filtered, or sorted
-- A management interface where records can be viewed or acted upon
-- The words "list", "manage", "view all", "records", or "results"
+Any list/management view of records — the registry
+(`node_modules/@spark-web/design-system/patterns/CLAUDE.md`) owns surface and
+feature-type classification.
 
 ---
 
@@ -27,17 +24,24 @@ Use this pattern when the PRD describes any of the following:
 
 Read these before implementing — they own the component-level rules:
 
-- `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
+- `node_modules/@spark-web/page-header/CLAUDE.md` — PageHeader API, action type
+  rules
+- `node_modules/@spark-web/data-table/CLAUDE.md` — DataTable API, column defs,
+  loading/empty states, headerClassName tokens
+- `node_modules/@spark-web/badge/CLAUDE.md` — status tone mapping
+- `node_modules/@spark-web/meatball-menu/CLAUDE.md` — MeatballMenu API
+- `node_modules/@spark-web/stack/CLAUDE.md` — vertical stacking and gap
+- `node_modules/@spark-web/box/CLAUDE.md` — flex layout utilities
+- `node_modules/@spark-web/columns/CLAUDE.md` — responsive multi-column layout
+- `node_modules/@spark-web/field/CLAUDE.md` — Field API, labelVisibility
+- `node_modules/@spark-web/select/CLAUDE.md` — Select API, filter dropdown
+  pattern
+- `node_modules/@spark-web/multi-select/CLAUDE.md` — MultiSelect filter
+  dropdowns
+- `node_modules/@spark-web/text/CLAUDE.md` — Text API
+- `node_modules/@spark-web/text-input/CLAUDE.md` — TextInput API
+- `node_modules/@spark-web/alert/CLAUDE.md` — page-level feedback Alert
+- `node_modules/@spark-web/icon/CLAUDE.md` — icon sizing and tones (SearchIcon)
 
 ---
 
@@ -66,8 +70,8 @@ manual `Stack + Heading`.
 <PageHeader label={pageTitle} />
 ```
 
-See `packages/page-header/CLAUDE.md` for action types (button, link, meatball),
-statusBadge, and controls props.
+See `node_modules/@spark-web/page-header/CLAUDE.md` for action types (button,
+link, meatball), statusBadge, and controls props.
 
 Rules:
 
@@ -111,7 +115,7 @@ Rules:
 The outermost container fills the full viewport height.
 
 ```tsx
-<Stack height="full" className={css({ minHeight: '100vh' })}>
+<Stack height="full" css={{ minHeight: '100vh' }}>
 ```
 
 Documented exception:
@@ -129,13 +133,11 @@ Sits inside the outer wrapper. Owns all page padding and gap between sections.
 <Stack
   padding="large"
   gap="large"
-  className={css({
-    backgroundColor: theme.color.background.neutral,
-    flex: 1,
-    display: 'flex',
-    flexDirection: 'column',
-    overflow: 'hidden',
-  })}
+  flex={1}
+  display="flex"
+  flexDirection="column"
+  overflow="hidden"
+  css={{ backgroundColor: theme.color.background.neutral }}
 >
 ```
 
@@ -145,11 +147,17 @@ Token mappings:
 - `gap="large"` — between all sections, Spark token
 - `backgroundColor` — `theme.color.background.neutral` via `useTheme()`
 
-Documented exceptions:
+Spark props (not exceptions):
+
+- `flex={1}` — makes content area fill remaining height (Box `flex` prop)
+- `display="flex"` + `flexDirection="column"` — required to activate `flex={1}`
+  (Box props)
+- `overflow="hidden"` — scroll containment (Box `overflow` prop)
+
+Documented exception:
 
-- `flex: 1` — makes content area fill remaining height, no Spark flex prop
-- `display: 'flex'` + `flexDirection: 'column'` — required to activate flex: 1
-- `overflow: 'hidden'` — scroll containment, no Spark overflow prop on Stack
+- `backgroundColor: theme.color.background.neutral` — accessed via `useTheme()`,
+  not a Box prop, so it goes through the `css` prop
 
 ---
 
@@ -158,29 +166,43 @@ Documented exceptions:
 Renders filter dropdowns and a search input in a horizontal row.
 
 ```tsx
-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"
-    label="Label"
-    options={options}
-    placeholder="Filter by..."
-    fieldProps={FieldProps}
-  />
-</Columns>;
+  {/* Search — always first */}
+  <Field label="Search" labelVisibility="hidden">
+    <TextInput
+      placeholder="Search by..."
+      value={search}
+      onChange={e => setSearch(e.target.value)}
+    >
+      <InputAdornment placement="start">
+        <SearchIcon size="xxsmall" tone="muted" />
+      </InputAdornment>
+    </TextInput>
+  </Field>
+
+  {/* Multi-select filter */}
+  <Box>
+    <VisuallyHidden as="span" id="status-filter-label">
+      Status
+    </VisuallyHidden>
+    <MultiSelect
+      aria-labelledby="status-filter-label"
+      options={[{ label: '', options: statusOptions }]}
+      placeholder="Filter by status..."
+      onChange={setStatusFilter}
+    />
+  </Box>
+
+  {/* Single-select filter */}
+  <Field label="Role" labelVisibility="hidden">
+    <Select
+      placeholder="Filter by role..."
+      options={roleOptions}
+      value={roleFilter}
+      onChange={e => setRoleFilter(e.target.value)}
+    />
+  </Field>
+</Columns>
 ```
 
 Rules:
@@ -190,13 +212,18 @@ Rules:
 - **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`
-- Always pass `fieldProps={{ labelVisibility: 'hidden' as const }}` on both
-  `MultiSelectField` and `SelectField` — define it as a constant outside the
-  component to avoid re-renders
+- Multi-select filter dropdowns use `MultiSelect` from
+  `@spark-web/multi-select`. Its `options` are grouped — pass
+  `[{ label: '', options }]` for a flat list. It renders no visible label, so
+  label it for assistive technology via `aria-labelledby` pointing at a
+  `VisuallyHidden` element from `@spark-web/a11y`
+- Single-select filter dropdowns use `Select` from `@spark-web/select`, always
+  wrapped in a `Field`
+- Filter labels are never visible — wrap `TextInput` and `Select` in a `Field`
+  with `labelVisibility="hidden"`; the `label` is still required for
+  accessibility
+- Working in portal-hub? Apply the substitutions in
+  `node_modules/@spark-web/design-system/patterns/internal-admin/portal-hub.md`.
 - If no filtering or searching is needed, omit this section entirely
 
 ---
@@ -207,32 +234,33 @@ Wraps the DataTable to enable vertical scrolling without the page scrolling.
 
 ```tsx
 <Box display="flex" flexDirection="column">
-  <div
-    className={css({
-      position: 'relative',
-      flex: 1,
-      minHeight: 0,
-      overflowY: 'auto',
-    })}
+  <Box
+    position="relative"
+    flex={1}
+    css={{ minHeight: 0, overflowY: 'auto' }}
   >
     <DataTable ... />
-  </div>
+  </Box>
 </Box>
 ```
 
-Documented exceptions — all required for flex scroll behaviour:
+Spark props and documented exceptions — all required for flex scroll behaviour:
 
-- `position: 'relative'` — scroll container positioning
-- `flex: 1` — fills available height
-- `minHeight: 0` — classic flex scroll fix, prevents overflow
-- `overflowY: 'auto'` — enables vertical scrolling
+- `position="relative"` — scroll container positioning (Box `position` prop)
+- `flex={1}` — fills available height (Box `flex` prop)
+- `minHeight: 0` — classic flex scroll fix, prevents overflow (documented
+  exception — Box `minHeight` only accepts `0` via the prop, so this goes
+  through `css`)
+- `overflowY: 'auto'` — enables vertical scrolling (documented exception — no
+  axis-specific overflow prop, so this goes through `css`)
 
 ---
 
 ## Section 6 — Table
 
-Always uses `@spark-web/data-table`. See `packages/data-table/CLAUDE.md` for
-column definition API, loading/empty states, sorting, and expansion.
+Always uses `@spark-web/data-table`. See
+`node_modules/@spark-web/data-table/CLAUDE.md` for column definition API,
+loading/empty states, sorting, and expansion.
 
 Apply canonical list-page header styling via `headerClassName`. Use the named
 import `import { css as reactCss } from '@emotion/react'` — `headerClassName`
@@ -270,14 +298,14 @@ Column rules:
   exist
 
 Row interaction rules — see
-`packages/design-system/patterns/internal-admin/CLAUDE.md`:
+`node_modules/@spark-web/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
-`packages/design-system/patterns/internal-admin/CLAUDE.md`. Do not duplicate
-them here.
+`node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md`. Do
+not duplicate them here.
 
 ---
 
@@ -285,12 +313,30 @@ them here.
 
 Render `TablePagination` outside and below DataTable — never nested inside it.
 
-- **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
+```tsx
+{
+  /* COMPONENT GAP: TablePagination is NOT a spark-web component — build a
+    placeholder from @spark-web/box + @spark-web/button (prev/next + "Show N of
+    M") and flag it for product design review before production. Props:
+    total, pageSize, current, dataShowing, onChange(page). */
+}
+{
+  total > PAGE_SIZE && (
+    <TablePagination
+      total={total}
+      pageSize={PAGE_SIZE}
+      dataShowing={rows.length}
+      onChange={setPage}
+      current={page}
+    />
+  );
+}
+```
+
+Render-only-when `total > pageSize`, default `pageSize` **20**, and
+total-from-a-dedicated-count-query are enforced by the Do NOTs and checklist
+below. No additional wrapper needed — content area `gap="large"` handles
+spacing.
 
 ---
 
@@ -300,42 +346,23 @@ Use this skeleton as the starting point for new builds and uplifts. Do not use
 existing page implementations as a structural reference.
 
 ```tsx
-<Stack height="full" className={css({ minHeight: '100vh' })}>
+<Stack height="full" css={{ minHeight: '100vh' }}>
   <PageHeader label={pageTitle} />
 
-  <Stack
-    padding="large"
-    gap="large"
-    className={css({
-      backgroundColor: theme.color.background.neutral,
-      flex: 1,
-      display: 'flex',
-      flexDirection: 'column',
-      overflow: 'hidden',
-    })}
-  >
+  <Stack /* Section 3 content-area props — copy verbatim from Section 3 */>
     <Columns gap="large" collapseBelow="desktop">
-      {/* search first, then filters */}
+      {/* search first, then filters — Section 4 */}
     </Columns>
 
-    <Box display="flex" flexDirection="column">
-      <div
-        className={css({
-          position: 'relative',
-          flex: 1,
-          minHeight: 0,
-          overflowY: 'auto',
-        })}
-      >
-        <DataTable
-          items={items}
-          columns={columns}
-          isLoading={isLoading}
-          emptyState={emptyState}
-        />
-      </div>
-    </Box>
+    {/* Section 5 scroll wrapper — copy verbatim from Section 5, wrapping: */}
+    <DataTable
+      items={items}
+      columns={columns}
+      isLoading={isLoading}
+      emptyState={emptyState}
+    />
 
+    {/* COMPONENT GAP: TablePagination — see Section 7 */}
     {total > PAGE_SIZE && (
       <TablePagination
         total={total}
@@ -356,16 +383,15 @@ existing page implementations as a structural reference.
 These raw CSS values are required and have no Spark token equivalent. Use them
 exactly as written. Do not substitute alternatives.
 
-| Value                                         | Property                     | Reason                                  |
-| --------------------------------------------- | ---------------------------- | --------------------------------------- |
-| `minHeight: '100vh'`                          | Outer Stack                  | No Spark minHeight prop                 |
-| `flex: 1`                                     | Content area, scroll wrapper | No Spark flex prop                      |
-| `display: 'flex'` + `flexDirection: 'column'` | Content area                 | Required for flex: 1                    |
-| `overflow: 'hidden'`                          | Content area                 | No Spark overflow on Stack              |
-| `position: 'relative'`                        | Scroll div                   | No Spark position prop                  |
-| `minHeight: 0`                                | Scroll div                   | Flex scroll fix                         |
-| `overflowY: 'auto'`                           | Scroll div                   | No Spark overflow prop                  |
-| `backgroundColor: background.neutral`         | Content area                 | Accessed via useTheme(), not a Box prop |
+| Value                                       | Property                       | Reason                                           |
+| ------------------------------------------- | ------------------------------ | ------------------------------------------------ |
+| `minHeight: '100vh'`                        | Outer Stack                    | No Spark minHeight prop                          |
+| `minHeight: 0`                              | Scroll Box                     | Flex scroll fix — Box `minHeight` only accepts 0 |
+| `overflowY: 'auto'`                         | Scroll Box                     | No axis-specific overflow prop                   |
+| `backgroundColor: background.neutral`       | Content area                   | Accessed via useTheme(), not a Box prop          |
+| `boxShadow: inset 0 -2px ...`               | DataTable `headerClassName`    | Canonical header underline — no token equivalent |
+| `textTransform: 'capitalize'`, `svg stroke` | DataTable `headerClassName` th | Canonical header text/icon styling               |
+| `width: '100%'`                             | DataTable `className`          | Table fills the scroll wrapper                   |
 
 ---
 
@@ -375,8 +401,8 @@ exactly as written. Do not substitute alternatives.
   `<Stack height="full">`. Container constrains width and removes full-height
   layout and scroll containment behaviour
 - NEVER place DataTable directly inside the content area Stack — always use the
-  `<Box display="flex" flexDirection="column"> <div className={...}>` scroll
-  wrapper from Section 5. Omitting it breaks page scroll containment
+  `<Box display="flex" flexDirection="column">` + inner scroll `<Box>` 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
@@ -401,13 +427,49 @@ exactly as written. Do not substitute alternatives.
   list page — those values belong in detail-page.md only
 - NEVER render an external loading spinner/text outside DataTable — always use
   the `isLoading` prop on DataTable to show loading state
-- NEVER use `Stack + Text weight="semibold"` to label a MultiSelectField or
-  SelectField filter — always use
-  `fieldProps={{ labelVisibility: 'hidden' as const }}`
-- NEVER omit `fieldProps={{ labelVisibility: 'hidden' as const }}` on
-  SelectField filter dropdowns — the same hidden label rule that applies to
-  MultiSelectField applies to SelectField equally
-- NEVER use `@spark-web/multi-select` in portal-hub — it is not installed; use
-  `MultiSelectField` from `@brighte/ui-components`
+- NEVER use `Stack + Text weight="semibold"` to label a select or multi-select
+  filter — labels are provided accessibly but never visibly:
+  `labelVisibility="hidden"` on `Field`, or `aria-labelledby` + `VisuallyHidden`
+  for `MultiSelect`
 - NEVER use `className` with a string from `@emotion/css` on DataTable — use
   `SerializedStyles` from `@emotion/react`'s `css` tagged template
+
+---
+
+## Validation checklist
+
+Run before marking any list-page task complete and fix every violation; the
+uplift protocol in `node_modules/@spark-web/design-system/CLAUDE.md` runs this
+list PASS/FAIL against existing pages.
+
+1. PageHeader from `@spark-web/page-header` renders the page H1 via `label` — no
+   manual Stack + Heading.
+2. Outer wrapper is `Stack height="full"` with the documented
+   `minHeight: '100vh'` exception — not Container, and no padding on the outer
+   wrapper.
+3. Content area Stack has `padding="large" gap="large"`, neutral background via
+   the `css` prop, and `flex={1}` / `display="flex"` / `flexDirection="column"`
+   / `overflow="hidden"` as Spark Box props — nothing else.
+4. If search/filtering exists: filter row is
+   `Columns gap="large" collapseBelow="desktop"`, search input first (leftmost),
+   all labels hidden but accessible — `labelVisibility="hidden"` on each
+   `Field`, `aria-labelledby` + `VisuallyHidden` for `MultiSelect` (or the
+   consumer-overlay equivalent).
+5. DataTable sits inside the flex scroll wrapper from Section 5 — never directly
+   in the content Stack.
+6. DataTable receives `isLoading` and `emptyState` — no external spinner/loading
+   text.
+7. Status columns use `<Badge>` (dot + label) with a tone from the surface tone
+   mapping — never plain text, never StatusBadge, never `tone="pending"`.
+8. Actions column (if present) is last, `size: 80`, empty header; MeatballMenu
+   when 2+ row actions; row click/hover follows the surface rules; no hardcoded
+   column widths except the actions column.
+9. Pagination renders outside DataTable, only when `total > pageSize` (default
+   20), with `total` from a dedicated count query.
+10. No raw CSS values beyond the Documented exceptions table (which includes the
+    Section 6 canonical header styling).
+11. Every component is `@spark-web/*` or an explicit consumer-overlay
+    substitute; anything missing is flagged with a `// COMPONENT GAP:` comment.
+12. DataTable header uses the canonical `headerClassName` styling from Section
+    6, passed as `SerializedStyles` from `@emotion/react`'s `css` — never a
+    string class from `@emotion/css`.

package/patterns/internal-admin/portal-hub.md

@@ -0,0 +1,165 @@
+# Internal admin — portal-hub consumer overlay
+
+Consumer overlay for the **portal-hub** repo (see Consumer overlays in
+`node_modules/@spark-web/design-system/patterns/CLAUDE.md`) — it overrides the
+internal-admin pattern files and component-level CLAUDE.md files ONLY where it
+explicitly says so; every other rule applies to portal-hub unchanged.
+
+---
+
+## Filter fields (overrides list-page.md Section 4)
+
+`@spark-web/multi-select` is not available to app code in portal-hub (it is a
+dependency of the internal ui-components package only). Filter and search fields
+come from `@brighte/ui-components` instead. This override applies ONLY to
+component substitutions; all other Section 4 rules — search input always first,
+filter ordering broadest to most specific, hidden labels, omit the section when
+no filtering exists — apply unchanged. The substitutions:
+
+- Multi-select filter dropdowns use `MultiSelectField` from
+  `@brighte/ui-components`
+- Single-select filter dropdowns use `SelectField` from `@brighte/ui-components`
+- The search input uses `TextInputField` from `@brighte/ui-components` with the
+  same start-adornment `SearchIcon`
+
+Always pass `fieldProps={{ labelVisibility: 'hidden' as const }}` on both
+`MultiSelectField` and `SelectField` — define it as a constant outside the
+component to avoid re-renders:
+
+```tsx
+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"
+    label="Label"
+    options={options}
+    placeholder="Filter by..."
+    fieldProps={FieldProps}
+  />
+</Columns>;
+```
+
+Note the casing: the prop is `FieldProps` (capital F) on `TextInputField` and
+`fieldProps` (lowercase f) on `MultiSelectField`/`SelectField` — match the
+snippet exactly.
+
+Do NOTs (portal-hub):
+
+- NEVER import `@spark-web/multi-select` directly in portal-hub app code; use
+  `MultiSelectField` from `@brighte/ui-components`
+- NEVER omit the hidden-label `fieldProps` constant on SelectField filter
+  dropdowns — define it once outside the component and pass it everywhere
+
+---
+
+## Text inputs (overrides the 'Controlled usage with form state' sections in text-input/text-area CLAUDE.md)
+
+In portal-hub, prefer the `Field`-wrapped bindings from `@brighte/ui-components`
+over hand-wiring `@spark-web/text-input` / `@spark-web/text-area` into forms:
+
+- Prefer `TextInputField` from `@brighte/ui-components` when used with
+  `react-hook-form`. Pass `placeholder` directly, and use `FieldProps` to pass
+  `description` (renders as muted hint text below the label):
+
+```tsx
+<TextInputField
+  control={control}
+  name="subject"
+  label="Subject"
+  placeholder="Type here..."
+  FieldProps={{ description: 'Enter a brief summary of the issue' }}
+/>
+```
+
+- Prefer `TextAreaField` from `@brighte/ui-components` when used with
+  `react-hook-form`. Pass `placeholder` directly:
+
+```tsx
+<TextAreaField
+  control={control}
+  name="note"
+  label="Note"
+  placeholder="Type your note here..."
+/>
+```
+
+---
+
+## Section cards (overrides detail-page.md Section 7)
+
+portal-hub uses a custom wrapper at `@components/PortalTable/SectionCard` — not
+`@spark-web/section-card`. The API differs from the Spark component:
+
+```tsx
+import { SectionCard } from '@components/PortalTable/SectionCard';
+
+<SectionCard label="Section Title">{/* section content */}</SectionCard>;
+```
+
+| Prop       | Type        | Notes                                                                        |
+| ---------- | ----------- | ---------------------------------------------------------------------------- |
+| `label`    | `string`    | Optional — card header text; usually provided — header only renders when set |
+| `tag`      | `TagProps`  | Optional — tag rendered in the card header                                   |
+| `action`   | `ReactNode` | Optional — right-side header control                                         |
+| `controls` | `ReactNode` | Optional — additional header controls                                        |
+
+Return `null` for sections conditionally hidden — never render an empty card.
+
+---
+
+## Modal sizing (ACCREDITATION_MODAL_CSS)
+
+The shared admin modal size constant described in
+`node_modules/@spark-web/modal-dialog/CLAUDE.md` already exists in portal-hub —
+do not define a new one. The standard size constant used across all admin
+confirmation modals is defined in `apps/admin-portal/src/utils/constants.tsx`:
+
+```ts
+export const ACCREDITATION_MODAL_CSS = {
+  width: '100vw',
+  maxWidth: '550px',
+} as const;
+```
+
+Always pass this constant via `css={ACCREDITATION_MODAL_CSS}` — never set width
+inline or use a raw pixel value.
+
+---
+
+## Row-as-link reference implementation
+
+The row-as-link navigation pattern documented in
+`node_modules/@spark-web/data-table/CLAUDE.md` has a reference implementation in
+portal-hub at `apps/admin-portal/src/components/RowLink` (uses TanStack Router).
+
+---
+
+## TablePagination
+
+portal-hub supplies its own `TablePagination` component. It is the
+`TablePagination` referenced by both the list-page and detail-page patterns.
+Props used by the patterns:
+
+| Prop          | Notes                                             |
+| ------------- | ------------------------------------------------- |
+| `total`       | Total record count — from a dedicated count query |
+| `pageSize`    | 20 on list pages; 5 on detail-page section tables |
+| `dataShowing` | Number of rows on the current page                |
+| `onChange`    | Page change handler                               |
+| `current`     | Current page number                               |
+
+This is a confirmed COMPONENT GAP — no `@spark-web` pagination component exists
+yet. Until one ships, every consumer supplies its own pagination component.