@arcforgelabs/flow 2026.10.19 → 2026.10.20-beta.1

package/README.md

@@ -16,7 +16,8 @@ from an earlier private codebase one module at a time (`CONTRIBUTING.md`,
 "Porting from the earlier codebase"). Today it holds the repository's rules,
 CI, the release track (npm, container image and GitHub Release, on a beta and
 a stable channel), the integration port, a health check, Clerk sign-in with
-roles kept in Flow, and the first part of the core: the PostgreSQL data model
+roles kept in Flow, a People page for owners, the design systems Arc Forge
+Labs' Field uses, and the first part of the core: the PostgreSQL data model
 for organisations, contacts, the price list and invoices. It is not ready to
 run a lab.
 
@@ -29,6 +30,7 @@ run a lab.
 | `CONTRIBUTING.md` | How to file issues and pull requests, porting rules, merging |
 | `SECURITY.md` | How to report a security problem, the trust model, and the rules held hard |
 | `LICENSE` | MIT licence |
+| `docs/DESIGN.md` | The design systems (theme families), how pages and Clerk's components take them, and the screens |
 | `docs/DATA_MODEL.md` | The PostgreSQL records, the rules the database holds, and how to change the schema |
 | `docs/RELEASING.md` | Versions and channels, the release workflows, how to cut and roll back a release, and the one-time setup |
 | `docs/SELF_HOSTING.md` | Running a Flow release with Docker, Node or Replit, the update notice, and Clerk sign-in |

package/npm-shrinkwrap.json

@@ -1,15 +1,25 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.19",
+  "version": "2026.10.20-beta.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.19",
+      "version": "2026.10.20-beta.1",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.23.2",
+        "@fontsource-variable/atkinson-hyperlegible-next": "5.3.0",
+        "@fontsource-variable/dm-sans": "5.3.0",
+        "@fontsource-variable/geist": "5.3.0",
+        "@fontsource-variable/ibm-plex-sans": "5.3.0",
+        "@fontsource-variable/instrument-sans": "5.3.0",
+        "@fontsource-variable/jetbrains-mono": "5.3.0",
+        "@fontsource-variable/lora": "5.3.0",
+        "@fontsource-variable/nunito-sans": "5.3.0",
+        "@fontsource-variable/playfair-display": "5.3.0",
+        "@fontsource-variable/space-grotesk": "5.3.0",
         "drizzle-orm": "0.45.3",
         "express": "5.3.0",
         "express-rate-limit": "8.7.0",
@@ -951,6 +961,96 @@
         "node": ">=18"
       }
     },
+    "node_modules/@fontsource-variable/atkinson-hyperlegible-next": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/atkinson-hyperlegible-next/-/atkinson-hyperlegible-next-5.3.0.tgz",
+      "integrity": "sha512-UnLzNUy1RWoLDfydAatP4NaRm99X/WbQEph7q/PymJnCFIOOwKOx3pBmp5ys8trO0dM+CKGuJgeZP9fAR4mQpA==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource-variable/dm-sans": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/dm-sans/-/dm-sans-5.3.0.tgz",
+      "integrity": "sha512-BpUG5bqePiDFMBM4ZtLSlPdAIOM990uB1dlXzIf4aw21yQR7BmykedLXXXMqGWsR18aMLOsbWccwJNh3ztTQaA==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource-variable/geist": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/geist/-/geist-5.3.0.tgz",
+      "integrity": "sha512-j0m+vLQuG5XAYoHtGCVu0spvlGreR3EzpECUVzkFmI1mTVnAO38l/NEPDCFgZ177JxzYJCLSmTQibIiYPilGrA==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource-variable/ibm-plex-sans": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/ibm-plex-sans/-/ibm-plex-sans-5.3.0.tgz",
+      "integrity": "sha512-agG8tXFEo0hD9+J7npa4vbbWult52eMLVaQ6WQRlhs/iCAojrMAoejru85W9HTVXHfyUj96KM7gp/KGAS87XaQ==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource-variable/instrument-sans": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/instrument-sans/-/instrument-sans-5.3.0.tgz",
+      "integrity": "sha512-u4gKbDBTNFGkg997tfQn3eHOhHuquWUFTRT/rwzuKtrxX5P2ekfs2x+LgBPP4P32+cC+vUwF1Cr+IdRoPQbrGw==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource-variable/jetbrains-mono": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/jetbrains-mono/-/jetbrains-mono-5.3.0.tgz",
+      "integrity": "sha512-F32xpS2NsGYoQi2ADSkKTgpJj7ozajsGgDJ8woTnqjmIB+dxDIqImjl4pXZVEExu8UFZ2ndhmX18EBS/hdz3Lw==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource-variable/lora": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/lora/-/lora-5.3.0.tgz",
+      "integrity": "sha512-2ph8KiZ8Bn141hWuC3ErtpJ+Ui8p2MJQn8TJNRSRmLmnCIOCtHfiBM9R7WLRPeUG/q6hXyHOxWQ8DvRSX+ixvQ==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource-variable/nunito-sans": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/nunito-sans/-/nunito-sans-5.3.0.tgz",
+      "integrity": "sha512-Vk1PSfckNDwgw2yGcsvJP3o/0zEW8Rp6KzbD8Ql/6iRHQshnhhAjt+cSIfAUyp5vQuSlleGHFW2LfYaaex0diw==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource-variable/playfair-display": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/playfair-display/-/playfair-display-5.3.0.tgz",
+      "integrity": "sha512-IHdzTvE8eGIXHteZql7KXoqdc3Gfm+Zs1u4XlSC3MeplkwviT3sx/P6gI0tLwg/xIYLF4ZJYveZ5V+bl9cnDwA==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource-variable/space-grotesk": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/space-grotesk/-/space-grotesk-5.3.0.tgz",
+      "integrity": "sha512-2IxmvfB08i9vnGB3Ym/AXvhRE+8XOjWMXIyDum03c+tPwH0FUoMNQfGpU8NXPxjbws0Vvss3AH0Zqt4oJBBAdw==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
     "node_modules/@stablelib/base64": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/@stablelib/base64/-/base64-1.0.1.tgz",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.19",
