Typography

Installation

  yarn add @chewy/kib-foundations

Import

  @use '~@chewy/kib-foundations/src/typography';

Functions

get

@function get($path) { ... }@function get($path) { 
  @return -get-type-style-property($path...);
 }
Description

Get a single type style property definition.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$path

The map path to the desired property definition.

List none
Returns
List or String or Number

Return the value of the type style property.

Requires

get-weight

@function get-weight($name) { ... }@function get-weight($name) { 
  @return get('weight-#{$name}');
 }
Description

Get a type weight style property

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$name

The name of the defined type style.

String none
Returns
String

Return the custom property and fallback of the weight style.

Requires
Used by

get-type-style-with-fallback

@function get-type-style-with-fallback($path) { ... }@function get-type-style-with-fallback($path) { 
  $theme-map: common.get-theme-map(settings.$themes, settings.$preferred-theme);
  $type-style: map.get($theme-map, $path...);

  // Fallback to default theme if type style doesn't exist on the preferred theme to avoid an error
  @if not $type-style {
    @warn "Attempting to fallback to '#{common.$default-theme}' theme";

    $theme-map: common.get-theme-map(settings.$themes, common.$default-theme);
    $type-style: map.get($theme-map, $path...);
  }

  @return $type-style;
 }
Description

Retrieve a defined type style group definition from the preferred theme map first, then if not found retry with the fallback default theme.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$path

Path of type style definition in theme map

List none
Returns
Map

Theme map containing a style definition.

Requires
Used by

get-type-style

@function get-type-style($name) { ... }@function get-type-style($name) { 
  $type-style: null;
  $is-hero: string.index($name, 'hero');
  $has-alternate: string.index($name, 'alternate');

  @if $alternate or $is-hero {
    @if $alternate and $is-hero and not $has-alternate {
      $name: '#{$name}-alternate';
    }

    $type-style: get-type-style-with-fallback('deprecated', $name);
  } @else {
    $type-style: get-type-style-with-fallback($name);
  }

  @if not $type-style {
    $alt-msg: if($alternate, 'alternate variant of the ', '');
    @error "The #{$alt-msg}type style "#{$name}" does not exist.";
  }

  @return -transform-type-style($type-style);
 }
Description

Get a defined type style group definition.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$name

The name of the defined type style.

String none
Returns
Map

Return a map containing a style definition.

Throws
  • The #{$alt-msg}type style

Used by

get-properties

@function get-properties($theme: settings.$preferred-theme, $deprecated: false) { ... }@function get-properties($theme: settings.$preferred-theme, $deprecated: false) { 
  $theme-map: common.get-theme-map(settings.$themes, $theme);

  @if not $deprecated {
    $theme-map: map.deep-remove($theme-map, 'deprecated');
  }

  $transformed: -recursive-transform($theme-map);
  $flattened: common.flatten-map($transformed);
  $properties: ();

  // Filter out any properties that have other properties as values.
  // This is because the style-as will being those other properties anyway, so
  // the "middle-man" properties aren't used anywhere and thus don't need to be set.
  @each $name, $value in $flattened {
    @if meta.type-of($value) != 'string' or not string.index($value, 'var(') {
      $properties: map.set($properties, $name, $value);
    }
  }

  @return $properties;
 }
Description

Returns a theme's typography tokens as a flattened map

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$theme

Name of the theme

Stringsettings.$preferred-theme
$deprecated

Include deprecated typography styles. Not recommended.

Boolfalse
Returns
Map

Final flattened map

Requires
Used by

-transform-type-style

@function -transform-type-style($type-style) { ... }@function -transform-type-style($type-style) { 
  $map: $type-style;

  @each $key, $value in $map {
    $transformed: $value;

    @if meta.type-of($value) == number and math.unit($value) == 'px' {
      @if $key == 'font-size' {
        $transformed: unit.rem($value);
      } @else if $key == 'line-height' {
        $line-height: $value;
        $font-size: map.get($map, 'font-size');
        $transformed: math.div($line-height, $font-size);
      }
    }

    @if $key == 'paragraph-spacing' {
      $transformed: spacing.get('s4');
    }

    $map: map.set($map, $key, $transformed);
  }

  @return $map;
 }
Description

Runs some transforms on properties in a type style group definition.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$type-style

The name of the defined type style.

Map none
Returns
Map

Return a map containing a style definition.

Requires
Used by

-recursive-transform

