jigsass-utils-spacing

Spacing Utils

Introduction

A collection of dynamically generated spacing utility classes.

Class names follow the Emmet abbreviation syntax, with colons (':') replaced by two dashes (--) to follow BEM naming conventions.

Available classes

.u-m--<amount>: margin
.u-mt--<amount>: margin top
.u-me--<amount>: margin end (right in LTR, left in RTL)
.u-mb--<amount>: margin bottom
.u-ms--<amount>: margin start (left in LTR, right in RTL)
.u-mh--<amount>: horizontal margins (left and right)
.u-mv--<amount>: vertical margins (top and bottom)
.u-mr--<amount>: margin right
.u-ml--<amount>: margin left
.u-p--<amount>: padding
.u-pt--<amount>: padding top
.u-pe--<amount>: padding end (right in LTR, left in RTL)
.u-pb--<amount>: padding bottom
.u-ps--<amount>: padding start (left in LTR, right in RTL)
.u-ph--<amount>: horizontal padding
.u-pv--<amount>: vertical padding
.u-pr--<amount>: padding right
.u-pl--<amount>: padding left

Where <amount> can be either a unitless number representing a number of typographic rhythm units as defined in $jigsass-sizes a percentage, or a length specified in pixels.

JigSass Spacing supports negative margins, using min-<number> modifiers (e.g., h-mt--min-4), as well as auto margins (e.g., h-m--auto).

Additionally, JigSass Spacing provide the autospace (.u-autospace) set of helper classes for intelligently spacing an element's direct descendants:

.u-autospace--<amount>
.u-autospace--<amount>(<n>up)

.u-autospace--<amount> classes will give all but the first direct descendant of the element carrying the class a margin-top of <amount>.

Similarly, .u-autospace--<amount>(<n>up) classes will give all but the n direct descendants of the element carrying the class a margin-top of <amount>, allowing for intelligent spacing of grid-like layouts.

For an in-depth presentation of the technique, see this article by Heydon Pickering.

Installation

Using npm:

npm i -S jigsass-utils-spacing

Usage

Import JigSass Utils Spacing into your main scss file near its very end, together with all other utilities (utilities should always be the last to be imported).

@import 'path/to/jigsass-utils-spacing/scss/index';

Like all other JigSass Utils, JigSass Spacing does not automatically generate any CSS when imported. You would need to explicitly indicate that each individual spacing class should actually be generated in each component or object it is used in (clarification: This will include style declarations inside .foo and .bar):

// _c.foo.scss
.foo {
  @include jigsass-util(u-mt, $modifier: 6px); // <-- margin-top: 6px

  ...
}

// _c.bar.scss
.bar {
  @include jigsass-util(u-pb, $modifier: 12px);  // <-- padding-bottom: 12px
  @include jigsass-util(u-m, $modifier: 0, $from: large); // <-- margin: 0 from large bp and on.

  ...
}

Doing so helps us a great deal with portability, as no matter where we import component or object partials, the correct utility classes will be generated. Think of it as a poor man's dependency management.

Developer communication is also assisted by including "dependencies" wherever they are required, as anyone going through a partial, can easily understand how it should be marked up with just a glance.

As far as bloat goes, just don't worry about it - the actual styles will only be generated once, at the location in the cascade where the Jigsass Spacing partial was imported into the main file.

JigSass Spacing classes are responsive-enabled, using JigSass MQ and the breakpoints defined in the $jigsass-breakpoints variable.

Based on the breakpoint arguments passed to jigsass-util when including a Spacing class, responsive modifiers are generated according to the following logic:

.u-m--<modifier>[-[-from-<breakpoint-name>][-until-<breakpoint-name>][-misc-<breakpoint-name>]]

So, assuming the medium, large and landscape breakpoints are defined in $jigsass-breakpoints as 600px, 1024px and (orientation: landscape) respectively,

@include jigsass-util(u-m, $modifier: 2);

will generate the .u-m--2 class, which is not limited to any media-query.

@include jigsass-util(u-p, $modifier: 4, $until: medium);

will generate the .u-p--4--until-medium class, which will be in effect at (max-width: 37.49em) and will override styles in the default class until that point.

@include jigsass-util(u-mb, $modifier: 12px, $from: large, $misc: landscape);

will generate the .u-mb--12px--from-large-when-landscape class, which will go into effect at (min-width: 64em) and (orientation: landscape) and will override styles in the default class under these conditions.

License: MIT

u-autospace--1

A utility class to intelligently space the direct descendants of an element.

Include with:

@include jigsass-util(u-autospace, $modifier: 1 [, $from, $until, $misc]);

Example

<div class='fpo--b  u-autospace--1'>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>









</div>

u-autospace--4

A utility class to intelligently space the direct descendants of an element.

Include with:

@include jigsass-util(u-autospace, $modifier: 4 [, $from, $until, $misc]);

Example

<div class='fpo--b  u-autospace--4'>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>









</div>

u-autospace--2(3up)

A utility class to intelligently space the direct descendants of an element.