+  "version": "2026.10.20-beta.1",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -35,6 +35,16 @@
   },
   "dependencies": {
     "@clerk/backend": "3.23.2",
+    "@fontsource-variable/atkinson-hyperlegible-next": "5.3.0",
+    "@fontsource-variable/dm-sans": "5.3.0",
+    "@fontsource-variable/geist": "5.3.0",
+    "@fontsource-variable/ibm-plex-sans": "5.3.0",
+    "@fontsource-variable/instrument-sans": "5.3.0",
+    "@fontsource-variable/jetbrains-mono": "5.3.0",
+    "@fontsource-variable/lora": "5.3.0",
+    "@fontsource-variable/nunito-sans": "5.3.0",
+    "@fontsource-variable/playfair-display": "5.3.0",
+    "@fontsource-variable/space-grotesk": "5.3.0",
     "drizzle-orm": "0.45.3",
     "express": "5.3.0",
     "express-rate-limit": "8.7.0",

package/server/app.js

@@ -4,6 +4,9 @@ import { createSignInRouter } from './auth/routes.js';
 import { deployedBuildStatus } from './deployed-build.js';
 import { integrationsHealth } from './integrations/health.js';
 import { rateLimit } from './rate-limit.js';
+import { DEFAULT_FAMILY } from './theme/themes.js';
+import { messagePage } from './ui/page.js';
+import { createUiAssetsRouter } from './ui/routes.js';
 
 // The Flow HTTP app. Routes are added per module (invoices, bills, payments,
 // dashboard).
@@ -19,7 +22,8 @@ import { rateLimit } from './rate-limit.js';
 // (server/deployed-build.js); `updates` is a server/update-check.js checker.
 // `integrations` is the started registry (server/integrations/index.js); each
 // adapter's own routes are mounted under /api/<id>, and GET /health reports
-// each one (server/integrations/health.js).
+// each one (server/integrations/health.js). `defaultFamily` is the design
+// system every page starts on (FLOW_THEME, server/theme/themes.js).
 export function createApp({
   build = deployedBuildStatus(),
   database = null,
@@ -30,6 +34,7 @@ export function createApp({
   rateLimitPerMinute = 120,
   signInRateLimitPerMinute = 30,
   clerkProxyRateLimitPerMinute = 300,
+  defaultFamily = DEFAULT_FAMILY,
   log = console,
 } = {}) {
   const app = express();
@@ -59,6 +64,9 @@ export function createApp({
     app.use(auth.clerkProxy.path, rateLimit({ limit: clerkProxyRateLimitPerMinute, windowMs: 60_000 }), auth.clerkProxy.handler);
   }
 
+  // The design systems, Flow's components and the faces every page loads.
+  app.use(createUiAssetsRouter());
+
   app.use('/api', rateLimit({ limit: rateLimitPerMinute, windowMs: 60_000 }));
 
   // Machine access first, with its own authentication (issue #9). A Clerk
@@ -82,7 +90,10 @@ export function createApp({
     }
   }
 
-  for (const { path, handler } of integrations?.routes({ db: database?.db ?? null, personAuth: auth?.personAuth ?? null, log }) ?? []) {
+  // An adapter's own pages (such as the end of connecting Xero) use
+  // `messagePage` so they look like the rest of Flow.
+  const page = (options) => messagePage({ ...options, defaultFamily });
+  for (const { path, handler } of integrations?.routes({ db: database?.db ?? null, personAuth: auth?.personAuth ?? null, log, messagePage: page }) ?? []) {
     app.use(path, handler);
   }
 
@@ -91,6 +102,7 @@ export function createApp({
     db: database?.db ?? null,
     clerk: auth?.clerk ?? null,
     personAuth: auth?.personAuth ?? null,
+    defaultFamily,
     rateLimitPerMinute: signInRateLimitPerMinute,
     log,
   }));

package/server/auth/routes.js

@@ -1,4 +1,3 @@
-import { fileURLToPath } from 'node:url';
 import express from 'express';
 import { FlowError } from '../core/errors.js';
 import { rateLimit } from '../rate-limit.js';
@@ -13,8 +12,7 @@ import {
   updatePerson,
 } from './people.js';
 import { isPlainEmail } from './settings.js';
-
-const signInPage = fileURLToPath(new URL('./sign-in.html', import.meta.url));
+import { APP_PATHS, appPage } from '../ui/app-page.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const ERROR_STATUS = { invalid: 400, forbidden: 403, not_found: 404, conflict: 409 };
 
@@ -49,8 +47,10 @@ function sendError(res, error, log) {
 // off, person routes answer 503 and nothing else is mounted. The sign-in page
 // and its config have their own limit per client (`rateLimitPerMinute`);
 // /api/me and /api/people sit under the app's /api limit as well.
-export function createSignInRouter({ settings, db, clerk, personAuth, rateLimitPerMinute = 30, log = console }) {
+// `defaultFamily` is the installation's design system (FLOW_THEME).
+export function createSignInRouter({ settings, db, clerk, personAuth, defaultFamily, rateLimitPerMinute = 30, log = console }) {
   const router = express.Router();
+  const page = appPage({ defaultFamily });
   const signInOn = settings.mode === 'clerk';
   const signInLimit = rateLimit({ limit: rateLimitPerMinute, windowMs: 60_000 });
 
@@ -72,10 +72,11 @@ export function createSignInRouter({ settings, db, clerk, personAuth, rateLimitP
   });
 
   router.get('/', signInLimit, (_req, res) => res.redirect(302, '/sign-in'));
-  router.get('/sign-in', signInLimit, (_req, res) => {
+  // Signed out, every one of these shows sign-in.
+  router.get(APP_PATHS, signInLimit, (_req, res) => {
     res.set('Cache-Control', 'no-store');
     res.set('X-Frame-Options', 'DENY');
-    res.sendFile(signInPage);
+    res.type('html').send(page);
   });
 
   if (!signInOn) {

package/server/index.js

@@ -6,6 +6,7 @@ import { createPersonAuth } from './auth/session.js';
 import { resolveSignInSettings } from './auth/settings.js';
 import { migrateDatabase, openDatabase } from './db/index.js';
 import { createIntegrations } from './integrations/index.js';
+import { resolveDefaultFamily } from './theme/themes.js';
 import { createUpdateChecker, UPDATE_CHECK_INTERVAL_MS } from './update-check.js';
 
 const port = Number(process.env.FLOW_PORT || process.env.PORT || 19300);
@@ -18,6 +19,13 @@ try {
   console.error(`[auth] ${error.message}`);
   process.exit(1);
 }
+let defaultFamily;
+try {
+  defaultFamily = resolveDefaultFamily();
+} catch (error) {
+  console.error(`[ui] ${error.message}`);
+  process.exit(1);
+}
 let integrations;
 try {
   integrations = createIntegrations();
@@ -76,8 +84,8 @@ const trustProxy = process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT ? 1 : fa
 
 const updates = createUpdateChecker();
 
-createApp({ database, auth, trustProxy, updates, integrations }).listen(port, () => {
-  console.log(`[flow] listening on ${port}`);
+createApp({ database, auth, trustProxy, updates, integrations, defaultFamily }).listen(port, () => {
+  console.log(`[flow] listening on ${port}; design system ${defaultFamily} (FLOW_THEME)`);
 });
 
 // The update notice: a release build logs when a newer release is out on its

package/server/integrations/port.js

@@ -102,7 +102,7 @@ export function defineAdapter(adapter) {
     // stop() ends that work (tests, shutdown).
     start: start ?? null,
     stop: stop ?? null,
-    // Optional HTTP routes: routes({ db, personAuth, log }) returns a router
+    // Optional HTTP routes: routes({ db, personAuth, log, messagePage }) returns a router
     // mounted at /api/<id> (registry.routes).
     routes: routes ?? null,
   });
@@ -195,7 +195,7 @@ export function createRegistry({ log = console } = {}) {
         .filter((a) => ready(a) && typeof a.capabilities[capability] === 'function');
     },
     // The adapters' own HTTP routes, each under /api/<id>. `context` is
-    // { db, personAuth, log }. An enabled, ready adapter's router is built
+    // { db, personAuth, log, messagePage }. An enabled, ready adapter's router is built
     // once, here; a request to an adapter that is off gets its turned-off
     // answer (503), so a turned-off adapter never reads its settings or
     // tables.

package/server/integrations/xero/index.js

@@ -49,7 +49,7 @@ export function createXeroAdapter({ runtime: given = null } = {}) {
       // cursor is the next `since`.
       pullPayments: ({ organisationId, since }) => readPayments(database, current(), organisationId, { since: new Date(since) }),
     },
-    routes: ({ db, personAuth, log }) => createXeroRouter({ db, personAuth, runtime: current(), log }),
+    routes: ({ db, personAuth, log, messagePage }) => createXeroRouter({ db, personAuth, runtime: current(), log, messagePage }),
   };
 }
 

package/server/integrations/xero/routes.js

@@ -9,6 +9,8 @@ import { recordXeroEvidence, recordXeroPayments } from './ledger.js';
 import { decryptToken, deleteConnection, describeConnection, readConnection, saveConnection } from './connections.js';
 import { authorizeUrl, exchangeCode, fetchConnections, revokeToken, selectConnection } from './oauth.js';
 import { writesAllowed } from './settings.js';
+import { DEFAULT_FAMILY } from '../../theme/themes.js';
+import { messagePage as themedMessagePage } from '../../ui/page.js';
 
 // The Xero adapter's routes, mounted at /api/xero (server/integrations/port.js).
 //
@@ -33,14 +35,6 @@ import { writesAllowed } from './settings.js';
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-function escapeHtml(value) {
-  return String(value ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
-}
-
-function page(title, text) {
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escapeHtml(title)}</title></head>`
-    + `<body style="font-family: system-ui, sans-serif; max-width: 36rem; margin: 3rem auto; padding: 0 1rem; line-height: 1.5"><h1>${escapeHtml(title)}</h1><p>${escapeHtml(text)}</p></body></html>`;
-}
 
 export function sendError(res, error, log) {
   const status = error instanceof FlowError ? (error.status ?? 400) : 500;
@@ -75,7 +69,10 @@ export const handle = (log, fn) => async (req, res) => {
   }
 };
 
-export function createXeroRouter({ db, personAuth, runtime, log = console }) {
+// `messagePage` draws the callback's answer in the installation's design
+// system (server/ui/page.js); the server's app passes it.
+export function createXeroRouter({ db, personAuth, runtime, log = console, messagePage = (options) => themedMessagePage({ ...options, defaultFamily: DEFAULT_FAMILY }) }) {
+  const page = (title, text, tone) => messagePage({ title, text, tone });
   const { settings } = runtime;
   const router = express.Router();
   router.use(express.json({ limit: '256kb' }));
@@ -116,10 +113,10 @@ export function createXeroRouter({ db, personAuth, runtime, log = console }) {
     res.set('Cache-Control', 'no-store');
     const entry = runtime.states.consume(req.query.state);
     if (!entry) {
-      return res.status(400).type('html').send(page('Xero was not connected', 'This approval link has expired or was already used. Start again from Flow.'));
+      return res.status(400).type('html').send(page('Xero was not connected', 'This approval link has expired or was already used. Start again from Flow.', 'danger'));
     }
     if (req.query.error) {
-      return res.status(400).type('html').send(page('Xero was not connected', 'The approval was cancelled in Xero. Start again from Flow if you meant to connect.'));
+      return res.status(400).type('html').send(page('Xero was not connected', 'The approval was cancelled in Xero. Start again from Flow if you meant to connect.', 'danger'));
     }
     try {
       const tokens = await exchangeCode(settings, runtime.transport, typeof req.query.code === 'string' ? req.query.code : '');
@@ -153,11 +150,11 @@ export function createXeroRouter({ db, personAuth, runtime, log = console }) {
       });
       runtime.remember(entry.organisationId, tokens);
       log.info?.(`[xero] organisation ${entry.organisationId} connected to Xero tenant ${connection.tenantId} (${settings.mode}) by person ${entry.personId}`);
-      return res.type('html').send(page('Xero is connected', `Flow is connected to ${connection.tenantName || 'your Xero organisation'} (${settings.mode}). You can close this tab.`));
+      return res.type('html').send(page('Xero is connected', `Flow is connected to ${connection.tenantName || 'your Xero organisation'} (${settings.mode}). You can close this tab.`, 'success'));
     } catch (error) {
       log.error?.(`[xero] connect failed: ${error.code ?? 'error'}: ${error.message}`);
       const message = error instanceof FlowError ? error.message : 'Something went wrong talking to Xero. Try again.';
-      return res.status(error.status && error.status < 500 ? error.status : 502).type('html').send(page('Xero was not connected', message));
+      return res.status(error.status && error.status < 500 ? error.status : 502).type('html').send(page('Xero was not connected', message, 'danger'));
     }
   });
 

package/server/theme/color-contrast.js

@@ -0,0 +1,54 @@
+// WCAG 2.1 contrast helpers for theme tokens (server/theme/themes.js and
+// scripts/port-openclaw-themes.mjs). Colours are #rrggbb.
+
+export const HEX = /^#[0-9a-f]{6}$/i;
+
+function rgb(hex) {
+  return [1, 3, 5].map((i) => Number.parseInt(hex.slice(i, i + 2), 16));
+}
+
+function luminance(hex) {
+  const [r, g, b] = rgb(hex).map((c) => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrast(a, b) {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Black or white, whichever reads better on the fill. */
+export function inkOn(fill) {
+  return luminance(fill) > 0.179 ? '#000000' : '#ffffff';
+}
+
+/** The colour, darkened or lightened just enough to read as text on `bg`. */
+export function readableOn(color, bg, target = 4.5) {
+  if (!HEX.test(color) || !HEX.test(bg)) return color;
+  const toward = luminance(bg) > 0.179 ? [0, 0, 0] : [255, 255, 255];
+  const from = rgb(color);
+  for (let pct = 0; pct <= 100; pct += 2) {
+    const mixed = `#${from.map((c, i) => Math.round(c + (toward[i] - c) * pct / 100).toString(16).padStart(2, '0')).join('')}`;
+    if (contrast(mixed, bg) >= target) return mixed;
+  }
+  return toward[0] ? '#ffffff' : '#000000';
+}
+
+/**
+ * A boundary colour for controls on `bg` (an input's or an outlined button's
+ * edge): `bg` mixed toward `ink` just enough to stand out at `target`
+ * (WCAG 1.4.11 asks 3:1 for the parts that show where a control is).
+ */
+export function boundaryOn(bg, ink, target = 3) {
+  if (!HEX.test(bg) || !HEX.test(ink)) return ink;
+  const from = rgb(bg);
+  const toward = rgb(ink);
+  for (let pct = 0; pct <= 100; pct += 2) {
+    const mixed = `#${from.map((c, i) => Math.round(c + (toward[i] - c) * pct / 100).toString(16).padStart(2, '0')).join('')}`;
+    if (contrast(mixed, bg) >= target) return mixed;
+  }
+  return ink;
+}

package/server/theme/font-families.js

@@ -0,0 +1,28 @@
+// Each design system's faces, as the fontsource packages Flow serves under
+// /assets/fonts/<package>/ (server/ui/routes.js). A page loads only the chosen
+// family's faces, plus JetBrains Mono for codes. Shared by the server and the
+// browser, so it imports nothing.
+export const MONO_FONT = 'jetbrains-mono';
+
+export const FAMILY_FONTS = {
+  harbour: ['nunito-sans', 'playfair-display'],
+  beacon: ['atkinson-hyperlegible-next'],
+  tide: ['ibm-plex-sans'],
+  claw: ['instrument-sans'],
+  knot: ['geist'],
+  dash: ['dm-sans'],
+  absolutely: ['space-grotesk'],
+  phosphor: [],
+  crt: [],
+  manuscript: ['lora'],
+  rose: ['dm-sans'],
+  miami: ['space-grotesk'],
+};
+
+/** Every package a family can ask for, so the server serves only these. */
+export const FONT_PACKAGES = [...new Set([MONO_FONT, ...Object.values(FAMILY_FONTS).flat()])];
+
+/** The stylesheet URLs a family needs, mono first. */
+export function fontStylesheets(family) {
+  return [MONO_FONT, ...(FAMILY_FONTS[family] ?? [])].map((name) => `/assets/fonts/${name}/index.css`);
+}