JigSass Tools typography

NPM version Build Status Dependency Status

Installation

Using npm:

npm i -S jigsass-tools-typography

Usage

@import 'path/to/jigsass-tools-typography/scss/index';

jigsass-tools-typography is based on a typographic system that sets the font-size of the html element to a fourth of the desired line-height, which will then serve as the base-unit for establishing and maintaining a vertical rhythm. It then sets the font-size of the body element to the base font size, and its line-height to 4rem.

By default, the base font size is set at 16px, while the vertical rhythm is at 6px, giving us a default line-height 1.5 times the default font-size (24px).

All sizes can be defined on a per-breakpoint level. jigsass-tools-typography depends on jigsass-tools-mq to manage media-queries and breakpoints definitions.

A good place to start at, is by defining these two sizes and other the other jigsass-tools-typography configuration variables so that they match your project's settings and design:

// Default output unit, where applicable
$jigsass-defaule-unit: rem;

// Should a pixel fallback be included for rem values
$jigsass-rem-px-fallback: false;

// User-defined ratios for building modular scales.
// Extends the default map
$jigsass-ratios: (
  some-ratio: 1.273;
);

$jigsass-default-ratio: major-second;


// Extends the default map of named-sizes.
$jigsass-sizes: (
  // ** Override defaults ** //
  // Will be set as the font-size of the `html` element
  // and used as the basic unit of vertical rhythm.
  rhythm-unit: (
    default: 6px,   // In `default` breakpoint.
    medium: 7px     // In `medium` breakpoint.
  ),      

  // Will be used to set the `font-size` of the `body` element.
  body: (
    default: 16px,  // In `default` breakpoint.
    medium: 18px,   // In `medium`breakpoint.
  ),            

  // The minimum amount of pixels above and below text lines
  min-line-padding: (default: 2px), 

  // ** Named sizes ** //
  headline: (
   default: body 3 golden,  // format: base (named-size or number) [exponent [ratio]]
  ),
)

The sizes are then easily available, converted into the unit of your choice:

@include jigsass-set-baseline;

.headline {
  @include jigsass-font-size(headline, $bps: all, $unit: rem);
  padding-right: jigsass-get-size(rhythm-unit, $unit: rem);
}

License: MIT

_math

functions

jigsass-pow

@function jigsass-pow($base, $base) { ... }

Description

pow with non-integer exponents

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$base

The base number to be multiplied.

Numbernone
$base

The exponent to use for multiplication.

Numbernone

Returns

Number

The results of $base to power $exponent.

Used by

Author

typography - settings

functions

jigsass-get-rhythm-unit

@function jigsass-get-rhythm-unit($bp: $jigsass-mq-active-breakpoint) { ... }

Description

Get the spacing unit for a given breakpoint

If a spacing unit isn't explicitly defined in the rhythm-unit key of the sizes palette map for the given breakpoint, the spacing unit for the last previously defined breakpoint will be used.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$bp

The breakpoint to get a spacing-unit for.

String$jigsass-mq-active-breakpoint

Returns

Number

The base spacing unit for the passed breakpoint.

Throws

  • jigsass-get-rhythm-unit: rhythm-unit is not defined in the the sizes pallete.

  • jigsass-get-rhythm-unit: rhythm-unit should be a

Requires

Used by

jigsass-get-size

@function jigsass-get-size($size, $context: jigsass-get-body-font-size(), $unit: $jigsass-default-unit) { ... }

Description

Retrieve the value of a named size from the $jigsass-sizes palette.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$size

When a String: A named-size from the $jigsass-sizes palette.

When a Number: A length to be converted into the unit defined in $unit.

When a List: First item is the base for multiplication, second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

String or Number or Listnone
$context

When converting to or from relative units, the absolute length (in px) which is the basis of conversion (e.g. for $lengths in em units, would normally be the font-size of the current element).

Numberjigsass-get-body-font-size()
$unit

The output unit to convert $size to.

String$jigsass-default-unit

Returns

Number

The size, converted to the specified unit.

