@shiftbrainstd/harmonic-modular-scale NPM

Harmonic Modular Scale

Harmonic Modular Scale Typography

A Sass module to manage your project’s typographic scale using a harmonic progression.

See the explanatory article for details (Japanese).

This documentation refers to the Sass APIs. To use the library with JavaScript read the documentation here.

Install

npm install @shiftbrainstd/harmonic-modular-scale

Usage

Import the module in your Sass file:

@use "@shiftbrainstd/harmonic-modular-scale" as hms;

This module exposes a main function and a mixin:

get-sizes: a function returning a list containing a font-size and an optional line-height.
sizes: a mixin outputting a font-size and line-height. Uses get-sizes internally.

`get-sizes` function

The get-sizes function accepts the following arguments:

argument	type	default	description
`$font-size-degree`	number	0	An integer indicating the font size in the harmonic scale. The returned value will be relative to the base font size.
`$line-height-degree`	number	null	The increments of line height relative to the minimum height that can contain the current font size. It must be an integer.

It will return a list containing the calculated font-size and line-height values.

Example:

$sizes: hms.get-sizes(3, 2);
// $sizes == (calc(1rem * 8 / 5), calc(1em * 45 / 32))

If the first argument passed to the function is a list, its first and second elements will be used as the $font-size-degree and $line-height-degree argument.

$list: (3, 2)
$sizes: hms.get-sizes($list);

// equivalent to hms.get-sizes(3, 2);

Note: when $line-height-degree is null the returned list will contain only the font-size value.

`get-line-height` function

The get-line-height function accepts the following arguments:

argument	type	default	description
`$font-size-degree`	number	0	An integer indicating the font size in the harmonic scale. The returned value will be relative to the base font size.
`$line-height-degree`	number	null	The increments of line height relative to the minimum height that can contain the current font size. It must be an integer.
`$lines`	number	1	The number to multiply the line height for.
`$as-line-height`	boolean	false	If true, returns the value relative to the current font-size. If false, returns the value relative to the root font size.

It will returns line-hieght value related to the $base-font-size. It is helpful when you need to set sizes based on typographic scale.

Input:

.my-selector {
  margin-top: hms.get-line-height(0, 3, 2);
  margin-bottom: hms.get-line-height(0, 3);
}

Output:

.my-selector {
  margin-top: calc(1rem * 56 / 32 * 2);
  margin-bottom: calc(1rem * 56 / 32);
}

`sizes` mixin

The sizes mixin accepts the same arguments as get-sizes and outputs font-size and line-height rules.

Input:

.my-selector {
  @include hms.sizes(3, 2);
}

Output:

.my-selector {
  font-size: calc(1rem * 8 / 5);
  line-height: calc(1em * 45 / 32);
}

Note: when $line-height-degree is null the mixin outputs only the font-size rule.

Setup

While the default settings should fit most scenarios, you can customize the module output by setting the following parameters:

parameter	type	default	description
`$scale-factor`	number	8	the scale factor
`$base-font-size`	number	1rem	base font size (used as the `0` scale value)
`$line-height-unit`	number	0.25rem	the base increment value at which line-height is calculated
`$use-calc`	boolean	true	if `true` returns a CSS calc expression

Example:

@use 'harmonic-modular-scale' as hms with (
  $use-calc: false, // output rem values
  $base-font-size: 1.25rem // set 20px as the base font-size
);

Integration with `polyrhythm-typography`

You can use the get-sizes function as the polyrhythm-typography’s type scaler:

// main.scss
@use "sass:meta";
@use "@shiftbrainstd/harmonic-modular-scale";

@use "@shiftbrainstd/polyrhythm-typography" as pt with (
  $type-scaler: meta.get-function("get-sizes", $module: "harmonic-modular-scale")
);

See the polyrhythm-typography documentation for more details.