@bitforgehq/ui 0.3.1 → 0.3.2

package/ai/reference/bf-size.md

@@ -48,6 +48,7 @@ type BfSize = 'sm' | 'md' | 'lg'
 - [bf-segmented](../components/segmented.md)
 - [BfSegmentedSize](bf-segmented-size.md)
 - [bf-select](../components/select.md)
+- [bf-sidebar-toggle](../components/sidebar-toggle.md)
 - [bf-tab-group](../components/tab-group.md)
 - [bf-table](../components/table.md)
 - [bf-textarea](../components/textarea.md)

package/ai/reference/bf-stat-appearance.md

@@ -0,0 +1,33 @@
+# BfStatAppearance
+
+The three stat surfaces, plain, an outlined card or a sunken tile
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The surface of a `bf-stat`, as its `variant` input takes it: a `BfStatVariant` or tile (a
+sunken, borderless tile for a stats row inside a raised card). A new type, so `Record`s over
+the released `BfStatVariant` keep compiling.
+
+```ts
+import { type BfStatAppearance } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfStatAppearance = BfStatVariant | 'tile'
+```
+
+## Values
+
+- `plain`
+- `card`
+- `tile`
+
+## Uses
+
+- [BfStatVariant](bf-stat-variant.md)
+
+## Used by
+
+- [bf-stat](../components/stat.md)

package/ai/reference/bf-stat-variant.md

@@ -23,4 +23,4 @@ type BfStatVariant = 'plain' | 'card'
 
 ## Used by
 
-- [bf-stat](../components/stat.md)
+- [BfStatAppearance](bf-stat-appearance.md)

package/ai/reference/bf-table-harness.md

