@12-apps/ui 6.38.0 → 6.39.0

package/src/components/data-display/MapPreview/mapProjection.ts

@@ -1,4 +1,9 @@
-export const TILE_SIZE = 256;
+/**
+ * One tile's extent in Web Mercator's world units at zoom 0 — the projection's
+ * own coordinate space, not a drawn length: the tile index it yields is the
+ * same at any drawn size. `MapTiles` draws one world unit as one design px.
+ */
+export const TILE_WORLD_UNITS = 256;
 
 // Metres covered by one pixel at zoom 0 on the equator; each zoom level halves it.
 const EQUATOR_METRES_PER_PIXEL = 156543.03392;
@@ -12,8 +17,8 @@ const project = (lat: number, lng: number) => {
   const boundedSiny = Math.max(-0.9999, Math.min(0.9999, siny));
 
   return {
-    x: TILE_SIZE * (0.5 + lng / 360),
-    y: TILE_SIZE * (0.5 - Math.log((1 + boundedSiny) / (1 - boundedSiny)) / (4 * Math.PI)),
+    x: TILE_WORLD_UNITS * (0.5 + lng / 360),
+    y: TILE_WORLD_UNITS * (0.5 - Math.log((1 + boundedSiny) / (1 - boundedSiny)) / (4 * Math.PI)),
   };
 };
 
@@ -22,8 +27,8 @@ export const getTileCoordinates = (lat: number, lng: number, zoom: number) => {
   const world = project(lat, lng);
 
   return {
-    x: Math.floor(Math.floor(world.x * scale) / TILE_SIZE),
-    y: Math.floor(Math.floor(world.y * scale) / TILE_SIZE),
+    x: Math.floor(Math.floor(world.x * scale) / TILE_WORLD_UNITS),
+    y: Math.floor(Math.floor(world.y * scale) / TILE_WORLD_UNITS),
   };
 };
 

package/src/components/data-display/Table/Table.helpers.ts

@@ -1,5 +1,12 @@
 import type { TableProps } from './Table.types';
 
