harmonink

Getting started

harmonink reads a font file, works out how big its letters actually are, and gives you the CSS to set it at a consistent reading size. No dependencies, no runtime, Node 22 or newer.

Install

npm  i harmonink
pnpm add harmonink
yarn add harmonink
bun  add harmonink

Deno resolves it at the import site, so there is nothing to install:

import { measure, normalize, toCSS } from 'npm:harmonink';

None of these is a special build. The package is ES modules with no dependencies and no install scripts, which is why every package manager treats it the same way.

Your first run

Point it at a font file and look at what comes back.

import { readFileSync } from 'node:fs';
import { measure, normalize } from 'harmonink';

const metrics = measure(readFileSync('EBGaramond.woff2'));
const rules = normalize(metrics);

metrics is what the font is. Nothing in it is a judgement:

{
  family: 'EB Garamond',
  xHeightRatio: 0.4043,     // the reading band, as a fraction of the em box
  capHeightRatio: 0.6523,
  inkRatio: 0.9941,         // tallest ascender to lowest descender
  advanceX: 1.029,          // average letter width, in x-heights
  gapBox: 0.1028,           // empty space inside each letter's own width
  gapStem: 0.5315,          // space beside a letter at stem height
  ...
}

rules is what to do about it:

{
  sizeAdjust: 123.46,       // grow the face by a quarter
  lineHeight: 27,           // px, at the 16px base
  letterSpacing: 0,         // already comfortably spaced
  fontWeight: 300,          // lighter, because the face got bigger
  renderedSize: 19.75,      // what 16px now draws at
  category: 'serif',
  capAnchored: false,
  trackClamped: false,
}

EB Garamond has a small x-height for a serif, so it comes out a quarter larger than you asked for and its weight drops to compensate. A face already in the comfortable range comes back with sizeAdjust: 100 and nothing to do.

The two are separate on purpose. Measurements are facts about the file and will not change. The rules are opinions about what to do with them, and those will move as the ruleset improves. If you want the facts and your own rules, takemeasure and ignore the rest.

In the browser

measureLive gets the same numbers from a font the browser has already loaded. It needs no parser and no font file of its own, so it works on anything the page can render, including a file the user just dropped in.

import { measureLive } from 'harmonink/live';
import { normalize } from 'harmonink/normalize';

await document.fonts.load('512px "Lora"');
const rules = normalize(measureLive('Lora', { em: 512 }));

Import by subpath in the browser. The root export pulls in the woff2 parser and itsnode:zlib dependency, which you do not want in a bundle.

It draws each glyph to a canvas and counts pixels rather than trustingactualBoundingBox*, because that API rounds differently on every platform. Chromium on Linux snaps it to 1/64 of the em, which at a 512px em is an 8px grid. Results carry approximate: true as a reminder that they came from pixels rather than outlines.

From the terminal

npx harmonink ./fonts/*.woff2 -o src/styles/fonts.css
npx harmonink ./fonts/Lora.woff2 --json
npx harmonink ./fonts/*.woff2 --grid 24

The first writes a stylesheet, the second gives you the raw numbers, the third pins every face to a 24px line grid instead of letting the leading follow the font.

What it writes

/* harmonink — EB Garamond · x-height normalized to 19.75px · serif */

@font-face {
  font-family: "EB Garamond";
  src: url("./EBGaramond.woff2");
  font-display: swap;
  size-adjust: 123.46%;
}

.text-normalized {
  font-family: "EB Garamond";
  font-size: 1em;
  line-height: 1.6875;
  font-weight: 300;
}

The correction sits in size-adjust, inside the@font-face rule. That matters more than it looks: yourfont-size stays whatever you set it to, so anything computing from it still works and you can change the number later without redoing the maths.

The class uses relative units so it composes. 1em inherits, and the line height is a ratio rather than a pixel count, so dropping the class on something set at 18px gives you proportional leading instead of the wrong leading. Passselector to toCSS if you want a different class name.

size-adjust and letter-spacing are both left out when they come out as the identity. Writing them claims a correction that never happened, and a stray letter-spacing: 0em would override whatever the element inherited.

Wiring it into a build

For fonts you ship yourself, run it once at build time and commit the CSS. Nothing reaches the browser except a stylesheet.

// scripts/fonts.mjs
import { readFileSync, writeFileSync, readdirSync } from 'node:fs';
import { measure, normalize, toCSS } from 'harmonink';

const out = readdirSync('public/fonts')
  .filter(f => f.endsWith('.woff2'))
  .map(f => {
    const rules = normalize(measure(readFileSync(`public/fonts/${f}`)));
    return toCSS(rules, {
      src: `/fonts/${f}`,
      selector: `.font-${rules.family.toLowerCase().replace(/\W+/g, '-')}`,
    });
  });

writeFileSync('src/styles/fonts.css', out.join('\n'));

Add it as a prebuild script and the stylesheet regenerates whenever the fonts change. Measure in the browser only when you cannot know the font in advance, like a theme picker or an upload.

Checking it worked

Set two corrected fonts side by side at the same font-size and look at the lowercase. The tops of the letters should line up. If one still reads smaller than the other, one of two things is happening.

Either the face was cap-anchored, which happens to about one in six and is a deliberate trade explained onHow it works. Or the correction hit the 90% floor, which the sizeAdjust value will tell you outright.

renderedSize is the quickest sanity check. Multiply it byxHeightRatio and you get the height of the reading band in pixels. Across corrected fonts that number should be close to 8.6.

NextHow it works