Generate Typography Design Tokens from Font Metrics

Walks a fonts directory, computes the analyser's exact line-height plus ratios, and writes a tokens file. TTF/OTF only here; add wawoff2/pako for web fonts.

import fs from "node:fs";
import path from "node:path";
import opentype from "opentype.js";

const dir = "src/fonts";
const tokens = {};

for (const file of fs.readdirSync(dir).filter(f => /\.(ttf|otf)$/i.test(f))) {
  const font = opentype.parse(fs.readFileSync(path.join(dir, file)).buffer);
  const upm = font.unitsPerEm;
  const os2 = font.tables.os2 ?? {};
  const typoLH = (os2.sTypoAscender + Math.abs(os2.sTypoDescender) + (os2.sTypoLineGap ?? 0)) / upm;
  const winLH  = (os2.usWinAscent + os2.usWinDescent) / upm;
  const safe   = +Math.max(typoLH, winLH, 1.0).toFixed(3);
  const family = path.parse(file).name;
  tokens[family] = {
    "line-height":      { "$value": safe, "$type": "number" },
    "x-height-ratio":   { "$value": +(os2.sxHeight / upm).toFixed(4), "$type": "number" },
    "cap-height-ratio": { "$value": +(os2.sCapHeight / upm).toFixed(4), "$type": "number" },
  };
}
fs.writeFileSync("tokens/typography.json", JSON.stringify(tokens, null, 2));

What the script writes. Style Dictionary consumes this shape directly.

{
  "Inter-Regular": {
    "line-height":      { "$value": 1.21,   "$type": "number" },
    "x-height-ratio":   { "$value": 0.5459, "$type": "number" },
    "cap-height-ratio": { "$value": 0.7275, "$type": "number" }
  },
  "SourceSerif-Regular": {
    "line-height":      { "$value": 1.32,   "$type": "number" },
    "x-height-ratio":   { "$value": 0.475,  "$type": "number" },
    "cap-height-ratio": { "$value": 0.66,   "$type": "number" }
  }
}

Reuse JAD's exact handler instead of writing the math. POST the font, get the analyser JSON, pluck the safe line-height.

# Schema first (confirms it takes no options):
curl -sS http://127.0.0.1:9789/../api/v1/tools/font-metrics-analyzer
# → { ..., "options": [] }

# Run it:
curl -sS -X POST http://127.0.0.1:9789/v1/tools/font-metrics-analyzer/run \
  -F 'files=@src/fonts/Inter-Regular.ttf' \
  | jq '.recommended_line_height.safe'
# → 1.21

Wire the Node script into the build so a font update reshapes the tokens automatically. No manual line-height edits.

- name: Generate typography tokens
  run: |
    npm i opentype.js style-dictionary
    node scripts/font-metrics-tokens.mjs
    npx style-dictionary build --config sd.config.json
- name: Fail if tokens changed but weren't committed
  run: git diff --exit-code tokens/ build/css/typography.css

Style Dictionary turns the number tokens into CSS variables your stylesheet references.

/* generated by Style Dictionary from typography.json */
:root {
  --inter-regular-line-height: 1.21;
  --inter-regular-x-height-ratio: 0.5459;
  --inter-regular-cap-height-ratio: 0.7275;
}
body { font-family: "Inter"; line-height: var(--inter-regular-line-height); }

font.tables.os2 is undefined, so sTypoAscender etc. are undefined and arithmetic yields NaN. Guard with os2 = font.tables.os2 ?? {} and detect: if the typo fields are missing, compute line-height from font.tables.hhea instead ((hhea.ascender + |hhea.descender| + hhea.lineGap)/upm) and skip the ratio tokens. The web tool does the same fallback internally.

Dividing zero by UPM gives a 0 ratio, which would emit a misleading token (it's not that the x-height is zero — it's unknown). Detect !sxHeight and omit the x-height-ratio token, logging a warning. Don't emit 0 — downstream size-matching would scale to nothing.

opentype.parse expects an sfnt; a raw WOFF2 buffer will fail. Decompress with wawoff2.decompress() (WOFF2) or pako.inflate per-table (WOFF) before parsing — the exact steps the web tool uses. Simpler on paid tiers: POST the WOFF2 to the runner, which decompresses it for you and returns the metrics JSON.

opentype.js reads the static OS/2/head values, i.e. the default instance's metrics — not per-axis MVAR values. If your design system ships multiple instances with different metrics, freeze each one (fonttools varLib.instancer or variable-font-freezer) and run the script over the frozen files so each instance gets correct tokens.

Floating-point ratios with full precision change in the last digits across machines, churning your git diff. Round deliberately (.toFixed(3) for line-height, .toFixed(4) for ratios, matching the web tool's 3-dp line-height) so the committed tokens only change when the metric meaningfully changes.

The runner API at 127.0.0.1:9789 only answers when the runner is running and paired. In a headless CI box, pair it as part of the job or just use the pure opentype.js path, which has no runner dependency. Check GET /v1/health on the runner before POSTing.

Two files (e.g. Regular and a webfont subset) can share an internal family name, overwriting each other in the tokens object. Key the token group by the filename stem (or filename + style) rather than the OS/2 family name to keep every face distinct.

The analyser handler — and therefore the obvious automation around it — doesn't read the post table. If your tokens need underlinePosition/underlineThickness/italicAngle, read font.tables.post.* yourself in the same script, or pull them from font-metadata-extractor. Don't expect them in the metrics JSON.

The runner's metrics handler only accepts ttf/otf/woff/woff2 and rejects .ttc. In your own Node script, opentype.js can parse a specific font from a collection if you pass the right offset, but it's easier to extract the faces first. Filter .ttc out of the directory walk or pre-split it.