feat(ui): establish table and list density contract

2026-09-13 09:14:35 +02:00
parent 2cdcab9e21
commit c99f4fb7dd
42 changed files with 5388 additions and 23 deletions
@@ -51,6 +51,7 @@ import { useI18n } from "../i18n/I18nProvider";
 import { JobApplication } from "../types";
 import { useViewResource } from "../hooks/useViewResource";
 import { getWorkflowAction } from "../jobWorkflowSignals";
+import type { ContentDensity } from "../theme";

 interface PagedResult<T> {
  items: T[];
@@ -179,6 +180,8 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
  const [jobs, setJobs] = useState<JobApplication[]>([]);
  const [total, setTotal] = useState(0);
  const [page, setPage] = useState(() => queryPage(location.search));
+  // Presentation only: not an account preference, saved-view field or API input.
+  const [density, setDensity] = useState<ContentDensity>("comfortable");
  const [selectedIds, setSelectedIds] = useState<number[]>([]);
  const [search, setSearch] = useState(() => new URLSearchParams(location.search).get("q") ?? "");
  const debouncedSearch = useDebouncedValue(search, 250);
@@ -456,6 +459,15 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
  const statusOptions = ["Waiting", "Interview", "Offer", "Rejected", "Ghosted"] as const;
  const visibleDesktopColumns = 6 + Number(columns.status) + Number(columns.dateApplied) + Number(columns.daysSince) + Number(columns.jobUrl);
  const selectedCompanyIsLoading = companyFilterId !== "All" && !companies.some((company) => company.id === companyFilterId);
+  const densityControl = (
+    <FormControl size="small" sx={{ minWidth: 150, width: { xs: "100%", sm: "auto" } }}>
+      <InputLabel id="job-table-density-label">{t("listDensity")}</InputLabel>
+      <Select labelId="job-table-density-label" label={t("listDensity")} value={density} onChange={(event) => setDensity(event.target.value as ContentDensity)}>
+        <MenuItem value="comfortable">{t("densityComfortable")}</MenuItem>
+        <MenuItem value="compact">{t("densityCompact")}</MenuItem>
+      </Select>
+    </FormControl>
+  );

  return (
    <Box>
@@ -537,6 +549,7 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
                {t("jobTableColumns")}
              </Button>
            </Box>
+            {densityControl}
          </Stack>
        </Paper>
      ) : (
@@ -589,6 +602,7 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
            {mode === "jobs" ? <FormControlLabel control={<Checkbox checked={includeDeleted} onChange={(e) => changeIncludeDeleted(e.target.checked)} />} label={t("jobTableShowDeleted")} sx={{ mr: 0 }} /> : null}
            <SavedViewsMenu current={{ q: search.trim() || undefined, status: statusFilter !== "All" ? statusFilter : undefined, companyId: companyFilterId === "All" ? undefined : (companyFilterId as number), location: locationFilter.trim() || undefined, needsFollowUp: needsFollowUpOnly ? true : undefined, readiness: readinessFilter === "all" ? undefined : readinessFilter }} onApply={applySavedView} />
            {!isMobile ? <Tooltip title={t("jobTableColumns")}><IconButton aria-label={t("jobTableColumns")} onClick={(e) => setColumnsAnchor(e.currentTarget)}><ViewColumnIcon /></IconButton></Tooltip> : null}
+            {densityControl}
          </Box>
        </Box>
      )}
@@ -605,8 +619,8 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col

      <Menu anchorEl={columnsAnchor} open={Boolean(columnsAnchor)} onClose={() => setColumnsAnchor(null)}>
        {([ ["status", t("settingsColumnStatus")], ["dateApplied", t("settingsColumnDateApplied")], ["daysSince", t("settingsColumnDays")], ["jobUrl", t("settingsColumnJobUrl")] ] as const).map(([key, label]) => (
-          <MenuItem key={key} onClick={() => onColumnsChange({ ...columns, [key]: !columns[key] })}>
-            <Checkbox checked={columns[key]} />
+          <MenuItem key={key} aria-label={label} onClick={() => onColumnsChange({ ...columns, [key]: !columns[key] })}>
+            <Checkbox checked={columns[key]} inputProps={{ "aria-label": label }} />
            {label}
          </MenuItem>
        ))}
@@ -629,16 +643,17 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
      ) : null}

      <Paper