+/**
+ * A virtualised row's height in design px: the caller's `rowHeight`, else 52.
+ * Resolved here rather than in {@link TABLE_DEFAULTS} so the one number is read
+ * where it is drawn (`rem`) and where the window is positioned with it (`remPx`).
+ */
+export const tableRowHeight = (rowHeight: number | undefined): number => rowHeight ?? 52;
+
 export const TABLE_DEFAULTS: Partial<TableProps> = {
   variant: 'default',
   stripeColor: 'neutral',
@@ -13,7 +20,6 @@ export const TABLE_DEFAULTS: Partial<TableProps> = {
   selectedRows: [],
   sortable: false,
   virtualScrolling: false,
-  rowHeight: 52,
   overscan: 5,
   responsive: false,
   showColumnToggle: true,

package/src/components/data-display/Table/Table.hooks.ts

@@ -2,22 +2,31 @@ import { useTheme } from '@mui/material/styles/index.js';
 import useMediaQuery from '@mui/material/useMediaQuery/index.js';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
+import { rem, remPx } from '../../../tokens/relative';
+
 import type { ColumnConfig, TableProps } from './Table.types';
 
+/**
+ * The virtual window. `rowHeight` and `containerHeight` are design px: the
+ * window is computed in the px `scrollTop` is measured in (`remPx`), and what it
+ * hands back to draw with stays in design px (`offsetY`) or is CSS already
+ * (`totalHeight`), so the rows and the window share one pitch at any type scale.
+ */
 export const useVirtualScrolling = (
   data: Record<string, unknown>[],
   rowHeight: number,
   containerHeight: number,
   overscan: number = 5
 ) => {
+  const theme = useTheme();
   const [scrollTop, setScrollTop] = useState(0);
   
   const visibleItems = useMemo(() => {
-    const visibleHeight = containerHeight;
-    const startIndex = Math.floor(scrollTop / rowHeight);
+    const pitch = remPx(theme, rowHeight);
+    const startIndex = Math.floor(scrollTop / pitch);
     const endIndex = Math.min(
       data.length,
-      Math.ceil((scrollTop + visibleHeight) / rowHeight)
+      Math.ceil((scrollTop + remPx(theme, containerHeight)) / pitch)
     );
     
     const start = Math.max(0, startIndex - overscan);
@@ -27,10 +36,12 @@ export const useVirtualScrolling = (
       startIndex: start,
       endIndex: end,
       items: data.slice(start, end),
-      totalHeight: data.length * rowHeight,
+      /** Every row at the scaled pitch, as CSS. */
+      totalHeight: rem(theme, data.length * rowHeight),
+      /** Where the first mounted row sits, in design px. */
       offsetY: start * rowHeight,
     };
-  }, [data, rowHeight, containerHeight, scrollTop, overscan]);
+  }, [data, rowHeight, containerHeight, scrollTop, overscan, theme]);
 
   const handleScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
     setScrollTop(e.currentTarget.scrollTop);

package/src/components/data-display/Table/Table.types.ts

@@ -22,7 +22,9 @@ export interface ColumnConfig {
   label: string;
   sortable?: boolean;
   filterable?: boolean;
+  /** A number is design px, scaled with the theme's type scale; a string is used as given. */
   width?: number | string;
+  /** Design px, scaled with the theme's type scale. */
   minWidth?: number;
   priority?: number; // 1 = highest priority, higher numbers = lower priority
   align?: 'left' | 'center' | 'right';
@@ -191,7 +193,8 @@ export interface TableProps extends Omit<MuiTableProps, 'variant'> {
   virtualScrolling?: boolean;
   
   /**
-   * Height of each row for virtual scrolling (required if virtualScrolling is true)
+   * Height of each row for virtual scrolling (default 52) — design px, scaled
+   * with the theme's type scale.
    */
   rowHeight?: number;
   
@@ -226,7 +229,8 @@ export interface TableProps extends Omit<MuiTableProps, 'variant'> {
   showColumnToggle?: boolean;
   
   /**
-   * Container height for virtual scrolling
+   * Container height for virtual scrolling (default 400). A number is design
+   * px, scaled with the theme's type scale; a string is used as given.
    */
   containerHeight?: number | string;
   

package/src/components/data-display/Table/TableParts.tsx

@@ -5,8 +5,12 @@ import TableCell from '@mui/material/TableCell/index.js';
 import TableHead from '@mui/material/TableHead/index.js';
 import TableRow from '@mui/material/TableRow/index.js';
 import TableSortLabel from '@mui/material/TableSortLabel/index.js';
+import { useTheme, type Theme } from '@mui/material/styles/index.js';
 import React, { useCallback } from 'react';
 
+import { rem } from '../../../tokens/relative';
+
+import { tableRowHeight } from './Table.helpers';
 import { useVirtualScrolling } from './Table.hooks';
 import { useTableRowRenderer } from './TableParts.hooks';
 import type { ColumnConfig, TableBodyProps, TableHeaderProps } from './Table.types';
@@ -23,6 +27,10 @@ const ariaSortFor = (
   return direction === 'asc' ? 'ascending' : 'descending';
 };
 
+/** A column's `width`/`minWidth` as CSS: a number is design px, a string as given. */
+const columnLength = (theme: Theme, value: number | string | undefined): string | undefined =>
+  typeof value === 'number' ? rem(theme, value) : value;
+
 // One header cell. Sorting is offered when the table is sortable and the column
 // has not opted out; aria-sort mirrors the visible indicator.
 const HeaderCell: React.FC<{
@@ -31,13 +39,17 @@ const HeaderCell: React.FC<{
   sortConfig?: { key: string; direction: 'asc' | 'desc' };
   onSort: (columnKey: string) => void;
 }> = ({ column, sortable, sortConfig, onSort }) => {
+  const theme = useTheme();
   const canSort = Boolean(sortable) && column.sortable !== false;
   const isSorted = sortConfig?.key === column.key;
 
   return (
     <TableCell
       align={column.align || 'left'}
-      style={{ minWidth: column.minWidth, width: column.width }}
+      style={{
+        minWidth: columnLength(theme, column.minWidth),
+        width: columnLength(theme, column.width),
+      }}
       aria-sort={ariaSortFor(canSort, isSorted, sortConfig?.direction)}
     >
       {canSort ? (
@@ -120,10 +132,12 @@ export const TableDataRow: React.FC<{
   rowData: Record<string, unknown>;
   rowKey: string | number;
   index: number;
+  /** Where a virtualised row sits, in design px — drawn through `rem`, like its height. */
   offsetY: number;
   columns: ColumnConfig[];
   selected: boolean;
   selectable?: boolean;
+  /** Design px; 52 when unset (`tableRowHeight`). */
   rowHeight?: number;
   onRowClick?: TableBodyProps['onRowClick'];
   onRowFocus?: TableBodyProps['onRowFocus'];
@@ -145,8 +159,9 @@ export const TableDataRow: React.FC<{
   onRowBlur,
   onSelect,
   virtualScrolling,
-  renderCell }) => (
-
+  renderCell }) => {
+  const theme = useTheme();
+  return (
       <TableRow
         key={String(rowKey)}
         selected={selected}
@@ -155,12 +170,12 @@ export const TableDataRow: React.FC<{
         onFocus={(event: React.FocusEvent<globalThis.HTMLTableRowElement>) => onRowFocus?.(event, rowData)}
         onBlur={(event: React.FocusEvent<globalThis.HTMLTableRowElement>) => onRowBlur?.(event, rowData)}
         style={virtualScrolling ? { 
-          transform: `translateY(${offsetY}px)`,
+          transform: `translateY(${rem(theme, offsetY)})`,
           position: 'absolute',
           top: 0,
           left: 0,
           right: 0,
-          height: rowHeight } : undefined}
+          height: rem(theme, tableRowHeight(rowHeight)) } : undefined}
       >
         {selectable && (
           <TableCell padding="checkbox">
@@ -186,16 +201,19 @@ export const TableDataRow: React.FC<{
           );
         })}
       </TableRow>
-);
+  );
+};
 
 // Only the rows in view are rendered, positioned by absolute offset inside a
-// spacer sized to the full data set.
+// spacer sized to the full data set. `rowHeight`, `containerHeight` and every
+// offset are design px, drawn through `rem`.
 const VirtualisedBody: React.FC<{
   visibleItems: {
     items: Record<string, unknown>[];
     startIndex: number;
     offsetY: number;
-    totalHeight: number;
+    /** As CSS. */
+    totalHeight: string;
   };
   rowHeight: number;
   containerHeight: number;
@@ -205,12 +223,13 @@ const VirtualisedBody: React.FC<{
     index: number,
     offsetY?: number,
   ) => React.ReactNode;
-}> = ({ visibleItems, rowHeight, containerHeight, onScroll, renderTableRow }) => (
-
+}> = ({ visibleItems, rowHeight, containerHeight, onScroll, renderTableRow }) => {
+  const theme = useTheme();
+  return (
     <Box
       onScroll={onScroll}
       style={{
-        height: containerHeight,
+        height: rem(theme, containerHeight),
         overflow: 'auto',
         position: 'relative' }}
     >
@@ -224,8 +243,8 @@ const VirtualisedBody: React.FC<{
         )}
       </TableBody>
     </Box>
-  
-);
+  );
+};
 
 const PlainBody: React.FC<{
   data: TableBodyProps['data'];
@@ -238,35 +257,12 @@ const PlainBody: React.FC<{
 );
 
 // Enhanced Table Body Component  
-export const EnhancedTableBody: React.FC<TableBodyProps> = React.memo(({
-  data,
-  columns,
-  selectedRows = [],
-  onRowClick,
-  onRowFocus,
-  onRowBlur,
-  onSelectionChange,
-  rowKeyExtractor,
-  selectable,
-  renderRow,
-  renderCell,
-  virtualScrolling,
-  containerHeight,
-  rowHeight,
-  overscan = 5 }) => {
-  const renderTableRow = useTableRowRenderer({
-    columns,
-    selectedRows,
-    onRowClick,
-    onRowFocus,
-    onRowBlur,
-    onSelectionChange,
-    rowKeyExtractor,
-    selectable,
-    renderRow,
-    renderCell,
-    virtualScrolling,
-    rowHeight });
+export const EnhancedTableBody: React.FC<TableBodyProps> = React.memo((props) => {
+  const { data, virtualScrolling, containerHeight, overscan = 5 } = props;
+  // The row renderer takes the body's own props; its `rowHeight` stays the
+  // caller's design px, and the row resolves the default where it draws it.
+  const renderTableRow = useTableRowRenderer({ ...props, selectedRows: props.selectedRows ?? [] });
+  const rowHeight = tableRowHeight(props.rowHeight);
 
   const { visibleItems, handleScroll } = useVirtualScrolling(
     data, 

package/src/components/form/Calendar/Calendar.tsx

@@ -3,6 +3,8 @@ import Box from '@mui/material/Box/index.js';
 import Paper from '@mui/material/Paper/index.js';
 import React from 'react';
 
+import { rem, sxRem } from '../../../tokens/relative';
+
 import { resolveCalendarProps } from './Calendar.helpers';
 import { useCalendar } from './Calendar.hooks';
 import type { CalendarProps } from './Calendar.types';
@@ -16,9 +18,9 @@ const containerSx = (monthsToShow: number): SxProps<Theme> => ({
   gap: 3,
   outline: 'none',
   '&:focus-within': {
-    outline: '2px solid',
+    outline: (theme: Theme) => `${rem(theme, 2)} solid`,
     outlineColor: 'primary.main',
-    outlineOffset: 2,
+    outlineOffset: sxRem(2),
   },
 });
 

package/src/components/form/Calendar/CalendarDay.tsx

@@ -3,9 +3,12 @@ import Box from '@mui/material/Box/index.js';
 import type { FC } from 'react';
 import React from 'react';
 
+import { rem, sxRem } from '../../../tokens/relative';
+
 import type { DayRenderArgs } from './Calendar.types';
 
-const CELL_SIZE = 40;
+/** A day cell's edge, 40 design px through the theme's type scale. */
+const CELL_SIZE = sxRem(40);
 
 interface DayState extends DayRenderArgs {
   outside: boolean;
@@ -72,9 +75,9 @@ const dayCellSx = (day: DayRenderArgs, visible: boolean): SxProps<Theme> => ({
     backgroundColor: hoverBackgroundFor(day),
   },
   '&:focus': {
-    outline: '2px solid',
+    outline: (theme: Theme) => `${rem(theme, 2)} solid`,
     outlineColor: 'primary.main',
-    outlineOffset: 1,
+    outlineOffset: sxRem(1),
   },
 });
 

package/src/components/form/Calendar/CalendarMonth.tsx

@@ -6,12 +6,15 @@ import Typography from '@mui/material/Typography/index.js';
 import type { FC } from 'react';
 import React from 'react';
 
+import { sxRem } from '../../../tokens/relative';
+
 import { getMonthName } from './Calendar.dates';
 import type { CalendarProps, MonthMatrix } from './Calendar.types';
 import type { DayCellContext } from './CalendarDayCell';
 import { CalendarDayCell } from './CalendarDayCell';
 
-const SPACER_WIDTH = 32;
+/** The nav spacer's width and the weekday row's height, 32 design px through the type scale. */
+const SPACER_WIDTH = sxRem(32);
 
 const GRID_SX = { display: 'grid', gridTemplateColumns: 'repeat(7, 1fr)', gap: 0.5 } as const;
 
@@ -66,7 +69,7 @@ const WeekdayHeader: FC<{ weekdayNames: string[] }> = ({ weekdayNames }) => (
           alignItems: 'center',
           justifyContent: 'center',
           height: SPACER_WIDTH,
-          fontSize: '0.875rem',
+          fontSize: sxRem(14),
           fontWeight: 'bold',
           color: 'text.secondary',
         }}
@@ -109,7 +112,7 @@ export const CalendarMonth: FC<CalendarMonthProps> = ({
        January's 5th and February's. Without a per-month hook a test can only
        reach a day positionally, which is exactly what the flakiness gate
        refuses. Additive: `calendar-grid` below is unchanged. */
-    <Box sx={{ minWidth: 280 }} data-testid={`calendar-month-${monthIndex}`}>
+    <Box sx={{ minWidth: sxRem(280) }} data-testid={`calendar-month-${monthIndex}`}>
       <MonthNavHeader
         title={title}
         showPrevious={monthIndex === 0}

package/src/components/form/Switch/Switch.metrics.ts

@@ -87,12 +87,26 @@ export const MUI_SHADOWS: Record<number, string> = {
   3: ELEVATION_SHADOWS[3],
 };
 
-/** The iOS thumb's own three-layer shadow, which the web writes out literally. */
-export const IOS_THUMB_SHADOW = `0 3px 1px 0 ${alpha(SWITCH_BLACK, 0.04)}, 0 3px 8px 0 ${alpha(SWITCH_BLACK, 0.12)}, 0 1px 0 0 ${alpha(SWITCH_BLACK, 0.08)}`;
+/**
+ * How a shadow builder writes one of its lengths. Native takes the px as they
+ * stand ({@link AS_PX}); the web hands in its type scale (`rem`), so the iOS
+ * shadows scale with the theme like every other length it draws.
+ */
+export type ShadowLength = (px: number) => string;
+
+/** A length written as the px it was drawn at — what native reads. */
+export const AS_PX: ShadowLength = (value) => `${value}px`;
+
+/** The iOS thumb's own three-layer shadow. */
+export const iosThumbShadow = (length: ShadowLength = AS_PX): string =>
+  `0 ${length(3)} ${length(1)} 0 ${alpha(SWITCH_BLACK, 0.04)}, 0 ${length(3)} ${length(8)} 0 ${alpha(SWITCH_BLACK, 0.12)}, 0 ${length(1)} 0 0 ${alpha(SWITCH_BLACK, 0.08)}`;
+
+/** {@link iosThumbShadow} in px, as native draws it. */
+export const IOS_THUMB_SHADOW = iosThumbShadow();
 
-/** The iOS track's inset hairline. */
-export const iosTrackShadow = (): string =>
-  `inset 0 0 0 0.5px ${alpha(SWITCH_BLACK, 0.1)}, inset 0 2px 3px ${alpha(SWITCH_BLACK, 0.12)}`;
+/** The iOS track's inset hairline and inner shade. */
+export const iosTrackShadow = (length: ShadowLength = AS_PX): string =>
+  `inset 0 0 0 ${length(0.5)} ${alpha(SWITCH_BLACK, 0.1)}, inset 0 ${length(2)} ${length(3)} ${alpha(SWITCH_BLACK, 0.12)}`;
 
 /** The resting track: a black wash on iOS, the disabled ink elsewhere. */
 export const TRACK_ALPHA = { ios: 0.1, android: 0.2, other: 0.3 } as const;

package/src/components/form/Switch/Switch.styles.ts

@@ -12,7 +12,6 @@ import {
 import {
   DISABLED,
   IOS_BASE_OFFSET,
-  IOS_THUMB_SHADOW,
   IOS_TRAVEL_INSET,
   SWITCH_GLASS,
   SWITCH_GLOW,
@@ -30,6 +29,7 @@ import {
   TRACK_LABEL,
   TRACK_RADIUS,
   geometryOf,
+  iosThumbShadow,
   iosTrackShadow,
   lookOf,
   seconds,
@@ -108,7 +108,9 @@ const lengthOrPercent = (theme: Theme, value: number | string): string =>
   typeof value === 'number' ? rem(theme, value) : value;
 
 const thumbShadow = (theme: Theme, look: SwitchLook): string =>
-  look === 'ios' ? IOS_THUMB_SHADOW : (theme.shadows[THUMB_ELEVATION[look]] ?? 'none');
+  look === 'ios'
+    ? iosThumbShadow((px) => rem(theme, px))
+    : (theme.shadows[THUMB_ELEVATION[look]] ?? 'none');
 
 /** The ripple that expands from the thumb on hover. */
 const rippleOverlay = (palette: ColorPalette): CSSObject => ({
@@ -356,7 +358,7 @@ const trackSx = (
     opacity: 1,
     transition: `all ${seconds(SWITCH_TRANSITION.ms)} ${SWITCH_TRANSITION.easing}`,
     position: 'relative',
-    boxShadow: look === 'ios' ? iosTrackShadow() : 'none',
+    boxShadow: look === 'ios' ? iosTrackShadow((px) => rem(theme, px)) : 'none',
     ...(glass && {
       backgroundColor: alpha(theme.palette.background.paper, SWITCH_GLASS.trackAlpha),
       backdropFilter: `blur(${rem(theme, SWITCH_GLASS.trackBlur)})`,

package/src/components/layout/CardGrid/CardGrid.tsx

@@ -1,11 +1,13 @@
+import { useTheme, type Theme } from "@mui/material/styles/index.js";
 import { Children, type CSSProperties, type ReactNode, type Ref } from "react";
 
+import { rem } from "../../../tokens/relative";
 import { cn } from "../../../utils/cn";
 
 /**
  * How the grid turns surplus row space into layout:
  *
- * - `"fixed"` — every column is exactly `cardWidth` px; leftover row space is
+ * - `"fixed"` — every column is exactly `cardWidth` design px; leftover row space is
  *   spread as even gutters (`justify-content: space-around`). Cards never resize;
  *   the column count changes with the viewport. This is the original tabwoah
  *   card-grid behavior.
@@ -14,7 +16,7 @@ import { cn } from "../../../utils/cn";
  *   left-aligned at a single track's width rather than stretching edge to edge.
  * - `"scroll"` — a single row that scrolls horizontally, with fluid-width cards
  *   sized from the container so that exactly {@link SCROLL_VISIBLE_CARDS} cards
- *   plus a {@link SCROLL_PEEK_WIDTH}px sliver of the next one fit on screen (up
+ *   plus a `GRID.peekPx` sliver of the next one fit on screen (up
  *   to `maxCardWidth`, past which more cards simply fit). The sliver is the
  *   point: it makes the rail visibly continue past the fold, so the row reads as
  *   swipeable instead of as a finished pair of cards. Wrapping is off; the row
@@ -23,19 +25,27 @@ import { cn } from "../../../utils/cn";
  */
 export type CardGridVariant = "fixed" | "fluid" | "scroll";
 
-/** The grid gap, in px — mirrors the `gap: 1rem` below, for the scroll math. */
-const GRID_GAP = 16;
+/**
+ * The grid's own lengths, in design px — every one drawn through `rem`, so the
+ * `gap` the grid lays out with and the gap the scroll track math reserves are
+ * the same length at any type scale.
+ */
+const GRID = {
+  /** Between cards: the grid's `gap`, and what the scroll math reserves per gap. */
+  gapPx: 16,
+  /**
+   * `scroll`: the next card left visible past the last whole one — the
+   * "there's more, swipe" hint. Wide enough to read as a clipped card (rounded
+   * edge + a slice of its photo) rather than as a rendering glitch.
+   */
+  peekPx: 28,
+  /** Under the row — the tabwoah original's Tailwind `pb-0.5`. */
+  paddingBottomPx: 2,
+} as const;
 
 /** `scroll`: how many WHOLE cards the rail commits to showing at once. */
 const SCROLL_VISIBLE_CARDS = 2;
 
-/**
- * `scroll`: px of the next card left visible past the last whole one — the
- * "there's more, swipe" hint. Wide enough to read as a clipped card (rounded
- * edge + a slice of its photo) rather than as a rendering glitch.
- */
-const SCROLL_PEEK_WIDTH = 28;
-
 /**
  * The `scroll` track width: the widest a card can be while the container still
  * shows `SCROLL_VISIBLE_CARDS` of them plus the peek — or, when there is nothing
@@ -46,25 +56,27 @@ const SCROLL_PEEK_WIDTH = 28;
  * that follow them (one between each pair, one before the peeked card), and the
  * peek. With no overflow there are only N-1 gaps and no peek.
  */
-function scrollTrackWidth(count: number, max: number): string {
+function scrollTrackWidth(theme: Theme, count: number, max: number): string {
   const tracks = Math.max(1, Math.min(count, SCROLL_VISIBLE_CARDS));
   const overflows = count > tracks;
   const gaps = overflows ? tracks : tracks - 1;
-  const reserved = gaps * GRID_GAP + (overflows ? SCROLL_PEEK_WIDTH : 0);
-  return `min(${max}px, calc((100% - ${reserved}px) / ${tracks}))`;
+  const reserved = gaps * GRID.gapPx + (overflows ? GRID.peekPx : 0);
+  return `min(${rem(theme, max)}, calc((100% - ${rem(theme, reserved)}) / ${tracks}))`;
 }
 
 interface CardGridProps {
   /**
-   * `"fixed"`: the exact column width in px. `"fluid"`: the minimum column width
+   * `"fixed"`: the exact column width. `"fluid"`: the minimum column width
    * (columns grow from here). `"scroll"`: only seeds the default `maxCardWidth`
    * — a scroll track has no minimum, because a minimum is exactly what would
    * break the "two cards plus a peek" promise on a narrow phone.
+   *
+   * Design px, scaled with the theme's type scale.
    */
   cardWidth: number;
   /**
-   * `"scroll"` only: the maximum fluid card width in px. Defaults to
-   * `1.6 × cardWidth`.
+   * `"scroll"` only: the maximum fluid card width. Defaults to
+   * `1.6 × cardWidth`. Design px, scaled with the theme's type scale.
    */
   maxCardWidth?: number;
   /** Layout behavior — see {@link CardGridVariant}. Defaults to `"fixed"`. */
@@ -84,8 +96,8 @@ interface CardGridProps {
  *
  * Ported from the tabwoah card grid (the `"fixed"` variant is verbatim). The one
  * adaptation: that app is Tailwind (`className="grid gap-4 pb-0.5"`); this one
- * has no Tailwind, so those three utilities (display:grid, gap 1rem,
- * padding-bottom 2px) live in `style`.
+ * has no Tailwind, so those three utilities (display:grid, gap 16 design px,
+ * padding-bottom 2 design px) live in `style`, drawn through `rem`.
  */
 export function CardGrid({
   cardWidth,
@@ -96,10 +108,11 @@ export function CardGrid({
   containerRef,
   children,
 }: CardGridProps) {
+  const theme = useTheme();
   const style: CSSProperties = {
     display: "grid",
-    gap: "1rem",
-    paddingBottom: "2px",
+    gap: rem(theme, GRID.gapPx),
+    paddingBottom: rem(theme, GRID.paddingBottomPx),
   };
 
   if (variant === "scroll") {
@@ -109,14 +122,14 @@ export function CardGrid({
     // always fit (see `scrollTrackWidth`). Scroll-snap makes a swipe settle on a
     // card boundary instead of drifting mid-card.
     style.gridAutoFlow = "column";
-    style.gridAutoColumns = scrollTrackWidth(Children.count(children), max);
+    style.gridAutoColumns = scrollTrackWidth(theme, Children.count(children), max);
     style.overflowX = "auto";
     style.overflowY = "hidden";
     style.scrollSnapType = "x mandatory";
   } else if (variant === "fluid") {
-    style.gridTemplateColumns = `repeat(auto-fill, minmax(${cardWidth}px, 1fr))`;
+    style.gridTemplateColumns = `repeat(auto-fill, minmax(${rem(theme, cardWidth)}, 1fr))`;
   } else {
-    style.gridTemplateColumns = `repeat(auto-fill, ${cardWidth}px)`;
+    style.gridTemplateColumns = `repeat(auto-fill, ${rem(theme, cardWidth)})`;
     // `space-around` only distributes leftover width in the fixed variant; the
     // fluid variant consumes it via `1fr` and scroll overflows instead.
     style.justifyContent = "space-around";