Automate Ligature Previews and CSS in Your Build Pipeline

The minimal call: POST the font and sample text, get the self-contained preview back. Save it as a build artifact.

curl -s -X POST 127.0.0.1:9789/v1/tools/ligature-toggler/run \
  -F 'file=@src/fonts/Brand-Display.woff2' \
  -F 'options={"sampleText":"Affinity Office"}' \
  -o dist/previews/Brand-Display.ligatures.html

# -> self-contained HTML, font base64-inlined, 3 rendered rows

The Toggler doesn't detect features — the inspector does. Use its JSON to drive whether you emit dlig.

# Step 1: detect (inspector returns JSON tag list)
curl -s -X POST 127.0.0.1:9789/v1/tools/opentype-features-inspector/run \
  -F 'file=@src/fonts/Brand-Display.woff2' > feats.json

# Step 2: emit dlig only if present
if jq -e '.tags | index("dlig")' feats.json >/dev/null; then
  echo 'h1,h2{font-feature-settings:"liga" 1,"calt" 1,"dlig" 1;}' >> dist/typography.css
else
  echo 'h1,h2{font-feature-settings:"liga" 1,"calt" 1;}' >> dist/typography.css
fi

Emit one preview per font so reviewers can eyeball ligature rendering across the whole family in a PR.

mkdir -p dist/previews
for f in src/fonts/*.woff2; do
  name=$(basename "$f" .woff2)
  curl -s -X POST 127.0.0.1:9789/v1/tools/ligature-toggler/run \
    -F "file=@$f" \
    -F 'options={"sampleText":"office difficult fluffy"}' \
    -o "dist/previews/$name.ligatures.html"
done

Force an explicit decision when a font swap drops a feature your tokens assume. The Toggler can't gate this — the inspector's JSON does.

# Expect every *-Display font to ship dlig
for f in src/fonts/*-Display.woff2; do
  curl -s -X POST 127.0.0.1:9789/v1/tools/opentype-features-inspector/run \
    -F "file=@$f" > feats.json
  if ! jq -e '.tags | index("dlig")' feats.json >/dev/null; then
    echo "::error::$f has no dlig but a display font is expected to"
    exit 1
  fi
done

Render the same sample text against old and new font versions and diff the HTML/screenshot to catch unintended rendering changes.

# Render both versions with identical sample text
for v in v1 v2; do
  curl -s -X POST 127.0.0.1:9789/v1/tools/ligature-toggler/run \
    -F "file=@fonts/$v/Brand.woff2" \
    -F 'options={"sampleText":"office difficult fluffy"}' \
    -o "diff/$v.html"
done
# headless-render diff/v1.html vs diff/v2.html -> flag pixel deltas

The Ligature Toggler returns HTML, never a list of feature tags — it renders three fixed rows and does not parse GSUB. If your script needs to know whether a font has dlig/salt/ss01, call opentype-features-inspector, which returns JSON. Wiring the Toggler into a detection step will fail silently (you'll be grepping HTML).

POSTing to 127.0.0.1:9789 with no runner returns a connection error. Confirm the runner is up (GET /v1/health) and that you're on a Pro or Developer plan — the local-runner dispatch path is gated to paid tiers. On free tier the tool runs only in the browser, not via CI.

The schema has exactly one option, sampleText. Extra keys like liga or dlig in the options object are ignored — there is no API to change which features the three rows show. Don't build a pipeline assuming you can request, say, an hlig-only row.

The size cap (5 MB free, 50 MB Pro, 1 GB Developer) applies to the runner too. A huge CJK font on Pro near 50 MB will be rejected with a tier-limit error. Subset first with font-subsetter or upgrade the tier for the build account.

If the font has no dlig glyphs, rows 2 and 3 of the generated HTML are identical — correct, not a render bug. Don't write a CI assertion that the two rows must differ; instead detect dlig via the inspector and only assert on fonts that should have it.

The previews are deterministic given the same font + sample text, so committing them gives reproducible PR diffs; gitignoring keeps the repo lean if you trust CI to regenerate. Most teams attach them as build artifacts rather than committing, since fonts change rarely.

The Toggler inlines the font as-is, so a variable font renders at its default axis values. If your typography uses a specific instance, freeze it first with variable-font-freezer and feed the static file to the pipeline so the preview matches production.

The inlined @font-face uses font-display: block, so a headless screenshot taken too early may capture invisible text mid-decode. Wait for fonts to load (document.fonts.ready) before snapping, or compare the raw HTML instead of a pixel render.