Table of contents

• Introduction
• Table of Contents
• Installation
• How to use
  • Full library
  • Individual modules
• Examples
  • Icons
  • Buttons and tokens
  • Basic navigation containers
  • Simple columns
  • Tooltips
  • Fluid pictures and images
  • Normalizing
• Notes
  • @use syntax
  • Resetting configs
  • Changing configs
  • SASS maps
• Comments

Installation

Run to install:

npm i @squirrel-forge/sass-util

How to use

Make use of your IDE's autocompletion and checkout the example implementation and the generated output.

Note that the @use syntax works differently than the classic @import, check the use syntax notes for relevant details and or refer to the official sass docs.

Full library import

Import the library with custom namespace:

@use '~@squirrel-forge/sass-util' as util;

Import the library with custom variable settings:

@use '~@squirrel-forge/sass-util' as util with (
    $config-value: 'string',
);

When using the full package, make use of the namespacing to select from the individual submodules.

@include util.media-config((
  custom-breakpoint: 'screen and (max-width: 10rem)',
));
@include util.media-query('custom-breakpoint') {
  // @content
}

Not recommended, but possible: If you wish to use modules more than once and require configuration changes, then you need to modify the namespaces variables directly, but keep in mind that the values change permanently even for other contexts and need to be reset manually, since modules are only loaded once.

Loading individual modules

Import a module directly:

@use '~@squirrel-forge/sass-util/media';

When using submodules directly, namespacing is shorter, without the parent prefixes, this way you have granular control over which modules to use.

@include media.config((
  custom-breakpoint: 'screen and (max-width: 10rem)',
));
@include media.query('custom-breakpoint') {
  // @content
}

Examples

Following, some examples, none of these claim to be complete in the display of their abilities and shortcomings.

Icons

Following all available CSS styled icons.

Actions and status:

Arrows and rotation:

Player controls and flip axis:

Special, custom image and font icons:

Button and token variants

Basic navigation containers

Columns

Columns can be used with any content and simple responsive options.

Columns can also be applied to simple navigation containers.

Tooltips

CSS based tooltips that can be combined with almost anything.

Use them to describeDescribe your link here. inline links in differentDescribe your link here. ways.

Or use them for some buttons to describe their actions.

Fluid picture and images

Normalizing

Text normalize adds normalized headline and paragraph spacing.

This provides simplified contextualized spacing rule possibilities, especially when combined with other elements such as lists or images.

• var(--ui-text-normalize-headline-margin)
• var(--ui-text-normalize-paragraph-margin)
• var(--ui-text-normalize-size-adjust)
• var(--ui-list-margin)
• var(--ui-list-padding)
• var(--ui-list-indent-width)
• var(--ui-list-item-margin)
• var(--ui-list-item-after-margin)

Elements can be evenly spaced and the list for example is separated from the paragraphs.

Allowing for many types to be combined and controlled via a few css vars.

Without influencing defaults or specifics for other contexts.

Notes

Following some notes on sass behaviours directly relevant to using the library and modules.

@use syntax

When loading via the @use syntax versus the classic @import, there are a few things to keep in mind.

Using the with keyword to set any configuration variables can only be done the first time a module is loaded with @use, any attempt to do it differently will produce an error.

Resetting configs

With any modules that allow extending, config mixins can be reset the maps index to an empty list by passing an explicit null value, as following example demonstrates:

To clear all previously defined decals:

@include util.images-decals-config(null);

To add a fresh/new data set:

@include util.images-decals-config((
  example: (
    before: true,
    after: true,
    width: 1,
    height: 1,
    url: 'example.jpg'
  ),
));

Changing configuration for multiple usages

If you wish to change configuration variables in specific situations, note that anything that module will do afterwards will use the new value even when loaded in a different context within the same compile tree.

You can set values from the given use context as following:

@use '~@squirrel-forge/sass-util' as util with (
  $images-decals-props: 'decal-',
);

This renders the initial configuration:

:root { @include util.images-decals-properties; }

Then we change a config value and the output changes:

util.$images-decals-props: 'foo-';
.context { @include util.images-decals-properties; }

If we use this module again later or in another file loaded after the above code, then we need to reset the value if we want the initial setting:

util.$images-decals-props: 'decal-';

Sass maps

Inside map declarations to use comma or space separated, list values, wrap them in braces to make them an explicit list value, for example for font-family declarations:

$map: (
  key: (
    font-family: ("Oxygen", sans-serif),
  ),
);

Or you can escape the value as following:

$map: (
  key: (
    font-family: #{"Oxygen", sans-serif},
  ),
);

Comments

For further detailed documentation, please check the sass sources on github or directly install the module from npm.