Skip to content

Latest commit

 

History

History
172 lines (118 loc) · 9.41 KB

README.md

File metadata and controls

172 lines (118 loc) · 9.41 KB
Raw

Capsize


@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.