Font-System

font-system is a font face compiler and optimizer that splits multiple fonts into separate unicode codepoint ranges and creates applicable CSS @font-face blocks for each.

The benefit of such a technique is smaller font download sizes, forcing the browser to only download parts of the fonts that are actually being used. This vastly simplifies internationalization (i18n) by removing the need to specify fonts alongside translations, and instead allows developers to specify a single font face that works across all languages in an efficient way.

Check out the example/ directory to see a working sample configuration, build script and test page.

Installation

You can either install font-system globally:

$ npm i -g font-system
$ font-system --help

... locally:

$ npm i --save-dev font-system
$ ./node_modules/.bin/font-system --help

... or run it directly via npx:

$ npm font-system --help

Usage

$ font-system [-hBUGDf] [-d display] [-b boldness] [-N boldness] [-p base_path] [-O name] -o output_dir/ config.json


  -h, --help                   Show this help message

  -o, --out-dir output_dir     The directory in which font files
                               and CSS are written (directory must exist)

  -B, --numeric-bold           Don't use human-readable boldness, but instead
                               numeric boldness

  -b, --bold boldness          The weight class ("boldness") number to
                               assign to boldness (default = 700)

                               See NOTES about boldness.

  -N, --normal boldness        The weight class ("boldness") number to
                               assign to regular weighted fonts (default = 400)

                               See NOTES about boldness.

  -p, --path base_path         The base path for all fonts;
                               the generated font base name is appended to this path

  -O, --out-name name          The name of the generated .css file (without .css extension)
                               (default = "fonts")

  -U, --unicode-ranges         Use unicode ranges in the generated font files instead
                               of the group numbers (more descriptive file names that
                               are also much longer)

  -G, --no-groups              Ignore the groupings specified by unicode-pages.
                               This will generate more granular fonts but will
                               require the browser makes more HTTP requests.

  -D, --display type           Specifies a font-display value.
                               Must be one of: auto, block, swap, fallback, optional

  -f, --fb-ranges              Generate (potentially large) fallback font ranges
                               based on which glyphs are available in the range.
                               This will increase CSS size but eliminate any aggressive
                               fallback font fetching.

font-system aims to be an all-in-one font compiler and optimizer for situations where multiple fonts are used to cover multiple languages (scripts).

To use font-system, pass a config.json file that contains a mapping of font face names to unicode script names (described below) to arrays of font files relative to the config.json's directory.

For example, the following config.json creates a CSS font face called MainTypeface (used by giving an element the CSS property font-family: "MainTypeface") using the latin glyphs from the Roboto font and the cyrillic glyphs from the PT Sans font. For any glyphs that aren't included in those ranges/fonts, we've specified that the browser should fallback (@) to the full fonts in the latin group (meaning two sets of latin fonts are generated by font-system).

{
    "MainTypeface": {
        "@": "latin",
        "latin": [
            "./Roboto-Normal.ttf",
            "./Roboto-Normal-Italic.ttf"
        ],
        "cyrillic": [
            "./PT Sans-Normal.ttf"
        ]
    }
}

Script names are those defined as keys in the unicode-pages package.

All script names can either be an array of font paths relative to the config file (NOT the current working directory!) OR a single string referencing another script.

Recursive references are allowed, as long as they are not circular.

The fallback key (@) indicates a font face that is used in the event the browser cannot find a more specific font for a given glyph (specified by the unicode glyph ranges belonging to any of the declared scripts).

While not explicitly mandatory, it is usually ideal to specify a base set of fonts with any extraneous glyphs. When in doubt, set this to match/reference your "latin" fonts.

Notes

In the case where -B is not supplied, font-system will assign specific weight classes ("boldness" numbers) a CSS-friendly weight.

For regularly weighted ("unweighted" or "unbolded") fonts, the CSS will simply omit any bold specifiers. The default for this weight is 400 and can be overridden using the -N flag.

For bold weighted fonts, the CSS will specify font-weight: bold for fonts with the specified weight class. The default for this weight is 700 and can be overridden using the -b flag.

In all other cases, the numeric weight is specified with the font-weight property.

When -B is supplied, the font weight number is specified for all fonts and no human-readable font weight is used. The -N and -b flags are ignored when -B is specified.

It's worth mentioning this utility was designed to work with the Google Font project, and makes a small number of assumptions about the fonts being loaded in. If you're seeing issues with a particular font, please open an issue at https://github.com/kor-tech/font-system.

Is it okay to use a synthetic/app-specific font family name?

Yes; it's even encouraged by the specification.

License

font-system is Copyright © 2019 by Kor Technologies. It is released under the MIT License.