@capsizecss/metrics
v3.4.0
Published
Font metrics library for system and Google fonts
Downloads
329,171
Readme
@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 theunpack
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.