@@ -6,7 +6,7 @@ Class from `@bitforgehq/ui/testing` · since 0.3.1
 
 Harness for `bf-table`. It works by column header text and row position, so a test never needs
 the column keys or the row keys (except `getSort()`, which returns the column's `key`, as the
-`sort` model holds it).
+`sort` model holds it). It reads and drives a stacked table (`stack`) the same way.
 
 ```ts
 import { BfTableHarness } from '@bitforgehq/ui/testing';

package/ai/reference/bf-table-stack.md

@@ -0,0 +1,29 @@
+# BfTableStack
+
+When a table stacks its rows into cards: never, when narrow, or under touch
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+When a `bf-table` renders each row as a card of label/value pairs: `never` (the default),
+`narrow` while the table is narrower than 36rem (a container query), or `coarse` under a coarse
+pointer at any width.
+
+```ts
+import { type BfTableStack } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTableStack = 'never' | 'narrow' | 'coarse'
+```
+
+## Values
+
+- `never`
+- `narrow`
+- `coarse`
+
+## Used by
+
+- [bf-table](../components/table.md)

package/ai/reference/bf_sidebar_state_storage.md

@@ -0,0 +1,20 @@
+# BF_SIDEBAR_STATE_STORAGE
+
+Injection token for the store that keeps the collapsed sidebar between visits
+
+Injection token from `@bitforgehq/ui` · since 0.3.2
+
+Where `BfSidebarStateService` keeps whether the sidebar is collapsed (the key
+`bf-sidebar-collapsed`, `'true'` or `'false'`): `localStorage` when it is available, otherwise
+an in-memory map. Provide another store (`sessionStorage`, or an in-memory one in tests) to keep
+it elsewhere.
+
+```ts
+import { BF_SIDEBAR_STATE_STORAGE } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+const BF_SIDEBAR_STATE_STORAGE: InjectionToken<Pick<Storage, "getItem" | "setItem">>
+```

package/ai/reference/provide-bf-labels.md

@@ -7,9 +7,10 @@ Function from `@bitforgehq/ui` · since 0.3.0
 Replaces built-in strings, merged over the parent's (validation merged key by key); a key left
 out or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers
 every string. In a component's `providers` it covers that sub-tree's widgets and form controls
-(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `theme`,
-`themeSystem`, `themeLight`, `themeDark`, `breadcrumb`, `breadcrumbExpand`, `navigation`,
-`navBadge`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,
+(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,
+`tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,
+`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,
+`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,
 `calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,
 `statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,
 `dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,

package/ai/reference/provide-bf-sidebar-state.md

@@ -0,0 +1,20 @@
+# provideBfSidebarState
+
+Remembers the collapsed sidebar between visits, for desktop web apps
+
+Function from `@bitforgehq/ui` · since 0.3.2
+
+Lets `BfSidebarStateService` remember the collapsed sidebar: it stores every change of its
+`collapsed` signal (key `bf-sidebar-collapsed`, `localStorage` in the browser), so the app opens
+with the sidebar as the user left it. Add it to `ApplicationConfig.providers` and bind the
+sidebar's `[(collapsed)]` to `sidebarState.collapsed`.
+
+```ts
+import { provideBfSidebarState } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+function provideBfSidebarState(): EnvironmentProviders
+```

package/bin/bf-ui.js

@@ -3,16 +3,24 @@
  * bf-ui CLI, shipped inside @bitforgehq/ui.
  *
  * Usage: bf-ui sync-ai [--check]
+ *        bf-ui theme <hex> [--dark <hex>]
  *
- * Installs (or checks) the agent guide `ai/UI_GUIDE.md`, bundled next to this script, into the
- * consuming project as `.ai/UI_GUIDE.md`.
+ * `sync-ai` installs (or checks) the agent guide `ai/UI_GUIDE.md`, bundled next to this script,
+ * into the consuming project as `.ai/UI_GUIDE.md`.
+ *
+ * `theme` derives the brand token set (`--color-primary` and the tokens built on it) for light and
+ * dark mode from one brand colour, checks every contrast pair the widgets draw with it, and prints
+ * a `@theme` block and a `.dark` block to paste after the theme import. It exits 1, naming each
+ * failing pair and a shade that passes, when a pair misses its minimum.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 
-const USAGE = 'Usage: bf-ui sync-ai [--check]';
+const USAGE = ['Usage: bf-ui sync-ai [--check]', '       bf-ui theme <hex> [--dark <hex>]'].join(
+  '\n',
+);
 
 const CLAUDE_SNIPPET = `## Shared UI library
 - Before creating any UI primitive, read \`.ai/UI_GUIDE.md\` (from @bitforgehq/ui).
@@ -59,10 +67,432 @@ function syncAi({ check }) {
   console.log(CLAUDE_SNIPPET);
 }
 
+/* ---------- theme: colour maths (OKLCH and WCAG, the same formulas as culori) ---------- */
+
+/** WCAG 1.4.3 (text) and 1.4.11 (non-text: state cues, boundaries, focus rings). */
+const TEXT = 4.5;
+const NON_TEXT = 3;
+const WHITE = '#ffffff';
+/** Dark-mode text on `primary` when the deep tint of the brand misses 4.5:1. */
+const DARK_ON_PRIMARY_FALLBACK = '#09090b';
+/** Lightness search bounds and step (OKLCH `l`). */
+const L_FLOOR = 0.05;
+const L_CEILING = 0.95;
+const L_STEP = 0.01;
+
+/**
+ * The shipped neutrals of `theme.css` the brand tokens are drawn on, per mode. A brand override
+ * leaves them alone; `tools/bf-ui-cli.test.ts` keeps them equal to `theme.css`.
+ */
+const NEUTRALS = {
+  light: {
+    bg: '#f7f5ef',
+    surface: '#ffffff',
+    'surface-muted': '#efece5',
+    'surface-sunken': '#efece3',
+    text: '#1f2a22',
+  },
+  dark: {
+    bg: '#111214',
+    surface: '#1e2024',
+    'surface-muted': '#262930',
+    'surface-sunken': '#18191c',
+    text: '#ececee',
+  },
+};
+
+/**
+ * Every pair of `tools/theme-contrast.test.ts` that involves a brand token (the rest, status,
+ * tooltip and chart colours, does not change with the brand). `primary` on `surface` and `bg` is
+ * the checkbox box, radio ring and toggle track: the shipped theme meets 3:1 there, so a brand
+ * colour has to as well.
+ */
+const PAIRS = [
+  { fg: 'on-primary', bg: 'primary', min: TEXT, use: 'primary button, count badge, check mark' },
+  { fg: 'on-primary', bg: 'primary-hover', min: TEXT, use: 'primary button hover' },
+  { fg: 'on-primary', bg: 'primary-pressed', min: TEXT, use: 'primary button pressed' },
+  { fg: 'primary-text', bg: 'bg', min: TEXT, use: 'text button, link, field label' },
+  { fg: 'primary-text', bg: 'surface', min: TEXT, use: 'text button, link on a card' },
+  { fg: 'primary-strong', bg: 'primary-soft', min: TEXT, use: 'tonal button, chip, badge, tab' },
+  { fg: 'primary-strong', bg: 'primary-soft-hover', min: TEXT, use: 'tonal hover' },
+  { fg: 'primary-strong', bg: 'primary-soft-pressed', min: TEXT, use: 'tonal, text, tab pressed' },
+  { fg: 'primary-strong', bg: 'bg', min: TEXT, use: 'text button hover' },
+  { fg: 'primary-strong', bg: 'surface', min: TEXT, use: 'text button hover, radio dot' },
+  { fg: 'primary-strong', bg: 'surface-sunken', min: NON_TEXT, use: 'segment cue, progress' },
+  { fg: 'primary-strong', bg: 'surface-muted', min: NON_TEXT, use: 'read-only toggle and radio' },
+  { fg: 'text', bg: 'primary-soft-pressed', min: TEXT, use: 'outline button pressed' },
+  { fg: 'ring', bg: 'bg', min: NON_TEXT, use: 'focus ring' },
+  { fg: 'ring', bg: 'surface', min: NON_TEXT, use: 'focus ring on a card' },
+  { fg: 'primary', bg: 'surface', min: NON_TEXT, use: 'checkbox box, radio ring' },
+  { fg: 'primary', bg: 'bg', min: NON_TEXT, use: 'toggle track on the page' },
+];
+
+/** The brand tokens in the order `theme.css` declares them. */
+const TOKEN_ORDER = [
+  'primary',
+  'primary-hover',
+  'primary-pressed',
+  'primary-soft',
+  'primary-soft-hover',
+  'primary-soft-pressed',
+  'primary-strong',
+  'on-primary',
+  'primary-text',
+  'selected',
+  'ring',
+];
+
+/** `#rgb` or `#rrggbb` (the `#` optional), lower-cased to `#rrggbb`; `undefined` when invalid. */
+function normalizeHex(value) {
+  const match = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(value ?? '');
+  if (!match) {
+    return undefined;
+  }
+  const digits = match[1].toLowerCase();
+  return `#${digits.length === 3 ? [...digits].map((d) => d + d).join('') : digits}`;
+}
+
+function hexToRgb(hex) {
+  const n = Number.parseInt(hex.slice(1), 16);
+  return { r: ((n >> 16) & 255) / 255, g: ((n >> 8) & 255) / 255, b: (n & 255) / 255 };
+}
+
+function toLinear(c) {
+  const abs = Math.abs(c);
+  return abs <= 0.04045 ? c / 12.92 : (Math.sign(c) || 1) * Math.pow((abs + 0.055) / 1.055, 2.4);
+}
+
+function fromLinear(c) {
+  const abs = Math.abs(c);
+  return abs > 0.0031308
+    ? (Math.sign(c) || 1) * (1.055 * Math.pow(abs, 1 / 2.4) - 0.055)
+    : c * 12.92;
+}
+
+/** A `#rrggbb` colour as OKLCH (`h` is undefined for a grey). */
+function hexToOklch(hex) {
+  const rgb = hexToRgb(hex);
+  const r = toLinear(rgb.r);
+  const g = toLinear(rgb.g);
+  const b = toLinear(rgb.b);
+  const L = Math.cbrt(0.412221469470763 * r + 0.5363325372617348 * g + 0.0514459932675022 * b);
+  const M = Math.cbrt(0.2119034958178252 * r + 0.6806995506452344 * g + 0.1073969535369406 * b);
+  const S = Math.cbrt(0.0883024591900564 * r + 0.2817188391361215 * g + 0.6299787016738222 * b);
+  const l = 0.210454268309314 * L + 0.7936177747023054 * M - 0.0040720430116193 * S;
+  let a = 1.9779985324311684 * L - 2.4285922420485799 * M + 0.450593709617411 * S;
+  let bb = 0.0259040424655478 * L + 0.7827717124575296 * M - 0.8086757549230774 * S;
+  if (rgb.r === rgb.g && rgb.g === rgb.b) {
+    a = 0;
+    bb = 0;
+  }
+  const c = Math.sqrt(a * a + bb * bb);
+  const hue = (Math.atan2(bb, a) * 180) / Math.PI;
+  return { l, c, h: c ? ((hue % 360) + 360) % 360 : undefined };
+}
+
+/** An OKLCH colour as (unclamped) sRGB channels. */
+function oklchToRgb(l, c, h) {
+  const rad = ((h ?? 0) / 180) * Math.PI;
+  const a = c ? c * Math.cos(rad) : 0;
+  const b = c ? c * Math.sin(rad) : 0;
+  const L = Math.pow(l + 0.3963377773761749 * a + 0.2158037573099136 * b, 3);
+  const M = Math.pow(l - 0.1055613458156586 * a - 0.0638541728258133 * b, 3);
+  const S = Math.pow(l - 0.0894841775298119 * a - 1.2914855480194092 * b, 3);
+  return {
+    r: fromLinear(4.0767416360759574 * L - 3.3077115392580616 * M + 0.2309699031821044 * S),
+    g: fromLinear(-1.2684379732850317 * L + 2.6097573492876887 * M - 0.3413193760026573 * S),
+    b: fromLinear(-0.0041960761386756 * L - 0.7034186179359362 * M + 1.7076146940746117 * S),
+  };
+}
+
+function inGamut({ r, g, b }) {
+  return r >= 0 && r <= 1 && g >= 0 && g <= 1 && b >= 0 && b <= 1;
+}
+
+function rgbToHex({ r, g, b }) {
+  const byte = (v) => Math.round(Math.max(0, Math.min(1, v || 0)) * 255);
+  return `#${((1 << 24) | (byte(r) << 16) | (byte(g) << 8) | byte(b)).toString(16).slice(1)}`;
+}
+
+/**
+ * An OKLCH colour as `#rrggbb`, its chroma reduced by bisection to the largest that fits sRGB
+ * (culori's `clampChroma(color, 'oklch')`), so a lightness step keeps its hue.
+ */
+function toHex(l, c, h) {
+  const rgb = oklchToRgb(l, c, h);
+  if (inGamut(rgb)) {
+    return rgbToHex(rgb);
+  }
+  if (!inGamut(oklchToRgb(l, 0, h))) {
+    return rgbToHex(oklchToRgb(l, 0, h));
+  }
+  let start = 0;
+  let end = c;
+  let lastGood = 0;
+  let mid = 0;
+  while (end - start > 0.4 / 8192) {
+    mid = start + (end - start) * 0.5;
+    if (inGamut(oklchToRgb(l, mid, h))) {
+      lastGood = mid;
+      start = mid;
+    } else {
+      end = mid;
+    }
+  }
+  const last = oklchToRgb(l, mid, h);
+  return rgbToHex(inGamut(last) ? last : oklchToRgb(l, lastGood, h));
+}
+
+function luminance(hex) {
+  const { r, g, b } = hexToRgb(hex);
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+
+/** The WCAG 2.x contrast ratio of two `#rrggbb` colours. */
+function contrast(a, b) {
+  const la = luminance(a);
+  const lb = luminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/**
+ * The first colour of hue `h` and chroma `c`, from lightness `start` stepping 0.01 darker (-1) or
+ * lighter (+1), that reaches `min` on every backdrop; it stops at the 0.05 / 0.95 bounds.
+ */
+function searchLightness(start, c, h, direction, backdrops, min) {
+  let l = start;
+  let hex = toHex(l, c, h);
+  while (backdrops.some((bd) => contrast(hex, bd) < min) && l > L_FLOOR && l < L_CEILING) {
+    l += direction * L_STEP;
+    hex = toHex(l, c, h);
+  }
+  return hex;
+}
+
+/* ---------- theme: the derivation (the docs site's theme configurator, white on primary) ---------- */
+
+/**
+ * Light mode. `primary` is the brand colour itself and `on-primary` stays white (the library's
+ * look: white labels on brand buttons, a white check mark); hover is 0.06 and pressed 0.12 darker
+ * in OKLCH lightness, walked back towards `primary` while white would miss 4.5:1. The soft tints
+ * (tonal fills) sit at lightness 0.94 / 0.90 / 0.86 with a little of the brand's chroma;
+ * `primary-strong` (text on the soft tints) starts 0.18 darker and steps darker until 4.5:1 on
+ * them and on `bg` and `surface`; `primary-text` steps darker from the brand until 4.5:1 on `bg`
+ * and `surface`; the ring starts at lightness 0.62 and steps darker until 3:1.
+ */
+function lightTokens(hex) {
+  const { l, c, h } = hexToOklch(hex);
+  const backdrops = [NEUTRALS.light.surface, NEUTRALS.light.bg];
+  const step = (by) => {
+    let stepL = l - by;
+    let stepHex = toHex(stepL, c, h);
+    while (contrast(stepHex, WHITE) < TEXT && stepL < l) {
+      stepL += L_STEP;
+      stepHex = toHex(stepL, c, h);
+    }
+    return stepHex;
+  };
+  const softChroma = Math.min(c * 0.35, 0.06);
+  const soft = [0.94, 0.9, 0.86].map((softL) => toHex(softL, softChroma, h));
+  return {
+    primary: hex,
+    'primary-hover': step(0.06),
+    'primary-pressed': step(0.12),
+    'primary-soft': soft[0],
+    'primary-soft-hover': soft[1],
+    'primary-soft-pressed': soft[2],
+    'primary-strong': searchLightness(
+      Math.max(l - 0.18, 0.25),
+      c,
+      h,
+      -1,
+      [...soft, ...backdrops],
+      TEXT,
+    ),
+    'on-primary': WHITE,
+    'primary-text': searchLightness(l, c, h, -1, backdrops, TEXT),
+    selected: toHex(0.96, softChroma, h),
+    ring: searchLightness(0.62, c * 0.6, h, -1, backdrops, NON_TEXT),
+  };
+}
+
+/**
+ * Dark mode. Without `--dark`, `primary` is the brand lifted to OKLCH lightness 0.76 (chroma
+ * x 0.95); with it, the given colour. Hover and pressed are 0.06 and 0.12 lighter; `on-primary` is
+ * a deep tint of the brand (lightness 0.16), or near black when that misses 4.5:1. The soft tints
+ * sit at lightness 0.30 / 0.35 / 0.40; `primary-strong` and `primary-text` step lighter from
+ * `primary` until 4.5:1 on their backdrops; the ring starts at 0.56 and steps lighter until 3:1.
+ */
+function darkTokens(lightHex, darkHex) {
+  const base = hexToOklch(lightHex);
+  const given = darkHex ? hexToOklch(darkHex) : undefined;
+  const h = given ? given.h : base.h;
+  const c = given ? given.c / 0.95 : base.c;
+  const primaryL = given ? given.l : 0.76;
+  const primaryC = c * 0.95;
+  const primary = darkHex ?? toHex(primaryL, primaryC, h);
+  const backdrops = [NEUTRALS.dark.surface, NEUTRALS.dark.bg];
+  const soft = [0.3, 0.35, 0.4].map((softL) => toHex(softL, c * 0.4, h));
+  const onPrimaryTint = toHex(0.16, c * 0.5, h);
+  return {
+    primary,
+    'primary-hover': toHex(primaryL + 0.06, primaryC, h),
+    'primary-pressed': toHex(primaryL + 0.12, primaryC, h),
+    'primary-soft': soft[0],
+    'primary-soft-hover': soft[1],
+    'primary-soft-pressed': soft[2],
+    'primary-strong': searchLightness(primaryL, primaryC, h, 1, [...soft, ...backdrops], TEXT),
+    'on-primary':
+      contrast(primary, onPrimaryTint) >= TEXT ? onPrimaryTint : DARK_ON_PRIMARY_FALLBACK,
+    'primary-text': searchLightness(primaryL, primaryC, h, 1, backdrops, TEXT),
+    selected: toHex(0.24, c * 0.35, h),
+    ring: searchLightness(0.56, c * 0.6, h, 1, backdrops, NON_TEXT),
+  };
+}
+
+/** Each pair's ratio under `tokens` (brand tokens over the mode's neutrals). */
+function checkPairs(tokens, mode) {
+  const all = { ...NEUTRALS[mode], ...tokens };
+  return PAIRS.map((pair) => {
+    const ratio = contrast(all[pair.fg], all[pair.bg]);
+    return { ...pair, fgHex: all[pair.fg], bgHex: all[pair.bg], ratio, ok: ratio >= pair.min };
+  });
+}
+
+/**
+ * The nearest shade of `hex` (same hue and chroma, 0.01 lightness steps: darker for light mode,
+ * lighter for dark mode) whose whole derived set passes; `undefined` when none does.
+ */
+function suggestShade(hex, mode, derive) {
+  const { l, c, h } = hexToOklch(hex);
+  const direction = mode === 'light' ? -1 : 1;
+  for (
+    let next = l + direction * L_STEP;
+    next > L_FLOOR && next < L_CEILING;
+    next += direction * L_STEP
+  ) {
+    const candidate = toHex(next, c, h);
+    if (checkPairs(derive(candidate), mode).every((result) => result.ok)) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+function cssBlock(selector, tokens, results) {
+  const nameWidth = Math.max(...results.map((r) => `${r.fg} on ${r.bg}`.length));
+  const lines = [
+    `${selector} {`,
+    ...TOKEN_ORDER.map((name) => `  --color-${name}: ${tokens[name]};`),
+    '  /* Contrast (WCAG 2.x): ratio, minimum, result, where the widgets draw the pair',
+    ...results.map(
+      (r) =>
+        `     ${`${r.fg} on ${r.bg}`.padEnd(nameWidth)}  ${r.ratio.toFixed(2).padStart(5)}:1` +
+        ` >= ${String(r.min).padEnd(3)}  ${r.ok ? 'ok  ' : 'FAIL'}  ${r.use}`,
+    ),
+    '  */',
+    '}',
+  ];
+  return lines.join('\n');
+}
+
+function theme(args) {
+  const [colour, ...rest] = args;
+  let darkArg;
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--dark' && darkArg === undefined && i + 1 < rest.length) {
+      darkArg = rest[++i];
+    } else {
+      console.error(USAGE);
+      process.exit(1);
+    }
+  }
+  const light = normalizeHex(colour);
+  const dark = darkArg === undefined ? undefined : normalizeHex(darkArg);
+  if (!light || (darkArg !== undefined && !dark)) {
+    const bad = light ? darkArg : colour;
+    console.error(
+      `bf-ui theme: "${bad ?? ''}" is not a hex colour (#rgb or #rrggbb; quote it, since # starts a comment in some shells).`,
+    );
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  const lightSet = lightTokens(light);
+  const darkSet = darkTokens(light, dark);
+  const lightResults = checkPairs(lightSet, 'light');
+  const darkResults = checkPairs(darkSet, 'dark');
+
+  const describe = dark ? `${light} (light) and ${dark} (dark)` : light;
+  const neutrals = (mode) =>
+    Object.entries(NEUTRALS[mode])
+      .map(([name, value]) => `${name} ${value}`)
+      .join(', ');
+  console.log(
+    [
+      `/* @bitforgehq/ui brand tokens for ${describe}, from \`bf-ui theme\`.`,
+      "   Paste into styles.css after @import '@bitforgehq/ui/theme.css'.",
+      `   Checked against the shipped light neutrals: ${neutrals('light')};`,
+      `   and dark neutrals: ${neutrals('dark')}. */`,
+      cssBlock('@theme', lightSet, lightResults),
+      '',
+      cssBlock('.dark', darkSet, darkResults),
+    ].join('\n'),
+  );
+
+  const lightFailed = lightResults.filter((r) => !r.ok);
+  const darkFailed = darkResults.filter((r) => !r.ok);
+  if (lightFailed.length === 0 && darkFailed.length === 0) {
+    return;
+  }
+  for (const [mode, failed] of [
+    ['light', lightFailed],
+    ['dark', darkFailed],
+  ]) {
+    if (failed.length === 0) {
+      continue;
+    }
+    console.error(
+      `bf-ui theme: ${failed.length} ${mode} pair${failed.length === 1 ? '' : 's'} below the minimum:`,
+    );
+    for (const r of failed) {
+      console.error(
+        `  ${r.fg} ${r.fgHex} on ${r.bg} ${r.bgHex}: ${r.ratio.toFixed(2)}:1 < ${r.min}:1 (${r.use})`,
+      );
+    }
+  }
+  // A darker light colour, a lighter dark one: the nearest shades of the same hue that pass.
+  const lightShade = lightFailed.length ? suggestShade(light, 'light', lightTokens) : light;
+  const darkShade = darkFailed.length
+    ? suggestShade(dark ?? darkSet.primary, 'dark', (candidate) =>
+        darkTokens(lightShade ?? light, candidate),
+      )
+    : dark;
+  if (lightShade === undefined || (darkFailed.length > 0 && darkShade === undefined)) {
+    console.error('  No shade of this hue passes in that mode; pick another colour.');
+  } else {
+    const changed = [
+      lightFailed.length ? 'a darker light' : '',
+      darkFailed.length ? 'a lighter dark' : '',
+    ]
+      .filter(Boolean)
+      .join(' and ');
+    console.error(
+      `  Try ${changed} shade: bf-ui theme '${lightShade}'${darkShade ? ` --dark '${darkShade}'` : ''}`,
+    );
+  }
+  process.exit(1);
+}
+
 function main() {
   const args = process.argv.slice(2);
   const [command, ...rest] = args;
 
+  if (command === 'theme') {
+    theme(rest);
+    return;
+  }
+
   if (command !== 'sync-ai') {
     console.error(USAGE);
     process.exit(1);