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
$ npm install @littlemissrobot/sass-spacing
$ npm install --save-dev @littlemissrobot/sass-spacing
Usage
- Import the library from the node_modules folder:
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _s;
- Pass the configuration:
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing" as _s with (
$baseline: 8px,
$baseline-typo: 4px,
$system: "linear",
$base-font-size: 16px,
$base-line-height: 1.5rem,
$ratio: "minor-second"
);
- Functionality of the library is now available through the namespace
_s
. - After configuration, the library can be used throughout separate files with
partials:
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing/layout" as _sl;
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-spacing/typography" as _st;
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 _s 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:
Scales the baseline on a linear scale where each step is a multiple of the
baseline.
$baseline: 8px;
$system: "linear";
Scale the baseline where each number is the sum of the two preceding ones.
$baseline: 8px;
$system: "fibonacci";
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";
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 _s with (
$base-font-size: 16px
);
_s.rem(16px);
_s.rem(32px);
Layout
These are namespace with l_:
@use "@littlemissrobot/sass-spacing" as _s;
_s.l_step(1);
Or can be included through the partial:
@use "@littlemissrobot/sass-spacing/layout" as _sl;
_sl.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 _s with (
$baseline: 8px,
$baseline-typo: 4px,
$system: "linear",
$base-font-size: 16px,
);
@use "@littlemissrobot/sass-spacing/layout" as _sl;
_sl.step(1);
_sl.step(2);
_sl.step(1, _s.$baseline-typo);
_sl.step(2, _s.$baseline-typo);
_sl.step(1, _s.$baseline, "px");
_sl.step(2, _s.$baseline, "px");
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 _s with (
$baseline: 8px,
$baseline-typo: 4px,
$system: "linear",
$base-font-size: 16px,
);
@use "@littlemissrobot/sass-spacing/layout" as _sl;
_sl.snap(20px);
_sl.step(19px);
_sl.step(21px);
_sl.step(32px);
_sl.step(31px);
_sl.step(1rem);
_sl.step(1.2rem);
_sl.step(1.3rem);
_sl.step(12px, _s.$baseline-typo);
_sl.step(14px, _s.$baseline-typo);
_sl.step(13px, _s.$baseline-typo);
_sl.step(40px, _s.$baseline-typo);
Typography
These are namespace with t_:
@use "@littlemissrobot/sass-spacing" as _s;
_s.t_ratio(1);
Or can be included through the partial:
@use "@littlemissrobot/sass-spacing/typography" as _st;
_st.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 _s with (
$base-font-size: 16px,
$ratio: "minor-second",
);
@use "@littlemissrobot/sass-spacing/typography" as _st;
_st.ratio(1);
_st.ratio(1, "px");
_st.ratio(5);
_st.ratio(5, "px");
_st.ratio(-5);
_st.ratio(-5, "px");
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 _s with (
$baseline: 8px,
$system: "linear",
$base-font-size: 16px,
$base-line-height: 1.5rem,
$ratio: "minor-second",
);
@use "@littlemissrobot/sass-spacing/typography" as _st;
_st.line-height(16px);
_st.line-height(32px);
_st.line-height(_st.ratio(5));
_st.line-height(32px, 1.2);
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 _s with (
$base-font-size: 16px,
);
@use "@littlemissrobot/sass-spacing/typography" as _st;
:root {
@include st.root();
}
@use "@littlemissrobot/sass-spacing" as _s with (
$base-font-size: 10px,
);
@use "@littlemissrobot/sass-spacing/typography" as _st;
:root {
@include st.root();
}