@pixelherz/sassbox NPM

sassbox

Sass utils we frequently use in our projects.

Getting Started

Installing

Install using npm:

npm i @pixelherz/sassbox

Usage

Import the toolbox in your project.

@use '@pixelherz/sassbox' [with (<my-config>) ];

Configuration

Typically you'll want to @use a configured @forward of the library. Here's a sample:

// e.g. /styles/_sassbox.scss – configured @forward of the library
@forward '@pixelherz/sassbox' with (
    $font-sizes: (
      's': 16px,
      'm': 24px,
      'l': 36px,
    ),
    $line-heights: (
      's': 20px,
      'm': 30px,
      'l': 45px,
    ),
    // ... custom configuration
  );

// e.g. /component/component.styles.scss
@use '../styles/sassbox';
@include sassbox.normalize();

Have a look at the Docs for a complete list of configuration options.

Documentation

Documentation is available online included in the npm packages (./docs) or can be built from source code.

CSS grid vs. relative grid

Sassbox includes a bunch of mixins and functions that help you build grid layouts. Be aware that the library supports two flavours of layout grids:

Relative grid (rel-grid)
CSS grid (css-grid)

Variable, function and mixin names indicate their purpose (rel-grid for relative grids, css-grid for CSS grid).

Write docs

We use SassDoc for documentation.

Build docs

npm run docs

Upgrade Guide

Upgrade from v0.11.1 to v1.x

1. Import

Update your @forward, @use or @import statement (with clause is optional). Usage of @import is discouraged. We recommend to replace it with a configured @forward. If you prefere, you can also use @use.

// v0.x
@forward '@pixelherz/sassbox/sassbox' [with (...) ];
@use '@pixelherz/sassbox/sassbox' [with (...) ];
@import '@pixelherz/sassbox/sassbox';

Use a single configured @forward to import the library. Then @use this forward. Note that the import path has changed.

// Configured @forward
// e.g. styles/lib/_sassbox.scss
@forward '@pixelherz/sassbox' with (
    $breakpoints: (
      foo: 576px,
      bar: 768px,
    ),
    $layout-max-width: 1360px,
    [...]
  );

// Consume the configured forward in your app/components
// e.g. my-app/my-component/my-component.scss
@use '../../styles/lib/sassbox';

2. Configuration

Move configuration to the with() statement in your configured forward (s. section import).
Remove all prefixes from configuration variables (ph- and mq-).
Remove $ph-font-family--default as it's no longer required.
Rename the following configuration property

v0.x	v1.x
`$grid-offset`	`$layout-offset`

3. Use namespace

// prior 1.x
@include offset-text();
// v1.x
@include sassbox.offset-text();

4. Update deprecations

The names of some variables, functions and mixins have changed. Their signature has not changed. Update these with the new names.

v0.x	v1.x
`un-button()`	`reset-button()`
`pxToRem()`	`px-to-rem()`
`remToPx()`	`rem-to-px()`
`font-size()`	`use-type()`
`inject-css-grid()`	`use-css-grid()`
`grid-offset`	`layout-offset`
`grid-width()`	`get-rel-grid-width()`
`grid-max-offset`	`get-layout-max-offset()`
`apply-grid-offset()`	`use-layout-offset()`

5. Normalize

In 0.x versions, normalize was applied by default. With 1.x, normalize has moved to a mixin to give you more control. When upgrading from 0.x you have to apply sassbox.normalize() manually which is typically done in your root stylesheet.

// e.g. styles.scss
@use './styles/lib/sassbox';
@include sassbox.normalize();

6. Replace `sass-mq` with `sassbox.mq`

Remove sass-mq as it's now part of this library.

// Remove imports
@import '~sass-mq/mq'; // <-- delete

// prior v1.x
@include mq($from: 'my-breakpoint') {
}
// v1.x
@include sassbox.mq($from: 'my-breakpoint') {
}