@littlemissrobot/sass-typography

Little Miss Robot - Sass typography

This package contains logic and functionality to define a reusable typographic configuration.

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

IMPORTANT

• Make use of Dart Sass:

  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.

• Generate only what you need:

  This library generates classes based on your configuration. The larger the configuration, the more css, the larger the CSS file. DO NOT enable all the config options, but only the ones you actually use and need!

Install

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

Usage

• Import the library from the node_modules folder:

@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-typography" as _typography;

• Pass the configuration to the dependencies and the library:

// Dependency
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-breakpoints" with (
	$viewports: (
		"0": 0,
		"3": 320px,
		"4": 480px,
		"7": 720px,
		"9": 992px,
		"12": 1200px
	)
);

// Library
@use "YOUR-PATH-TO-NODE_MODULES/@littlemissrobot/sass-typography" as _typography with (
	$styles: (
		h1: (
			font-size: 24px,
			line-height: 1.5
		),
		p: (
			font-size: 16px,
			line-height: 1.5
		)
	)
);

• Functionality of the library is now available through the namespace _typography.

Configuration

@use " @littlemissrobot/sass-typography" as _typography with (
	$fonts: (),
	$variable-fonts: (),
	$styles: (
		h1: (
			font-size: 24px,
			line-height: 1.5,
			"7": (
				font-size: 32px
			)
		),
		p: (
			base: (
				font-size: 16px,
				line-height: 1.5,
			),
			variants: (
				small: (
					font-size: 14px,
				),
				large: (
					font-size: 18px,
				)
			)
		)
	);

fonts

The $fonts is a sass list where each item in that list is a list of parameters that are passed to a mixin that generates a font-face to load the font. If you want to disable the font-load on import of the library, you can use:

$load-fonts: false;

and load them manually with the load-font mixin from the library.

The parameters passed, in order, in the list are:

• font-name
• location
• font-weight
• font-style
• font-swap

$fonts: (
  ("Lato", "/assets/fonts/Lato-Black", 900, normal),
  ("Lato", "/assets/fonts/Lato-Bold", 700, normal),
  ("Lato", "/assets/fonts/Lato-Regular", 400, normal)
);

variable-fonts

The $variable-fonts is a sass list where each item in that list is a list of parameters that are passed to a mixin that generates a font-face to load the font. If you want to disable the font-load on import of the library, you can use:

$load-variable-fonts: false;

and load them manually with the load mixin from the library.

The parameters passed, in order, in the list are:

• font-name
• location
• font-weight
• font-style
• font-swap

$variable-fonts: (
  ("Lato", "/assets/fonts/Lato-Black", 900, normal),
  ("Lato", "/assets/fonts/Lato-Bold", 700, normal),
  ("Lato", "/assets/fonts/Lato-Regular", 400, normal)
);

styles

The $styles is a sass map where every key is the name of a font-style. A font-style is a group of typographic CSS properties. Each value that is placed in px is automatically converted to rem. For example:

$styles: (
  h1: (
    font-size: 24px,
    line-height: 1.5,
  ),
);

In this style, breakpoints can be added as well to create responsive tyopgraphy. These breakpoints carry the names defined with the dependency @littlemissrobot/sass-breakpoints. For example:

@use "@littlemissrobot/sass-breakpoints" with (
	$viewports: (
		"7": 720px
	)
);

$styles: (
  h1: (
    font-size: 24px,
    line-height: 1.5,
    "7": (
      font-size: 32px,
    ),
  ),
);

This map structure can be expanded more to support a more complex configuration:

@use "@littlemissrobot/sass-breakpoints" with (
	$viewports: (
		"7": 720px
	)
);

$styles: (
  h1: (
    base: (
      font-size: 24px,
      line-height: 1.5,
      "7": (
        font-size: 32px,
      ),
    ),
    small: (
      font-size: 20px,
      line-height: 1.5,
      "7": (
        font-size: 28px,
      ),
    ),
  ),
);

If you are in need of some modifiers or variants of a certain font-style. Make use of the keys base and variants:

• base: The original group of properties creating the font-style
• variants: Modifiers or variable styls to adjust the base typography. These get merged with bae to create the respective style. Each variant must have a unique key identifying it.

@use "@littlemissrobot/sass-breakpoints" with (
	$viewports: (
		"7": 720px
	)
);

$styles: (
  h1: (
    base: (
      font-size: 24px,
      line-height: 1.5,
    ),
    variants: (
      small: (
        font-size: 18px,
      ),
      bold: (
        font-weight: bold,
      ),
    ),
  ),
);

Mixins

set($path)

Retrieve the font-style from the configuration based on the path of keys within the $styles configuration map. The path is a string where each key is separated by a space. If you need a specific variant within the variants key of a font-style, simply place it within the path and the function will automatically select it and combine it with the base of the parent font style.

Parameters:

• $path: The path of keys that contain the desired font-style. If the last character in the path is "!", then an !important tag is added after every property.

@use "@littlemissrobot/sass-typography" as _typography with (
	$styles: (
		h1: (
			base: (
				font-size: 24px,
				line-height: 1.5,
				"7": (
					font-size: 32px
				)
			),
			variants: (
				small: (
					font-size: 20px,
					line-height: 1.5,
					"7": (
						font-size: 28px
					)
				)
			)
		),
	)
);

h1 {
  @include _typography.set(h1);
  @include _typography.set(h1, "!");
  @include _typography.set(h1, small);
}

load-font($name, $url, $font-weight, $font-style, $font-display)

Load a custom font using @font-face. If the $fonts variable is passed, the fonts will be loaded automatically using this mixin.

Parameters:

• $name: The font-family name
• $url: the url to the location of the font
• $font-weight: the weight of the font
• $font-style: the style of the font
• $font-display: the way the font should be displayed when loaded

@use "@littlemissrobot/sass-typography" as _typography with (
	$fonts: (
		("Lato", "/assets/fonts/Lato-Bold", 700, normal),
		("Lato", "/assets/fonts/Lato-Regular", 400, normal),
	),
);

load-variable-font($name, $url, $font-weight, $font-style, $font-display)

Load a custom variable font using @font-face. If the $variable-fonts variable is passed, the fonts will be loaded automatically using this mixin.

Parameters:

• $name: The font-family name
• $url: the url to the location of the font
• $font-weight: the weight of the font
• $font-style: the style of the font
• $font-display: the way the font should be displayed when loaded

@use "@littlemissrobot/sass-typography" as _typography with (
	$variable-fonts: (
		("Lato", "/assets/fonts/Lato-Bold", 100 900, normal),
	),
);