Generate a Type Scale in CI from the Runner API

The minimal CI step: POST options, save the CSS. Works in any image with curl; no Node, Python, or native font libs required.

curl -s -X POST http://127.0.0.1:9789/v1/tools/typography-scale-builder/run \
  -H 'Content-Type: application/json' \
  -d '{"options":{"baseSize":16,"scaleRatio":1.25,"steps":8}}' \
  -o tokens/type-scale.css

# tokens/type-scale.css now holds the static + fluid blocks

Drop into a package.json prebuild. Fetches the scale and writes it where the bundler will pick it up. Same engine as the browser, no extra deps.

// scripts/gen-type-scale.mjs
import { writeFile } from 'node:fs/promises';

const res = await fetch('http://127.0.0.1:9789/v1/tools/typography-scale-builder/run', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ options: { baseSize: 16, scaleRatio: 1.333, steps: 9, scaleOrigin: 2 } }),
});
const css = await res.text();
await writeFile('src/styles/type-scale.css', css);
console.log('wrote type-scale.css');

The tool gives CSS; if your pipeline wants JSON tokens, parse them out. This regex reads the static block's name + px comment. From here you can feed Style Dictionary.

// from the generated CSS text
const re = /--font-size-([\w]+):\s*[\d.]+rem;\s*\/\*\s*([\d.]+)px/g;
const tokens = {};
for (const [, name, px] of css.matchAll(re)) {
  tokens[name] = { value: `${px}px`, type: 'fontSize' };
}
// tokens = { xs:{value:'10.24px'...}, sm:{...}, base:{...}, ... }
// write tokens.json and run Style Dictionary's transforms

If you would rather not call the runner, the math is one line and matches the tool's rounding exactly (px rounded to 2 dp). Useful for pure-static-site generators.

const LABELS = ['xs','sm','base','lg','xl','2xl','3xl','4xl','5xl','6xl','7xl','8xl'];
function scale(base = 16, ratio = 1.25, steps = 8, origin = 2) {
  return Array.from({ length: steps }, (_, i) => {
    const px = Math.round(base * ratio ** (i - origin) * 100) / 100;
    return { name: LABELS[i] ?? `step-${i}`, px, rem: +(px / base).toFixed(3) };
  });
}
// scale() === the tool's static block, value for value

Regenerate in CI and diff against the committed file. A non-empty diff means the config and the artifact disagree — fail the build so the scale stays the single source of truth.

node scripts/gen-type-scale.mjs
if ! git diff --quiet src/styles/type-scale.css; then
  echo 'type-scale.css is out of date — regenerate and commit'
  git --no-pager diff src/styles/type-scale.css
  exit 1
fi

The endpoint returns text/css and nothing else — the same type-scale.css the browser produces. There is no format=json or platform=ios parameter. For other platforms, parse the rem/px from the CSS (cookbook) or recompute from base × ratio, then run your own transformer. Document this in your pipeline so teammates do not look for a flag that does not exist.

http://127.0.0.1:9789 only responds if the JAD runner is installed and paired on that machine. In ephemeral CI agents you must start/pair it as a setup step, or fall back to the recompute-locally recipe (no runner needed). A connection-refused error means the runner is not up — check the setup step before the generation step.

scaleRatioName only accepts the eight known names; an unknown name falls back to the default. To use an arbitrary ratio (e.g. 1.27), send the numeric scaleRatio field instead — the handler reads scaleRatio directly. Sending both is fine; the numeric one is what the math uses.

The fluid clamp() uses baseSize as the root font size for its rem/vw math. If you generate at base 18 but your site's html is 16px, the fluid values render off from the px comments. Keep baseSize and your actual root font-size aligned, or generate at 16 and scale via the ratio.

The label list runs to 8xl (12 names). A steps: 12 run emits all of them. If your downstream config only knows xs–4xl, the extra tokens are silently unused but still in the CSS. Either trim the steps or extend your consuming config to map the larger tokens.

The static block uses irregular padding before the px comment (it is cosmetic). Anchor your regex on --font-size-NAME: and the rem; plus the /* Npx */ comment rather than fixed column positions. The cookbook regex is tolerant of the spacing; copy it rather than hand-rolling a brittle one.

The tool rounds px to two decimals before dividing for rem (3 dp). If you recompute with full precision you may see 1.5625 where the tool shows 1.563. For pixel rendering this is irrelevant, but if you assert equality in tests, round your recomputed values the same way the tool does (Math.round(px*100)/100).

This is a generative tool — needsFile is false. The runner endpoint expects only an options object; do not send a multipart file. If your generic runner wrapper always attaches a file, the type-scale call will still work but the file is ignored. Keep the request to { options: {...} }.

The output is variables only — no h1 { font-size: var(--font-size-4xl) } rules. Generate those in your own template after writing the CSS. This keeps the artifact framework-neutral. The mapping example in the online builder guide shows a sensible default assignment.