@littlemissrobot/sass-spacing

Little Miss Robot - Sass spacing

This repository contains logic and functionality to define and insert consistent spacing in the form of layout and typography.

This package does not contain or generate any CSS. It simply provides a system with @function and @mixin statement to manage spacing. It is part of the @littlemissrobot/sass-system package.

IMPORTANT

This library makes use of Dart Sass, which is the primary implementation of Sass. Make sure that your Sass compiler is making use of Dart Sass.

This means that if you are using a task manager (like Gulp) or a module bundler (like Webpack), you must indicate which compiler it should use for compiling Sass to CSS.

Furthermore, this library makes heavy use of Sass modules: @use. Therefore we recommend importing and using this library with the @use statement.

Install

# As a dependency
$ npm install @littlemissrobot/sass-spacing
# As a dev-dependency
$ npm install --save-dev @littlemissrobot/sass-spacing

Usage

1. Import the library from the node_modules folder:

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _spacing;

1. Pass the configuration:

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _spacing with (
    $baseline: 8px,
    $baseline-typo: 4px,
    $system: "linear",
    $base-font-size: 16px,
    $base-line-height: 1.5rem,
    $ratio: "minor-second"
);

1. Functionality of the library is now available through the namespace _spacing.
2. After configuration, the library can be used throughout separate files with partials:

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing/layout" as _spacing-layout;
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing/typography" as _spacing-typography;

Concept

The main focus of this library is to create consistent spacing and visually clear verticaly rythm.

The first part of this library is spacing. This is one of the biggest influences in creating a distinguisable brand. Not providing a consistent unit of measurement can lead to layout inconsistencies between pages or other projects.

We recommend using multiples of 8, why? Because 8 is divisble by 2 and 4 and becomes important when displays multiply pixel sizes due to higher resolutions. For example: a resolution of 1.5 would multiply 5px baseline and result in half a pixel offset, which might result in an edge that appears blurred. Half pixels don't happen on a 8px baseline grid.

The second part of this library is typography. Spacing and typography influence each other and should be used together. Mainly the line height place a big part in the spacing system. This is due to the fact that line height determines how much spacing there is between each line of typography and should be consistent with the spacing baseline.

Configuration

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _spacing with (
    $baseline: 8px,
    $baseline-typo: 4px,
    $system: "linear",
    $base-font-size: 16px,
    $base-line-height: 1.5rem,
    $ratio: "minor-second"
);

$baseline

• unit: px
• default: 8px
• required: true

The $baseline is the spacing baseline for determining a scale. We recommend using 8px, but if you require a smaller value, we suggest using 4px.

$baseline-typo

• unit: px
• default: 4px
• required: false

The $baseline-typo is an alternative spacing baseline which should only be used for typography. This is done to lessen the gap for line-heights and create more variants for typography. This can also be used to create spacing between smaller typographic components. But keep in mind, that the $baseline should be divisble by the $baseline-typo.

$system

• default: "linear"
• required: false

The $system variable determines how the spacing baseline should be scaled in steps. By passing a predefined string, you tell the library how it should scale the $baseline. The predefined systems are:

• linear

Scales the baseline on a linear scale where each step is a multiple of the baseline.

$baseline: 8px;
$system: "linear";

// 8, 16, 24, 32, 40, 48

• fibonacci

Scale the baseline where each number is the sum of the two preceding ones.

$baseline: 8px;
$system: "fibonacci";

// 8, 16, 24, 40, 64, 104

• geometric-progression

Scale the baseline where each number is the power and the step its exponent. When using this system, we recommend using 2px because it will create more possibilities.

$baseline: 2px;
$system: "geometric-progression";

// 2, 4, 8, 16, 32, 64, 128

• custom

Create your own scale by passing a list of numbers to multiply the baseline with.

$baseline: 16px;
$system: (0.125, 0.25, 0.5, 0.75, 1, 1.5, 2, 2.5, 3)

// 2, 4, 8, 12, 16, 24, 32, 40, 48

$base-font-size

• unit: px
• default: 16px
• required: true

The $base-font-size is the font-size placed on the root element. This is used the create different steps based on a ratio and determine the ratio in which the line-heights should get automagically calculated.

$base-line-height

• unit: rem
• default: 1.5rem
• required: true

The $base-line-height is the line-height placed on the root element or on the base typography element: <p>. This should be a step from the spacing baseline to create a correct vertical rythm.

$ratio

• default: false
• required: false

The $ratio is an optional number or a predefined string that can be passed to calculate each step for the font-size. To see these in action you can test them out in the modular-scale tool.

The predefined strings and its number are based on the modular scale:

• minor-second: 1.067,
• major-second: 1.125,
• minor-third: 1.2,
• major-third: 1.25,
• perfect-fourth: 1.333,
• augmented-fourth: 1.414,
• perfect-fifth: 1.5,
• minor-sixth: 1.6,
• golden: 1.618,
• major-sixth: 1.667,
• minor-seventh: 1.778,
• major-seventh: 1.875,
• octave: 2,
• major-tenth: 2.5,
• major-eleventh: 2.667,
• major-twelfth: 3,
• double-octave: 4

Functions

rem($value)

Convert a pixel value and to a rem value. This conversion based on the $base-font-size determined in the configuration.

Parameters:

• $value: The pixel value to convert

@use "@littlemissrobot/sass-spacing" as _spacing with (
    $base-font-size: 16px
);