@function -recursive-transform($map) { ... }@function -recursive-transform($map) { 
  @each $key, $value in $map {
    @if meta.type-of($value) == 'map' {
      // It's a type style group, so transform it
      @if map.has-key($value, 'font-size') {
        $value: -transform-type-style($value);
        $map: map.set($map, $key, $value);
      } @else {
        // We need to go deeper
        $map: map.set($map, $key, -recursive-transform($value));
      }
    }
  }

  @return $map;
 }
Description

Recursively transforms all map properties with the transform-type-style function.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$map

The map to recursively transform

Map none
Returns
Map

The transformed map

Requires
Used by

-get-type-style-value

@function -get-type-style-value($theme: settings.$default-theme, $alias) { ... }@function -get-type-style-value($theme: settings.$default-theme, $alias) { 
  $theme-map: common.get-theme-map(settings.$themes, $theme);
  $has-key: map.has-key($theme-map, $path...);

  @if not $has-key {
    @error "Type style value (#{$path}) not found.";
  }

  @return map.get($theme-map, $path...);
 }
Description

Retrieves a typography style property value

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$theme

Name of the theme

Stringsettings.$default-theme
$alias

Alias of spacing unit

String none
Returns
Number

Spacing value from the theme

Throws
  • Type style value (#{$path}) not found.

Requires
Used by

-get-type-style-property

@function -get-type-style-property($path) { ... }@function -get-type-style-property($path) { 
  $theme-map: common.get-theme-map(settings.$themes, settings.$preferred-theme);

  @if not map.has-key($theme-map, $path...) {
    @error "The type style property (#{$path}) does not exist.";
  }

  $property: common.get-property-name('typography', $path...);
  $fallback: -get-type-style-value(settings.$preferred-theme, $path...);

  @return string.unquote('var(#{$property}, #{$fallback})');
 }
Description

Get a single type style property definition.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$path

The map path to the desired property definition.

List none
Returns
List or String or Number

Return the value of the type styoe property.

Throws
  • The type style property (#{$path}) does not exist.

Requires
Used by

Mixins

custom-properties

@mixin custom-properties($theme: 'base', $deprecated: false, $overrides) { ... }@mixin custom-properties($theme: 'base', $deprecated: false, $overrides) { 
  $typography-properties: functions.get-properties($theme, $deprecated);

  @if $overrides {
    $typography-properties: map.deep-merge($typography-properties, $overrides);
  }

  @each $key, $value in $typography-properties {
    #{common.get-property-name('typography', $key)}: $value;
  }
 }
Description

Generates CSS Custom Properties for a Chirp theme's typography tokens

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$theme

The name of the theme to look up

String'base'
$deprecated

Includes custom properties for deprecated type styles

Boolfalse
$overrides

Map that overrides any matching values within the theme

Map none
Example

Apply all available properties to the :root of the page

@use '~@chewy/kib-foundations/src/typography';

:root {
  @include typography.custom-properties;
}

Apply properties to a selector

@use '~@chewy/kib-foundations/src/typography';

.chirp-typography {
  @include typography.custom-properties;
}

Override a typography property

@use '~@chewy/kib-foundations/src/typography';

.chirp-typography-custom {
  @include typography.custom-properties($overrides: ('text-typeface': Roboto));
}
Requires

style-as

@mixin style-as($name, $alternate) { ... }@mixin style-as($name, $alternate) { 
  $style: functions.get-type-style($type-style, $alternate);

  @each $name, $value in $style {
    $property-name: common.get-property-name(
      'typography',
      if($alternate, 'deprecated', null),
      $type-style,
      $name
    );
    $css-variable: '';

    @if meta.type-of($value) == 'string' and string.index($value, 'var(') {
      $css-variable: $value;
    } @else {
      $css-variable: var(#{$property-name}, #{$value});
    }

    @if $name == 'text-case' and $name {
      text-transform: $css-variable;
    } @else if $name == 'text-decoration' {
      text-decoration: if($value == 'strikethrough', line-through, $value);
    } @else {
      #{$name}: $css-variable;
    }
  }
 }
Description

Generate styles using custom properties from a defined type style.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$name

The name of the type style

String none
$alternate

Applies the deprecated alternate type style definition

Boolean none
Example

Apply styles for a type style definition

@use '~@chewy/kib-foundations/src/typography';

.my-custom-class {
  @include typography.style-as('display-1');
}

Apply styles for a deprecated alternate type style definition

@use '~@chewy/kib-foundations/src/typography';

.my-custom-class {
  @include typography.style-as('display-1', $alternate: true);
}
Requires