Throws

  • jigsass-get-size: #{$_size} is a #{type-of($_size)}, not a valid CSS length.

Requires

Used by

jigsass-merge-sizes

@function jigsass-merge-sizes() { ... }

Description

A util function to merge default and user-defined sizes.

Parameters

None.

Returns

Map

Requires

Used by

jigsass-get-min-line-padding

@function jigsass-get-min-line-padding($bp: $jigsass-mq-active-breakpoint) { ... }

Description

Get the minimal padding between lines of text for a given breakpoint

If a minimal line-padding isn't explicitly defined in the min-line-padding key of the sizes palette map for the given breakpoint, the padding for the last previously defined breakpoint will be used.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$bp

The breakpoint to get padding for.

String$jigsass-mq-active-breakpoint

Returns

Number

The minimal padding between lines of text for the passed breakpoint.

Throws

  • jigsass-get-min-line-padding: min-line-padding is not defined in

  • jigsass-get-min-line-padding: min-line-padding should be a

Requires

Used by

jigsass-get-body-font-size

@function jigsass-get-body-font-size($bp: $jigsass-mq-active-breakpoint) { ... }

Description

Get the base font-size for a given breakpoint

If a font-size isn't explicitly defined in the body key of the sizes palette map for the given breakpoint, the font-size for the last previously defined breakpoint will be used.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$bp

The breakpoint to get a font-size for.

String$jigsass-mq-active-breakpoint

Returns

Number

The base font-size for the passed breakpoint.

Throws

  • jigsass-get-body-font-size: body is not defined in the the sizes pallete.

  • jigsass-get-body-font-size: body should be a

Requires

Used by

[private] _jigsass-get-config-bp-value

@function _jigsass-get-config-bp-value($bp, $source) { ... }

Description

Get the value of a base unit for a given breakpoint

If a unit isn't explicitly defined in the $source map for the given breakpoint, the spacing unit for the last previously defined breakpoint will be used.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$bp

The breakpoint to get a spacing-unit for.

Stringnone
$source

The map of spacing units to search in.

Mapnone

Returns

Number

The base unit for the passed breakpoint.

Throws

  • _jigsass-get-config-bp-value: #{inspect($source)}

Used by

[private] _jigsass-get-ratio

@function _jigsass-get-ratio($ratio) { ... }

Description

Get a ratio's value by name or number.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$ratio

The name of a ratio, or a number to serve as the ratio.

String or Numbernone

Returns

Number

Throws

  • #{$_extracted-ratio} is not a defined ratio.

Requires

Used by

variables

jigsass-default-unit

$jigsass-default-unit: rem !default;

Description

The default output unit.

Type

String

jigsass-ratios

$jigsass-ratios: () !default;

Description

User-defined ratios for modular scales.

Define your own values BEFORE importing.

Type

Map

Used by

jigsass-default-ratio

$jigsass-default-ratio: major-second !default;

Description

The default ratio used to construct modular scales.

Type

String

Used by

jigsass-sizes

$jigsass-sizes: (
  // headings
  zeta: (
    default: body
  ),
  epsilon: (
    default: body 1
  ),
  delta: (
    default: body 2
  ),
  gamma: (
    default: body 3
  ),
  beta: (
    default: body 4
  ),
  alpha: (
    default: body 5
  ),

  // small print
  milli: (
    default: body -1
  ),
  micro: (
    default: body -2
  )
) !default;

Description

Reusable responsive named sizes

A per-breakpoint mapping of name to sizes formatted as name: size or name: base multiplier [ratio]

Type

Map

Map structure

Map keyNameMap keyDescriptionMap keyTypeMap keyValue
size

Values of given size at different breakpoints

Mapnone
size.breakpoint

The assigned size at the given breakpoint.

When a List: First item is the base for multiplication, second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

When a String: An alias to another size.

Number or List or Stringnone

Example