+        data-content-density={density}
        sx={{
          mt: 2,
          overflow: "hidden",
          borderRadius: 4,
          border: "none",
-          boxShadow: "0px 1px 2px 0px rgba(15,23,42,0.04), 0px 8px 24px -12px rgba(15,23,42,0.12)",
+          boxShadow: "var(--customShadows-section, none)",
        }}
      >
        {isMobile ? (
-          <Stack spacing={1.25} sx={{ p: 1.25 }}>
+          <Stack spacing="var(--app-list-gap)" sx={{ p: 1.25 }}>
            <Box sx={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 1, px: 0.5 }}>
              <FormControlLabel control={<Checkbox checked={selectedAllOnPage} indeterminate={selectedIds.length > 0 && !selectedAllOnPage} onChange={(e) => toggleSelectAll(e.target.checked)} />} label={t("jobTableSelectAll")} sx={{ mr: 0 }} />
            </Box>
@@ -652,7 +667,7 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
                  data-job-row-id={job.id}
                  role={mode === "jobs" && !job.isDeleted ? "link" : undefined}
                  tabIndex={mode === "jobs" && !job.isDeleted ? 0 : undefined}
-                  aria-label={mode === "jobs" && !job.isDeleted ? `Open ${job.jobTitle} at ${job.company?.name ?? "company"}` : undefined}
+                  aria-label={mode === "jobs" && !job.isDeleted ? t("jobTableOpenJob", { title: job.jobTitle, company: job.company?.name ?? t("jobTableCompany") }) : undefined}
                  onClick={(event) => {
                    if (mode === "jobs" && !job.isDeleted && !isInteractiveTarget(event.target)) openJob(job.id);
                  }}
@@ -663,20 +678,20 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
                    }
                  }}
                  sx={{
-                    p: 1.5,
+                    p: "var(--app-list-item-padding)",
                    borderRadius: 3.5,
                    cursor: mode === "jobs" && !job.isDeleted ? "pointer" : "default",
-                    backgroundColor: alpha(theme.palette.primary.main, 0.03),
+                    backgroundColor: isSelected ? "action.selected" : alpha(theme.palette.primary.main, 0.03),
                    borderColor: alpha(theme.palette.primary.main, 0.08),
                    boxShadow: `0 10px 24px ${alpha(theme.palette.common.black, theme.palette.mode === "dark" ? 0.18 : 0.06)}`,
                    "&:hover": mode === "jobs" && !job.isDeleted ? { backgroundColor: "action.hover" } : undefined,
                    "&:focus-visible": { outline: "3px solid", outlineColor: "primary.main", outlineOffset: 2 },
                  }}
                >
-                  <Stack spacing={1.25}>
-                    <Box sx={{ display: "flex", alignItems: "flex-start", justifyContent: "space-between", gap: 1 }}>
-                      <Box sx={{ display: "flex", alignItems: "flex-start", gap: 1, minWidth: 0, flex: 1 }}>
-                        <Checkbox checked={isSelected} onChange={(e) => toggleSelected(job.id, e.target.checked)} sx={{ mt: -0.5, ml: -1 }} />
+                  <Stack spacing="var(--app-list-gap)">
+                    <Box sx={{ display: "flex", alignItems: "flex-start", justifyContent: "space-between", gap: 1, flexWrap: "wrap" }}>
+                      <Box sx={{ display: "flex", alignItems: "flex-start", gap: 1, minWidth: 0, flex: "1 1 180px" }}>
+                        <Checkbox inputProps={{ "aria-label": t("jobTableSelectJob", { title: job.jobTitle }) }} checked={isSelected} onChange={(e) => toggleSelected(job.id, e.target.checked)} sx={{ mt: -0.5, ml: -1 }} />
                        <Box sx={{ minWidth: 0 }}>
                          <Typography variant="body2" sx={{ color: "text.secondary", overflowWrap: "anywhere" }}>
                            {job.company?.name ?? t("jobTableCompany")}
@@ -686,7 +701,7 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
                          </Typography>
                        </Box>
                      </Box>
-                      {columns.status ? <Chip label={statusLabel(t, job.status)} size="small" color={toneName as any} sx={{ fontWeight: 800 }} /> : null}
+                      {columns.status ? <Chip label={statusLabel(t, job.status)} size="small" color={toneName as any} sx={{ fontWeight: 800, maxWidth: "100%", height: "auto", minHeight: 24, "& .MuiChip-label": { whiteSpace: "normal", overflowWrap: "anywhere", py: 0.5 } }} /> : null}
                    </Box>

                    <Box sx={{ display: "flex", gap: 0.75, flexWrap: "wrap" }}>
