Wire Kerning Audits into Your Design System CI

The core of the CI check, mirroring exactly what the browser tool does: parse, read font.kerningPairs, drop zero values, count. This is the legacy kern table only.

// count-kern.mjs
import opentype from 'opentype.js';
import { readFileSync } from 'node:fs';

function kernCount(path) {
  const font = opentype.parse(readFileSync(path).buffer);
  const pairs = font.kerningPairs ?? {};   // kern TABLE only
  let n = 0;
  for (const k of Object.keys(pairs)) {
    if (pairs[k] !== 0) n++;               // drop zero-value pairs
  }
  return n;
}

console.log(kernCount(process.argv[2]));
// Note: WOFF2 must be decompressed first — opentype.parse
// expects raw SFNT/TTF/OTF bytes, not a WOFF2 wrapper.

Read the committed baseline, recompute, and exit non-zero on a large drop. Percentage thresholds so it works across fonts of different sizes.

// kern-gate.mjs
import { readFileSync } from 'node:fs';
import { kernCount } from './count-kern.mjs';

const base = JSON.parse(readFileSync('fonts.kerning-baseline.json'));
let failed = false;
for (const [path, baseline] of Object.entries(base)) {
  const now = kernCount(path);
  const dropPct = baseline ? (baseline - now) / baseline * 100 : 0;
  if (now === 0 && baseline > 0) {
    console.error(`FAIL ${path}: kerning vanished (was ${baseline})`);
    failed = true;
  } else if (dropPct > 30) {
    console.error(`FAIL ${path}: ${dropPct.toFixed(0)}% drop`);
    failed = true;
  } else if (dropPct > 10) {
    console.warn(`WARN ${path}: ${dropPct.toFixed(0)}% drop`);
  }
}
process.exit(failed ? 1 : 0);

Instead of bundling opentype.js, POST the font to the paired local runner and read the same JSON the browser tool emits. The font never leaves your machine. pairLimit is the only option; for a count check you only need total_kerning_pairs, which is independent of pairLimit.

# Discover the schema (the one option: pairLimit)
curl http://127.0.0.1:9789/../  # GET /api/v1/tools/kerning-pair-auditor

# Run the audit on a font
curl -s -X POST \
  -F 'files=@dist/fonts/BrandSans.ttf' \
  http://127.0.0.1:9789/v1/tools/kerning-pair-auditor/run \
  | node -e 'const d=JSON.parse(require("fs").readFileSync(0));\
             console.log(JSON.parse(d.content).total_kerning_pairs)'

# total_kerning_pairs is the full non-zero count regardless
# of pairLimit (pairLimit only caps the returned pairs array).

Before trusting a count, verify the font is kern-table-based. If its baseline is zero, a count check measures nothing — skip it and rely on a visual/GPOS review instead.

for (const [path, baseline] of Object.entries(base)) {
  if (baseline === 0) {
    console.log(`SKIP ${path}: GPOS-kerned, count check N/A`);
    continue;  // count of 0 is permanent; nothing to detect
  }
  // ... run the count comparison ...
}

// A baseline of 0 means kerning lives in GPOS. The count check
// cannot see it. Use desktop fontTools (ttx -t GPOS) or a
// visual render diff for those fonts instead.

The most valuable thing this check actually finds: a build step that stripped layout tables. JAD's in-browser font-subsetter uses opentype.js and drops GPOS/GSUB — run the count AFTER subsetting to catch it.

# Pre-subset:  BrandSans.ttf       → kernCount 842
# Post-subset: BrandSans.subset.ttf → kernCount 842  (kern TABLE survived)
#   ... but if the source kerned via GPOS:
# Pre-subset:  total_kerning_pairs 0  (GPOS, invisible to count)
# Post-subset: total_kerning_pairs 0  (GPOS now DROPPED by opentype.js subsetter)
#   → count is 0 both times; the regression is INVISIBLE to a count check.
#
# Lesson: count checks catch kern-TABLE drops. For GPOS-kerned
# fonts, use a layout-preserving subsetter (hb-subset/pyftsubset)
# and verify the GPOS kern feature survived with fontTools.

If a font is GPOS-kerned, font.kerningPairs is permanently empty (zero), so the count never changes and the check passes forever while detecting nothing. Always verify a non-zero baseline before relying on the gate. A baseline of 0 means 'skip this font' — the count check is structurally blind to GPOS kerning.

opentype.parse expects raw SFNT/TTF/OTF bytes. A WOFF2 buffer fails to parse. Decompress first (the browser tool uses a WASM wawoff2 build; in Node use the wawoff2 package or woff2_decompress). The runner endpoint handles this for you — POST the WOFF2 and it decompresses internally.

If you switch to hb-subset/pyftsubset (which preserve GPOS), a GPOS kern regression won't show in the kern-table count because the count was zero to begin with. To gate GPOS kerning you need a fontTools-based check on the GPOS kern feature, not a font.kerningPairs count. The count gate only protects legacy-table kerning.

An absolute threshold like 'fail on drop > 50 pairs' is noise on a 2,000-pair font and over-strict on a 100-pair font. Use percentage thresholds (warn > 10%, fail > 30%) so one rule works across a design system with mixed baselines. The threshold table above is a starting point.

A deliberate foundry re-cut that reduces pair count will fail the gate until you update fonts.kerning-baseline.json. That's the intended behaviour — it forces explicit human acknowledgement. Update the baseline in the same PR as the font change so the diff documents the decision.

A font could drop one brand-critical pair while adding others, leaving the total count flat. A count-only gate won't catch this. Add an explicit critical-pairs assertion (look up glyph indices via cmap, check the key exists in font.kerningPairs) for pairs you can't afford to lose.

The count is a pure function of the font bytes, so a version-string bump with no glyph/table change produces an identical count and the gate stays green. This is correct — reruns on unchanged fonts are idempotent. The gate reacts to table content, not metadata.

The HTTP-API approach needs the @jadapps/runner running and paired on the CI machine at 127.0.0.1:9789. If it isn't, the POST fails with connection refused. For CI where you can't run the runner, use the direct opentype.js approach instead — it needs only npm i opentype.js and a WOFF2 decompressor.