@shiftbrainstd/harmonic-modular-scale

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
• Usage
  • get-sizes function
  • get-line-height function
  • sizes mixin
  • Setup
  • Integration with polyrhythm-typography
• Run demo
• Run tests
• Author
• 🤝 Contributing
• 📝 License

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.

Run demo

npm start

Run tests

npm run test

Author

👤 Shiftbrain Standard Design Unit (https://standard.shiftbrain.com/)

• Twitter: @ShiftbrainStd
• Github: @ShiftbrainStd

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.

📝 License

Copyright © 2019 Shiftbrain Standard Design Unit.
This project is MIT licensed.

---

This README was generated with ❤️ by readme-md-generator