$jigsass-sizes: (
  //  --- Override default sizes --- //
  rhythm-unit: (
    default: 6px,
    large: 7px
  ),
  body: (
    default: 16px,
    large: 18px
  ),

  //  --- Font sizes --- //
  zeta: (
    default: body
  ),
  milli: (
    default: body -1/* , $jigsass-default-ratio */
  ),

  // --- Lengths --- //
  page: (
    xl: 1200px
  ),
);

Used by

jigsass-rem-px-fallback

$jigsass-rem-px-fallback: false !default;

Description

Should fallback values in px also be outputted when outputting rems.

Type

Boolean

Used by

[private] _jigsass-default-sizes

$_jigsass-default-sizes: (
  rhythm-unit: (
    default: 6px
  ),
  body: (
    default: 16px
  ),
  min-line-padding: (
    default: 2px
  )
);

Description

Default named sizes required by jigsass-tools-typography

Do not directly redefine this map. To override with your own values, define these and other named sizes in $jigsass-sizes before importing this file.

Map structure

keyNamekeyDescriptionkeyTypekeyValue
rhythm-unit

The basic spacing unit to construct vertical rhythm from. Should be a quarter of the desired basic line-height in a given breakpoint.

Will be used to set the font-size on the html element in percentage.

Breakpoint names must correspond with those defined in $jigsass-breakpoints.lengths

Map(default: 6px)
body

Base font size in pixels for each breakpoint,

Will be used to define the font-size on the body element.

Breakpoint names must correspond with those defined in $jigsass-breakpoints.lengths

Map(default: 16px)
min-line-padding

The minimum amount of pixels above and below text lines

Breakpoint names must correspond with those defined in $jigsass-breakpoints.lengths

Map(default: 2px)

Used by

[private] _jigsass-ratios

$_jigsass-ratios: (
  golden: 1.618,
  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,
  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,
);

Description

Common ratios for building modular scales.

To add your own ratios, define the $jigsass-ratios map.

Type

Map

Used by

Links

typography - unit conversion

functions

jigsass-convert-length

@function jigsass-convert-length($length, $to-unit: $jigsass-default-unit, $from-context: jigsass-get-body-font-size(), $to-context) { ... }

Description

Convert any CSS length or percentage value to any another.

Based on accoutrement-scale/units

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$length

The length or percentage to convert

Numbernone
$to-unit

String matching a css unit keyword, e.g. em, %, etc.

String$jigsass-default-unit
$from-context

When converting from relative units, the absolute length (in px) to which $length refers (e.g. for $lengths in em units, would normally be the font-size of the current element).

Numberjigsass-get-body-font-size()
$to-context

For converting to relative units, the absolute length in px to which the output value will refer. Defaults to the same as $from-context, since it is rarely needed.

Numbernone

Returns

Number

Throws

  • jigsass-convert-length: Context paremeters must resolve to a value in pixel units.

  • Failed to convert #{$length} into #{$to-units}.

Requires

Used by

[private] _jigsass-type-get-px

@function _jigsass-type-get-px($length) { ... }

Description

Converted a value to px ig possible.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$length

The number to be converted to px if comparable.

Numbernone

Returns

Number or False

Either the px value of the converted $length or false.

Used by

[private] _jigsass-type-get-number

@function _jigsass-type-get-number($unit) { ... }

Description

Get a 0 value for any absolute unit.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$unit

The unit to return as a number.

Stringnone

Returns

Number or False

Either the 0 value of a unit or false.

Used by

[private] _jigsass-rem-fallback-values

@function _jigsass-rem-fallback-values($value) { ... }

Description

Get the px/rem versions of a value.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$value

The value to convert

Numbernone

Returns

Map

A map of px corresponding rem values

Requires

Used by

[private] _jigsass-list-convert-rems

@function _jigsass-list-convert-rems() { ... }

Description

Get the px/rem versions of a list (or nested lists).

Parameters

None.

Requires

Used by

[private] jigsass-strip-unit

@function jigsass-strip-unit($num) { ... }

Description

Convert a length to a unitless number

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$num

The number to strip the unit from

Numbernone

Returns

Number

Throws

  • jigsass-strip-unit: #{$num} is a #{type-of($num)}, not a number.

variables

jigsass-units-root-font-size

