@capsizecss/metrics

@capsizecss/metrics

Font metrics library for system and Google fonts.

npm install @capsizecss/metrics

Usage

Import the metrics for your chosen font to pass them directly into capsize.

import { createStyleObject } from '@capsizecss/core';
import arialMetrics from '@capsizecss/metrics/arial';

const capsizeStyles = createStyleObject({
  fontSize: 16,
  leading: 24,
  fontMetrics: arialMetrics,
});

In addition to common system fonts, Google fonts are also supported.

import { createStyleObject } from '@capsizecss/core';
import lobsterMetrics from '@capsizecss/metrics/lobster';

const capsizeStyles = createStyleObject({
  fontSize: 16,
  leading: 24,
  fontMetrics: lobsterMetrics,
});

Variants

Metrics for the available variants of a font can be imported by weight and font style.

import metrics from '@capsizecss/metrics/ {font-family} / {weight}{style}';

The format follows the convention used by Google Fonts for variant names: either a standalone weight or style (e.g. regular, italic), a specific weight (e.g. numeric 100 to 900), or a combination of both (e.g. 100italic-900italic).

[!NOTE] Each font only includes the variants that are available for that specific font.

import arialRegular from '@capsizecss/metrics/arial/regular';
import arialItalic from '@capsizecss/metrics/arial/italic';
import arialBold from '@capsizecss/metrics/arial/700';
import arialBoldItalic from '@capsizecss/metrics/arial/700italic';

The top-most import path for a font family (e.g. without a variant: @capsizecss/metrics/arial) will return the regular variant. In the case of a Google Font that has no regular variant, the first variant in the variants array is returned.

Font metrics

The font metrics object returned contains the following properties if available:

Property	Type	Description
familyName	string	The font’s family name as authored by font creator
fullName	string	The font’s full name as authored by font creator
postscriptName	string	The font’s unique PostScript name as authored by font creator
category	string	The style of the font: serif, sans-serif, monospace, display, or handwriting.
capHeight	number	The height of capital letters above the baseline
ascent	number	The height of the ascenders above baseline
descent	number	The descent of the descenders below baseline
lineGap	number	The amount of space included between lines
unitsPerEm	number	The size of the font’s internal coordinate grid
xHeight	number	The height of the main body of lower case letters above baseline
xWidthAvg	number	The average width of character glyphs in the font for the selected unicode subset. Calculated based on character frequencies in written text (see below), falling back to the built in xAvgCharWidth from the OS/2 table.
subsets	{ [subset]: { xWidthAvg: number } }	A lookup of the xWidthAvg metric by subset (see supported subsets below)

How xWidthAvg is calculated

The xWidthAvg metric is derived from character frequencies in written language. The value takes a weighted average of character glyph widths in the font, falling back to the built in xAvgCharWidth from the OS/2 table if the glyph width is not available.

The purpose of this metric is to support generating CSS metric overrides (e.g. ascent-override, size-adjust, etc) for fallback fonts, enabling inference of average line lengths so that a fallback font can be scaled to better align with a web font. This can be done either manually or using createFontStack.

For this technique to be effective, the metric factors in a character frequency weightings as observed in written language, using “abstracts” from Wikinews articles as a data source. Below is the source analysed for each supported subset:

Subset	Language
latin	English (source)
thai	Thai (source)

[!TIP] Need support for a different unicode subset? Either create an issue or follow the steps outlined in the generate-weightings script in the unpack package and open a PR.

For more information on how to access the metrics for different subsets, see the subsets section below.

Subsets

The top level xWidthAvg metric represents the average character width for the latin subset. However, the xWidthAvg for each supported subset is available explicitly within the subsets field.

For example:

import arial from '@capsizecss/metrics/arial';

const xWidthAvgDefault = arial.xWidthAvg;
const xWidthAvgLatin = arial.subsets.latin.xWidthAvg; // Same as above
const xWidthAvgThai = arial.subsets.thai.xWidthAvg;

Supporting APIs

fontFamilyToCamelCase

A helper function to support tooling that needs to convert the font family name to the correct casing for the relevant metrics import.

import { fontFamilyToCamelCase } from '@capsizecss/metrics';

const familyName = fontFamilyToCamelCase('--apple-system'); // => `appleSystem`
const metrics = await import(`@capsizecss/metrics/${familyName}`);

entireMetricsCollection

Provides the entire metrics collection as a JSON object, keyed by font family name.

---

⚠️ CAUTION: Importing this will result in a large JSON structure being pulled into your project!

It is not recommended to use this client side.

---

import { entireMetricsCollection } from '@capsizecss/metrics/entireMetricsCollection';

const metrics = entireMetricsCollection['arial'];

or for a specific variant:

import { entireMetricsCollection } from '@capsizecss/metrics/entireMetricsCollection';

const arialBoldItalic = entireMetricsCollection['arial'].variants['700italic'];

Thanks

• SEEK for giving us the space to do interesting work.

License

MIT.