@littlemissrobot/sass-spacing

Little Miss Robot - Sass spacing

This repository contains logic and functionality to define and insert consistent spacing throughout the UI.

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,
    $base-font-size: 16px
);

1. Functionality of the library is now available through the namespace _spacing.

Concept

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

Spacing 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.

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. We provide no functions to control this because line height really depends on the font-family used. We don't want to enforce these baseline rules onto the line-height, but we recommend to respect them.

Configuration

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _spacing with (
    $baseline: 8px,
    $base-font-size: 16px,
);

$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.

$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.

Functions

rem($value, $is-multiple-of-baseline)

Convert a pixel value and to a rem value. This conversion based on the $base-font-size determined in the configuration. This makes sure that the converted rem value is a multiple of the defined $baseline in the config.

Parameters:

• $value: The pixel value to convert
• $is-multiple-of-baseline: Default to true to make sure every value is aligned to the $baseline, pass false to avoid have this validation.

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

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

step($value, $result-unit)

Calculate a step of the $baseline, calculated in a linear pattern. By default this will return a number in rem.

Parameters:

• $value: The step of the baseline
• $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,
    $base-font-size: 16px,
);

_spacing.step(1); // 0.5rem
_spacing.step(2); // 1rem
_spacing.step(1, "px"); // 8px
_spacing.step(2, "px"); // 16px

snap($value)

Calculate the closest step to the passed value, based on the $baseline. 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.

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

_spacing.snap(20px); // 24px
_spacing.snap(19px); // 16px
_spacing.snap(21px); // 24px
_spacing.snap(32px); // 32px
_spacing.snap(31px); // 32px
_spacing.snap(1rem); // 1rem
_spacing.snap(1.2rem); // 1rem
_spacing.snap(1.3rem); // 1.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,
);

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

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

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