$jigsass-units-root-font-size: 16px !default;

Description

The font-size of the html element. _Only re define this to fit your design if using _units.scss as a standalone module. Otherwise, define the default size of the html element in the rhythm-unit key of the $jigsass-sizes map._

Type

Number

Used by

mixins

jigsass-rem

@mixin jigsass-rem($property, $values, $bps, $px-fallback: $jigsass-rem-px-fallback) { ... }

Description

Convert the values of a given property from px to rem at specified breakpoints.

Optionally include fallback in pixel values.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$property

The css property name.

Stirngnone
$values

The value or list of values for the property.

Number or List or Stringnone
$bps

(false) list of breakpoints to output the converted values in. all iterates over the breakpoints defined in the rhythm-unit key of the sizes palette.

String or List or Booleannone
$px-fallback

Determines if pixel fallback will be generated

Boolean$jigsass-rem-px-fallback

Requires

[private] _jigsass-px2rem

@mixin _jigsass-px2rem($property, $values, $px-fallback) { ... }

Description

Private helper function to convert the values of a given property from px to rem. Optionally include fallback in pixel values

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$property

The css property name.

Stringnone
$values

The value or list of values for the property.

Number or List or Stringnone
$px-fallback

Determines if pixel fallback will be generated

Booleannone

Requires

Used by

typography - vertical rhythm

mixins

jigsass-border-top

@mixin jigsass-border-top($width, $lines: 1, $style: solid) { ... }

Description

Apply a border-top without messing up the vertical rhythm.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$width

When a String: A named-size from the $jigsass-sizes palette.

When a Number: A length to be converted into the unit defined in $unit.

When a List: First item is the base for multiplication, second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

String or Number or Listnone
$lines

The number of typographic lines occupied by the border and padding add together.

Number1
$style

The border style (and, oprionally, color).

Can take a string containing the border style, e.g dotted or a list containing the border style and color, e.g. solid rebeccapurple.

String or Listsolid

Requires

jigsass-set-baseline

@mixin jigsass-set-baseline($percentage: true) { ... }

Description

Establish a responsive typographic baseline.

Sets the font-size of the html element to a single rhythm unit in every breakpoint defined in $jigsass-sizes.rhythm-unit.

Additionally sets a line-height of 4rem on the body element, and a font-size in each breakpoint defined in $jigsass-get-body-font-size;

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$percentage

Set the html element's font-size in % instead of px

Booleantrue

Throws

  • Generating pixel fallback to rem values depends on the

Requires

jigsass-font-size

@mixin jigsass-font-size($size, $bps: false, $lines: false, $context: false, $unit: $jigsass-default-unit) { ... }

Description

Set font-size and line-height properties based on size and vertical rhythm configurations.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$size

When a String: A named-size from the $jigsass-sizes palette.

When a Number: A length to be converted into the unit defined in $unit.

When a List: First item is the base for multiplication, second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

String or Number or Listnone
$bps

A list of breakpoints to generate font-size in. all will generate a font-size definition for each rhythm-unit breakpoint and each breakpoint defined for $size in the $jigsass-sizes map.

String or List or Booleanfalse
$lines

Override the default number of typographic lines occupied by the element.

Number or Booleanfalse
$context

When converting to or from relative units, the absolute length (in px) which is the basis of conversion (e.g. for $lengths in em units, would normally be the font-size of the current element).

Number or Booleanfalse
$unit

The output unit to convert $size to.

String$jigsass-default-unit

Requires

jigsass-border

@mixin jigsass-border($side, $width, $lines: 1, $style: solid) { ... }

Description

Apply a border to an element without throwing off the vertical rhythm.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$side

The side of the element to apply the border to. Can be one of { all | top | right | bottom | left }

Stringnone
$width

When a String: A named-size from the $jigsass-sizes palette.

When a Number: A length to be converted into the unit defined in $unit.

When a List: First item is the base for multiplication, second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

String or Number or Listnone
$lines

The number of typographic lines occupied by the border and padding add together.

Number1
$style