_spacing.rem(16px); // 1rem
_spacing.rem(32px); // 2rem

Layout

These are namespace with _spacing-layout:

@use "@littlemissrobot/sass-spacing" as _spacing;

_spacing.layout_step(1);

Or can be included through the partial:

@use "@littlemissrobot/sass-spacing/layout" as _spacing-layout;

_spacing-layout.step(1);

Functions

step($value, $base, $result-unit)

Calculate a step of the $baseline, based on the $system. By default this will return a number in rem.

Parameters:

• $value: The step of the baseline
• $base (optional): The baseline to use, this should either be the $baseline or the $baseline-typo.
• $result-unit: The unit in which to return the value in. This can either be px or rem. By default this would be rem and we recommend using rem.

@use "@littlemissrobot/sass-spacing" as _spacing with (
    $baseline: 8px,
    $baseline-typo: 4px,
    $system: "linear",
    $base-font-size: 16px,
);

@use "@littlemissrobot/sass-spacing/layout" as _spacing-layout;

_spacing-layout.step(1); // 0.5rem
_spacing-layout.step(2); // 1rem
_spacing-layout.step(1, _spacing.$baseline-typo); // 0.25rem
_spacing-layout.step(2, _spacing.$baseline-typo); // 0.5rem
_spacing-layout.step(1, _spacing.$baseline, "px"); // 8px
_spacing-layout.step(2, _spacing.$baseline, "px"); // 16px

snap($value, $base)

Calculate the closest step to the passed value, based on the $baseline and $system. Returns a number in the same unit as the passed value.

Parameters:

• $value: The number in pixels or rem used for snapping to the grid.
• $base (optional): The baseline to use, this should either be the $baseline or the $baseline-typo.

@use "@littlemissrobot/sass-spacing" as _spacing with (
    $baseline: 8px,
    $baseline-typo: 4px,
    $system: "linear",
    $base-font-size: 16px,
);

@use "@littlemissrobot/sass-spacing/layout" as _spacing-layout;

_spacing-layout.snap(20px); // 24px
_spacing-layout.step(19px); // 16px
_spacing-layout.step(21px); // 24px
_spacing-layout.step(32px); // 32px
_spacing-layout.step(31px); // 32px
_spacing-layout.step(1rem); // 1rem
_spacing-layout.step(1.2rem); // 1rem
_spacing-layout.step(1.3rem); // 1.5rem
_spacing-layout.step(12px, _spacing.$baseline-typo); // 12px
_spacing-layout.step(14px, _spacing.$baseline-typo); // 16px
_spacing-layout.step(13px, _spacing.$baseline-typo); // 12px
_spacing-layout.step(40px, _spacing.$baseline-typo); // 40px

Typography

These are namespace with typography_:

@use "@littlemissrobot/sass-spacing" as _spacing;

_spacing.typography_ratio(1);

Or can be included through the partial:

@use "@littlemissrobot/sass-spacing/typography" as _spacing-typography;

_spacing-typography.ratio(1);

Functions

ratio($value, $result-unit)

Used to calculate a step of a font-size based on the $base-font-size and $ratio in the configuration.

Parameters:

• $value: The step of the base-font-size
• $result-unit: The unit in which to return the value in. This can either be px or rem. By default this would be rem and we recommend using rem.

@use "@littlemissrobot/sass-spacing" as _spacing with (
	$base-font-size: 16px,
	$ratio: "minor-second",
);

@use "@littlemissrobot/sass-spacing/typography" as _spacing-typography;

_spacing-typography.ratio(1); // 1rem
_spacing-typography.ratio(1, "px"); // 16px
_spacing-typography.ratio(5); // 1.296rem
_spacing-typography.ratio(5, "px"); // 20.739px
_spacing-typography.ratio(-5); // 0.723em
_spacing-typography.ratio(-5, "px"); // 11.569px

line-height($value, $result-unit)

Used to calculate the line-height for a font-size based on the ratio between the $base-font-size and $base-line-height and eventually snap it to the closest step of the $baseline-grid and its $system.

Parameters:

• $font-size: The font-size to calculate the line-height for.
• $ratio (optional): The ratio to calculate the line-height.

@use "@littlemissrobot/sass-spacing" as _spacing with (
	$baseline: 8px,
	$system: "linear",
	$base-font-size: 16px,
	$base-line-height: 1.5rem,
	$ratio: "minor-second",
);

@use "@littlemissrobot/sass-spacing/typography" as _spacing-typography;

_spacing-typography.line-height(16px); // 24px
_spacing-typography.line-height(32px); // 48px
_spacing-typography.line-height(_spacing-typography.ratio(5)); // 2rem
_spacing-typography.line-height(32px, 1.2); // 2.5rem

Mixins

Calculate the root font-size, based on the base font-size of the system and the default browser font-size. Return a font-size in percentage. Should always be placed on the root element!

Parameters:

@use "@littlemissrobot/sass-spacing" as _spacing with (
	$base-font-size: 16px,
);

@use "@littlemissrobot/sass-spacing/typography" as _spacing-typography;

:root {
	@include _spacing-typography.root(); // font-size: 100%;
}

@use "@littlemissrobot/sass-spacing" as _spacing with (
	$base-font-size: 10px,
);

@use "@littlemissrobot/sass-spacing/typography" as _spacing-typography;

:root {
	@include _spacing-typography.root(); // font-size: 62.5%;
}