Polyrhythm Typography Module

Usage no npm install needed!

<script type="module">
  import shiftbrainstdPolyrhythmTypography from 'https://cdn.skypack.dev/@shiftbrainstd/polyrhythm-typography';


Polyrhythm Typography

Version Documentation Maintenance

Polyrhythm Typography Module

A library to create and manage beautiful and consistent typographic rules for your project. Distributes as a Sass and JavaScript module

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


npm install @shiftbrainstd/polyrhythm-typography



First of all setup the project’s typefaces as a map where each key identifies the typeface and its value has the following properties:

  • family {list} - List of font family strings (required)
  • style {string} - font-style value
  • weight {string} - font-weight value


$typefaces: (
  "sans": (
    "family": ("Helvetica Neue", "Arial", sans-serif),
    "style": normal,
    "weight": 400,
  // ...,

Then define some CSS breakpoints. polyrhythm-typography comes with the following values:

$mq-breakpoints: (
  "xs": 0,
  "sm": 36em, // 576px
  "md": 48em, // 768px
  "lg": 64em, // 1024px
  "xl": 80em, // 1280px


polyrhythm-typography uses Sass modules. To import and setup it use the following syntax:

@use 'polyrhythm-typography' as pt with (
  $typefaces: $typefaces,
  $mq-breakpoints: $mq-breakpoints

.component__title {
  @include pt.textstyle(/* configuration */);

Using textstyle

The module exposes a textstyle mixin accepting a configuration map with the following properties:

name type description
typeface string Typeface id as defined in $typefaces
sizes list A list containing a scalar value for the font size (-2 to 4) and its line-height (0 to 4)
case string Font case. Supported values are "all-lowercase", "all-caps", "small-caps" and "all-small-caps"
tracking number Letter spacing multiplier
breakpoints map Breakpoint modifiers settings. (see below)


$textstyle-body: (
  typeface: "sans",
  sizes: (0, 3),
  tracking: 50,

.component__body {
  @include pt.textstyle($textstyle-body);

Setup size scales

The default values provided by the library should work pretty fine to enforce a consistent modular scale system across the project.

Anyway, you can can provide your own customized values in the module configuration:

$font-sizes: (
  2: 2rem,
  1: 1.5rem,
  0: 1rem,
  -1: 0.5rem,

/// Default line heights
/// @type Map
$line-heights: (
  4: 2,
  3: 1.75,
  2: 1.5,
  1: 1.25,
  0: 1,

@use "polyrhythm-typography" as pt with (
  // ...
  $font-sizes: $font-sizes,
  $line-heights: $line-heights,

$textstyle-body: (
  sizes: (1, 3)

.component__body {
  @include pt.textstyle($textstyle-body);


  font-size: 1.5rem;
  line-height: 1.75rem;


Use a custom type scaler calculator

By default polyrhythm-typography uses an internal function (aka type scaler) that matches numeric size scales with the corresponding values on the $font-sizes and $line-heights maps.

If you need more control over the calculation process, you can provide your custom type scaler function.

A type scaler function receives a list with two numeric values (font-size and line-height) and must return a list with valid CSS font-size and line-height (optional) values.

Here is an example:

// _helpers.scss
@use "sass:list";

// $input: (1, 3)
@function my-scaler($input) {
  $sizes: ();
  @each $i in $input {
    $sizes: list.append($sizes, $i * 10px);
  @return $sizes; // (10px, 30px)

To instruct polyrhythm-typography to use your custom type scaler pass it as the module configuration’s $type-scaler option:

// main.scss
@use "sass:meta";
@use "helpers";

@use "polyrhythm-typography" as pt with (
  //... other configurations
  $type-scaler: meta.get-function("my-scaler", $module: "helpers")

Note: $font-sizes and $line-heights configuration options will not have any effect when using a custom type scaler function.

Breakpoint modifiers

To override certain configuration values for a given breakpoint set the breakpoints property:

$textstyle-body: (
  typeface: "sans",
  sizes: (0, 3),
  tracking: 50,
  breakpoints: (
    md: (
      // change the font size at md
      sizes: (2, 3)

Run demo

npm start

Run tests

npm run test


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

🤝 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