Include with:

@include jigsass-util(u-autospace, $modifier: 2(3up) [, $from, $until, $misc]);

Example

<div class='fpo--b fpo--autospace3 u-autospace--2(3up)'>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>









</div>

u-autospace--4(2up)

A utility class to intelligently space the direct descendants of an element.

Include with:

@include jigsass-util(u-autospace, $modifier: 4(2up) [, $from, $until, $misc]);

Example

<div class='fpo--b fpo--autospace2 u-autospace--4(2up)'>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>
  <div><div class='fpo'></div></div>









</div>

u-m--auto

A utility class to set the margin on all sides of an element.

Include with:

@include jigsass-util(u-m, $modifier: auto [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-m--auto'>
    This element has auto margin on all sides.
  </div>
</div>

u-m--1

A utility class to set the margin on all sides of an element.

Include with:

@include jigsass-util(u-m, $modifier: 1 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-m--1'>
    This element has a 1 rhythm units margin on all sides.
  </div>
</div>

u-m--2

A utility class to set the margin on all sides of an element.

Include with:

@include jigsass-util(u-m, $modifier: 2 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-m--2'>
    This element has a 2 rhythm units margin on all sides.
  </div>
</div>

u-m--3

A utility class to set the margin on all sides of an element.

Include with:

@include jigsass-util(u-m, $modifier: 3 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-m--3'>
    This element has a 3 rhythm units margin on all sides.
  </div>
</div>

u-m--4

A utility class to set the margin on all sides of an element.

Include with:

@include jigsass-util(u-m, $modifier: 4 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-m--4'>
    This element has a 4 rhythm units margin on all sides.
  </div>
</div>

u-mt--auto

A utility class to set the top margin of an element.

Include with:

@include jigsass-util(u-mt, $modifier: auto [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-mt--auto'>
    This element has auto top margin.
  </div>
</div>

u-mt--1

A utility class to set the top margin of an element.

Include with:

@include jigsass-util(u-mt, $modifier: 1 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-mt--1'>
    This element has a 1 rhythm units top margin.
  </div>
</div>

u-mt--2

A utility class to set the top margin of an element.

Include with:

@include jigsass-util(u-mt, $modifier: 2 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-mt--2'>
    This element has a 2 rhythm units top margin.
  </div>
</div>

u-mt--3

A utility class to set the top margin of an element.

Include with:

@include jigsass-util(u-mt, $modifier: 3 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-mt--3'>
    This element has a 3 rhythm units top margin.
  </div>
</div>

u-mt--4

A utility class to set the top margin of an element.

Include with:

@include jigsass-util(u-mt, $modifier: 4 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-mt--4'>
    This element has a 4 rhythm units top margin.
  </div>
</div>

u-me--auto

A utility class to set the margin on the horizontal end of an element.

Include with:

@include jigsass-util(u-me, $modifier: auto [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-me--auto'>
    This element has auto margin on the horizontal end.
  </div>
</div>

u-me--1

A utility class to set the margin on the horizontal end of an element.

Include with:

@include jigsass-util(u-me, $modifier: 1 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-me--1'>
    This element has a 1 rhythm units margin on the horizontal end.
  </div>
</div>

u-me--2

A utility class to set the margin on the horizontal end of an element.

Include with:

@include jigsass-util(u-me, $modifier: 2 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-me--2'>
    This element has a 2 rhythm units margin on the horizontal end.
  </div>
</div>

u-me--3

A utility class to set the margin on the horizontal end of an element.

Include with:

@include jigsass-util(u-me, $modifier: 3 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-me--3'>
    This element has a 3 rhythm units margin on the horizontal end.
  </div>
</div>

u-me--4

A utility class to set the margin on the horizontal end of an element.

Include with:

@include jigsass-util(u-me, $modifier: 4 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-me--4'>
    This element has a 4 rhythm units margin on the horizontal end.
  </div>
</div>

u-mb--auto

A utility class to set the bottom margin of an element.

Include with:

@include jigsass-util(u-mb, $modifier: auto [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-mb--auto'>
    This element has auto bottom margin.
  </div>
</div>

u-mb--1

A utility class to set the bottom margin of an element.

Include with:

@include jigsass-util(u-mb, $modifier: 1 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-mb--1'>
    This element has a 1 rhythm units bottom margin.
  </div>
</div>

u-mb--2

A utility class to set the bottom margin of an element.

Include with:

@include jigsass-util(u-mb, $modifier: 2 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-mb--2'>
    This element has a 2 rhythm units bottom margin.
  </div>
</div>

u-mb--3

A utility class to set the bottom margin of an element.

Include with:

@include jigsass-util(u-mb, $modifier: 3 [, $from, $until, $misc]);

Example

<div class='fpo--b'>
  <div class='fpo  u-mb--3'>
    This element has a 3 rhythm units bottom margin.
  </div>
</div>

u-mb--4

A utility class to set the bottom margin of an element.

Include with:

@include jigsass-util(u-mb, $modifier: 4 [, $from, $until, $misc]);