The border style (and, oprionally, color).

Can take a string containing the border style, e.g dotted or a list containing the border style and color, e.g. solid rebeccapurple.

String or Listsolid

Requires

Used by

jigsass-border-bottom

@mixin jigsass-border-bottom($width, $lines: 1, $style: solid) { ... }

Description

Apply a border-bottom without messing up the vertical rhythm.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$width

When a String: A named-size from the $jigsass-sizes palette.

When a Number: A length to be converted into the unit defined in $unit.

When a List: First item is the base for multiplication, second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

String or Number or Listnone
$lines

The number of typographic lines occupied by the border and padding add together.

Number1
$style

The border style (and, oprionally, color).

Can take a string containing the border style, e.g dotted or a list containing the border style and color, e.g. solid rebeccapurple.

String or Listsolid

Requires

jigsass-border-horizontal

@mixin jigsass-border-horizontal($width, $lines: 1, $style: solid) { ... }

Description

Apply a border to the top and bottom of an element without messing up the vertical rhythm.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$width

When a String: A named-size from the $jigsass-sizes palette.

When a Number: A length to be converted into the unit defined in $unit.

When a List: First item is the base for multiplication, second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

String or Number or Listnone
$lines

The number of typographic lines occupied by the border and padding add together.

Number1
$style

The border style (and, oprionally, color).

Can take a string containing the border style, e.g dotted or a list containing the border style and color, e.g. solid rebeccapurple.

String or Listsolid

Requires

jigsass-borders

@mixin jigsass-borders($width, $lines: 1, $style: solid) { ... }

Description

Apply a border to all sides of an element without messing up the vertical rhythm.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$width

When a String: A named-size from the $jigsass-sizes palette.

When a Number: A length to be converted into the unit defined in $unit.

When a List: First item is the base for multiplication, second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

String or Number or Listnone
$lines

The number of typographic lines occupied by the border and padding add together.

Number1
$style

The border style (and, oprionally, color).

Can take a string containing the border style, e.g dotted or a list containing the border style and color, e.g. solid rebeccapurple.

String or Listsolid

Requires

[private] _jigsass-font-size

@mixin _jigsass-font-size() { ... }

Description

A private helper for use when setting font-size and line-height properties based on size and vertical rhythm configurations.

Parameters

None.

Requires

Used by

[private] _jigsass-border

@mixin _jigsass-border() { ... }

Description

A private helper for use when setting borders that don't mess up the vertical rhythm.

Parameters

None.

Requires

Used by

functions

jigsass-rhythm

@function jigsass-rhythm($lines, $context: jigsass-get-body-font-size(), $unit) { ... }

Description

Get the length of x typographic lines.

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$lines

The number of Typographic lines to get the length of.

Numbernone
$context

When converting to or from relative units, the absolute length (in px) which is the basis of conversion (e.g. for $lengths in em units, would normally be the font-size of the current element).

Number or String or Listjigsass-get-body-font-size()
$unit

The unit to convert to.

Stringnone

Returns

Number

Requires

Used by

jigsass-lines-for-size

@function jigsass-lines-for-size($size, $rhythm: jigsass-get-rhythm-unit()) { ... }

Description

Get the number of Typographic lines required for a given font-size

Parameters

parameterNameparameterDescriptionparameterTypeparameterDefault value
$size

When a Number: A font-size.

When a String: A named size from the jigsass-sizes palette.

When a List: First item is the base for multiplication (named size or number), second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

Number or String or Listnone
$rhythm

The length of a single typographic line.

When a Number: A length.

When a String: A named size from the jigsass-sizes palette.

When a List: First item is the base for multiplication (named size or number), second item is the multiplier, third, optional, item is the ratio. If there are only two items in the name list, ratio will resolve to the value of $jigsass-default-ratio.

Number or String or Listjigsass-get-rhythm-unit()

Returns

Number

Requires

Used by

variables

[private] _jigsass-browser-default-font-size

$_jigsass-browser-default-font-size: 16px;

Description

The default font size in most (all?) browsers.

Type

Number

Used by