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 $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

Requires
Used by

get-type-style-variant-weight

@function get-type-style-variant-weight($type-style, $variant) { ... }@function get-type-style-variant-weight($type-style, $variant) { 
  $theme-map: common.get-theme-map(settings.$themes, common.$default-theme);
  $category: null;
  $weight-token: null;

  @while not $weight-token {
    @each $c in settings.$type-style-categories {
      $found: string.index($type-style, $c);

      @if $found {
        $category: $c;
        $weight-token: '#{$category}-weight-#{$variant}';
      } @else {
        $weight-token: -1;
      }
    }
  }

  @if $weight-token and $weight-token != -1 and not map.has-key($theme-map, $weight-token) {
    @error "#{$weight-token}: Variant '#{$variant}' does not exist for '#{$type-style}' type style.";
  }

  $property-name: common.get-property-name('typography', $category, 'weight', $variant);
  $value: map.get($theme-map, $weight-token);

  @return var(#{$property-name}, #{$value});
 }
Description

Returns a font weight variant custom property and fallback for the new typography tokens set. This is used to override the default font-weight with the variant value instead.

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

Type style name

String none
$variant

Variant name (strong, stronger)

String none
Returns
Map

Variant font weight value

Throws
  • #{$weight-token}: Variant

Requires
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');
  }

  $properties: common.flatten-map($theme-map);

  @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

-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) { 
  @if $theme == 'base' {
    @include webTokens.custom-properties($deprecated);
  } @else if $theme == 'petmd' {
    @include petmdTokens.custom-properties($deprecated);
  } @else if $theme == 'gordita' {
    @include gorditaTokens.custom-properties($deprecated);
  } @else if $theme == 'enterprise' {
    @include enterpriseTokens.custom-properties($deprecated);
  } @else {
    @error "Theme '#{$theme}' not found.";
  }

  @if $overrides {
    @each $key, $value in $overrides {
      #{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));
}
Throws
  • Theme

Requires

style-as

@mixin style-as($name, $variant, $alternate) { ... }@mixin style-as($name, $variant, $alternate) { 
  @if map.has-key(settings.$aliases, $type-style) {
    $type-style: map.get(settings.$aliases, $type-style);
  }

  // Returns alias equivalent if it exists
  @if map.has-key(settings.$aliases, $type-style) and not $alternate {
    $alias-style: map.get(settings.$aliases, $type-style);

    @if meta.type-of($alias-style) == 'list' and list.length($alias-style) == 2 {
      $type-style: list.nth($alias-style, 1);
      $variant: list.nth($alias-style, 2);
    }
  }

  $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: var(#{$property-name}, #{$value});

    @if $name == 'font-weight' {
      font-weight: if(
        $variant,
        functions.get-type-style-variant-weight($type-style, $variant),
        $css-variable
      );
    } @else if $name == 'text-case' {
      text-transform: $css-variable;
    } @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
$variant

The variant 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 variant type style

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

.my-custom-class {
  @include typography.style-as('editorial-heading-2', 'strong');
}

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