@@ -767,8 +782,8 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
            ) : null}
          </Stack>
        ) : (
-          <Box sx={{ overflowX: "auto" }}>
-            <Table size="small" sx={{ minWidth: 980 }}>
+          <Box role="region" aria-label={t("jobTableScrollRegion")} tabIndex={0} sx={{ overflowX: "auto", "&:focus-visible": { outlineOffset: -3 } }}>
+            <Table aria-label={t(mode === "trash" ? "trash" : "jobApplications")} size="small" sx={{ minWidth: 980 }}>
              <TableHead>
                <TableRow>
                  <TableCell padding="checkbox"><Checkbox inputProps={{ "aria-label": t("jobTableSelectAll") }} checked={selectedAllOnPage} indeterminate={selectedIds.length > 0 && !selectedAllOnPage} onChange={(e) => toggleSelectAll(e.target.checked)} /></TableCell>
@@ -792,8 +807,9 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
                        key={job.id}
                        data-job-row-id={job.id}
                        hover={mode === "jobs" && !job.isDeleted}
+                        selected={isSelected}
                        tabIndex={mode === "jobs" && !job.isDeleted ? 0 : undefined}
-                        aria-label={mode === "jobs" && !job.isDeleted ? `Open ${job.jobTitle} at ${job.company?.name ?? "company"}` : undefined}
+                        aria-label={mode === "jobs" && !job.isDeleted ? t("jobTableOpenJob", { title: job.jobTitle, company: job.company?.name ?? t("jobTableCompany") }) : undefined}
                        onClick={(event) => {
                          if (mode === "jobs" && !job.isDeleted && !isInteractiveTarget(event.target)) openJob(job.id);
                        }}
@@ -811,7 +827,7 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
                      >
                        <TableCell padding="checkbox"><Checkbox inputProps={{ "aria-label": t("jobTableSelectJob", { title: job.jobTitle }) }} checked={isSelected} onChange={(e) => toggleSelected(job.id, e.target.checked)} /></TableCell>
                        <TableCell sx={{ minWidth: 140, fontWeight: 700 }}>{job.company?.name ?? ""}</TableCell>
-                        <TableCell>
+                        <TableCell sx={{ minWidth: 260 }}>
                          <Box sx={{ display: "flex", alignItems: "center", gap: 1, flexWrap: "wrap" }}>
                            <Typography component="span" sx={{ fontWeight: 800, overflowWrap: "anywhere" }}>{job.jobTitle}</Typography>
                            {actionSignals.map((signal) => (
@@ -825,7 +841,7 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
                                sx={{ fontWeight: 800, cursor: "pointer" }}
                                clickable
                                onClick={signal.onClick}
-                                aria-label={`${job.jobTitle} — ${signal.label} signal`}
+                                aria-label={t("jobTableWorkflowSignal", { title: job.jobTitle, signal: signal.label })}
                              />
                            ))}
                          </Box>
@@ -853,7 +869,7 @@ export default function JobTable({ refreshToken, pageSize, onPageSizeChange, col
            </Table>
          </Box>
        )}
-        <TablePagination component="div" count={total} page={page} onPageChange={(_, next) => { setPage(next); updateListRoute({ page: next > 0 ? String(next + 1) : null }); }} rowsPerPage={pageSize} onRowsPerPageChange={(e) => { onPageSizeChange(Number(e.target.value) as 15 | 20 | 25); setPage(0); updateListRoute({ page: null }); }} rowsPerPageOptions={[15, 20, 25]} />
+        <TablePagination component="div" labelRowsPerPage={t("settingsRowsPerPage")} labelDisplayedRows={({ from, to, count }) => t("tableDisplayedRows", { from, to, count })} getItemAriaLabel={(type) => t(type === "next" ? "tableNextPage" : type === "previous" ? "tablePreviousPage" : type === "first" ? "tableFirstPage" : "tableLastPage")} count={total} page={page} onPageChange={(_, next) => { setPage(next); updateListRoute({ page: next > 0 ? String(next + 1) : null }); }} rowsPerPage={pageSize} onRowsPerPageChange={(e) => { onPageSizeChange(Number(e.target.value) as 15 | 20 | 25); setPage(0); updateListRoute({ page: null }); }} rowsPerPageOptions={[15, 20, 25]} />
      </Paper>

      <EditJobDialog open={editJobId !== null} jobId={editJobId} onClose={() => setEditJobId(null)} onSaved={() => setReloadToken((token) => token + 1)} />
@@ -1003,6 +1003,17 @@ export const translations = {
    securityCheck: "Security check",
    dashboardTotalCount: "{count} total",
    jobTableSelectJob: "Select {title}",
+    listDensity: "List density",
+    densityComfortable: "Comfortable",
+    densityCompact: "Compact",
+    jobTableScrollRegion: "Job table — scroll for more columns",
+    jobTableOpenJob: "Open {title} at {company}",
+    jobTableWorkflowSignal: "{title} — {signal} signal",
+    tableDisplayedRows: "{from}–{to} of {count}",
+    tableNextPage: "Go to next page",
+    tablePreviousPage: "Go to previous page",
+    tableFirstPage: "Go to first page",
+    tableLastPage: "Go to last page",
    characterCount: "{count} characters",
    back: "Back",
    continue: "Continue",
@@ -3443,6 +3454,17 @@ export const translations = {
    securityCheck: "Sikkerhetskontroll",
    dashboardTotalCount: "{count} totalt",
    jobTableSelectJob: "Velg {title}",
+    listDensity: "Listetetthet",
+    densityComfortable: "Komfortabel",
+    densityCompact: "Kompakt",
+    jobTableScrollRegion: "Jobbtabell — rull for å se flere kolonner",
+    jobTableOpenJob: "Åpne {title} hos {company}",
+    jobTableWorkflowSignal: "{title} — {signal}",
+    tableDisplayedRows: "{from}–{to} av {count}",
+    tableNextPage: "Gå til neste side",
+    tablePreviousPage: "Gå til forrige side",
+    tableFirstPage: "Gå til første side",
+    tableLastPage: "Gå til siste side",
    characterCount: "{count} tegn",
    back: "Tilbake",
    continue: "Fortsett",
@@ -0,0 +1,127 @@
+import React, { useState } from "react";
+import "@testing-library/jest-dom";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import { MemoryRouter, useLocation } from "react-router-dom";
+import { api } from "./api";
+import JobTable, { type JobTableColumns } from "./components/JobTable";
+import { ConfirmProvider } from "./confirm";
+import { PromptProvider } from "./prompt";
+import { ToastProvider } from "./toast";
+import { I18nProvider } from "./i18n/I18nProvider";
+import { translations } from "./i18n/translations";
+
+jest.mock("./components/EditJobDialog", () => ({ open, onClose }: { open: boolean; onClose: () => void }) => open ? <div role="dialog" aria-label="Edit job"><button onClick={onClose}>Close editor</button></div> : null);
+
+const mockedApi = api as jest.Mocked<typeof api>;
+const job = { id: 42, companyId: 1, company: { id: 1, name: "Østlandet" }, jobTitle: "Platform engineer", status: "Custom review", dateApplied: "2026-08-01", daysSince: 2, location: "Tromsø", jobUrl: "https://example.test/listing", isDeleted: false };
+const t = translations.en;
+
+function Consumer({ mode }: { mode: "jobs" | "trash" }) {
+  const location = useLocation();
+  const [pageSize, setPageSize] = useState<15 | 20 | 25>(15);
+  const [columns, setColumns] = useState<JobTableColumns>({ status: true, dateApplied: true, daysSince: true, jobUrl: true });
+  return <><output aria-label="Current route">{location.pathname}{location.search}</output><JobTable mode={mode} refreshToken={0} pageSize={pageSize} onPageSizeChange={setPageSize} columns={columns} onColumnsChange={setColumns} /></>;
+}
+function show(mode: "jobs" | "trash" = "jobs", query = "") {
+  return render(<MemoryRouter initialEntries={[`/${mode}${query}`]}><I18nProvider><ToastProvider><ConfirmProvider><PromptProvider><Consumer mode={mode} /></PromptProvider></ConfirmProvider></ToastProvider></I18nProvider></MemoryRouter>);
+}
+const calls = () => mockedApi.get.mock.calls.filter(([url]) => url === "/jobapplications");
+const lastParams = () => calls().at(-1)?.[1]?.params as Record<string, unknown>;
+beforeEach(() => {
+  localStorage.clear();
+  jest.clearAllMocks();
+  mockedApi.get.mockImplementation((url: string) => Promise.resolve({ data: url === "/companies" ? [job.company] : url === "/jobapplications" ? { items: [job], total: 31, page: 1, pageSize: 15 } : [] } as any));
+});
+
+test("row status/edit/delete controls retain selection and do not open the workspace", async () => {
+  show();
+  const row = await screen.findByRole("row", { name: /open platform engineer/i });
+  fireEvent.click(within(row).getByRole("checkbox"));
+  fireEvent.click(within(row).getByRole("button", { name: `${t.jobTableEdit}: ${job.jobTitle}` }));
+  expect(screen.getByRole("dialog", { name: "Edit job" })).toBeVisible();
+  fireEvent.click(screen.getByText("Close editor"));
+  expect(within(row).getByRole("checkbox")).toBeChecked();
+  fireEvent.click(within(row).getByRole("button", { name: `${t.jobTableSoftDelete}: ${job.jobTitle}` }));
+  fireEvent.click(within(await screen.findByRole("dialog")).getByRole("button", { name: /cancel/i }));
+  expect(mockedApi.delete).not.toHaveBeenCalled();
+  fireEvent.click(await within(row).findByRole("button", { name: `${t.jobTableQuickStatus}: ${job.jobTitle}` }));
+  fireEvent.click(await screen.findByRole("menuitem", { name: /Interview/ }));
+  await waitFor(() => expect(mockedApi.patch).toHaveBeenCalledWith("/jobapplications/42/status", { status: "Interview" }));
+  expect(screen.getByLabelText("Current route")).toHaveTextContent(/^\/jobs$/);
+});
+
+test("table sort, page-size and optional columns keep their existing independent contracts", async () => {
+  show("jobs", "?q=platform&location=Troms%C3%B8");
+  await screen.findByRole("row", { name: /open platform engineer/i });
+  fireEvent.click(screen.getByRole("button", { name: t.jobTableCompany }));
+  await waitFor(() => expect(lastParams()).toMatchObject({ q: "platform", location: "Tromsø", sortBy: "company", sortDir: "asc" }));
+  fireEvent.click(screen.getByRole("button", { name: "Go to next page" }));
+  await waitFor(() => expect(lastParams().page).toBe(2));
+  fireEvent.mouseDown(screen.getByRole("combobox", { name: /rows per page/i }));
+  fireEvent.click(await screen.findByRole("option", { name: "20" }));
+  await waitFor(() => expect(lastParams()).toMatchObject({ page: 1, pageSize: 20 }));
+  fireEvent.click(screen.getByRole("button", { name: t.jobTableColumns }));
+  fireEvent.click(await screen.findByRole("menuitem", { name: t.settingsColumnJobUrl }));
+  expect(screen.queryByRole("link", { name: t.jobTableLink })).not.toBeInTheDocument();
+});
+
+test("Trash select-all and bulk restore use the original IDs without workspace navigation", async () => {
+  show("trash");
+  await screen.findByText(job.jobTitle);
+  fireEvent.click(screen.getByRole("checkbox", { name: t.jobTableSelectAll }));
+  fireEvent.click(screen.getByRole("button", { name: t.jobTableRestoreSelected }));
+  await waitFor(() => expect(mockedApi.post).toHaveBeenCalledWith("/jobapplications/42/restore"));
+  expect(screen.getByLabelText("Current route")).toHaveTextContent(/^\/trash$/);
+});
+
+async function compact() {
+  fireEvent.mouseDown(screen.getByRole("combobox", { name: t.listDensity }));
+  fireEvent.click(await screen.findByRole("option", { name: t.densityCompact }));
+}
+
+test("density preserves selected rows, query, page, custom status, columns and listing link without refetch", async () => {
+  show("jobs", "?q=platform&page=2&sortBy=company&sortDir=asc");
+  const row = await screen.findByRole("row", { name: /open platform engineer/i });
+  const columns = within(row).getAllByRole("cell").length;
+  fireEvent.click(within(row).getByRole("checkbox"));
+  const before = calls().length;
+  expect(screen.getByRole("combobox", { name: t.listDensity })).toHaveTextContent(t.densityComfortable);
+  await compact();
+  expect(within(row).getByRole("checkbox")).toBeChecked();
+  expect(within(row).getAllByRole("cell")).toHaveLength(columns);
+  expect(within(row).getByText("Custom review")).toBeVisible();
+  expect(within(row).getByRole("link", { name: t.jobTableLink })).toHaveAttribute("href", job.jobUrl);
+  expect(screen.getByText("16–30 of 31")).toBeVisible();
+  expect(screen.getByLabelText("Current route")).toHaveTextContent("/jobs?q=platform&page=2&sortBy=company&sortDir=asc");
+  expect(calls()).toHaveLength(before);
+  fireEvent.click(screen.getByRole("button", { name: "Offer" }));
+  await waitFor(() => expect(mockedApi.patch).toHaveBeenCalledWith("/jobapplications/42/status", { status: "Offer" }));
+});
+
+test("density is local and resets on unmount without writing settings or a saved view", async () => {
+  const view = show();
+  await screen.findByText(job.jobTitle);
+  const stored = { ...localStorage };
+  await compact();
+  expect({ ...localStorage }).toEqual(stored);
+  expect(mockedApi.put).not.toHaveBeenCalled();
+  view.unmount();
+  show();
+  await screen.findByText(job.jobTitle);
+  expect(screen.getByRole("combobox", { name: t.listDensity })).toHaveTextContent(t.densityComfortable);
+});
+
+test("density survives an empty result and a failed refresh with the existing retry action", async () => {
+  show();
+  await screen.findByText(job.jobTitle);
+  await compact();
+  mockedApi.get.mockImplementation((url: string) => url === "/jobapplications" ? Promise.reject({ message: "Synthetic unavailable", response: { status: 503 } }) : Promise.resolve({ data: [] } as any));
+  fireEvent.click(screen.getByRole("button", { name: t.tableNextPage }));
+  expect(await screen.findByRole("alert")).toHaveTextContent("Synthetic unavailable");
+  expect(screen.getByRole("combobox", { name: t.listDensity })).toHaveTextContent(t.densityCompact);
+  mockedApi.get.mockResolvedValue({ data: { items: [], total: 0, page: 1, pageSize: 15 } } as any);
+  fireEvent.click(screen.getByRole("button", { name: /retry/i }));
+  await waitFor(() => expect(screen.queryByRole("alert")).not.toBeInTheDocument());
+  expect(screen.getByRole("combobox", { name: t.listDensity })).toHaveTextContent(t.densityCompact);
+  expect(screen.queryByText(job.jobTitle)).not.toBeInTheDocument();
+});
@@ -2,6 +2,8 @@ import { alpha, createTheme, darken, lighten } from "@mui/material/styles";

 type PaletteLike = Record<string, any>;

+export type ContentDensity = "comfortable" | "compact";
+
 // Existing provisional brand hue. Dark mode uses a lighter tone for readable text;
 // this does not settle the Phase 3 brand/identity decision.
 const ACCENT = "#5B5BD6";
@@ -300,6 +302,31 @@ export const getTheme = (_mode: "light" | "dark") => {
        "@media (min-width: 1440px)": {
          ":root": { "--app-page-gutter": "32px" },
        },
+        // Opt-in MUI table/list spacing. Unmigrated consumers keep their defaults.
+        "[data-content-density]": {
+          "--app-table-cell-py": "12px",
+          "--app-list-item-padding": "16px",
+          "--app-list-gap": "12px",
+          "--app-data-target": "32px",
+        },
+        '[data-content-density="compact"]': {
+          "--app-table-cell-py": "8px",
+          "--app-list-item-padding": "12px",
+          "--app-list-gap": "8px",
+        },
+        // Density never shrinks hit regions. Coarse pointers and phone cards get
+        // 44px targets in either mode; desktop controls keep at least 32px.
+        "@media (pointer: coarse), (max-width: 767.95px)": {
+          "[data-content-density]": { "--app-data-target": "44px" },
+        },
+        "[data-content-density] .MuiIconButton-root, [data-content-density] .MuiCheckbox-root": {
+          minWidth: "var(--app-data-target)", minHeight: "var(--app-data-target)",
+        },
+        "[data-content-density] .MuiTableSortLabel-root, [data-content-density] .MuiChip-clickable, [data-content-density] .MuiButton-root, [data-content-density] a": {
+          minHeight: "var(--app-data-target)",
+        },
+        "[data-content-density] a": { display: "inline-flex", alignItems: "center" },
+        "[data-content-density] .MuiTableCell-paddingCheckbox": { width: "auto" },
        body: {
          WebkitFontSmoothing: "antialiased",
          MozOsxFontSmoothing: "grayscale",
@@ -525,8 +552,8 @@ export const getTheme = (_mode: "light" | "dark") => {
          background: theme.vars.palette.grey[100],
        }),
        root: {
-          paddingTop: 10,
-          paddingBottom: 10,
+          paddingTop: "var(--app-table-cell-py, 10px)",
+          paddingBottom: "var(--app-table-cell-py, 10px)",
        },
      },
    },